dxltieclient.client module¶

class dxltieclient.client.TieClient(dxl_client)¶

Bases: dxlbootstrap.client.Client

This client provides a high level wrapper for communicating with the McAfee Threat Intelligence Exchange (TIE) DXL service.

The purpose of this client is to allow users to access the features of TIE (manage reputations, determine where a file has executed, etc.) without having to focus on lower-level details such as TIE-specific DXL topics and message formats.

Constructor parameters:

Parameters:	dxl_client -- The DXL client to use for communication with the TIE DXL service

add_certificate_reputation_change_callback(rep_change_callback)¶

Registers a dxltieclient.callbacks.ReputationChangeCallback with the client to receive certificate reputation change events.

See the dxltieclient.callbacks.ReputationChangeCallback class documentation for more details.

Param:	rep_change_callback: The `dxltieclient.callbacks.ReputationChangeCallback` instance that will receive certificate reputation change events.

add_file_detection_callback(detection_callback)¶

Registers a dxltieclient.callbacks.DetectionCallback with the client to receive file detection events.

See the dxltieclient.callbacks.DetectionCallback class documentation for more details.

Param:	detection_callback: The `dxltieclient.callbacks.DetectionCallback` instance that will receive file detection events.

add_file_first_instance_callback(first_instance_callback)¶

Registers a dxltieclient.callbacks.FirstInstanceCallback with the client to receive file first instance events.

See the dxltieclient.callbacks.FirstInstanceCallback class documentation for more details.

Param:	first_instance_callback: The `dxltieclient.callbacks.FirstInstanceCallback` instance that will receive file first instance events.

add_file_reputation_change_callback(rep_change_callback)¶

Registers a dxltieclient.callbacks.ReputationChangeCallback with the client to receive file reputation change events.

See the dxltieclient.callbacks.ReputationChangeCallback class documentation for more details.

Param:	rep_change_callback: The `dxltieclient.callbacks.ReputationChangeCallback` instance that will receive file reputation change events.

get_certificate_first_references(sha1, public_key_sha1=None, query_limit=500)¶

Retrieves the set of systems which have referenced the specified certificate (as identified by hashes).

Example Usage

# Get the list of systems that have referenced the certificate
system_list = \
    tie_client.get_certificate_first_references(
        "6EAE26DB8C13182A7947982991B4321732CC3DE2",
        public_key_sha1="3B87A2D6F39770160364B79A152FCC73BAE27ADF")

Systems

The systems that have referenced the certificate are returned as a Python list.

An example list is shown below:

[
    {
        "agentGuid": "{3a6f574a-3e6f-436d-acd4-bcde336b054d}",
        "date": 1475873692
    },
    {
        "agentGuid": "{68125cd6-a5d8-11e6-348e-000c29663178}",
        "date": 1478626172
    }
]

Each entry in the list is a dict (dictionary) containing details about a system that has referenced the certificate. See the dxltieclient.constants.FirstRefProp constants class for details about the information that is available for each system in the dict (dictionary).

Parameters:	sha1 -- The SHA-1 of the certificate public_key_sha1 -- The SHA-1 of the certificate's public key (optional) query_limit -- The maximum number of results to return
Returns:	A `list` containing a `dict` (dictionary) for each system that has referenced the certificate. See the `dxltieclient.constants.FirstRefProp` constants class for details about the information that is available for each system in the `dict` (dictionary).

get_certificate_reputation(sha1, public_key_sha1=None)¶

Retrieves the reputations for the specified certificate (as identified by the SHA-1 of the certificate and optionally the SHA-1 of the certificate's public key)

While the SHA-1 of the certificate is required, passing the optional SHA-1 of the certificate's public key can result in additional reputations being located across the set of certificate reputation providers.

Example Usage

# Determine reputations for certificate (identified by hashes)
reputations_dict = \
    tie_client.get_certificate_reputation(
        "6EAE26DB8C13182A7947982991B4321732CC3DE2",
        public_key_sha1="3B87A2D6F39770160364B79A152FCC73BAE27ADF")

Reputations

The Reputations for the certificate are returned as a Python dict (dictionary).

The key for each entry in the dict (dictionary) corresponds to a particular provider of the associated reputation. The list of certificate reputation providers can be found in the dxltieclient.constants.CertProvider constants class.

An example reputations dict is shown below:
{
    "2": {
        "attributes": {
            "2108821": "92",
            "2109077": "1454912619",
            "2117524": "0",
            "2120596": "0"
        },
        "createDate": 1476318514,
        "providerId": 2,
        "trustLevel": 99
    },
    "4": {
        "attributes": {
            "2109333": "4",
            "2109589": "1476318514",
            "2139285": "73183493944770750"
        },
        "createDate": 1476318514,
        "providerId": 4,
        "trustLevel": 0
    }
}
The "2" key corresponds to a reputation from the "Global Threat Intelligence (GTI)" reputation provider while the "4" key corresponds to a reputation from the "Enterprise" reputation provider.

Each reputation contains a standard set of properties (trust level, creation date, etc.). These properties are listed in the dxltieclient.constants.ReputationProp constants class.

The following example shows how to access the trust level property of the "Enterprise" reputation:
trust_level = reputations_dict[CertProvider.ENTERPRISE][ReputationProp.TRUST_LEVEL]
Each reputation can also contain a provider-specific set of attributes as a Python dict (dictionary). These attributes can be found in the dxltieclient.constants module:

dxltieclient.constants.CertEnterpriseAttrib

Attributes associated with Enterprise reputation provider for certificates

dxltieclient.constants.CertGtiAttrib

Attributes associated with Global Threat Intelligence (GTI) reputation provider for certificates

The following example shows how to access the prevalence attribute from the "Enterprise" reputation:
ent_rep = reputations_dict[CertProvider.ENTERPRISE]
ent_rep_attribs = ent_rep[ReputationProp.ATTRIBUTES]
prevalence = int(ent_rep_attribs[CertEnterpriseAttrib.PREVALENCE])

Parameters:	sha1 -- The SHA-1 of the certificate public_key_sha1 -- The SHA-1 of the certificate's public key (optional)
Returns:	A `dict` (dictionary) where each value is a reputation from a particular reputation provider which is identified by the key. The list of certificate reputation providers can be found in the `dxltieclient.constants.CertProvider` constants class.

get_file_first_references(hashes, query_limit=500)¶

Retrieves the set of systems which have referenced (typically executed) the specified file (as identified by hashes).

Example Usage

# Get the list of systems that have referenced the file
system_list = \
    tie_client.get_file_first_references({
        HashType.MD5: "f2c7bb8acc97f92e987a2d4087d021b1",
        HashType.SHA1: "7eb0139d2175739b3ccb0d1110067820be6abd29",
        HashType.SHA256: "142e1d688ef0568370c37187fd9f2351d7ddeda574f8bfa9b0fa4ef42db85aa2"
    })

Systems

The systems that have referenced the file are returned as a Python list.

An example list is shown below:

[
    {
        "agentGuid": "{3a6f574a-3e6f-436d-acd4-b3de336b054d}",
        "date": 1475873692
    },
    {
        "agentGuid": "{68125cd6-a5d8-11e6-348e-000c29663178}",
        "date": 1478626172
    }
]

Each entry in the list is a dict (dictionary) containing details about a system that has referenced the file. See the dxltieclient.constants.FirstRefProp constants class for details about the information that is available for each system in the dict (dictionary).

Parameters:	hashes -- A `dict` (dictionary) of hashes that identify the file to lookup. The `key` in the dictionary is the hash type and the `value` is the hex representation of the hash value. See the `dxltieclient.constants.HashType` class for the list of hash type constants. query_limit -- The maximum number of results to return
Returns:	A `list` containing a `dict` (dictionary) for each system that has referenced the file. See the `dxltieclient.constants.FirstRefProp` constants class for details about the information that is available for each system in the `dict` (dictionary).

get_file_reputation(hashes)¶

Retrieves the reputations for the specified file (as identified by hashes)

At least one hash value of a particular hash type (MD5, SHA-1, etc.) must be specified. Passing additional hashes increases the likelihood of other reputations being located across the set of file reputation providers.

Example Usage

# Determine reputations for file (identified by hashes)
reputations_dict = \
    tie_client.get_file_reputation({
        HashType.MD5: "f2c7bb8acc97f92e987a2d4087d021b1",
        HashType.SHA1: "7eb0139d2175739b3ccb0d1110067820be6abd29",
        HashType.SHA256: "142e1d688ef0568370c37187fd9f2351d7ddeda574f8bfa9b0fa4ef42db85aa2"
    })

Reputations

The Reputations for the file are returned as a Python dict (dictionary).

The key for each entry in the dict (dictionary) corresponds to a particular provider of the associated reputation. The list of file reputation providers can be found in the dxltieclient.constants.FileProvider constants class.

An example reputations dict is shown below:
{
    "1": {
        "attributes": {
            "2120340": "2139160704"
        },
        "createDate": 1480455704,
        "providerId": 1,
        "trustLevel": 99
    },
    "3": {
        "attributes": {
            "2101652": "52",
            "2102165": "1476902802",
            "2111893": "56",
            "2114965": "1",
            "2139285": "73183493944770750"
        },
        "createDate": 1476902802,
        "providerId": 3,
        "trustLevel": 99
    }
}
The "1" key corresponds to a reputation from the "Global Threat Intelligence (GTI)" reputation provider while the "3" key corresponds to a reputation from the "Enterprise" reputation provider.

Each reputation contains a standard set of properties (trust level, creation date, etc.). These properties are listed in the dxltieclient.constants.ReputationProp constants class.

The following example shows how to access the trust level property of the "Enterprise" reputation:
trust_level = reputations_dict[FileProvider.ENTERPRISE][ReputationProp.TRUST_LEVEL]
Each reputation can also contain a provider-specific set of attributes as a Python dict (dictionary). These attributes can be found in the dxltieclient.constants module:

dxltieclient.constants.FileEnterpriseAttrib

Attributes associated with the Enterprise reputation provider for files

dxltieclient.constants.FileGtiAttrib

Attributes associated with the Global Threat Intelligence (GTI) reputation provider for files

dxltieclient.constants.AtdAttrib

Attributes associated with the Advanced Threat Defense (ATD) reputation provider

The following example shows how to access the prevalence attribute from the "Enterprise" reputation:
ent_rep = reputations_dict[FileProvider.ENTERPRISE]
ent_rep_attribs = ent_rep[ReputationProp.ATTRIBUTES]
prevalence = int(ent_rep_attribs[FileEnterpriseAttrib.PREVALENCE])

Parameters:	hashes -- A `dict` (dictionary) of hashes that identify the file to retrieve the reputations for. The `key` in the dictionary is the hash type and the `value` is the hex representation of the hash value. See the `dxltieclient.constants.HashType` class for the list of hash type constants.
Returns:	A `dict` (dictionary) where each value is a reputation from a particular reputation provider which is identified by the key. The list of file reputation providers can be found in the `dxltieclient.constants.FileProvider` constants class.

remove_certificate_reputation_change_callback(rep_change_callback)¶

Unregisters a dxltieclient.callbacks.ReputationChangeCallback from the client so that it will no longer receive certificate reputation change events.

Param:	rep_change_callback: The `dxltieclient.callbacks.ReputationChangeCallback` instance to unregister.

remove_file_detection_callback(detection_callback)¶

Unregisters a dxltieclient.callbacks.DetectionCallback from the client so that it will no longer receive file detection events.

Param:	detection_callback: The `dxltieclient.callbacks.DetectionCallback` instance to unregister.

remove_file_first_instance_callback(first_instance_callback)¶

Unregisters a dxltieclient.callbacks.FirstInstanceCallback from the client so that it will no longer receive file first instance events.

Param:	first_instance_callback: The `dxltieclient.callbacks.FirstInstanceCallback` instance to unregister.

remove_file_reputation_change_callback(rep_change_callback)¶

Unregisters a dxltieclient.callbacks.ReputationChangeCallback from the client so that it will no longer receive file reputation change events.

Param:	rep_change_callback: The `dxltieclient.callbacks.ReputationChangeCallback` instance to unregister.

set_certificate_reputation(trust_level, sha1, public_key_sha1=None, comment='')¶

Sets the "Enterprise" reputation (trust level) of a specified certificate (as identified by hashes).

Note

Client Authorization

The OpenDXL Python client invoking this method must have permission to send messages to the /mcafee/service/tie/cert/reputation/set topic which is part of the TIE Server Set Enterprise Reputation authorization group.

The following page provides an example of authorizing a Python client to send messages to an authorization group. While the example is based on McAfee Active Response (MAR), the instructions are the same with the exception of swapping the TIE Server Set Enterprise Reputation authorization group in place of Active Response Server API:

https://opendxl.github.io/opendxl-client-python/pydoc/marsendauth.html

Example Usage

# Set the enterprise reputation (trust level) for the certificate to Known Trusted
tie_client.set_certificate_reputation(
    TrustLevel.KNOWN_TRUSTED,
    "1C26E2037C8E205B452CAB3565D696512207D66D",
    public_key_sha1="B4C3B2D596D1461C1BB417B92DCD74817ABB829D",
    comment="Reputation set via OpenDXL")

Parameters:	trust_level -- The new trust level for the file. The list of standard trust levels can be found in the `dxltieclient.constants.TrustLevel` constants class. sha1 -- The SHA-1 of the certificate public_key_sha1 -- The SHA-1 of the certificate's public key (optional) comment -- A comment to associate with the certificate (optional)

set_external_file_reputation(trust_level, hashes, file_type=0, filename='', comment='')¶

Sets the "External" reputation (trust level) of a specified file (as identified by hashes).

Note

Client Authorization

The OpenDXL Python client invoking this method must have permission to send messages to the /mcafee/event/external/file/report topic which is part of the TIE Server Set External Reputation authorization group.

The following page provides an example of authorizing a Python client to send messages to an authorization group. While the example is based on McAfee Active Response (MAR), the instructions are the same with the exception of swapping the TIE Server Set External Reputation authorization group in place of Active Response Server API:

https://opendxl.github.io/opendxl-client-python/pydoc/marsendauth.html

Example Usage

# Set the External reputation (trust level) for file.exe to Known Trusted
tie_client.set_external_file_reputation(
TrustLevel.KNOWN_TRUSTED, {
    HashType.MD5: "f2c7bb8acc97f92e987a2d4087d021b1",
    HashType.SHA1: "7eb0139d2175739b3ccb0d1110067820be6abd29",
    HashType.SHA256: "142e1d688ef0568370c37187fd9f2351d7ddeda574f8bfa9b0fa4ef42db85aa2"
},
FileType.PEEXE,
filename="notepad.exe",
comment="Reputation set via OpenDXL")

Parameters:

trust_level -- The new trust level for the file. The list of standard trust levels can be found in the dxltieclient.constants.TrustLevel constants class.
hashes -- A dict (dictionary) of hashes that identify the file to update the reputation for. The key in the dictionary is the hash type and the value is the hex representation of the hash value. See the dxltieclient.constants.HashType class for the list of hash type constants.
file_type -- A number that represents the file type. The list of allowed file types can be found in the dxltieclient.constants.FileType constants class. (optional)
filename -- A file name to associate with the file (optional)
comment -- A comment to associate with the file (optional)

set_file_reputation(trust_level, hashes, filename='', comment='')¶

Sets the "Enterprise" reputation (trust level) of a specified file (as identified by hashes).

Note

Client Authorization

The OpenDXL Python client invoking this method must have permission to send messages to the /mcafee/service/tie/file/reputation/set topic which is part of the TIE Server Set Enterprise Reputation authorization group.

The following page provides an example of authorizing a Python client to send messages to an authorization group. While the example is based on McAfee Active Response (MAR), the instructions are the same with the exception of swapping the TIE Server Set Enterprise Reputation authorization group in place of Active Response Server API:

https://opendxl.github.io/opendxl-client-python/pydoc/marsendauth.html

Example Usage

 # Set the Enterprise reputation (trust level) for notepad.exe to Known Trusted
tie_client.set_file_reputation(
     TrustLevel.KNOWN_TRUSTED, {
         HashType.MD5: "f2c7bb8acc97f92e987a2d4087d021b1",
         HashType.SHA1: "7eb0139d2175739b3ccb0d1110067820be6abd29",
         HashType.SHA256: "142e1d688ef0568370c37187fd9f2351d7ddeda574f8bfa9b0fa4ef42db85aa2"
     },
     filename="notepad.exe",
     comment="Reputation set via OpenDXL")

Parameters:

trust_level -- The new trust level for the file. The list of standard trust levels can be found in the dxltieclient.constants.TrustLevel constants class.
hashes -- A dict (dictionary) of hashes that identify the file to update the reputation for. The key in the dictionary is the hash type and the value is the hex representation of the hash value. See the dxltieclient.constants.HashType class for the list of hash type constants.
filename -- A file name to associate with the file (optional)
comment -- A comment to associate with the file (optional)

static valid_parameter(constant, value)¶

dxltieclient.client module¶

Previous topic

Next topic

This Page