Basic First Instance Callback Example

This sample demonstrates registering a dxltieclient.callbacks.FirstInstanceCallback with the DXL fabric. The callback will receive first instance events when files are encountered for the first time within the local enterprise.

Prerequisites

• The samples configuration step has been completed (see Samples Configuration)
• A McAfee Threat Intelligence Exchange (TIE) Service is available on the DXL fabric

Running

To run this sample execute the sample/basic/basic_first_instance_callback.py script as follows:

c:\dxltieclient-python-sdk-0.3.0>python sample/basic/basic_first_instance_callback.py

The output should appear similar to the following:

Waiting for first instance events...

At this point the sample is listening for first instance events from the DXL fabric.

Execute New File

Execute a file that has not been previously seen within the local enterprise.

Detection Output

After the file has executed the first instance information should appear within the console that the sample is running (similar to the output below):

First instance on topic: /mcafee/event/tie/file/firstinstance
{
    "agentGuid": "{68125cd6-a5d8-11e6-348e-000c29663178}",
    "hashes": {
        "md5": "31dbe8cc443d2ca7fd236ac00a52fb17",
        "sha1": "2d6ca45061b7972312e00e5933fdff95bb90b61b",
        "sha256": "aa3c461d4c21a392e372d0d6ca4ceb1e4d88098d587659454eaf4d93c661880f"
    },
    "name": "MORPH.EXE"
}

The first line displays the DXL topic that the event was received on. In this particular case it is, "/mcafee/event/tie/file/firstinstance", which indicates that this is a file first instance event.

The following information is included in the first instance dict (dictionary):

• System the first instance of the file was found on
• File information (file name and associated hashes)

Details

The majority of the sample code is shown below:

class MyFirstInstanceCallback(FirstInstanceCallback):
    """
    My first instance callback
    """
    def on_first_instance(self, first_instance_dict, original_event):
        # Display the DXL topic that the event was received on
        print("First instance on topic: " + original_event.destination_topic)

        # Dump the dictionary
        print(MessageUtils.dict_to_json(first_instance_dict, True))

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

    # Connect to the fabric
    client.connect()

    # Create the McAfee Threat Intelligence Exchange (TIE) client
    tie_client = TieClient(client)

    # Create first instance callback
    first_instance_callback = MyFirstInstanceCallback()

    # Register first instance callback with the client
    tie_client.add_file_first_instance_callback(first_instance_callback)

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

A derived class from dxltieclient.callbacks.FirstInstanceCallback is defined which overrides the dxltieclient.callbacks.FirstInstanceCallback.on_first_instance() method to handle first instance events. When a new file is encountered within the local enterprise this method will display the topic that the event was received on and dump the first instance details.

Once a connection is established to the DXL fabric, a dxltieclient.client.TieClient instance is created.

An instance of the derived callback is constructed and registered with the dxltieclient.client.TieClient.add_file_first_instance_callback() method to receive file first instance events.