Basic Reputation Change Callback Example

This sample demonstrates registering a dxltieclient.callbacks.ReputationChangeCallback with the DXL fabric to receive reputation change events sent by the McAfee Threat Intelligence Exchange (TIE) DXL service when the reputation of a file or certificate changes.

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_reputation_change_callback_example.py script as follows:

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

The output should appear similar to the following:

Waiting for reputation change events...

At this point the sample is listening for both file and certificate reputation events from the DXL fabric.

Force Reputation Change

The next step is to force a reputation change for a file or certificate via ePO. The steps to accomplish this are listed below:

• Open ePO and navigate to the "TIE Reputations" page.
• Select the "File Search" or "Certificate Search" tab
• Select a file or certificate in the list
• Click the "Actions" button at the bottom left and select a new "Enterprise" reputation (for example, Known Trusted)
  • NOTE: It is safest to select a file (or certificate) that has a "GTI" Reputation of Known Trusted and simply set the "Enterprise" reputation to be the same (Known Trusted).
• Remove the override by clicking on the "Actions" button again and selecting "Remove Override"

Reputation Change Output

After the reputation change has occurred the reputation change information should appear within the console that the sample is running (similar to the output below):

Reputation change on topic: /mcafee/event/tie/file/repchange/broadcast
{
    "hashes": {
        "md5": "f2c7bb8acc97f92e987a2d4087d01221",
        "sha1": "7eb0139d2175739b3ccb0d1110067820be6abd2b"
    },
    "newReputations": {
        "1": {
            "attributes": {
                "2120340": "0"
            },
            "createDate": 1480551590,
            "providerId": 1,
            "trustLevel": 0
        },
        "3": {
            "attributes": {
                "2101652": "0",
                "2102165": "1480551374",
                "2111893": "244",
                "2114965": "1",
                "2139285": "73183493944770750"
            },
            "createDate": 1480551374,
            "providerId": 3,
            "trustLevel": 99
        }
    },
    "oldReputations": {
        "1": {
            "attributes": {
                "2120340": "0"
            },
            "createDate": 1480551590,
            "providerId": 1,
            "trustLevel": 0
        },
        "3": {
            "attributes": {
                "2101652": "0",
                "2102165": "1480551374",
                "2111893": "244",
                "2114965": "1",
                "2139285": "73183493944770750"
            },
            "createDate": 1480551374,
            "providerId": 3,
            "trustLevel": 0
        }
    },
    "updateTime": 1481222923
}

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

The reputation change information is separated into 4 distinct sections:

Hash values

A dict (dictionary) of hashes that identify the file or certificate whose reputation has changed.

New reputations

The new Reputations for the file or certificate whose reputation has changed as a Python dict (dictionary).

Old reputations

The previous Reputations for the file or certificate whose reputation has changed as a Python dict (dictionary).

Change time

The time the reputation change occurred.

Details

The majority of the sample code is shown below:

class MyReputationChangeCallback(ReputationChangeCallback):
    """
    My reputation change callback
    """
    def on_reputation_change(self, rep_change_dict, original_event):
        # Display the DXL topic that the event was received on
        print("Reputation change on topic: " + original_event.destination_topic)

        # Dump the dictionary
        print(MessageUtils.dict_to_json(rep_change_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 reputation change callback
    rep_change_callback = MyReputationChangeCallback()

    # Register callbacks with client to receive both file and certificate reputation change events
    tie_client.add_file_reputation_change_callback(rep_change_callback)
    tie_client.add_certificate_reputation_change_callback(rep_change_callback)

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

A derived class from dxltieclient.callbacks.ReputationChangeCallback is defined which overrides the dxltieclient.callbacks.ReputationChangeCallback.on_reputation_change() method to handle reputation change events. When a reputation change event occurs this method will display the topic that the event was received on and dump the reputation change 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 both the dxltieclient.client.TieClient.add_file_reputation_change_callback() and dxltieclient.client.TieClient.add_certificate_reputation_change_callback() methods to receive file and certificate reputation change events.