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 objectindicators=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.

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:

importdatetimefromthreatconnect.Config.FilterOperatorimportFilterOperator# 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 objectindicators=tc.indicators()owner='Example Community'filter1=indicators.add_filter()# only retrieve Indicators from the given ownerfilter1.add_owner(owner)# add a filter for Indicators that contain a 'Description' attributefilter1.add_pf_attribute('Description',FilterOperator.EQ)# add a filter for Indicators with a confidence rating greater than or equal to 50filter1.add_pf_confidence(50,FilterOperator.GE)# get a datestamp for the past weektoday=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 agofilter1.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 agofilter1.add_pf_last_modified(previous_week_datestamp,FilterOperator.GT)# add a filter for Indicators that have a threat rating greater than or equal to 3filter1.add_pf_rating(3,FilterOperator.GE)# add a filter for Indicators that have a threat assess confidence rating greater than or equal to 50filter1.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 3filter1.add_pf_threat_assess_rating(3,FilterOperator.GE)# add a filter for Indicators to return only Address Indicatorsfilter1.add_pf_type('Address',FilterOperator.EQ)# alternatively, add a filter for Indicators to return all indicators that are NOT Address Indicatorsfilter1.add_pf_type('Address',FilterOperator.NE)try:# retrieve Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))# iterate through the Indicatorsforindicatorinindicators: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).

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 objectindicators=tc.indicators()owner='Example Community'indicator='badguy@example.com'# set a filter to retrieve a specific Email Address Indicatorfilter1=indicators.add_filter()filter1.add_owner(owner)filter1.add_indicator(indicator)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 itforindicatorinindicators: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.

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 retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# set a filter to retrieve Email Address Indicatorsfilter1=indicators.add_filter(IndicatorType.EMAIL_ADDRESSES)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the retrieved Email Addresses and print themforindicatorinindicators:print(indicator)

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 objectindicators=tc.indicators()owner='Example Community'# create a new Indicator in the given ownerindicator=indicators.add('badguy@example.com',owner)# set the confidence rating for the Indicatorindicator.set_confidence(75)# set the threat rating for the Indicatorindicator.set_rating(2.5)# add a description attributeindicator.add_attribute('Description','Description Example')# add a tagindicator.add_tag('Example')# add a security labelindicator.set_security_label('TLP Green')try:# create the Indicatorindicator.commit()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)

Note

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

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 objectindicators=tc.indicators()owner='Example Community'indicator='badguy@example.com'# specify a specific email address from a specific owner (in this case 'badguy@example.com' from the 'Example Community')filter1=indicators.add_filter()filter1.add_owner(owner)filter1.add_indicator(indicator)# retrieve the Indicatorindicators.retrieve()try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 themforindicatorinindicators:# delete the Indicatorindicator.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.

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 objectindicators=tc.indicators()owner='Example Community'indicator='8743b52063cd84097a65d1633f5c74f5'# set a filter to retrieve a specific File Indicatorfilter1=indicators.add_filter()filter1.add_owner(owner)filter1.add_indicator(indicator)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 itforindicatorinindicators: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.

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 objectindicators=tc.indicators()# set a filter to retrieve a specific File Indicatorfilter1=indicators.add_filter()filter1.add_indicator('8743b52063cd84097a65d1633f5c74f5')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# if the File was found, print some information about itforindicatorinindicators:print(indicator.indicator)# load the file occurrencesindicator.load_file_occurrence()# iterate through the Indicator's file occurrencesforfile_occurrenceinindicator.file_occurrences:print(file_occurrence.date)print(file_occurrence.file_name)print(file_occurrence.id)print(file_occurrence.path)print('')

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 retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# set a filter to retrieve File Indicatorsfilter1=indicators.add_filter(IndicatorType.FILES)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the retrieved Files and print themforindicatorinindicators:print(indicator)

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 objectindicators=tc.indicators()owner='Example Community'# create a new Indicator in the given ownerindicator=indicators.add('8743b52063cd84097a65d1633f5c74f5',owner)# MD5 hash of string 'hashcat'indicator.set_indicator('b89eaac7e61417341b710b727768294d0e6a277b')#SHA1 hash of same stringindicator.set_indicator('127e6fbfe24a750e72930c220a8e138275656b8e5d8f48a98c3c92df2caba935')# SHA256 hash of same string# set the confidence rating for the Indicatorindicator.set_confidence(75)# set the threat rating for the Indicatorindicator.set_rating(2.5)# add a description attributeindicator.add_attribute('Description','Description Example')# add a tagindicator.add_tag('Example')# add a security labelindicator.set_security_label('TLP Green')try:# create the Indicatorindicator.commit()exceptRuntimeErrorase: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.

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.

fromdatetimeimportdatetime# 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().

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 objectindicators=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 Indicatorindicators.retrieve()try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 themforindicatorinindicators:# delete the Indicatorindicator.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.

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 objectindicators=tc.indicators()# set a filter to retrieve a specific File Indicatorfilter1=indicators.add_filter()filter1.add_indicator('8743b52063cd84097a65d1633f5c74f5')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# if the File was found, print some information about itforindicatorinindicators:print(indicator.indicator)# load the file occurrencesindicator.load_file_occurrence()# iterate through the Indicator's file occurrencesforfile_occurrenceinindicator.file_occurrences:# delete the file occurrenceindicator.delete_file_occurrence(file_occurrence.id)# commit the changesindicator.commit()

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 objectindicators=tc.indicators()owner='Example Community'indicator='example.com'# set a filter to retrieve a specific Host Indicatorfilter1=indicators.add_filter()filter1.add_owner(owner)filter1.add_indicator(indicator)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 itforindicatorinindicators: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.

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicatorfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# if the host was found, print the dns resolutionsforindicatorinindicators:print(indicator.indicator)# load the DNS resolutionsindicator.load_dns_resolutions()# iterate through the Host Indicator's DNS resolutionsfordnsinindicator.dns_resolutions:print(dns.ip)print(dns.owner_name)print(dns.resolution_date)print(dns.weblink)print('')

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 retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# set a filter to retrieve Host Indicatorsfilter1=indicators.add_filter(IndicatorType.HOSTS)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the retrieved Hosts and print themforindicatorinindicators:print(indicator)

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 objectindicators=tc.indicators()owner='Example Community'# create a new Indicator in the given ownerindicator=indicators.add('example.com',owner)# set the confidence rating for the Indicatorindicator.set_confidence(75)# set the threat rating for the Indicatorindicator.set_rating(2.5)# add a description attributeindicator.add_attribute('Description','Description Example')# add a tagindicator.add_tag('Example')# add a security labelindicator.set_security_label('TLP Green')try:# create the Indicatorindicator.commit()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)

Note

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

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 objectindicators=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 Indicatorindicators.retrieve()try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 themforindicatorinindicators:# delete the Indicatorindicator.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.

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 objectindicators=tc.indicators()owner='Example Community'indicator='192.168.0.1'# set a filter to retrieve a specific Address Indicatorfilter1=indicators.add_filter()filter1.add_owner(owner)filter1.add_indicator(indicator)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 itforindicatorinindicators: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.

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 retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# set a filter to retrieve Address Indicatorsfilter1=indicators.add_filter(IndicatorType.ADDRESSES)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the retrieved Addresses and print themforindicatorinindicators:print(indicator)

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 objectindicators=tc.indicators()owner='Example Community'# create a new Indicator in the given ownerindicator=indicators.add('4.3.254.1',owner)# set the confidence rating for the Indicatorindicator.set_confidence(75)# set the threat rating for the Indicatorindicator.set_rating(2.5)# add a description attributeindicator.add_attribute('Description','Description Example')# add a tagindicator.add_tag('Example')# add a security labelindicator.set_security_label('TLP Green')try:# create the Indicatorindicator.commit()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)

Note

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

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 objectindicators=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 Indicatorindicators.retrieve()try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 themforindicatorinindicators:# delete the Indicatorindicator.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.

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 objectindicators=tc.indicators()owner='Example Community'indicator='http://example.com/test/clickme.html'# set a filter to retrieve a specific URL Indicatorfilter1=indicators.add_filter()filter1.add_owner(owner)filter1.add_indicator(indicator)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 itforindicatorinindicators: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.

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 retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# set a filter to retrieve URL Indicatorsfilter1=indicators.add_filter(IndicatorType.URLS)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the retrieved URLs and print themforindicatorinindicators:print(indicator)

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 objectindicators=tc.indicators()owner='Example Community'# create a new Indicator in the given ownerindicator=indicators.add('http://example.com/test/clickme.html',owner)# set the confidence rating for the Indicatorindicator.set_confidence(75)# set the threat rating for the Indicatorindicator.set_rating(2.5)# add a description attributeindicator.add_attribute('Description','Description Example')# add a tagindicator.add_tag('Example')# add a security labelindicator.set_security_label('TLP Green')try:# create the Indicatorindicator.commit()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)

Note

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

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 objectindicators=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 Indicatorindicators.retrieve()try:# prove there is only one Indicator retrievedassertlen(indicators)==1exceptAssertionErrorase:# if the indicator doesn't exist in the given owner, raise an errorprint('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 themforindicatorinindicators:# delete the Indicatorindicator.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 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.

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 classfromthreatconnect.IndicatorObjectParserimportIndicatorObjectParser# 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 objectindicatorParser=IndicatorObjectParser(tc)# initialize the parser (which tunes it for your instance of ThreatConnect)indicatorParser.init();# iterate through the custom indicator types andforindicatorTypeinindicatorParser.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:')forfieldinindicatorType.fields:print(' - {} (type: {})'.format(field.label,field.type))print('')

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 retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# set a filter to retrieve ASN (Autonomous System Number) custom Indicatorsfilter1=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 Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the retrieved Indicators and print themforindicatorinindicators:print(indicator)print('')

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

The required fields for the custom Indicator type.

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.

# this import allows us to specify which Indicator type we want to retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# add the indicatorindicator=indicators.add({'AS Number':'ASN1234'},type=IndicatorType.CUSTOM_INDICATORS,api_entity='asn')# create the indicatorindicator.commit()

# this import allows us to specify which Indicator type we want to retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# add the indicatorindicator=indicators.add({'Block':'192.168.0.1/28'},type=IndicatorType.CUSTOM_INDICATORS,api_entity='cidrBlock')# create the indicatorindicator.commit()

# this import allows us to specify which Indicator type we want to retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# add the indicatorindicator=indicators.add({'Mutex':'test mutex'},type=IndicatorType.CUSTOM_INDICATORS,api_entity='mutex')# create the indicatorindicator.commit()

# this import allows us to specify which Indicator type we want to retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# add the indicatorindicator=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 indicatorindicator.commit()

# this import allows us to specify which Indicator type we want to retrievefromthreatconnect.Config.IndicatorTypeimportIndicatorType# 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 objectindicators=tc.indicators()# add the indicatorindicator=indicators.add({'User Agent String':'PeachWebKit/100.00 (KHTML, like Nothing Else)'},type=IndicatorType.CUSTOM_INDICATORS,api_entity='userAgent')# create the indicatorindicator.commit()

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# iterate through all associated groupsforassociated_groupinindicator.group_associations:# print details about the associated groupprint(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 indicatorsforassociated_indicatorinindicator.indicator_associations:# print details about the associated indicatorprint(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.

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.

fromthreatconnect.Config.ResourceTypeimportResourceType# 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 objectindicators=tc.indicators()# define variableshost_name='example.com'incident_id=123456# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator(host_name)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# create an association between this indicator and the incidentindicator.associate_group(ResourceType.INCIDENTS,incident_id)# commit the changes to ThreatConnectindicator.commit()

Note

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

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.

fromthreatconnect.Config.ResourceTypeimportResourceType# 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 objectindicators=tc.indicators()# define variableshost_name='example.com'incident_id=123456# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator(host_name)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# remove the association between this indicator and the incidentindicator.disassociate_group(ResourceType.INCIDENTS,incident_id)# commit the changes to ThreatConnectindicator.commit()

Note

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

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# load the indicator's attributesindicator.load_attributes()forattributeinindicator.attributes:print(attribute.id)print(attribute.type)print(attribute.value)print(attribute.date_added)print(attribute.last_modified)print(attribute.displayed)print('')

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# add a description attribute that is displayed at the top of the indicator's page in ThreatConnectindicator.add_attribute('Description','Description Example',True)# add a description attribute that is not displayed at the top of the indicator's page in ThreatConnectindicator.add_attribute('Description','Description Example')# commit the changesindicator.commit()

Note

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

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# load the indicator's attributesindicator.load_attributes()# iterate through the indicator's attributesforattributeinindicator.attributes:print(attribute.id)# if the current attribute is a description attribute, update the value of the descriptionifattribute.type=='Description':indicator.update_attribute(attribute.id,'Updated Description')# commit the changesindicator.commit()

Note

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

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# load the indicator's attributesindicator.load_attributes()# iterate through the indicator's attributesforattributeinindicator.attributes:print(attribute.id)# if the current attribute is a description attribute, delete itifattribute.type=='Description':indicator.delete_attribute(attribute.id)# commit the changesindicator.commit()

Note

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

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# load the indicator's security labelindicator.load_security_label()# if this indicator has a security label, print some information about the sec. labelifindicator.security_labelisnotNone: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.

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# add the 'TLP Green' label to the indicatorindicator.add_security_label('TLP Green')# commit the indicator with the new security label to ThreatConnectindicator.commit()

Note

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

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# remove the 'TLP Green' label from the indicatorindicator.delete_security_label('TLP Green')# commit the indicator with the removed security label to ThreatConnectindicator.commit()

Note

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

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# load the indicator's tagsindicator.load_tags()# print details about each tag on the indicatorfortaginindicator.tags:print(tag.name)print(tag.weblink)print('')

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# add the 'Test' tag to the indicatorindicator.add_tag('Test')# commit the indicator with the new tag to ThreatConnectindicator.commit()

Note

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

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# remove the 'Test' tag from the indicatorindicator.delete_tag('Test')# commit the indicator with the removed tag to ThreatConnectindicator.commit()

Note

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

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# set the indicator's threat ratingindicator.set_rating(2.5)# set the indicator's confidence ratingindicator.set_confidence(100)# commit the changesindicator.commit()

Note

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

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.

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# add a false positiveindicator.add_false_positive()# commit the changesindicator.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.

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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# print the number of observations on this Indicatorforobservationinindicator.observations:print('Observation count: {}'.format(observation.count))print('Most recent observation: {}'.format(observation.date_observed))print('')

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

fromdatetimeimportdatetime# 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 objectindicators=tc.indicators()# set a filter to retrieve a specific host indicator: example.comfilter1=indicators.add_filter()filter1.add_indicator('example.com')try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print('Error: {0}'.format(e))sys.exit(1)# iterate through the Indicatorsforindicatorinindicators:print(indicator.indicator)# add two observations to the Indicatorindicator.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 ThreatConnectindicator.commit()

Note

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

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

fromthreatconnect.Config.FilterOperatorimportFilterOperator# 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 objectindicators=tc.bulk_indicators()owner='Example Community'# add a Filter and Post Filterstry:filter1=indicators.add_filter()filter1.add_owner(owner)# only download Indicators with a confidence rating greater than or equal to 75filter1.add_pf_confidence(75,FilterOperator.GE)# only download Indicators with a threat rating greater than 2.5filter1.add_pf_rating('2.5',FilterOperator.GT)exceptAttributeErrorase:print(e)sys.exit(1)try:# retrieve the Indicatorsindicators.retrieve()exceptRuntimeErrorase:print(e)sys.exit(1)# iterate through the resultsforindicatorinindicators:# if the Indicator is a File Indicator or custom Indicator, print it out appropriatelyifisinstance(indicator.indicator,dict):forindicator_type,indicator_valueinindicator.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.

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 .

importjsonimporttime# 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 datadst_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 jobpoll_time=5batch_job_ids=[]# instantiate a Batch Jobs Objectbatch_jobs=dst_tc.batch_jobs()# add a new Batch Jobbatch_job=batch_jobs.add()# configure the Batch Jobbatch_job.set_halt_on_error(False)# if True, abort processing after first errorbatch_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 Jobbatch_job.upload(json.dumps(indicators))try:# commit the Batch Jobbatch_job.commit()print('Created batchjob %s'%batch_job.id)batch_job_ids.append(batch_job.id)exceptRuntimeErrorase: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 finishedwhilelen(batch_job_ids)>0:# sleep for the poll_timetime.sleep(poll_time)total_time+=poll_timeprint('polling (total wait time {0} seconds)'.format(int(total_time)))# retrieve all of the Batch Jobsbatch_jobs=dst_tc.batch_jobs()forbatchIdinbatch_job_ids:# create a filter to find only the Batch Job that we are monitoringfilter=batch_jobs.add_filter()filter.add_id(batchId)# retrieve the desired Batch Job that we are monitoringbatch_jobs.retrieve()# iterate through the Batch Jobs (there will only be one)forbatch_jobinbatch_jobs:# if the Batch Job is done, print the details of the Batch Jobifbatch_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 themsuccess_total=0error_total=0unprocess_total=0# record statistics based on the Batch Jobsforbatch_jobinfinished_batches:# record success countifbatch_job.success_count:success_total+=batch_job.success_count# record unprocessed countifbatch_job.unprocess_count:unprocess_total+=batch_job.unprocess_count# record error countifbatch_job.error_count:error_total+=batch_job.error_count# print some more details about the errorsbatch_job.download_errors()forerrorinbatch_job.errors:print('Batch Job {0} errors: {1}'.format(batch_job.id,batch_job.errors))# print the final statistics of the Batch Jobsprint('All batch jobs completed, totals: '+'succeeded: {0}, failed: {1}, unprocessed: {2}'.format(success_total,error_total,unprocess_total))