Skip to main content

Getting Started

The following documents the C interface to the OESIS Framework including data types, functions, and components. Much of the documentation found in this form covers other languages extensions. Each language extension is catered to the language itself, however, all functionality is identical with each language.

Binaries​

The following are the binaries which are required for OESIS Framework to run properly. Note that the authenticity of all binaries can be verified by ensuring they are signed by OPSWAT, Inc.

BinaryDescription
libwaapi.dllThe entry point into OESIS Framework. This is the only one that needs to be loaded by integrating applications.
libwautils.dllRequired by libwaapi.dll
libwaheap.dllRequired by libwaapi.dll
libwaapi.libOptional. Stub library to allow for implicit integration.

The following binaries are required when using specific module extensions or deployment configurations.

BinaryDescription
libwalocal.dllRequired for method support using the manageability, vulnerability, and removal modules.
libwadeviceinfo.dllRequired for method support using the device info module.
libwaremoval.dllRequired for method support using the removal module.
libwavmodapi.dllRequired for method support using the vulnerability module.
libwaresource.dllRequired for offline deployments.
libwacollector.dllRequired for using the diagnostics module.
libwadriver.dllRequired for using the system driver module.
libwaadbrowser.dllRequired for using the advanced browser module.
libwainfection.dllRequired for using the infection module.
libwanetscan.dllRequired for using the netscan module.
libwaaddon.dllRequired for using the addon methods, which extend the core functionality.
rm.exeRequired by libwaremoval.dll.
wa_3rd_party_host_32.exe/wa_3rd_party_host_64.exeRequired by libwautils.dll and libwalocal.dll.

Remarks​

If the integrating application has the core libraries (libwaapi.dll, libwautils.dll and libwaheap.dll) in a location other than the executable location, a WINAPI call must be made to SetDllDirectory() specifying the library location. This must be done prior to loading libwaapi.dll. See msdn for reference.

The removal module on Windows (libwaremoval.dll) requires rm.exe and script.dat to perform uninstall operations. Two deployment modes are supported:

  • Sidecar mode (recommended): If both rm.exe and script.dat are placed in the same directory as libwaremoval.dll, they will be used directly without any file extraction. No files are written or deleted during operation. Both files must be present - if either is missing, the module falls back to legacy mode.
  • Legacy mode: If the sidecar files are absent, rm.exe and script.dat are automatically extracted to %ProgramData%\OPSWAT\OESIS\AR\ at runtime and deleted after use.

Headers​

The following are the C header files made available by the OESIS Framework

HeaderDescription
wa_api.hOnly header file that should be explicitly included in integrating applications. Contains function signatures exported by libwaapi.dll, and includes the other header files, making relevant defines and typedefs available.
wa_api_defs.hDefines exporters/importers
wa_api_error_codes.hDefines error codes
wa_api_fnc_ptr.hDefines function pointer helpers
wa_api_data_types.hDefines data types
wa_api_product_categories.hDefines product categories
wa_api_config_options.hDefines configuration options
wa_api_invoke_common.hDefines common methods for products
wa_api_invoke_method.hDefines common methods for products
wa_api_invoke_detect.hDefines detection methods
wa_api_json_keys.hDefines json object keys that map to json values

Functions​

All functions will return an error code that is used to determine the success or failure of the function call. Every function uses the same return signature WAAPI_DECLFUNCTION which is defined as follows:

#define WAAPI_DECLFUNCTION __declspec(dllimport) __int32 __stdcall

wa_api_setup​

Initialize the OESIS Framework with license and configuration parameters.

WAAPI_DECLFUNCTION wa_api_setup ( 
        const wa_wchar * json_config 
        wa_wchar ** json_out
);

The provided license key activates all deployed components. If the license key provided is valid for the primary component and not for others, it will not return an error until calls to the unlicensed component are attempted. If a component deployed is not licensed by the provided license key, then calls to wa_api_invoke will return WAAPI_ERROR_COMPONENT_NOT_LICENSED.

An example of the output from this call can be found in the OESIS Framework guide

Parameters​

NameDirectionDescription
json_config[IN]The configuration and licensing options for the interface. See possible configurations. Also, see the Quick Start guide for an example.
json_out[OUT]json_out The initialization results. An example of the output from this call can be found in the OESIS Framework guide.

The json_config parameter supports the following keys:

{
        "config" : { ... },
        "config_debug" : {
            "debug_log_output_path": string,
            "debug_log_level" : string,
            "debug_log_components" : [
                    string,
                    ...
            ],
            "debug_log_file_size": number,
            "debug_log_folder_size": number,
            "debug_log_time": number,
            "debug_log_count": number,
            "debug_log_signatures" : [
                    number,
                    ...
            ],
            "debug_log_methods" : [
                    number,
                    ...
            ],
            "log_mode": string
        },
        "get_current_config" : true,
        "reset_defaults" : true
}
KeyJSONDescription
configobjectSpecifies the desired configuration values to set. Optional if "get_current_config" is being used.
config_debugobject(optional) Specifies the desired configuration values for debug logs. Debug logs will be activated automatically if this key exists.
config_debug.debug_log_output_pathstring(optional) The directory where the debug logs will be written to.
config_debug.debug_log_levelstring(optional) Specifies the log level. This value can be OFF, DEBUG, ERROR, FATAL, INFO, WARNING, TRACE, or ALL.
config_debug.debug_log_componentsarray<string>(optional) Specifies the log components. Possible values are CORE, SETUP, TEARDOWN, INVOKE, or ALL.
config_debug.debug_log_file_sizenumber(optional) Specifies the log file size in MB.
config_debug.debug_log_folder_sizenumber(optional) Specifies the log folder size in MB.
config_debug.debug_log_timenumber(optional) Specifies the log retention time in hours.
config_debug.debug_log_countnumber(optional) Specifies the number of logs for retention..
config_debug.debug_log_signaturesarray<number>(optional) Specifies the desired signatures to be logged.
config_debug.debug_log_methodsarray<number>(optional) Specifies the desired methods to be logged.
config_debug.log_modestring(optional) Specifies how debug logs are written. Possible values:
encrypted : Write debug logs only to the encrypted log file.
plaintext : Write debug logs only to the plaintext log file.
all : Write debug logs to both the encrypted and plaintext log files.
Defaults to encrypted when absent or set to an unrecognized value.
get_current_configboolean(optional) If true, the current configuration settings will be returned in json_out without performing a setup or reconfig.
reset_defaultsboolean(optional) If true, the current configuration settings will be reset to default options before setting the options specified in the "config" object.

Return codes​

CodeDescription
WAAPI_OKOn successful initialization
WAAPI_ERROR_GENERALGeneral error has occurred, query details for more information
WAAPI_ERROR_LICENSE_MISSINGIf the license file is missing
WAAPI_ERROR_LICENSE_MISMATCHIf the license key provided does not match the license key file
WAAPI_ERROR_ALREADY_INITIALIZEDThe OESIS Framework is already initialized
WAAPI_ERROR_DATABASE_MISSINGThe database required for initialization is missing with the deployment
WAAPI_ERROR_DATABASE_CORRUPTEDThe database required for initialization exists, but is corrupted
WAAPI_ERROR_INVALID_JSONThe value passed in for json_config is not valid JSON format.

Remarks​

In order to release all internal structures created by a successful call to this function, you must call wa_api_teardown

wa_api_invoke​

Performs an invocation call to the component.

WAAPI_DECLFUNCTION wa_api_invoke( 
        const wa_wchar *json_in, 
        wa_wchar **json_out
);

The invocation call will be dispatched to the proper component based on the provided json_in parameters. If the component is deployed and licensed, the call will then dispatch the JSON input to the component for processing. If successful, the output results of the invocation will be returned in the json_out parameter. If failure, the error results of the invocation will be returned in the json_out parameter.

Parameters​

NameDirectionDescription
json_in[IN]The invocation input to dispatch to the component. The dispatching and definition of the expected format is defined per method and is included in the json_in.
json_out[OUT]The invocation output results. User can never pass NULL, must pass a valid pointer that can be allocated with content. See how to handle output results for details.

Return codes​

CodeDescription
WAAPI_OKOn success
WAAPI_ERROR_GENERALGeneral error has occurred, query details for more information
WAAPI_ERROR_COMPONENT_NOT_LICENSEDIf the component required to perform selected method call is not licensed for use.
WAAPI_ERROR_COMPONENT_LICENSE_EXPIREDIf the component required to perform selected method call's license has expired.
WAAPI_ERROR_COMPONENT_NOT_DEPLOYEDIf the component required to perform selected method call is licensed, but not deployed.
WAAPI_ERROR_NOT_INITIALIZEDOESIS Framework has not been initialized yet, see wa_api_setup for initialization details.
WAAPI_ERROR_INVALID_JSONThe value passed in for json_in is not valid JSON format.
WAAPI_ERROR_INVALID_INPUT_ARGSThe value passed in for json_in does not match the method description.
WAAPI_ERROR_COMA COM error occurred. Windows only.
WAAPI_ERROR_ACCESS_DENIEDThe access was denied to perform the requested action.

Remarks​

Each method invoked on the component can return additional error codes than mentioned. See each of the methods descriptions for additional information about possible error codes that can be returned by this OESIS Framework call.

The json_out pointer will be allocated by this function. It is the callers responsibility to call wa_api_free on this pointer to release the memory back to the process. If the function returns a failure error code, then the json_out parameter will allocated with memory containing the error information of the invocation, therefore a call to wa_api_free is still necessary.

wa_api_free​

Will release the memory of the pointer allocated by OESIS Framework calls.

WAAPI_DECLFUNCTION wa_api_free( 
        wa_wchar * json_data  
);

wa_api_invoke will allocate memory to the json_out parameters that contain the results of the function calls. It is up to the caller to release the memory allocated during these function calls using this function.

Parameters​

NameDirectionDescription
json_out[IN,OUT]The pointer to the memory that is to be released

Return codes​

CodeDescription
WAAPI_OKAlways

wa_api_teardown​

Deinitializes the OESIS Framework interface and destructs all internal structures created.

WAAPI_DECLFUNCTION wa_api_teardown( 
);

This function must be called to release all internally held memory, handles, etc. Should only be called when your integration is finished using the OESIS Framework.

Return codes​

CodeDescription
WAAPI_OKOn success
WAAPI_ERROR_GENERALGeneral error has occurred, query details for more information
WAAPI_ERROR_NOT_INITIALIZEDA successful call to wa_api_setup was never called

Remarks​

  • Call this function explicitly before your process begins to terminate — for example, just before returning from your entry point (main, or WinMain on Windows) on a clean exit path, or before any explicit process-exit call (exit(), or ExitProcess() on Windows). wa_api_teardown performs the orderly shutdown of the Framework's internal state (including external resources, in-flight operations, and any child processes) while the runtime is still healthy and every dependency is still alive.
  • Call this function from the same thread that called wa_api_setup. Some of the Framework's state is per-thread — thread-local storage, and on Windows the impersonation context and COM apartment — and can only be released safely from the thread that established it. Tearing down from a different thread leaves the original thread's state in place until the process exits.
  • Do not place this call in atexit, a signal handler, an abort() path, DllMain (Windows), or any other code that runs during process termination. By that point the runtime is in a partially torn-down state (on Windows, the operating system additionally holds the loader lock), which is not a safe environment for the cleanup this function performs and can lead to a crash during process shutdown.
  • Once wa_api_teardown returns, the application is free to proceed to exit normally.

wa_api_register_handler​

Register an event handler for the specified event. When the event is triggered the handler will be invoked.

WAAPI_DECLFUNCTION wa_api_register_handler( 
        const wa_wchar* json_event_info, 
        wa_event_handler event_handler,
        wa_int* handler_id
);

An event will be registered based on the provided json_event_info parameters. Each time the event is triggered event_handler will be called. The event can be unregistered by passing handler_id to wa_api_unregister_handler. All events will be unregistered on wa_api_teardown.

Parameters​

NameDirectionDescription
json_event_info[IN]The json formatted input which identifies what event is being registered.
event_handler[IN]A wa_event_handler which is a function pointer that takes a wa_wchar* as its only argument. The argument will be a json formatted string that differs based on the type of event the handler is registered with. The json string must be freed using wa_api_free when finished using it. See the OESIS Framework guide for details on possible return values.
handler_id[OUT]An id for the event. This is used to deregister the event later or to pass to async invoke calls.

The json_event_info parameter supports the following keys:

{
        "event_type" : number,
        "config" : { ... }
}
KeyJSONDescription
event_typenumberPossible values:
0 = Register for callbacks when Async Invoke calls complete. Each Async Invoke call must be passed the handler_id to the wa_api_invoke call's json_in parameter. For an example, see the OESIS Framework guide. Completed async jobs that are passed to event callbacks will not be retrievable by calls to QueryAsyncResults.
1 = Register for a callback when a process is started or stopped on the system.
2 = Register for a callback when a product is installed or uninstalled on the system.
3 = Register for callbacks when a product state changes. This is equivalent to making an Async wa_api_invoke call for a particular product signature and method, except the handler will be called every time the product state changes. Currently the only supported methods are: GetRealTimeProtectionState, GetFirewallState
4 = Register for callbacks when the driver blocks a drive through auto-blocking mode.
5 = Register a memory buffer for callbacks when the driver reads a file through WAAPI_MID_DRIVER_READ_FILE.
9 = Register for a callback when there is a progress change in the method InstallMissingPatches of Windows Update Agent.
(Windows only) 10 = Register for callbacks when a product state changes. This is equivalent to (event_type = 3) except the changes will be monitored and notified at real time without 5 seconds interval call of wa_api_invoke. The supported signatures and methods can be found in the latest support chart
configobject(optional)The config key is only needed for certain event_type values. The required config objects are detailed below:
event_type = 3: \{"signature": number, "method": number\} Where 'signature' is the product signature and 'method' is the method id for the call to monitor.
event_type = 5: \{"buffer": string, "size": number\} Where 'buffer' is the textual representation of the numeric pointer address of the pre-allocated memory buffer (i.e. pointer address as a stringified integer), and 'size' is the size of the user-allocated memory buffer (passed under 'buffer' key), in bytes.

Return codes​

CodeDescription
WAAPI_OKOn success
WAAPI_ERROR_GENERALGeneral error has occurred, query details for more information
WAAPI_ERROR_NOT_INITIALIZEDOESIS Framework has not been initialized yet, see wa_api_setup for initialization details.
WAAPI_ERROR_INVALID_JSONThe value passed in for json_event_info is not valid JSON format.
WAAPI_ERROR_INVALID_INPUT_ARGSThe value passed in for json_event_info does not contain required keys or is invalid.
WAAPI_ERROR_ACCESS_DENIEDThe access was denied to perform the requested action.

Remarks​

See the OESIS Framework guide for details on handling events.

wa_api_unregister_handler​

Unregisters an event handler.

WAAPI_DECLFUNCTION wa_api_unregister_handler( 
        const wa_int handler_id
);

The event is unregistered by using the handler_id that was returned from the wa_api_register_handler call.

Parameters​

NameDirectionDescription
handler_id[IN]The event handler id for the event to remove.

Return codes​

CodeDescription
WAAPI_OKOn success
WAAPI_ERROR_GENERALGeneral error has occurred, query details for more information
WAAPI_ERROR_NOT_INITIALIZEDOESIS Framework has not been initialized yet, see wa_api_setup for initialization details.
WAAPI_ERROR_INVALID_JSONThe value passed in for json_event_info is not valid JSON format.
WAAPI_ERROR_INVALID_INPUT_ARGSThe value passed in for json_event_info does not contain required keys or is invalid.
WAAPI_ERROR_ACCESS_DENIEDThe access was denied to perform the requested action.

Data types​

We only use primitive integer and character data types in all function calls. The complexity of function calls is handled by the JSON formatted input/output character streams.

Defines the integer data type used in function calls.

typedef __int32 wa_int;

Defines the character data type used in function calls.

typedef wchar_t wa_wchar;

Defines the event function pointer data type used in function calls.

typedef void (*wa_event_handler)( wa_wchar * json_event );

Configurations​

We have allowed the ability to configure the internal workings of the OESIS Framework to best fit your integration needs. We have assigned the default values for a reason, however, you may change these via the wa_api_setup function call.

For example, in order to enable pretty-printing of JSON output, you would pass the following JSON formatted character pointer to wa_api_setup for the json_config parameter.

{
     "config" :
     {
         "enable_pretty_print" : true
     }
}

The following are the available configuration keys for the API:

Pretty Print JSON

Configuration key for enabling/disabling pretty printing of JSON output returned in json_out from wa_api_invoke invocations

Type: boolean

Default: false

#define WAAPI_CONFIG_PRETTY_PRINT L"enable_pretty_print"

Component Object Model (COM) Concurrency Model

DEPRECATED

This configuration option is deprecated and may be removed in a future release.

Configuration key for enabling/disabling COM concurrency model. Windows only.

Type: boolean

Default: true

#define WAAPI_CONFIG_COM_MULTITHREADED L"com_multithreaded_model"

Database Location

Configuration key to set the location of the database. Allows you to specify the location of the database in your deployment. This is the location where your offline resources (libwaresource.dll) will be located. This may be a relative path from the location of the OESIS Framework deployment, but must begin with '.' to represent the working directory. By default, the database will be read from the directory of your OESIS Framework deployment.

Type: string

Default: deployment directory

#define WAAPI_CONFIG_DATABASE_LOCATION L"database_location"

Component Location

Configuration key to set the location of component libraries. This is the location where the OESIS Framework will look when trying to load external OESIS Framework modules, such as Manageabilty or Removal. This may be a relative path from the location of the OESIS Framework deployment, but must begin with '.' to represent the working directory. By default, the location will be the directory of your OESIS Framework deployment.

Type: string

Default: deployment directory

#define WAAPI_CONFIG_COMPONENT_LOCATION L"component_location"

Online Mode

OBSOLETE

This configuration option is obsolete and should no longer be used.

Configuration key for enabling/disabling on-line mode. If disabled, the database files must be created and deployed with the libraries.

Type: boolean

Default: false

#define WAAPI_CONFIG_ONLINE_MODE L"online_mode"

Silent Mode

Configuration key for enabling/disabling silent mode. If enabled, the client will not talk to V4 servers.

Type: boolean

Default: false

#define WAAPI_CONFIG_SILENT_MODE L"silent_mode"

Server Timeout

Configuration key for setting the HTTP timeout

Type: number

Default: 30

#define WAAPI_CONFIG_SERVER_TIMEOUT L"server_timeout"

Caching

Configuration key for enabling/disabling caching to disk for dynamically updated runtime data. NOTE: There are potential performance implications if caching is disabled, especially if using online mode.

Type: boolean

Default: true

#define WAAPI_CONFIG_CACHING L"caching"

Cache Location

Configuration key for setting the write location for the cache files. This location must have appropriate write permissions for the caller. This may be a relative path from the location of the OESIS Framework deployment, but must begin with '.' to represent the working directory. By default, the database will be read from the directory of your OESIS Framework deployment.

Type: string

Default: deployment directory

#define WAAPI_CONFIG_CACHE_LOCATION L"cache_location"

License Update

Configuration key for enabling/disabling updating the license.

Type: boolean

Default: false

#define WAAPI_CONFIG_LICENSE_UPDATE L"license_update"

License Location

Configuration key for setting the location of the license. This may be a relative path from the location of the OESIS Framework deployment, but must begin with '.' to represent the working directory.

Type: string

Default: deployment directory

#define WAAPI_CONFIG_LICENSE_LOCATION L"license_location"

URI Prefix

OBSOLETE

This configuration option is obsolete and should no longer be used.

Configuration key for URI prefix. This is used for configuring access to resources when using online mode.

Type: string

Default: api

#define WAAPI_CONFIG_URI_PREFIX L"uri_prefix"

License Key Bytes

Configuration key for license key byte string. Can be used in place of the key portion of the license.cfg file. This equates to the value found at 'license_key' in the license.cfg json.

Type: string

Default:

#define WAAPI_CONFIG_LICENSE_KEY_BYTES L"license_key_bytes"

License Bytes

Configuration key for license byte string. Can be used in place of the license portion of the license.cfg file. This equates to the value found at 'license' in the license.cfg json. If this option is used then automatic license updating is not supported and WAAPI_CONFIG_LICENSE_KEY_BYTES must be specified.

Type: string

Default:

#define WAAPI_CONFIG_LICENSE_BYTES L"license_bytes"

License Pass-key

Configuration key for the pass key string that was provided with the license file.

Type: string

Default:

#define WAAPI_CONFIG_PASSKEY_KEY L"passkey_string"

Deployment Location

Configuration key for deployment location string. This is the location of libwaapi.dll, libwautils.dll and libwaheap.dll. This parameter cannot be changed, but is available in the setup output as a convenience.

Type: string

Default: deployment directory

#define WAAPI_CONFIG_DEPLOYMENT_LOCATION L"deployment_location"

Secure Cache

Configuration key for enabling/disabling secure-cache mode. If disabled, signatures of the database files will not be checked by OESIS Framework.

Type: boolean

Default: false

#define WAAPI_CONFIG_SECURE_CACHE L"secure_cache"

Service Mode

Configuration key for enabling/disabling service mode. If the integrating application is running in a service context then this option should be enabled.

Type: boolean

Default: false

#define WAAPI_CONFIG_SERVICE_MODE L"service_mode"

Proxy Type

Configuration key for selecting web proxy type. Possible values are: 'NoProxy', 'ProxyNamed', 'ProxyReg', 'ProxyIE', 'ProxyAutoDiscover'. NoProxy: access internet directly. ProxyNamed: access internet through proxy specified by proxy name and proxy port. ProxyReg: access internet by detecting proxy settings in registry path HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\Connections. ProxyIE: access internet with proxy settings from Internet Explorer. ProxyAutoDiscover: access internet by detecting proxy settings automatically by DHCP or DNS.

Type: string

Default: ProxyReg

#define WAAPI_CONFIG_PROXY_TYPE L"proxy_type"

Proxy Name

Configuration key for http proxy name/ip address.

Type: string

Default:

#define WAAPI_CONFIG_PROXY_NAME L"proxy_name"

Secure Protocol

Configuration key for VMod's online secure protocols. Possible values are: 'SECURE_PROTOCOL_TLS1', 'SECURE_PROTOCOL_TLS1_1', 'SECURE_PROTOCOL_TLS1_2', 'SECURE_PROTOCOL_TLS1_3'. SECURE_PROTOCOL_TLS1: use TLS v1.0 or later. SECURE_PROTOCOL_TLS1_1: use TLS v1.1 or later. SECURE_PROTOCOL_TLS1_2: use TLS v1.2 or later. SECURE_PROTOCOL_TLS1_3: use TLS v1.3 or later.

Type: string

Default:

#define WA_VMOD_CONFIG_OPTION_SECURE_PROTOCOL L"secure_protocol"

Online Custom Header

Configuration key for VMod's online custom header for url

Type: object

Default: WAAPI_JSON_OBJECT

#define WA_VMOD_CONFIG_ONLINE_CUSTOM_HEADER L"online_custom_header"

Proxy Port

Configuration key for http proxy port.

Type: number

Default: 0

#define WAAPI_CONFIG_PROXY_PORT L"proxy_port"

Proxy Auto Logon Policy

Configuration key for http proxy auto logon policy. Possible values are: 'low', 'medium' and 'high'. low: An authenticated log on using the default credentials is performed for all requests. medium: An authenticated log on using the default credentials is performed only for requests on the local Intranet. high: Default credentials are not used.

Type: string

Default: medium

#define WAAPI_CONFIG_PROXY_AUTOLOGON_POLICY L"proxy_autologon_policy"

Mockup Mode API

Configuration key for enabling mockup mode. This will allow API invoke calls to be made where the output results are hardcoded to return specific values. This requires the mockup.json file to be present in the waapi deployment directory.

Type: boolean

Default: false

#define WAAPI_CONFIG_MOCKUP_MODE L"mockup_mode"

Metadefender API Key

Configuration key for Infection Module. This will apply a Metadefender API key and use this key for scanning.

Type: string

Default:

#define WAAPI_CONFIG_CUSTOM_METASCAN_ONLINE_KEY L"custom_metascan_online_key"

Metadefender Target Server Address

Configuration key for Infection Module. This key specifies a local Metadefender server address with port. Correct format is 'server:port'.

Type: string

Default:

#define WAAPI_CONFIG_TARGET_METASCAN_SERVER L"target_metascan_server"

Metadefender Included Engines

Configuration key for Infection Module. This key specifies which Metadefender engines are to be used for scanning.

Type: string

Default:

#define WAAPI_CONFIG_METASCAN_ENGINES_INCLUDED L"metascan_engines_included"

Metadefender Excluded Engines

Configuration key for Infection Module. This key specifies which Metadefender engines are to be excluded from scanning.

Type: string

Default:

#define WAAPI_CONFIG_METASCAN_ENGINES_EXCLUDED L"metascan_engines_excluded"

Metadefender Included Sources

Configuration key for Infection Module. This key specifies which Metadefender sources are to be used for scanning.

Type: string

Default:

#define WAAPI_CONFIG_METASCAN_SOURCES_INCLUDED L"metascan_sources_included"

Metadefender Excluded Sources

Configuration key for Infection Module. This key specifies which Metadefender sources are to be excluded from scanning.

Type: string

Default:

#define WAAPI_CONFIG_METASCAN_SOURCES_EXCLUDED L"metascan_sources_excluded"

Metadefender Maximum File Size (in Megabytes)

Configuration key for Infection Module. Maximum file size that's permitted to be hashed.

Type: number

Default: 140

#define WAAPI_CONFIG_INFECTION_MAX_FILE_SIZE_HASHED_MB L"infection_max_file_size_hashed_mb"

Infection Maximum Chunk Size (in Kilobytes)

Configuration key for Infection Module. Configures maximum file chunk size permitted to upload to Metadefender.

Type: number

Default: 512

#define WAAPI_CONFIG_INFECTION_MAX_CHUNK_SIZE_KB L"infection_max_chunk_size_kb"

Refresh Infection Database

Configuration key for Infection Module. Signals whether the cache should be cleaned or not.

Type: boolean

Default: false

#define WAAPI_CONFIG_REFRESH_INFECTION_DATABASE L"refresh_infection_database"

Infection Batch Size

Configuration key for Infection Module. Defines how many items (file names or addresses) will be stored in memory for queued scanning operations.Minimum Batch Size: 10Maximum Batch Size: 1000

Type: number

Default: 100

#define WAAPI_CONFIG_INFECTION_BATCH_SIZE L"infection_batch_size"

Asyncronous API Mode

Configuration key for the asynchronous API. Possible values are: 0 (completely disabled), 1 (fully enabled), 2 (mixed mode). If disabled then 'async_job' keys on invoke calls will be ignored. If fully enabled then all calls will be made asynchronosly, regardless of 'async_job' key status. Partially enabled will allow calls to be made either synchronously or asynchronosly based on the 'async_job' invoke flag. Calls without the 'async_job' flag will automatically be synchronous in mixed mode.

Type: number

Default: 2

#define WAAPI_CONFIG_ASYNC_API_MODE L"async_api_mode"

JSON IO Validation

Configuration key for json IO type validation. If true, all required input and output json keys will be checked for existence and type correctness. Will add computation overhead on every call and is not recommended for production.

Type: boolean

Default: false

#define WAAPI_CONFIG_JSON_IO_VALIDATION L"json_io_validation"

JSON OUTPUT Skip Minor Error Message

Configuration key for filtering json_out error data. If true, all error message inside json_out will be filtered out in case the returned code by wa_api_invoke is a success code. Will add computation overhead on every call and is not recommended for production.

Type: boolean

Default: false

#define WAAPI_CONFIG_SKIP_MINOR_ERROR_MESSAGE L"skip_minor_error_message"

Low Resource Setup

Configuration key for specifying that setup should try to use less CPU and system resources during initialization. This has potentially significant impacts on setup performance and can add many seconds to the overall setup time.

Type: boolean

Default: false

#define WAAPI_CONFIG_LOW_RESOURCE_SETUP L"low_resource_setup"

Restrict Bundle Search

(Mac only) This configuration key defines folders to be excluded from the application bundle search. You can specify one or more values, separated by a vertical bar (|). Valid predefined options include: user_home, shared_folder, removable_media, desktop, documents, downloads, reminders, photos, calendars, contacts, and music. Custom paths are also supported (e.g., user_home|shared_folder|/Users/test/restricted). Additionally, the special value all_predefined_values can be used to exclude all predefined folders. When this value is used, no other predefined values should be listed, though custom paths are still allowed. The all_predefined_values option also supports an optional :except: clause to exclude specific predefined folders from the exclusion list (e.g., all_predefined_values:except:user_home,photos). This value is future-proof, any new simple predefined folders introduced later will automatically be covered by all_predefined_values without requiring an engine update. This restriction always takes precedence over per-user application-bundle detection: if user_home (or all_predefined_values) is excluded, no account's home directory is scanned for bundles, whether detection is run for a single active user or, via the detect_all_users_products flag on DetectProducts, for every local user; the exclusion is never silently overridden by the broader request.

Type: string

Default:

#define WAAPI_CONFIG_RESTRICT_BUNDLE_SEARCH L"restrict_bundle_search"

VMod Online Database Prefix URI

Configuration key for specifying prefix to VMod's online database to support online mode for some functions. It only supports HTTP/HTTPs.

Type: string

Default:

#define WA_VMOD_CONFIG_ONLINE_DATABASE_URI L"online_database_uri"

Proxy Password

Configuration key for web proxy password.

Type: string

Default:

#define WA_VMOD_CONFIG_PROXY_PASSWORD L"vmod_proxy_password"

Proxy Username

Configuration key for web proxy username. To use proxy with differnt domain name than the current domain. The input string to the method must uses double backslashes like 'domain\user' so it becomes quadruple backslashes in a json string

Type: string

Default:

#define WA_VMOD_CONFIG_PROXY_USER L"vmod_proxy_username"

Support Next-gen Tool

OBSOLETE

This configuration option is obsolete and should no longer be used.

Configuration key for generating and packaging libwaresource that include some desired database used for OESIS Framework Next-gen Tool.

Type: boolean

Default: false

#define WAAPI_CONFIG_SUPPORT_NEXTGEN_TOOL L"support_nextgen_tool"

Console Debug

Configuration key for enable/disable print debug stuff to console.

Type: boolean

Default: false

#define WAAPI_CONFIG_CONSOLE_DEBUG L"console_debug"

Online Miss Expired Time

Configuration key for VMod's online miss expired time in seconds.

Type: number

Default: 43200

#define WA_VMOD_CONFIG_ONLINE_MISS_EXPIRED_TIME L"online_miss_expired_time"

Online Hit Expired Time

Configuration key for VMod's online hit expired time in seconds.

Type: number

Default: 86400

#define WA_VMOD_CONFIG_ONLINE_HIT_EXPIRED_TIME L"online_hit_expired_time"

Objects Per Memory Pool

Configuration key to set the amount of fixed-size objects that each memory pool can allocate. Possible values are in [0-1000000]. Zero means to disable memory pool feature

Type: number

Default: 1000000

#define WAAPI_CONFIG_OBJECTS_PER_MEMORY_POOL L"objects_per_memory_pool"

Encryption API

(Windows only) Configuration key to set encryption api for using. Possible values are: 'CNG', 'CryptoAPI'. CNG: use Windows Cryptography API: Next Generation. CryptoAPI: use Windows Cryptography API. If this key is not set, the default value is 'CNG'

Type: string

Default: CNG

#define WAAPI_CONFIG_ENCRYPTION_API L"encryption_api"

Mobile devices protection

(Windows only) Configuration key to enable feature for allow/deny access to mobile devices (android, iOS).

Type: boolean

Default: false

#define WAAPI_CONFIG_DRIVER_ENABLE_MOBILE L"enable_mobile"

Apple drivers protection

(Windows only) Configuration key to enable feature for allow/deny syncing data with Apple devices (iPhone, iPad) via iTunes. This configuration only takes effect while 'enable_mobile' is 'true'.

Type: boolean

Default: false

#define WAAPI_CONFIG_DRIVER_ENABLE_APPLE_USB_DEVICES L"enable_apple_usb_devices"

Support set-GID protection

(Unix only) Configuration key to enable set‑GID protected execution for CLI processes spawned by the framework. Default value is false.

Type: boolean

Default: false

#define WAAPI_CONFIG_SUPPORT_SET_GID_PROTECTION L"support_set_gid_protection"

Enable WaHost

(Mac only) Configuration key to enable/disable the WaHost feature. When WaHost enabled, most of the OESIS Framework feature will be performed by WaHost. waapi will act as a client, it will forward the request from customer process to WaHost and return the result back to customer process.

Type: boolean

Default: false

#define WAAPI_CONFIG_ENABLE_WA_HOST L"enable_wa_host"

WaHost deploy path

(Mac only) Configuration Key for WaHost Deployment Location. This configuration key allows you to specify the deployment location for WaHost.

Type: string

Default: $HOME/Library/Application Support/$process_name/

#define WAAPI_CONFIG_WA_HOST_PATH L"wa_host_path"

Skip OS Check

Configuration key for disabling OS version checks. When enabled, allows SDK to run on unsupported OS versions and beta OS releases. Note that functionality is not guaranteed when running on unsupported operating systems.

Type: boolean

Default: false

#define WAAPI_CONFIG_SKIP_OS_CHECK L"skip_os_check"

Connectivity Check

Configuration key to configure connectivity check. This check will use HTTP GET requests over HTTP/HTTPS protocol to verify connectivity to specified endpoints. The check is performed by sending HTTP GET requests and evaluating the response to determine network availability.

Type: object

Default: {}

#define WAAPI_CONFIG_CONNECTIVITY_CHECK L"connectivity_check"

Connectivity Check Global URLs

When this option is set, the SDK will perform connectivity checks only against the specified endpoints instead of using default public URLs. Each endpoint should be specified as a full URL (e.g., "https://example.com:443"). If the port is not provided in the URL, the default port 80 will be used. This helps customers control network behavior, comply with internal security policies, and avoid unnecessary external requests.

Type: array

Default: ["https://www.google.com"]

#define WAAPI_CONFIG_GLOBAL_URLS L"connectivity_check.global_urls"

Product categories​

Classification of products can be used for detection and to determine functionality supported by a given product. A single product can encompass many product categories. The category "all" refers to all detectable products.

Available product categories:

All

Defines common product classification. This classification includes all product categories

#define WAAPI_CATEGORY_ALL 0

Public File Sharing

Defines public file sharing product classification

#define WAAPI_CATEGORY_PUBLIC_FILE_SHARING 1

Backup

Defines backup client product classification

#define WAAPI_CATEGORY_BACKUP_CLIENT 2

Encryption

Defines disk encryption product classification

#define WAAPI_CATEGORY_DISK_ENCRYPTION 3

Antiphishing

Defines antiphishing product classification

#define WAAPI_CATEGORY_ANTIPHISHING 4

Antimalware

Defines antimalware product classification

#define WAAPI_CATEGORY_ANTIMALWARE 5

Browser

Defines browser product classification

#define WAAPI_CATEGORY_BROWSER 6

Firewall

Defines firewall product classification

#define WAAPI_CATEGORY_FIREWALL 7

Messenger

Defines instant messenger product classification

#define WAAPI_CATEGORY_INSTANT_MESSENGER 8

Cloud Storage

Defines cloud storage product classification

#define WAAPI_CATEGORY_CLOUD_STORAGE 9

Data Loss Prevention

Defines data loss prevention product classification

#define WAAPI_CATEGORY_DATA_LOSS_PREVENTION 11

Patch Management

Defines patch management product classification

#define WAAPI_CATEGORY_PATCH_MANAGEMENT 12

VPN Client

Defines VPN client product classification

#define WAAPI_CATEGORY_VPN_CLIENT 13

Virtual Machine

Defines Virtual Machine product classification

#define WAAPI_CATEGORY_VIRTUAL_MACHINE 14

Health Agent

Defines health agent product classification

#define WAAPI_CATEGORY_HEALTH_AGENT 15

Remote Desktop Control

Defines remote desktop control classification

#define WAAPI_CATEGORY_REMOTE_CONTROL 16

P2P Agent

Defines a peer to peer application classification

#define WAAPI_CATEGORY_PEER_TO_PEER 17

Web Conference

Defines that the product has an online video and audio conferencing classification

#define WAAPI_CATEGORY_WEB_CONFERENCE 18

Gaming

Defines gaming product classification

#define WAAPI_CATEGORY_GAMING 19

Vulnerability Management

Defines vulnerability management classification

#define WAAPI_CATEGORY_VULNERABILITY_MANAGEMENT 20

AI Software

Defines a AI Software classification

#define WAAPI_CATEGORY_AI_SOFTWARE 21

System Diagnostic and Cleanup

Defines a system diagnostic and cleanup product classification

#define WAAPI_CATEGORY_SYSTEM_DIAGNOSTIC_AND_CLEANUP 22

EDR/XDR

Defines EDR/XDR product classification

#define WAAPI_CATEGORY_EDR_XDR 23

Unclassified

Defines that the product does not have an official classification

#define WAAPI_CATEGORY_UNCLASSIFIED 10