Basic First Instance Callback Example

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

The majority of the sample code is shown below:

Sample Code

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 FirstInstanceCallback is defined which overrides the 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 TieClient instance is created.

An instance of the derived callback is constructed and registered with the add_file_first_instance_callback method to receive file first instance events.

Output

When a first instance event is received the output should appear similar to the following:

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)