Indicators

Indicators Overview

An Indicator represents an atomic piece of information that has some intelligence value (see the article on the ThreatConnect data model for more details). Indicators are guaranteed to be unique within an Owner. For example, a single Organization can have only one instance of the email address Indicator badguy@bad.com.

In the ThreatConnect Python SDK, there is one Indicator class to handle all types of indicators. An object of the Indicator class can be instantiated as demonstrated below:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate an Indicators object
indicators = tc.indicators()

The following, high-level actions can be performed on Indicator objects:

• retrieve() - retrieve Indicator/Indicators from ThreatConnect

• commit() - commit a new or updated Indicator to ThreatConnect

• delete() - delete an Indicator from ThreatConnect

When retrieving Indicators from ThreatConnect, there are various filters which can be used to refine the Indicators returned by the retrieve() call.

There are also functions which enable the creation of Indicator metadata such as associations , attributes , security labels , tags , threat and confidence ratings , false positives , and observations .

Filtering Indicators

This section provides the available filters which can be used when retrieving Indicators from ThreatConnect.

Supported API Filters

API filters use the API filtering feature to limit the result set returned from the API.

Filter	Value Type	Description
add_adversary_id()	int	Filter Indicators on associated Adversary ID.
add_campaign_id()	int	Filter Indicators on associated Campaign ID.
add_document_id()	int	Filter Indicators on associated Document ID.
add_email_id()	int	Filter Indicators on associated Email ID.
add_incident_id()	int	Filter Indicators on associated Incident ID.
add_indicator()	str	Filter Indicators by Indicator value.
add_owner()	list or str	Filter Indicators by Owner.
add_security_label()	str	Filter Indicators on applied Security Label.
add_signature_id()	int	Filter Indicators on associated Signature ID.
add_tag()	str	Filter Indicators on applied Tag.
add_task_id()	int	Filter Indicators on associated Task ID.
add_threat_id()	int	Filter Indicators on associated Threat ID.
add_victim_id()	int	Filter Indicators on associated Victim ID.

Supported Post Filters

Post filters are applied on the results returned by the API request.

Filter	Value Type	Description
add_pf_attribute()	str	Filter Indicators on Attribute type.
add_pf_confidence()	int	Filter Indicators on Confidence value.
add_pf_date_added()	str	Filter Indicators on date added.
add_pf_last_modified()	str	Filter Indicators on last modified date.
add_pf_rating()	str	Filter Indicators on Rating.
add_pf_threat_assess_confidence()	int	Filter Indicators on Threat Assess Confidence.
add_pf_threat_assess_rating()	str	Filter Indicators on Threat Assess Rating.
add_pf_type()	str	Filter Indicators on Indicator type.

The example below demonstrates how to use each of the post filters listed above:

import datetime

from threatconnect.Config.FilterOperator import FilterOperator

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# create an Indicators object
indicators = tc.indicators()

owner = 'Example Community'

filter1 = indicators.add_filter()

# only retrieve Indicators from the given owner
filter1.add_owner(owner)

# add a filter for Indicators that contain a 'Description' attribute
filter1.add_pf_attribute('Description', FilterOperator.EQ)

# add a filter for Indicators with a confidence rating greater than or equal to 50
filter1.add_pf_confidence(50, FilterOperator.GE)

# get a datestamp for the past week
today = datetime.datetime.today()
delta = datetime.timedelta(days = 7)
previous_week_datestamp = (today - delta).isoformat() + 'Z'

# add a filter for Indicators that have been added at a date greater (thus, more recent) than a week ago
filter1.add_pf_date_added(previous_week_datestamp, FilterOperator.GT)

# add a filter for Indicators that have been modified at a date greater (thus, more recent) than a week ago
filter1.add_pf_last_modified(previous_week_datestamp, FilterOperator.GT)

# add a filter for Indicators that have a threat rating greater than or equal to 3
filter1.add_pf_rating(3, FilterOperator.GE)

# add a filter for Indicators that have a threat assess confidence rating greater than or equal to 50
filter1.add_pf_threat_assess_confidence(50, FilterOperator.GE)

# add a filter for Indicators that have a threat assess threat rating greater than or equal to 3
filter1.add_pf_threat_assess_rating(3, FilterOperator.GE)

# add a filter for Indicators to return only Address Indicators
filter1.add_pf_type('Address', FilterOperator.EQ)

# alternatively, add a filter for Indicators to return all indicators that are NOT Address Indicators
filter1.add_pf_type('Address', FilterOperator.NE)

try:
    # retrieve Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))

# iterate through the Indicators
for indicator in indicators:
    print(indicator.id)
    print(indicator.name)
    print(indicator.date_added)
    print(indicator.weblink)
    print('')

Note

The example above will first retrieve all of the Indicators from the owner and will then apply the post filter(s).

Email Addresses

An Email Address Indicator represents a valid email address (e.g., badguy@bad.com).

Retrieve Email Addresses

Retrieving a Single Email Address

This example demonstrates how to retrieve an Email Address Indicator from the ThreatConnect platform. The add_indicator filter allows us to specify the specific Indicator we would like to retrieve.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = '[email protected]'

# set a filter to retrieve a specific Email Address Indicator
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# if the Email Address was found, print some information about it
for indicator in indicators:
    print(indicator.indicator)
    print(indicator.weblink)
    print('')

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

Retrieving Multiple Email Addresses

This example demonstrates how to retrieve all Email Address Indicators in the default organization. The IndicatorType.EMAIL_ADDRESSES which is passed into the filter specifies which Indicator type we want to retrieve.

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve Email Address Indicators
filter1 = indicators.add_filter(IndicatorType.EMAIL_ADDRESSES)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the retrieved Email Addresses and print them
for indicator in indicators:
    print(indicator)

Create Email Addresses

The example below demonstrates how to create an Email Address Indicator in the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'

# create a new Indicator in the given owner
indicator = indicators.add('[email protected]', owner)
# set the confidence rating for the Indicator
indicator.set_confidence(75)
# set the threat rating for the Indicator
indicator.set_rating(2.5)

# add a description attribute
indicator.add_attribute('Description', 'Description Example')
# add a tag
indicator.add_tag('Example')
# add a security label
indicator.set_security_label('TLP Green')

try:
    # create the Indicator
    indicator.commit()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

Note

In the prior example, no API calls are made until the commit() method is invoked.

Delete Email Addresses

The example below demonstrates how to delete an Email Address Indicator from the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = '[email protected]'

# specify a specific email address from a specific owner (in this case '[email protected]' from the 'Example Community')
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

# retrieve the Indicator
indicators.retrieve()

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# iterate through the retrieved Indicators and delete them
for indicator in indicators:
    # delete the Indicator
    indicator.delete()

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

Files

A File Indicator represents a unique file hash or series of hashes (e.g., MD5, SHA-1, and SHA-256).

Retrieve Files

Retrieving a Single File Indicator

This example demonstrates how to retrieve a File Indicator from the ThreatConnect platform. The add_indicator filter allows us to specify the specific Indicator we would like to retrieve. If a File Indicator exists in ThreatConnect and has all three types of hashes (md5, sha1, and sha256), you can pass any one of those hashes into the add_indicator filter and it will return the File Indicator with that hash.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = '8743b52063cd84097a65d1633f5c74f5'

# set a filter to retrieve a specific File Indicator
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# if the File Indicator was found, print some information about it
for indicator in indicators:
    print(indicator.indicator)
    print(indicator.weblink)

    # File Indicator specific property giving the file size (in bytes)
    print(indicator.size)

    print('')

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

Retrieving File Occurrences

The code snippet below demonstrates how to retrieve a File Indicator’s occurrences:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific File Indicator
filter1 = indicators.add_filter()
filter1.add_indicator('8743b52063cd84097a65d1633f5c74f5')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# if the File was found, print some information about it
for indicator in indicators:
    print(indicator.indicator)

    # load the file occurrences
    indicator.load_file_occurrence()

    # iterate through the Indicator's file occurrences
    for file_occurrence in indicator.file_occurrences:
        print(file_occurrence.date)
        print(file_occurrence.file_name)
        print(file_occurrence.id)
        print(file_occurrence.path)
        print('')

Retrieving Multiple File Indicators

This example demonstrates how to retrieve all File Indicators in the default organization. The IndicatorType.FILES which is passed into the filter specifies which Indicator type we want to retrieve.

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve File Indicators
filter1 = indicators.add_filter(IndicatorType.FILES)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the retrieved Files and print them
for indicator in indicators:
    print(indicator)

Create Files

The example below demonstrates how to create a File Indicator in the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'

# create a new Indicator in the given owner
indicator = indicators.add('8743b52063cd84097a65d1633f5c74f5', owner) # MD5 hash of string 'hashcat'
indicator.set_indicator('b89eaac7e61417341b710b727768294d0e6a277b') #SHA1 hash of same string
indicator.set_indicator('127e6fbfe24a750e72930c220a8e138275656b8e5d8f48a98c3c92df2caba935') # SHA256 hash of same string
indicator.set_size(12345) # the file size (in bytes)
# set the confidence rating for the Indicator
indicator.set_confidence(75)
# set the threat rating for the Indicator
indicator.set_rating(2.5)

# add a description attribute
indicator.add_attribute('Description', 'Description Example')
# add a tag
indicator.add_tag('Example')
# add a security label
indicator.set_security_label('TLP Green')

try:
    # create the Indicator
    indicator.commit()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

Note

In the prior example, no API calls are made until the commit() method is invoked.

Note

File Indicators in ThreatConnect support MD5, SHA1, and SHA256 hashes.

Adding File Occurrences

A File occurrence can be added to File Indicators using the add_file_occurrence function which takes parameters in the following format: add_file_occurrence(<file_name>, <run_path>, <date>). Inserting the example code below into the previous code snippet before the indicator.commit() method will add a File occurrence.

from datetime import datetime

# set the date of the file occurrence (this example uses the current datetime stamp)
fo_date = (datetime.isoformat(datetime.today())) + 'Z'

# add a file occurrence with the following data: add_file_occurrence(<file_name>, <run_path>, <date>)
indicator.add_file_occurrence('badfile.exe', 'C:\windows', fo_date)

Note

A File occurrence will only be added to a File Indicator if the indicator.add_file_occurrence(...) function is followed by an indicator.commit().

Uploading File Occurrences

Uploading file occurrences is supported utilizing Batch V2 import mode. There is also a way to set file size, although the solution is not intuitive. See the following example, where the “intValue1” parameter is the desired file size (in bytes):

JSON Response:

{
    .....
    "type": "File",
    .....
    "intValue1": 1024,
    .....
    "fileOccurrence": [{
        "fileName": "test1.exe",
        "path": "C:\\windows\\test",
        "date": "2018-10-09T19:00:00-05:00"
    }, {
        "fileName": "test2.exe",
        "path": "C:\\windows\\test2",
        "date": "2018-10-08T19:00:00-05:00"
    }]
}

Delete Files

The example below demonstrates how to delete a File Indicator from the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = '8743b52063cd84097a65d1633f5c74f5'

# specify a specific file hash from a specific owner (in this case '8743b52063cd84097a65d1633f5c74f5' from the 'Example Community')
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

# retrieve the Indicator
indicators.retrieve()

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# iterate through the retrieved Indicators and delete them
for indicator in indicators:
    # delete the Indicator
    indicator.delete()

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

Deleting File Occurrences

A file occurrence can be deleted from File Indicators using the delete_file_occurrence function which takes the ID of the file occurrence to be deleted as an argument.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific File Indicator
filter1 = indicators.add_filter()
filter1.add_indicator('8743b52063cd84097a65d1633f5c74f5')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# if the File was found, print some information about it
for indicator in indicators:
    print(indicator.indicator)

    # load the file occurrences
    indicator.load_file_occurrence()

    # iterate through the Indicator's file occurrences
    for file_occurrence in indicator.file_occurrences:
        # delete the file occurrence
        indicator.delete_file_occurrence(file_occurrence.id)

    # commit the changes
    indicator.commit()

Hosts

A Host Indicator represents a valid hostname, which is also referred to as a domain (e.g., example.com).

Retrieve Hosts

Retrieving a Single Host

This example demonstrates how to retrieve a Host Indicator from the ThreatConnect platform. The add_indicator filter allows us to specify the specific Indicator we would like to retrieve.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = 'example.com'

# set a filter to retrieve a specific Host Indicator
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# if the Host was found, print some information about it
for indicator in indicators:
    print(indicator.indicator)
    print(indicator.weblink)
    print('')

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

Retrieving DNS Resolutions

The example below demonstrates how to retrieve a Host Indicator’s DNS Resolutions:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# if the host was found, print the dns resolutions
for indicator in indicators:
    print(indicator.indicator)

    # load the DNS resolutions
    indicator.load_dns_resolutions()

    # iterate through the Host Indicator's DNS resolutions
    for dns in indicator.dns_resolutions:
        print(dns.ip)
        print(dns.owner_name)
        print(dns.resolution_date)
        print(dns.weblink)
        print('')

Note

DNS Resolutions are only supported for the Host Indicator type.

Retrieving Multiple Hosts

This example demonstrates how to retrieve all Host Indicators in the default organization. The IndicatorType.HOSTS which is passed into the filter specifies which Indicator type we want to retrieve.

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve Host Indicators
filter1 = indicators.add_filter(IndicatorType.HOSTS)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the retrieved Hosts and print them
for indicator in indicators:
    print(indicator)

Create Hosts

The example below demonstrates how to create a Host Indicator in the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'

# create a new Indicator in the given owner
indicator = indicators.add('example.com', owner)
# set the confidence rating for the Indicator
indicator.set_confidence(75)
# set the threat rating for the Indicator
indicator.set_rating(2.5)

# add a description attribute
indicator.add_attribute('Description', 'Description Example')
# add a tag
indicator.add_tag('Example')
# add a security label
indicator.set_security_label('TLP Green')

try:
    # create the Indicator
    indicator.commit()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

Note

In the prior example, no API calls are made until the commit() method is invoked.

Optionally, turn on DNS resolution and/or ownership information for the host.

# Query PTR record for a given host
indicator.set_dns_active(True)

# Look up host ownership information
indicator.set_whois_active(True)

Delete Hosts

The example below demonstrates how to delete a Host Indicator from the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = 'example.com'

# specify a specific host from a specific owner (in this case 'example.com' from the 'Example Community')
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

# retrieve the Indicator
indicators.retrieve()

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# iterate through the retrieved Indicators and delete them
for indicator in indicators:
    # delete the Indicator
    indicator.delete()

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

IP Addresses

An Address Indicator represents a valid IP Address, either IPv4 or IPv6 (e.g., 192.168.0.1).

Retrieve IP Addresses

Retrieving a Single Address

This example demonstrates how to retrieve an Address Indicator from the ThreatConnect platform. The add_indicator filter allows us to specify the specific Indicator we would like to retrieve.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = '192.168.0.1'

# set a filter to retrieve a specific Address Indicator
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# if the Address was found, print some information about it
for indicator in indicators:
    print(indicator.indicator)
    print(indicator.weblink)
    print('')

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

Retrieving Multiple Addresses

This example demonstrates how to retrieve all Address Indicators in the default organization. The IndicatorType.ADDRESSES which is passed into the filter specifies which Indicator type we want to retrieve.

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve Address Indicators
filter1 = indicators.add_filter(IndicatorType.ADDRESSES)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the retrieved Addresses and print them
for indicator in indicators:
    print(indicator)

Create IP Addresses

The example below demonstrates how to create an Address Indicator in the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'

# create a new Indicator in the given owner
indicator = indicators.add('4.3.254.1', owner)
# set the confidence rating for the Indicator
indicator.set_confidence(75)
# set the threat rating for the Indicator
indicator.set_rating(2.5)

# add a description attribute
indicator.add_attribute('Description', 'Description Example')
# add a tag
indicator.add_tag('Example')
# add a security label
indicator.set_security_label('TLP Green')

try:
    # create the Indicator
    indicator.commit()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

Note

In the prior example, no API calls are made until the commit() method is invoked.

Delete IP Addresses

The example below demonstrates how to delete an Address Indicator from the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = '8.8.8.8'

# specify a specific address in a specific owner (in this case '8.8.8.8' in the 'Example Community')
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

# retrieve the Indicator
indicators.retrieve()

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# iterate through the retrieved Indicators and delete them
for indicator in indicators:
    # delete the Indicator
    indicator.delete()

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

URLs

A URL Indicator represents a valid URL, including protocol (e.g., hXXp://www.example[.]com/index.php?id=1).

Retrieve URLs

Retrieving a Single URL

This example demonstrates how to retrieve a URL Indicator from the ThreatConnect platform. The add_indicator filter allows us to specify the specific Indicator we would like to retrieve.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = 'http://example.com/test/clickme.html'

# set a filter to retrieve a specific URL Indicator
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# if the URL was found, print some information about it
for indicator in indicators:
    print(indicator.indicator)
    print(indicator.weblink)
    print('')

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

Retrieving Multiple URLs

This example demonstrates how to retrieve all URL Indicators in the default organization. The IndicatorType.URLS which is passed into the filter specifies which Indicator type we want to retrieve.

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve URL Indicators
filter1 = indicators.add_filter(IndicatorType.URLS)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the retrieved URLs and print them
for indicator in indicators:
    print(indicator)

Create URLs

The example below demonstrates how to create a URL Indicator in the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'

# create a new Indicator in the given owner
indicator = indicators.add('http://example.com/test/clickme.html', owner)
# set the confidence rating for the Indicator
indicator.set_confidence(75)
# set the threat rating for the Indicator
indicator.set_rating(2.5)

# add a description attribute
indicator.add_attribute('Description', 'Description Example')
# add a tag
indicator.add_tag('Example')
# add a security label
indicator.set_security_label('TLP Green')

try:
    # create the Indicator
    indicator.commit()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

Note

In the prior example, no API calls are made until the commit() method is invoked.

Delete URLs

The example below demonstrates how to delete a URL Indicator from the ThreatConnect platform:

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

owner = 'Example Community'
indicator = 'http://example.com/test/clickme.html'

# specify a specific URL from a specific owner (in this case 'http://example.com/test/clickme.html' from the 'Example Community')
filter1 = indicators.add_filter()
filter1.add_owner(owner)
filter1.add_indicator(indicator)

# retrieve the Indicator
indicators.retrieve()

try:
    # prove there is only one Indicator retrieved
    assert len(indicators) == 1
except AssertionError as e:
    # if the indicator doesn't exist in the given owner, raise an error
    print('AssertionError: The indicator {0} was not found in the "{1}" owner. '.format(indicator, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'or make sure that the {0} indicator specified by the `indicator` '.format(indicator) +
          'variable exists in that owner.')
    sys.exit(1)

# iterate through the retrieved Indicators and delete them
for indicator in indicators:
    # delete the Indicator
    indicator.delete()

Note

If you get an AssertionError when running this code, you likely need to change the name of the owner variable so that it is the name of an owner in your instance of ThreatConnect and/or you need to change the indicators variable so that it is an Indicator that exists in the given owner.

Custom Indicators

Custom Indicators types can be created in ThreatConnect and allow you to capture specific data points that will be helpful as you build intelligence. To view a list of the custom Indicators available on your instance of ThreatConnect, refer to the section on Retrieving Custom Indicator Types below or the API call described here.

Retrieving Custom Indicator Types

Before you can find custom Indicators of a certain type, you need to identify which types are available on your instance of ThreatConnect and find the api_entity of the Indicator type you are interested in retrieving. The example below demonstrates how to do this.

# this import allows us to initialize the IndicatorObjectParser class
from threatconnect.IndicatorObjectParser import IndicatorObjectParser

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate an IndicatorObjectParser object
indicatorParser = IndicatorObjectParser(tc)

# initialize the parser (which tunes it for your instance of ThreatConnect)
indicatorParser.init();

# iterate through the custom indicator types and
for indicatorType in indicatorParser.custom_indicator_types:
    print('Name: {}'.format(indicatorType.name))
    print('API Entity: {}'.format(indicatorType.api_entity))

    # print the fields returned for the given indicator type (and the fields required to create it)
    print('API Fields:')
    for field in indicatorType.fields:
        print('    - {} (type: {})'.format(field.label, field.type))
    print('')

Running the script above on the ThreatConnect public cloud (https://app.threatconnect.com/) returns the following:

Name: ASN
API Entity: asn
API Fields:
    - AS Number (type: text)

Name: CIDR
API Entity: cidrBlock
API Fields:
    - Block (type: text)

Name: Mutex
API Entity: mutex
API Fields:
    - Mutex (type: text)

Name: Registry Key
API Entity: registryKey
API Fields:
    - Key Name (type: text)
    - Value Name (type: text)
    - Value Type (type: selectone)

Name: User Agent
API Entity: userAgent
API Fields:
    - User Agent String (type: text)

Retrieving Custom Indicators of a Specific Type

The example below demonstrates how to retrieve all custom Indicators of a specific type. Before you do this, however, you need to know the API entity of the custom Indicator type you would like to retrieve. Refer to the section above this for more information regarding how you can find this value.

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve ASN (Autonomous System Number) custom Indicators
filter1 = indicators.add_filter(IndicatorType.CUSTOM_INDICATORS, api_entity='asn')
# The `api_entity` argument above could be replaced with `cidrBlock`, `mutex`,
# `registryKey`, or `userAgent` to retrieve indicators of those respective types.

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the retrieved Indicators and print them
for indicator in indicators:
    print(indicator)
    print('')

Creating Custom Indicators

The example below demonstrates how to create a custom Indicator. In order to do this, we must know the following information:

1. The required fields for the custom Indicator type.

2. The api_entity for the custom Indicator type.

There are some examples below that demonstrate how to create ASN, CIDR, Mutex, Registry Key, and User Agent Indicators. If you are trying to create a custom Indicator that is not one of these, refer to the previous section on Retrieving Custom Indicator Types to find the necessary information and plug that information into the format below.

The format when creating a custom Indicator is:

indicators.add({<INDICATOR_FIELD_NAME>: <INDICATOR_FIELD_VALUE>}, type=IndicatorType.CUSTOM_INDICATORS, api_entity=<API_ENTITY>)

Creating ASN Indicators

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# add the indicator
indicator = indicators.add({'AS Number': 'ASN1234'}, type=IndicatorType.CUSTOM_INDICATORS, api_entity='asn')

# create the indicator
indicator.commit()

Creating CIDR Indicators

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# add the indicator
indicator = indicators.add({'Block': '192.168.0.1/28'}, type=IndicatorType.CUSTOM_INDICATORS, api_entity='cidrBlock')

# create the indicator
indicator.commit()

Creating Mutex Indicators

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# add the indicator
indicator = indicators.add({'Mutex': 'test mutex'}, type=IndicatorType.CUSTOM_INDICATORS, api_entity='mutex')

# create the indicator
indicator.commit()

Creating Registry Key Indicators

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# add the indicator
indicator = indicators.add({'Key Name': 'HKEY_LOCAL_MACHINE\System\CurrentControlSet\Hardware Profiles\Current', 'Value Name': 'Autopopulate', 'Value Type': 'REG_DWORD'}, type=IndicatorType.CUSTOM_INDICATORS, api_entity='registryKey')

# create the indicator
indicator.commit()

Creating User Agent Indicators

# this import allows us to specify which Indicator type we want to retrieve
from threatconnect.Config.IndicatorType import IndicatorType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# add the indicator
indicator = indicators.add({'User Agent String': 'PeachWebKit/100.00 (KHTML, like Nothing Else)'}, type=IndicatorType.CUSTOM_INDICATORS, api_entity='userAgent')

# create the indicator
indicator.commit()

Indicator Associations

Retrieve Indicator Associations

The code snippet below demonstrates how to view Groups and Indicators which are associated with a given Indicator in ThreatConnect. This example assumes a Host Indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # iterate through all associated groups
    for associated_group in indicator.group_associations:
        # print details about the associated group
        print(associated_group.id)
        print(associated_group.name)
        print(associated_group.resource_type)
        print(associated_group.owner_name)
        print(associated_group.date_added)
        print(associated_group.weblink)
        print('')

    # iterate through all associated indicators
    for associated_indicator in indicator.indicator_associations:
        # print details about the associated indicator
        print(associated_indicator.id)
        print(associated_indicator.indicator)
        print(associated_indicator.type)
        print(associated_indicator.description)
        print(associated_indicator.owner_name)
        print(associated_indicator.rating)
        print(associated_indicator.confidence)
        print(associated_indicator.date_added)
        print(associated_indicator.last_modified)
        print(associated_indicator.weblink)
        print('')

Note

When the group_associations and indicator_associations properties are referenced, an API request is immediately invoked.

Indicator Associations Properties

Property Name	Type
id	int
indicator	str
type	str
description	str
owner_name	str
rating	str
confidence	str
date_added	str
last_modified	str
weblink	str

Create Indicator Associations

The code snippet below demonstrates how to create an association between an Indicator and a Group in ThreatConnect. This example assumes a Host Indicator example.com exists in the target owner and an Incident with the ID 123456.

from threatconnect.Config.ResourceType import ResourceType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# define variables
host_name = 'example.com'
incident_id = 123456

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator(host_name)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # create an association between this indicator and the incident
    indicator.associate_group(ResourceType.INCIDENTS, incident_id)

    # commit the changes to ThreatConnect
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Delete Indicator Associations

The code snippet below demonstrates how to remove an association between an Indicator and a Group in ThreatConnect. This example assumes a Host Indicator example.com exists in the target owner and an Incident with the ID 123456.

from threatconnect.Config.ResourceType import ResourceType

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# define variables
host_name = 'example.com'
incident_id = 123456

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator(host_name)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # remove the association between this indicator and the incident
    indicator.disassociate_group(ResourceType.INCIDENTS, incident_id)

    # commit the changes to ThreatConnect
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Indicator Metadata

Indicator Attributes

Retrieve Indicator Attributes

The code snippet below demonstrates how to retrieve the attributes from an Indicator. This example assumes a host indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # load the indicator's attributes
    indicator.load_attributes()

    for attribute in indicator.attributes:
        print(attribute.id)
        print(attribute.type)
        print(attribute.value)
        print(attribute.date_added)
        print(attribute.last_modified)
        print(attribute.displayed)
        print('')

Create Indicator Attributes

The code snippet below demonstrates how to create an attribute on an Indicator. This example assumes a host indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # add a description attribute that is displayed at the top of the indicator's page in ThreatConnect
    indicator.add_attribute('Description', 'Description Example', True)

    # add a description attribute that is not displayed at the top of the indicator's page in ThreatConnect
    indicator.add_attribute('Description', 'Description Example')

    # commit the changes
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Hint

The order in which you add attributes can be important. See ‘Order is Important when Adding Attributes’ for more details.

Update Indicator Attributes

The code snippet below demonstrates how to update an Indicator’s attribute. This example assumes a host indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # load the indicator's attributes
    indicator.load_attributes()

    # iterate through the indicator's attributes
    for attribute in indicator.attributes:
        print(attribute.id)

        # if the current attribute is a description attribute, update the value of the description
        if attribute.type == 'Description':
            indicator.update_attribute(attribute.id, 'Updated Description')

    # commit the changes
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Hint

The order in which you update attributes can be important. See ‘Order is Important when Adding Attributes’ for more details.

Delete Indicator Attributes

The code snippet below demonstrates how to delete an Indicator’s attribute. This example assumes a host indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # load the indicator's attributes
    indicator.load_attributes()

    # iterate through the indicator's attributes
    for attribute in indicator.attributes:
        print(attribute.id)

        # if the current attribute is a description attribute, delete it
        if attribute.type == 'Description':
            indicator.delete_attribute(attribute.id)

    # commit the changes
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Indicator Security Labels

Retrieve Indicator Security Labels

The code snippet below demonstrates how to retrieve the security label from an Indicator. This example assumes a host indicator example.com exists in the target owner and has a security label.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # load the indicator's security label
    indicator.load_security_label()

    # if this indicator has a security label, print some information about the sec. label
    if indicator.security_label is not None:
        print(indicator.security_label.name)
        print(indicator.security_label.description)
        print(indicator.security_label.date_added)
        print('')

Warning

Currently, the ThreatConnect Python SDK does not support multiple security labels. If an Indicator has multiple security labels, the Python SDK will only return one of them.

Create Indicator Security Labels

The code snippet below demonstrates how to add a security label to an Indicator. This example assumes a host indicator example.com exists in the target owner and that the target owner has a ‘TLP Green’ security label (security labels are not case sensitive when using the Python SDK).

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # add the 'TLP Green' label to the indicator
    indicator.add_security_label('TLP Green')

    # commit the indicator with the new security label to ThreatConnect
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Delete Indicator Security Labels

The code snippet below demonstrates how to delete a security label from an Indicator. This example assumes a host indicator example.com exists in the target owner and that the host has the ‘TLP Green’ security label (security labels are not case sensitive when using the Python SDK).

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # remove the 'TLP Green' label from the indicator
    indicator.delete_security_label('TLP Green')

    # commit the indicator with the removed security label to ThreatConnect
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Indicator Tags

Retrieve Indicator Tags

The code snippet below demonstrates how to retrieve the tags from an Indicator. This example assumes a host indicator example.com exists in the target owner (and it works better if the host has some tags on it).

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # load the indicator's tags
    indicator.load_tags()

    # print details about each tag on the indicator
    for tag in indicator.tags:
        print(tag.name)
        print(tag.weblink)
        print('')

Create Indicator Tags

The code snippet below demonstrates how to add a tag to an Indicator. This example assumes a host indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # add the 'Test' tag to the indicator
    indicator.add_tag('Test')

    # commit the indicator with the new tag to ThreatConnect
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Note

The length of a tag is limited to 128 characters.

Delete Indicator Tags

The code snippet below demonstrates how to delete a tag from an Indicator. This example assumes a host indicator example.com exists in the target owner and is tagged ‘Test’.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # remove the 'Test' tag from the indicator
    indicator.delete_tag('Test')

    # commit the indicator with the removed tag to ThreatConnect
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Indicator Threat and Confidence Ratings

Retrieve Indicator Threat and Confidence Ratings

The code snippet below demonstrates how to retrieve the threat and confidence ratings from an Indicator. This example assumes a host indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # print the indicator's threat rating
    print(indicator.rating)

    # print the indicator's confidence rating
    print(indicator.confidence)

    print('')

Create Indicator Threat and Confidence Ratings

The code snippet below demonstrates how to add/change the threat and/or confidence rating on an Indicator. This example assumes a host indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # set the indicator's threat rating
    indicator.set_rating(2.5)

    # set the indicator's confidence rating
    indicator.set_confidence(100)

    # commit the changes
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Indicator ThreatAssess Ratings

Retrieve Indicator ThreatAssess Threat and Confidence Ratings

The ThreatAssess Threat and Confidence ratings can be accessed via an Indicator’s threat_assess_rating and threat_assess_confidence properties, respectively. The example below demonstrates how to retrieve these properties.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# print the Indicator and ThreatAssess Threat rating for each Indicator
for indicator in indicators:
    print('\nIndicator: {}\n'.format(indicator.indicator) +
          'ThreatAssess Threat rating: {}\n'.format(indicator.threat_assess_rating) +
          'ThreatAssess Confidence rating: {}\n'.format(indicator.threat_assess_confidence))
    print('')

Indicator False Positives

Add Indicator False Positive

The code snippet below demonstrates how to add a false positive to an Indicator. This example assumes a host indicator example.com exists in the target owner.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # add a false positive
    indicator.add_false_positive()

    # commit the changes
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked. Thus, the false positive will not be added until the commit() method is invoked.

Indicator Observations

Retrieve Indicator Observations

The code snippet below demonstrates how to retrieve observations of an Indicator.

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # print the number of observations on this Indicator
    for observation in indicator.observations:
        print('Observation count: {}'.format(observation.count))
        print('Most recent observation: {}'.format(observation.date_observed))
        print('')

Create Indicator Observations

The code snippet below demonstrates how to add observations to an Indicator.

from datetime import datetime

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# instantiate Indicators object
indicators = tc.indicators()

# set a filter to retrieve a specific host indicator: example.com
filter1 = indicators.add_filter()
filter1.add_indicator('example.com')

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))
    sys.exit(1)

# iterate through the Indicators
for indicator in indicators:
    print(indicator.indicator)

    # add two observations to the Indicator
    indicator.add_observation(2)

    # you can also include a date observed when adding observations
    # indicator.add_observation(2, datetime.isoformat(datetime.today()) + 'Z')

    # commit the changes to ThreatConnect
    indicator.commit()

Note

In the prior example, no API calls are made until the commit() method is invoked.

Bulk Indicator Download

This section explains how to work with ThreatConnect Bulk Indicators.

Note

Bulk Download: None of the specified enrichment data is supported for download via this mechanism; only the basic “Indicator” data is given, which includes tags and attributes, but no file-specific-data, such as file size/occurrences, associations of any kind, or DNS resolutions are included.

Supported API Filters

Filter	Value Type	Description
add_owner()	list or str	Filter Indicators by Owner.

Supported Post Filters

Filter	Value Type	Description
add_pf_attribute()	str	Filter Indicators on Attribute type.
add_pf_confidence()	int	Filter Indicators on Confidence value.
add_pf_date_added()	str	Filter Indicators on date added.
add_pf_last_modified()	str	Filter Indicators on last modified date.
add_pf_rating()	str	Filter Indicators on Rating.
add_pf_tag()	str	Filter Indicators on Tag.
add_pf_threat_assess_confidence()	int	Filter Indicators on Threat Assess Confidence.
add_pf_threat_assess_rating()	str	Filter Indicators on Threat Assess Rating.
add_pf_type()	str	Filter Indicators on Indicator type.

Bulk Download Example

The ThreatConnect Python SDK has functionality to download Indicators from the ThreatConnect platform in bulk. The code snippet below demonstrates this capability

from threatconnect.Config.FilterOperator import FilterOperator

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

tc = ThreatConnect(api_access_id, api_secret_key, api_default_org, api_base_url)

# Bulk Indicator object
indicators = tc.bulk_indicators()

owner = 'Example Community'

# add a Filter and Post Filters
try:
    filter1 = indicators.add_filter()
    filter1.add_owner(owner)
    # only download Indicators with a confidence rating greater than or equal to 75
    filter1.add_pf_confidence(75, FilterOperator.GE)
    # only download Indicators with a threat rating greater than 2.5
    filter1.add_pf_rating('2.5', FilterOperator.GT)
except AttributeError as e:
    print(e)
    sys.exit(1)

try:
    # retrieve the Indicators
    indicators.retrieve()
except RuntimeError as e:
    print(e)
    sys.exit(1)

# iterate through the results
for indicator in indicators:
    # if the Indicator is a File Indicator or custom Indicator, print it out appropriately
    if isinstance(indicator.indicator, dict):
        for indicator_type, indicator_value in indicator.indicator.items():
            print('{0}: {1}'.format(indicator_type, indicator_value))
    else:
        print(indicator.indicator)

    print(indicator.id)
    print(indicator.owner_name)
    print(indicator.date_added)
    print(indicator.last_modified)
    print(indicator.rating)
    print(indicator.threat_assess_rating)
    print(indicator.confidence)
    print(indicator.threat_assess_confidence)
    print(indicator.type)
    print(indicator.weblink)

Warning

In order to use the bulk download capability, the “Enable Bulk Indicators” setting must be selected for the owner from which you want to download the data. Check with your ThreatConnect System Administrator if you have any questions.

Batch Commit

As demonstrated by the code snippet below, the ThreatConnect Python SDK supports adding indicators in bulk to the ThreatConnect platform.

The code snippet below assumes that indicator data is formatted in the same way as the JSON used by the API .

import json
import time

# replace the line below with the standard, TC script heading described here:
# https://docs.threatconnect.com/en/latest/python/quick_start.html#standard-script-heading
...

# define the owner where you would like to put the data
dst_owner = 'Example Community'

dst_tc = ThreatConnect(api_access_id, api_secret_key, dst_owner, api_base_url)

#
# populate 'indicators' list of dictionaries as formatted here:
# https://docs.threatconnect.com/en/latest/rest_api/indicators/indicators.html#batch-indicator-input-file-format
#
indicators = [
    {
        'rating': 3,
        'confidence': 75,
        'description': 'Malicious domain',
        'summary': 'example.com',
        'type': 'Host',
        'associatedGroup': [12345, 54321],
        'attribute': [
            {
                'type': 'Source',
                'value': 'SEIM log - 13/01/2017'
            }
        ],
        'tag': [
            {
                'name': 'MyTag'
            }
        ]
    }
]

# time (in seconds) to wait before checking the status of a batch job
poll_time = 5

batch_job_ids = []

# instantiate a Batch Jobs Object
batch_jobs = dst_tc.batch_jobs()

# add a new Batch Job
batch_job = batch_jobs.add()

# configure the Batch Job
batch_job.set_halt_on_error(False)             # if True, abort processing after first error
batch_job.set_attribute_write_type('Replace')  # replace attributes (can also be Append)
batch_job.set_action('Create')                 # create indicators (can also be Delete)
batch_job.set_owner(dst_owner)                 # owner to write indicators to

# set the indicators to be uploaded in this Batch Job
batch_job.upload(json.dumps(indicators))

try:
    # commit the Batch Job
    batch_job.commit()
    print('Created batchjob %s' % batch_job.id)
    batch_job_ids.append(batch_job.id)
except RuntimeError as e:
    print('Error creating Batch Job: {}'.format(e))
    sys.exit(1)

finished_batches = []
total_time = 0

# iterate through the Batch Jobs that have been started and see if they have finished
while len(batch_job_ids) > 0:
    # sleep for the poll_time
    time.sleep(poll_time)
    total_time += poll_time
    print('polling (total wait time {0} seconds)'.format(int(total_time)))

    # retrieve all of the Batch Jobs
    batch_jobs = dst_tc.batch_jobs()

    for batchId in batch_job_ids:
        # create a filter to find only the Batch Job that we are monitoring
        filter = batch_jobs.add_filter()
        filter.add_id(batchId)

        # retrieve the desired Batch Job that we are monitoring
        batch_jobs.retrieve()

        # iterate through the Batch Jobs (there will only be one)
        for batch_job in batch_jobs:
            # if the Batch Job is done, print the details of the Batch Job
            if batch_job.status == 'Completed':
                finished_batches.append(batch_job)
                batch_job_ids.remove(batchId)
                print('Finished batch job {0}: succeeded: {1}, ' +
                      'failed: {2}, unprocessed: {3}'.format(batchId, batch_job.success_count, batch_job.error_count, batch_job.unprocess_count))

# now that all of the Batch Jobs have finished, get some statistics on them
success_total = 0
error_total = 0
unprocess_total = 0

# record statistics based on the Batch Jobs
for batch_job in finished_batches:
    # record success count
    if batch_job.success_count:
        success_total += batch_job.success_count

    # record unprocessed count
    if batch_job.unprocess_count:
        unprocess_total += batch_job.unprocess_count

    # record error count
    if batch_job.error_count:
        error_total += batch_job.error_count

        # print some more details about the errors
        batch_job.download_errors()
        for error in batch_job.errors:
            print('Batch Job {0} errors: {1}'.format(batch_job.id, batch_job.errors))

# print the final statistics of the Batch Jobs
print('All batch jobs completed, totals: ' +
      'succeeded: {0}, failed: {1}, unprocessed: {2}'.format(success_total, error_total, unprocess_total))

Supported Functions and Properties

Property Name	Method	Required	Allowable Values
halt_on_error	set_halt_on_error	True	True, False
attribute_write_type	set_attribute_write_type	True	Replace, Append
action	set_action	True	Create, Delete
owner	set_owner	True	Any Owner
–	upload	True	Indicator JSON String