Getting Started

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

Binaries

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

libwaapi.dll The entry point into MetaDefender Endpoint Security SDK. This is the only one that needs to be loaded by integrating applications.
libwautils.dll Required by libwaapi.dll
libwaheap.dll Required by libwaapi.dll
libwaapi.lib Optional. Stub library to allow for implicit integration.

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

libwalocal.dll Required for method support using the manageability module.
libwadeviceinfo.dll Required for method support using the device info module.
libwaremoval.dll Required for method support using the removal module.
libwavmodapi.dll Required for method support using the vulnerability module.
libwaresource.dll Required for offline deployments.
libwacollector.dll Required for using the diagnostics module.
libwadriver.dll Required for using the system driver module.
libwaadbrowser.dll Required for using the advanced browser module.
libwainfection.dll Required for using the infection module.
libwanetscan.dll Required for using the netscan module.
libwaaddon.dll Required for using the addon methods, which extend the core functionality.
rm.exe Required by libwaremoval.dll.
wa_3rd_party_host_32.exe/wa_3rd_party_host_64.exe Required 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.

Headers

The following are the C header files made available by the MetaDefender Endpoint Security SDK

wa_api.h Only header file that should be explicitly included in integrating applications. Contains function signatures exported by libwaapi.dll, and includes the other header files, making relevent defines and typedefs available.
wa_api_defs.h Defines exporters/importers
wa_api_error_codes.h Defines error codes
wa_api_fnc_ptr.h Defines function pointer helpers
wa_api_data_types.h Defines data types
wa_api_product_categories.h Defines product categories
wa_api_config_options.h Defines configuration options
wa_api_invoke_common.h Defines common methods for products
wa_api_invoke_method.h Defines common methods for products
wa_api_invoke_detect.h Defines detection methods
wa_api_json_keys.h Defines 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 MetaDefender Endpoint Security SDK 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 MDES SDK guide

Parameters

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,
                    ...
            ]
        },
        "get_current_config" : true,
        "reset_defaults" : true
 }
Return codes
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
Return codes
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 MDES SDK 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 MetaDefender Endpoint Security SDK 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
Return codes
wa_api_teardown

Deinitializes the MetaDefender Endpoint Security SDK 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 MDES SDK.

Return codes
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

The json_event_info parameter supports the following keys:

 {
        "event_type" : number,
        "config" : { ... }
 }
Return codes
Remarks
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
Return codes

Data types

We only use primative integer and character data types in all function calls. The complexity of function calls is handled by the JSON formated 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 MDES SDK 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:

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: