Basic Threat Event Callback Example

This sample demonstrates registering a CommonThreatEventCallback with the DXL fabric to receive threat events sent by any product.

The majority of the sample code is shown below:

Sample Code

class MyThreatEventCallback(CommonThreatEventCallback):
    """
    My threat event callback
    """
    def on_threat_event(self, threat_event_dict, original_event):
        # Display the DXL topic that the event was received on
        print "Threat event on topic: " + original_event.destination_topic

        # Dump the dictionary
        print json.dumps(threat_event_dict, 
            sort_keys=True, indent=4, separators=(',', ': '))

# Create the client
with DxlClient(config) as client:

    # Connect to the fabric
    client.connect()

    # Create the Common Threat Event client
    threat_event_client = CommonThreatEventClient(client)

    # Create threat event change callback
    threat_event_callback = MyThreatEventCallback()

    # Register callbacks with client to receive threat events
    threat_event_client.add_threat_event_callback(threat_event_callback)

    # Wait forever
    print "Waiting for threat events..."
    while True:
        time.sleep(60)

A derived class from CommonThreatEventCallback is defined which overrides the on_threat_event method to handle threat events. When a threat event occurs this method will display the topic that the event was received on and dump the threat event details.

Once a connection is established to the DXL fabric, a CommonThreatEventClient instance is created.

An instance of the derived callback is constructed and registered with the add_threat_event_callback method to receive threat events.

Output

When a reputation change event is received the output should appear similar to the following:

Threat event on topic: /mcafee/event/epo/threat/response
{
    "event": {
        "analyzer": {
            "contentVersion": "",
            "detectedUTC": "2016-12-13T22:18:34.000Z",
            "detectionMethod": "Exploit Prevention",
            "engineVersion": "",
            "hostName": "SAMPLE-HOSTNAME",
            "id": "ENDP_AM_1020",
            "ipv4": "10.0.0.10",
            "ipv6": "0:0:0:0:0:FFFF:0A00:0010",
            "mac": "001122334455",
            "name": "McAfee Endpoint Security",
            "version": "10.5.0"
        },
        "category": "Host intrusion buffer overflow",
        "entity": {
            "groupName": null,
            "id": "11111111-2222-3333-4444-555555555555",
            "osPlatform": "Workstation",
            "osType": "Windows 7",
            "ruleName": null,
            "sessionId": null,
            "type": "device"
        },
        "eventDesc": "Buffer Overflow detected and blocked (GBOP)",
        "files": [],
        "id": 18052,
        "otherData": {
            "count": "1",
            "definedAt": "My Organization",
            "responseEventType": "Threat",
            "responseRuleName": "Send Threat Event via DXL",
            "threatSeverityString": "Critical"
        },
        "source": {
            "hostName": "",
            "ipv4": "10.0.0.10",
            "ipv6": "0:0:0:0:0:FFFF:0A00:0010",
            "mac": "",
            "port": null,
            "processName": "",
            "url": "",
            "userName": ""
        },
        "target": {
            "fileName": "C:\\DAC\\IEXPLORE.EXE",
            "hostName": "SAMPLE-HOSTNAME",
            "ipv4": "10.0.0.10",
            "ipv6": "0:0:0:0:0:FFFF:0A00:0010",
            "mac": "",
            "port": 0,
            "processName": "IEXPLORE.EXE",
            "protocol": "",
            "userName": "SAMPLE-HOSTNAME\\Administrator"
        },
        "threatActionTaken": "blocked",
        "threatHandled": 1,
        "threatName": "ExP:Heap",
        "threatSeverity": 2,
        "threatType": "Exploit Prevention",
        "uri": null
    },
    "eventMessageType": "McAfee Common Event",
    "eventMessageVersion": "1.0"
}

The threat event information is separated into several distinct sections:

General Threat Event Information

General information about the threat event, such as the Threat Event message version, and threat event type.

Event Properties

A dict (dictionary) of properties, including sub-members which each contain data about the analyzer, entity, files, source, target, and other data properties, respectively.

Analyzer Properties

A dict (dictionary) of properties pertaining to the analyzer used for the threat event.

Entity Properties

A dict (dictionary) of properties pertaining to the entity identified for the threat event.

Files Properties

A dict (dictionary) of file members pertaining to the files relevant for the threat event. Each file member has a list of file properties.

File members may contain one or more hash properties for the file.

Source Properties

A dict (dictionary) of properties pertaining to the source identified for the threat event.

Target Properties

A dict (dictionary) of properties pertaining to the source identified for the threat event.

Other Data Properties

A dict (dictionary) of properties pertaining to the source identified for the threat event. The data in these properties can be provided by the threat event sender as one or more of the following:

• A single value
  • e.g. "apiName":"send"
• A dict of multiple values of a single property type
  • e.g. "listOfSourceIPV4":"10.0.0.1, 10.0.0.2, 10.0.0.3, 10.0.0.3"
• A set of multiple distinct values of a single property type
  • e.g. "setOfSourceIPV4":"10.0.0.1, 10.0.0.2, 10.0.0.3"
• A count of the distinct values of a single property type
  • e.g. "distinctCountOfSourceHostName":"3"