Real-Time Monitoring (RTM)

Beta

The Real-time Monitoring feature is currently in Beta. Expect potential changes or improvements in future versions.

Supported platforms: Windows, macOS

Background

We recognize that traditional periodic compliance checks may pose challenges in ensuring timely adherence across all endpoints. To address this, the Real-time Monitoring feature has been introduced as an alternative to scheduled checks. This feature enables proactive tracking of changes at endpoints without relying on periodic scans.

Goal

• Implement a proactive mechanism for detecting and capturing device state changes in real-time.
• Reduce the reliance on periodic checks, reducing potential vulnerabilities that attackers could exploit.

Scope

Real-time Monitoring supports monitoring of specific Windows events of the OS, and of applications listed in the Support Chart version 3. For more details, you can access this documentation.

Usage

1. Verify Real-Time Monitoring Support for a Method

Before proceeding, confirm whether a specific method supports Real-Time Monitoring by referring to Support Chart version 3.

For example, when reviewing Support Chart version 3 for ANTIMALWARE products, you may find that Windows Defender (Signature ID: 477) supports Real-Time Monitoring through the GetRealTimeProtectionState method (Method ID: 1000).

2. Enable Real-Time Monitoring

To activate the Real-Time Monitoring feature, register for tracking real-time changes in a specific method's state using wa_api_register_handler, with event_type set to 10.

The following code snippet demonstrates how to monitor the GetRealTimeProtectionState method of Windows Defender in real-time:

#include <iostream>
#include <string>

// Callback function to handle method state change events
void OnRTMEventReceived(wa_wchar* json_event)
{
    std::wcout << L"[Callback] GetRealTimeProtectionState state change event received: " << json_event << std::endl;

    // TODO: Parse and process the json_event string as needed
    
    // Example of json_event content:
    // {
    //   "result": {
    //     "code": 0,
    //     "details": {
    //       "antispyware": false,
    //       "antivirus": false
    //     },
    //     "enabled": false,
    //     "method": 1000,
    //     "signature": 477,
    //     "timestamp": "1742553608",
    //     "timing": 7718
    //   }
    // }
    
    // Important: You own the memory of json_event, so free it after use
    wa_api_free(json_event);
}

int main()
{
    // Step 0: Setup SDK (via wa_api_setup)
    // ...
    
    // Step 1: Define handler configuration
    std::wstring json_in = LR"JSON(
    {
        "event_type": 10,
        "config": {
            "signature": 477,
            "method": 1000
        }
    }
    )JSON";

    // Step 2: Register handler
    wa_int handlerId = 0;
    auto returnCode = wa_api_register_handler(json_in.c_str(), OnRTMEventReceived, handlerId);
    
    if (WAAPI_SUCCESS(rc))
    {
        std::wcout << L"Handler registered successfully. Handler ID: " << handlerId << std::endl;
    }
    else
    {
        std::wcout << L"Failed to register handler. Error code: " << returnCode << std::endl;
        return 1;
    }

    // ... other application logic ...

    // When application about to end: Deinitilized SDK by call wa_api_teardown
    // ...  
    
    return 0;
}

Remarks

Examples of json_in with different options:

Basic Example — Monitor method 1000 of signature 477:

{
  "event_type": 10,
  "config": {
    "signature": 477,
    "method": 1000
  }
}

Skip Connection Check — Same as above, but skip checking connection status before monitoring:

{
  "event_type": 10,
  "config": {
    "signature": 477,
    "method": 1000,
    "skip_connection_check": true
  }
}

Different Method and Signature — Monitor method 1007 of signature 288:

{
  "event_type": 10,
  "config": {
    "signature": 288,
    "method": 1007
  }
}

3. Unregister When No Longer Needed

To stop monitoring the method, call:

wa_api_unregister_handler(handler_id);