Groups

Groups Overview

In ThreatConnect, Groups represent a collection of related behavior and/or intelligence (refer to the article on the ThreatConnect data model for more details).

The following group objects are available via the ThreatConnect 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 a generic Groups object
groups = tc.groups()

# instantiate an object for a specific Group type
adversaries = tc.adversaries()
campaigns = tc.campaigns()
documents = tc.documents()
emails = tc.emails()
incidents = tc.incidents()
signatures = tc.signatures()
threats = tc.threats()

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

  • retrieve() - retrieve Group/Groups from ThreatConnect
  • commit() - commit a new or updated Group to ThreatConnect
  • delete() - delete a Group from ThreatConnect

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

There are also functions which enable the creation of Group metadata such as associations , attributes , security labels , and tags.

Hint

When working with groups using the ThreatConnect Python SDK, it is often necessary to specify the ID corresponding to the Group you would like to work with. While the ID of a Group can be retrieved from the SDK, it can also be found in the URL of each Group. If you navigate to the page for a Group, the URL should look something like: https://app.threatconnect.com/auth/<GROUP-TYPE>/<GROUP-TYPE>.xhtml?<GROUP-TYPE>=123456 or https://app.threatconnect.com/auth/<GROUP-TYPE>/<GROUP-TYPE>.xhtml?<GROUP-TYPE>=123456&ow.... The number after the <GROUP-TYPE> key is the ID for the Group (in both of the previous examples, the ID of the Group is 123456).

Filtering Groups

This section provides the available filters which can be used when retrieving Groups 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_id() int Filter Groups by ID.
add_adversary_id() int Filter Groups on associated Adversary ID.
add_campaign_id() int Filter Groups on associated Campaign ID.
add_document_id() int Filter Groups on associated Document ID.
add_email_id() int Filter Groups on associated Email ID.
add_incident_id() int Filter Groups on associated Incident ID.
add_indicator() str Filter Groups on associated Indicator.
add_owner() list or str Filter Groups on Owner.
add_security_label() str Filter Groups on applied Security Label.
add_signature_id() int Filter Groups on associated Signature ID.
add_tag() str Filter Groups on applied Tag.
add_task_id() int Filter Groups on associated Task ID.
add_threat_id() int Filter Groups on associated Threat ID.
add_victim_id() int Filter Groups 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_name() str Filter Groups on name.
add_pf_date_added() str Filter Groups on date added.

The example below demonstrates how to use the add_pf_name() filter to find a Group with the name ‘Example Group’.

# 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 a Groups object
groups = tc.groups()

owner = 'Example Community'
filter1 = groups.add_filter()
# only retrieve Groups from the given owner
filter1.add_owner(owner)

# add a filter for Groups whose name matches the desired_group_name
desired_group_name = 'Example Group'
filter1.add_pf_name(desired_group_name)

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

# iterate through the Groups
for group in groups:
    print(group.id)
    print(group.name)
    print(group.date_added)
    print(group.weblink)

    # Group specific property
    print(group.type)
    print('')

The example below demonstrates how to use the add_pf_date_added() filter to find all Groups added within the past seven days.

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 a Groups object
groups = tc.groups()

owner = 'Example Community'

filter1 = groups.add_filter()
# only retrieve Groups from the given owner
filter1.add_owner(owner)

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

# add a filter to see all Groups with a date added datestamp greater than (thus, more recent) than the datestamp
filter1.add_pf_date_added(datestamp, FilterOperator.GE)

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

# iterate through the Groups
for group in groups:
    print(group.id)
    print(group.name)
    print(group.date_added)
    print(group.weblink)

    # Group specific property
    print(group.type)
    print('')

Note

Both of the examples above will first retrieve all of the Indicators from the owner and will then apply the post filter.

Generic Group Retrieval

This example demonstrates how to retrieve Groups while applying filters. In this example two filters will be added: one for the Owner and another for a Tag. The result set returned from this example will contain all Groups in the Example Community Owner that have the Nation State Tag.

# 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 a Groups object
groups = tc.groups()

owner = 'Example Community'

filter1 = groups.add_filter()
# only retrieve groups from the owner named: 'Example Community'
filter1.add_owner(owner)
# only retrieve groups tagged with: 'Nation State'
filter1.add_tag('Nation State')

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

# iterate through the Groups
for group in groups:
    print(group.id)
    print(group.name)
    print(group.date_added)
    print(group.weblink)

    # Group specific property
    print(group.type)

Adversaries

The Adversary Group represents a malicious actor or group of actors.

Retrieve Adversaries

Retrieving a Single Adversary

This example demonstrates how to retrieve a specific Adversary using the Adversary’s ID. The add_id filter specifies the ID of the Adversary which you 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 Adversaries object
adversaries = tc.adversaries()

# set a filter to retrieve only the Adversary with ID: 123456
filter1 = adversaries.add_filter()
filter1.add_id(123456)

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

# iterate through the retrieved Adversary (in this case there should only be one) and print its properties
for adversary in adversaries:
    print(adversary.id)
    print(adversary.name)
    print(adversary.date_added)
    print(adversary.weblink)
    print('')

Retrieving Multiple Adversaries

This example demonstrates how to retrieve Adversaries while applying filters. Two filters are added: one for the Owner and another for a Tag. The result set returned from this example will contain all Adversaries in the “Example Community” Owner that have the Nation State Tag.

# 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 Adversaries object
adversaries = tc.adversaries()

owner = 'Example Community'

# set a filter to only retrieve Adversaries in the 'Example Community' tagged: 'Nation State'
filter1 = adversaries.add_filter()
filter1.add_owner(owner)
filter1.add_tag('Nation State')

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

# iterate through the retrieved Adversaries and print their properties
for adversary in adversaries:
    print(adversary.id)
    print(adversary.name)
    print(adversary.date_added)
    print(adversary.weblink)
    print('')

Note

The filter1 object contains a filters property that provides a list of supported filters for the resource type being retrieved. To display this list, print(filter1.filters) can be used. For more on using filters see the Advanced Filter Tutorial.

Create Adversaries

Example Python SDK creating an adversary resource 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 Adversaries object
adversaries = tc.adversaries()

owner = 'Example Community'

# create a new Adversary in 'Example Community' with the name: 'New Adversary'
adversary = adversaries.add('New Adversary', owner)

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

try:
    # create the Adversary
    adversary.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.

Update Adversaries

The example below demonstrates how to update an Adversary Resource 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 Adversaries object
adversaries = tc.adversaries()

owner = 'Example Community'

# create an Adversary with an updated name
adversary = adversaries.add('Updated Adversary', owner)
# set the ID of the new Adversary to the ID of the existing Adversary you want to update
adversary.set_id(123456)

# you can update the Adversary metadata as described here: https://docs.threatconnect.com/en/latest/python/groups/groups.html#group-metadata

try:
    # update the Adversary
    adversary.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 Adversaries

The example below demonstrates how to delete an Adversary Resource 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 Adversaries object
adversaries = tc.adversaries()

owner = 'Example Community'

# create an empty Adversary
adversary = adversaries.add('', owner)
# set the ID of the new Adversary to the ID of the Adversary you would like to delete
adversary.set_id(123456)

try:
    # delete the Adversary
    adversary.delete()
except RuntimeError as e:
    print(e)
    sys.exit(1)

Note

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

Campaigns

The Campaign Group represents a collection of Incidents over time.

Retrieve Campaigns

Retrieving a Single Campaign

This example demonstrates how to retrieve a specific Campaign using the Campaign’s ID. The add_id filter specifies the ID of the Campaign which you 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 Campaigns object
campaigns = tc.campaigns()

# set a filter to retrieve only the Campaign with ID: 123456
filter1 = campaigns.add_filter()
filter1.add_id(123456)

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

# iterate through the retrieved Campaign (in this case there should only be one) and print its properties
for campaign in campaigns:
    print(campaign.id)
    print(campaign.name)
    print(campaign.date_added)
    print(campaign.weblink)
    print('')

Retrieving Multiple Campaigns

This example demonstrates how to retrieve Campaigns while applying filters. Two filters are added: one for the Owner and another for a Tag. The result set returned from this example will contain all Campaigns in the “Example Community” Owner that have the Nation State Tag.

# 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 Campaigns object
campaigns = tc.campaigns()

owner = 'Example Community'

# set a filter to only retrieve Campaigns in the 'Example Community' tagged: 'Nation State'
filter1 = campaigns.add_filter()
filter1.add_owner(owner)
filter1.add_tag('Nation State')

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

# iterate through the retrieved Campaigns and print their properties
for campaign in campaigns:
    print(campaign.id)
    print(campaign.name)
    print(campaign.date_added)
    print(campaign.weblink)
    print('')

Note

The filter1 object contains a filters property that provides a list of supported filters for the resource type being retrieved. To display this list, print(filter1.filters) can be used. For more on using filters see the Advanced Filter Tutorial.

Create Campaigns

The example below demonstrates how to create a Campaign Resource 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 Campaigns object
campaigns = tc.campaigns()

owner = 'Example Community'

# create a new Campaign in 'Example Community' with the name: 'New Campaign'
campaign = campaigns.add('New Campaign', owner)
# set the first seen date for the Campaign
campaign.set_first_seen('2017-05-21T00:00:00Z')  # OPTIONAL

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

try:
    # create the Campaign
    campaign.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.

Supported Properties

Property Name Method Required
first_seen set_first_seen False

Update Campaigns

The example below demonstrates how to update a Campaign Resource 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 Campaigns object
campaigns = tc.campaigns()

owner = 'Example Community'

# create Campaign with updated name
campaign = campaigns.add('Updated Campaign', owner)
# set the ID of the new Campaign to the ID of the existing Campaign you want to update
campaign.set_id(123456)

# you can update the Campaign metadata as described here: https://docs.threatconnect.com/en/latest/python/groups/groups.html#group-metadata

try:
    # update the Campaign
    campaign.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 Campaigns

The example below demonstrates how to delete a Campaign Resource 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 Campaigns object
campaigns = tc.campaigns()

owner = 'Example Community'

# create an empty Campaign
campaign = campaigns.add('', owner)
# set the ID of the new Campaign to the ID of the Campaign you would like to delete
campaign.set_id(123456)

try:
    # delete the Campaign
    campaign.delete()
except RuntimeError as e:
    print(e)
    sys.exit(1)

Note

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

Documents

The Document Group represents an actual file of interest, such as a PDF report that contains valuable intelligence or a malware sample.

Retrieve Documents

Retrieving a Single Document

This example demonstrates how to retrieve a specific Document using the Document’s ID. The add_id filter specifies the ID of the Document which you 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 Documents object
documents = tc.documents()

# set a filter to retrieve only the Document with ID: 123456
filter1 = documents.add_filter()
filter1.add_id(123456)

try:
    # retrieve the Document
    documents.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))

# iterate through the retrieved Documents (in this case there should only be one) and print its properties
for document in documents:
    print(document.id)
    print(document.name)
    print(document.date_added)
    print(document.owner_name)
    print(document.weblink)

    # Document specific property
    print(document.file_name)

    print('')
Downloading a Document’s Contents

Python SDK example of downloading the contents of the document stored with the Document Resource:

document.download()
if document.contents is not None:
    print(document.contents)

Retrieving Multiple Documents

This example will demonstrate how to retrieve documents while applying filters. In this example, two filters will be added, one for the Owner and another for a Tag. The result set returned from this example will contain any documents in the Example Community Owner that has a Tag of EXAMPLE.

# 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 Documents object
documents = tc.documents()

owner = 'Example Community'

# set a filter to only retrieve Documents in the 'Example Community' tagged: 'Nation State'
filter1 = documents.add_filter()
filter1.add_owner(owner)
filter1.add_tag('Nation State')

try:
    # retrieve the Documents
    documents.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))

# iterate through the retrieved Documents and print their properties
for document in documents:
    print(document.id)
    print(document.name)
    print(document.date_added)
    print(document.owner_name)
    print(document.weblink)
    print('')

Note

The filter1 object contains a filters property that provides a list of supported filters for the resource type being retrieved. To display this list, print(filter1.filters) can be used. For more on using filters see the Advanced Filter Tutorial.

Create Documents

The example below demonstrates how to create a Document Resource 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 Documents object
documents = tc.documents()

owner = 'Example Community'

# create a new Document in 'Example Community' with the name: 'New Document'
document = documents.add('New Document', owner)
document.set_file_name('New File.txt')

# open a file handle for a local file and read the contents thereof
fh = open('./sample1.zip', 'rb')
contents = fh.read()
# upload the contents of the file into the Document
document.upload(contents)

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

try:
    # create the Document
    document.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.

Supported Properties

Property Name Method Required
file_name set_file_name True
malware set_malware False
password set_password False

Create Malware Document

To create a malware document in ThreatConnect, make use of the set_malware and set_password functions 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 Documents object
documents = tc.documents()

owner = 'Example Community'

# create a new Document in 'Example Community' with the name: 'New Document'
document = documents.add('Malicious File', owner)
document.set_file_name('bad.exe')

# open a file handle for a local file and read the contents thereof
fh = open('./bad.exe.zip', 'rb')
contents = fh.read()
# upload the contents of the file into the Document
document.upload(contents)

document.set_malware(True)
# set the archive password for the zip (the default is "TCinfected")
document.set_password("TCinfected")

try:
    # create the Document
    document.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.

Update Documents

The example below demonstrates how to update a Document Resource 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 Documents object
documents = tc.documents()

owner = 'Example Community'

# create a Document with an updated name
document = documents.add('Updated Document', owner)
# set the ID of the new Document to the ID of the existing Document you want to update
document.set_id(123456)

# you can update the Document metadata as described here: https://docs.threatconnect.com/en/latest/python/groups/groups.html#group-metadata

try:
    # update the Document
    document.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 Documents

The example below demonstrates how to delete a Document Resource 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 Documents object
documents = tc.documents()

owner = 'Example Community'

# create an empty Document
document = documents.add('', owner)
# set the ID of the new Document to the ID of the Document you would like to delete
document.set_id(123456)

try:
    # delete the Document
    document.delete()
except RuntimeError as e:
    print(e)
    sys.exit(1)

Note

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

Emails

The E-mail Group represents an occurrence of a specific suspicious email, such as a phishing attempt.

Retrieve Emails

Retrieving a Single Email

This example demonstrates how to retrieve a specific Email using the Email’s ID. The add_id filter specifies the ID of the Email which you 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 Emails object
emails = tc.emails()

# set a filter to retrieve only the Email with ID: 123456
filter1 = emails.add_filter()
filter1.add_id(123456)

try:
    # retrieve the Email
    emails.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))

# iterate through the retrieved Emails (in this case there should only be one) and print its properties
for email in emails:
    print(email.id)
    print(email.name)
    print(email.date_added)
    print(email.weblink)

    # Email specific properties
    print(email.header)
    print(email.subject)
    print(email.from_address)
    print(email.to)
    print(email.body)
    print(email.score)

    print('')

Retrieving Multiple Emails

This example will demonstrate how to retrieve emails while applying filters. In this example, two filters will be added, one for the Owner and another for a Tag. The result set returned from this example will contain any emails in the Example Community Owner that has a Tag of EXAMPLE.

# 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 Emails object
emails = tc.emails()

owner = 'Example Community'

# set a filter to only retrieve Emails in the 'Example Community' tagged: 'Nation State'
filter1 = emails.add_filter()
filter1.add_owner(owner)
filter1.add_tag('Nation State')

try:
    # retrieve the Emails
    emails.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))

# iterate through the retrieved Emails and print their properties
for email in emails:
    print(email.id)
    print(email.name)
    print(email.date_added)
    print(email.weblink)

    # Email specific property
    print(email.score)

    print('')

Note

The filter1 object contains a filters property that provides a list of supported filters for the resource type being retrieved. To display this list, print(filter1.filters) can be used. For more on using filters see the Advanced Filter Tutorial.

Create Emails

The example below demonstrates how to create an Email Resource 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 Emails object
emails = tc.emails()

owner = 'Example Community'

# create a new Email in 'Example Community' with the name: 'New Email'
email = emails.add('New Email', owner)

# set Email specific properties
email.set_body('This is an email body.')  # REQUIRED
email.set_from_address('bad_guy@example.com')  # OPTIONAL
email.set_header('This is an improper email header.')  # REQUIRED
email.set_subject('This is an email subject.')  # REQUIRED
email.set_to('victim@example.com')  # OPTIONAL

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

try:
    # create the Email
    email.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.

Supported Properties

Property Name Method Required
body set_body True
header set_header True
subject set_subject True
from_address set_from_address False
score set_score False
to set_to False

Update Emails

The example below demonstrates how to update an Email Resource 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 Emails object
emails = tc.emails()

owner = 'Example Community'

# create an Email with an updated name
email = emails.add('Updated Email', owner)
# set the ID of the new Email to the ID of the existing Email you want to update
email.set_id(123456)

# you can update the Email metadata as described here: https://docs.threatconnect.com/en/latest/python/groups/groups.html#group-metadata

try:
    # update the Email
    email.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 Emails

The example below demonstrates how to delete an Email Resource 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 Emails object
emails = tc.emails()

owner = 'Example Community'

# create an empty Email
email = emails.add('', owner)
# set the ID of the new Email to the ID of the Email you would like to delete
email.set_id(123456)

try:
    # delete the Email
    email.delete()
except RuntimeError as e:
    print(e)
    sys.exit(1)

Note

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

Incidents

The Incident Group represents a snapshot of a particular intrusion, breach, or other event of interest.

Retrieve Incidents

Retrieving a Single Incident

This example demonstrates how to retrieve a specific Incident using the Incident’s ID. The add_id filter specifies the ID of the Incident which you 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 Incidents object
incidents = tc.incidents()

# set a filter to retrieve only the Incident with ID: 123456
filter1 = incidents.add_filter()
filter1.add_id(123456)

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

# iterate through the retrieved Incidents (in this case there should only be one) and print its properties
for incident in incidents:
    print(incident.id)
    print(incident.name)
    print(incident.date_added)
    print(incident.weblink)

    # Incident specific property
    print(incident.event_date)

    print('')

Retrieving Multiple Incidents

This example will demonstrate how to retrieve Incidents while applying filters. In this example, two filters will be added, one for the Owner and another for a Tag. The result set returned from this example will contain any Incidents in the Example Community Owner that has a Tag of EXAMPLE.

# 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 Incidents object
incidents = tc.incidents()

owner = 'Example Community'

# set a filter to only retrieve Incidents in the 'Example Community' tagged: 'Nation State'
filter1 = incidents.add_filter()
filter1.add_owner(owner)
filter1.add_tag('Nation State')

try:
    # retrieve the Incidents
    incidents.retrieve()
except RuntimeError as e:
    print('Error: {0}'.format(e))

# iterate through the retrieved Incidents and print their properties
for incident in incidents:
    print(incident.id)
    print(incident.name)
    print(incident.date_added)
    print(incident.weblink)

    # Incident specific property
    print(incident.event_date)

    print('')

Note

The filter1 object contains a filters property that provides a list of supported filters for the resource type being retrieved. To display this list, print(filter1.filters) can be used. For more on using filters see the Advanced Filter Tutorial.

Create Incidents

The example below demonstrates how to create an Incident Resource 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 Incidents object
incidents = tc.incidents()

owner = 'Example Community'

# create a new Incident in 'Example Community' with the name: 'New Incident'
incident = incidents.add('New Incident', owner)
# set the event date for the Incident
incident.set_event_date('2017-03-21T00:00:00Z')  # REQUIRED

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

try:
    # create the Incident
    incident.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.

Supported Properties

Property Name Method Required
event_date set_event_date True

Update Incidents

The example below demonstrates how to update an Incident Resource 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 Incidents object
incidents = tc.incidents()

owner = 'Example Community'

# create an Incident with an updated name
incident = incidents.add('Updated Incident', owner)
# set the ID of the new Incident to the ID of the existing Incident you want to update
incident.set_id(123456)

# you can update the Incident metadata as described here: https://docs.threatconnect.com/en/latest/python/groups/groups.html#group-metadata

try:
    # update the Incident
    incident.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 Incidents

The example below demonstrates how to delete an Incident Resource 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 Incidents object
incidents = tc.incidents()

owner = 'Example Community'

# create an empty Incident
incident = incidents.add('', owner)
# set the ID of the new Incident to the ID of the Incident you would like to delete
incident.set_id(123456)

try:
    # delete the Incident
    incident.delete()
except RuntimeError as e:
    print(e)
    sys.exit(1)

Note

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

Signatures

The Signature Group represents an actual Signature that can be used for detection or prevention in a supported format (Snort®, YARA, CybOX™, OpenIOC, ClamAV®, Suricata, Bro, and Regex).

Retrieve Signatures

Retrieving a Single Signature

This example demonstrates how to retrieve a specific Signature using the Signature’s ID. The add_id filter specifies the ID of the Signature which you 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 Signatures object
signatures = tc.signatures()

# set a filter to retrieve only the Signature with ID: 123456
filter1 = signatures.add_filter()
filter1.add_id(123456)

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

# iterate through the retrieved Signatures (in this case there should only be one) and print its properties
for signature in signatures:
    print(signature.id)
    print(signature.name)
    print(signature.date_added)
    print(signature.weblink)

    # Signature specific property
    print(signature.type)

    print('')
Downloading a Signature’s Content

Example Python code for downloading the Signature contents for the Signature Resource:

signature.download()

if signature.contents is not None:
    print(signature.contents)

Retrieving Multiple Signatures

This example will demonstrate how to retrieve Signatures while applying filters. In this example, two filters will be added, one for the Owner and another for a Tag. The result set returned from this example will contain any Signatures in the Example Community Owner that has a Tag of EXAMPLE.

# 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 Signatures object
signatures = tc.signatures()

owner = 'Example Community'

# set a filter to only retrieve Signatures in the 'Example Community' tagged: 'Nation State'
filter1 = signatures.add_filter()
filter1.add_owner(owner)
filter1.add_tag('Nation State')

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

# iterate through the retrieved Signatures and print their properties
for signature in signatures:
    print(signature.id)
    print(signature.name)
    print(signature.date_added)
    print(signature.weblink)
    print('')

Note

The filter1 object contains a filters property that provides a list of supported filters for the resource type being retrieved. To display this list, print(filter1.filters) can be used. For more on using filters see the Advanced Filter Tutorial.

Create Signatures

The example below demonstrates how to create a Signature Resource 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 Signatures object
signatures = tc.signatures()

owner = 'Example Community'

# create a new Signature in 'Example Community' with the name: 'New Signature'
signature = signatures.add('New Signature', owner)

# define Signature's content
file_text = 'rule example_sig : example\n{\n'
file_text += 'meta:\n        description = "This '
file_text += 'is just an example"\n\n '
file_text += 'strings:\n        $a = {6A 40 68 00 '
file_text += '30 00 00 6A 14 8D 91}\n        $b = '
file_text += '{8D 4D B0 2B C1 83 C0 27 99 6A 4E '
file_text += '59 F7 F9}\n    condition:\n '
file_text += '$a or $b\n}'

# set the file name of the Signature
signature.set_file_name('bad_file.txt')  # REQUIRED
# set the type of the Signature
signature.set_file_type('YARA')  # REQUIRED
# set the contents of the signature
signature.set_file_text(file_text)  # REQUIRED

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

try:
    # create the Signature
    signature.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.

Supported Properties

Property Name Method Required
file_name set_file_name True
file_text set_file_text True
file_type set_file_type True

Update Signatures

The example below demonstrates how to update a Signature Resource 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 Signatures object
signatures = tc.signatures()

owner = 'Example Community'

# create a Signature with an updated name
signature = signatures.add('Updated Signature', owner)

# even if you are not updating these values, you need to set them
signature.set_file_name('updated.sig')
signature.set_file_type('Yara')

# set the ID of the new Signature to the ID of the existing Signature you want to update
signature.set_id(123456)

# you can update the Signature metadata as described here: https://docs.threatconnect.com/en/latest/python/groups/groups.html#group-metadata

try:
    # update the Signature
    signature.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 Signatures

The example below demonstrates how to delete a Signature Resource 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 Signatures object
signatures = tc.signatures()

owner = 'Example Community'

# create an empty Signature
signature = signatures.add('', owner)
# set the ID of the new Signature to the ID of the Signature you would like to delete
signature.set_id(123456)

try:
    # delete the Signature
    signature.delete()
except RuntimeError as e:
    print(e)
    sys.exit(1)

Note

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

Threats

The Threat Group represents a group of related activity, whether or not attribution is known. This relation can be based on technology (e.g., Shellshock) or pertain to a grouping of activity that is presumed to be by the same selection of actors (e.g., Bitterbug).

Retrieve Threats

Retrieving a Single Threat

This example demonstrates how to retrieve a specific Threat using the Threat’s ID. The add_id filter specifies the ID of the Threat which you 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 Threats object
threats = tc.threats()

# set a filter to retrieve only the Threat with ID: 123456
filter1 = threats.add_filter()
filter1.add_id(123456)

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

# iterate through the retrieved Threats (in this case there should only be one) and print its properties
for threat in threats:
    print(threat.id)
    print(threat.name)
    print(threat.date_added)
    print(threat.weblink)
    print('')

Retrieving Multiple Threats

This example will demonstrate how to retrieve Threats while applying filters. In this example, two filters will be added, one for the Owner and another for a Tag. The result set returned from this example will contain any Threats in the Example Community Owner that has a Tag of EXAMPLE.

# 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 Threats object
threats = tc.threats()

owner = 'Example Community'

# set a filter to only retrieve Threats in the 'Example Community' tagged: 'Nation State'
filter1 = threats.add_filter()
filter1.add_owner(owner)
filter1.add_tag('Nation State')

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

# iterate through the retrieved Threats and print their properties
for threat in threats:
    print(threat.id)
    print(threat.name)
    print(threat.date_added)
    print(threat.weblink)
    print('')

Note

The filter1 object contains a filters property that provides a list of supported filters for the resource type being retrieved. To display this list, print(filter1.filters) can be used. For more on using filters see the Advanced Filter Tutorial.

Create Threats

The example below demonstrates how to create a Threat Resource 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 Threat object
threats = tc.threats()

owner = 'Example Community'

# create a new Threat in 'Example Community' with the name: 'New Threat'
threat = threats.add('New Threat', owner)

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

try:
    # create the Threat
    threat.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.

Update Threats

The example below demonstrates how to update a Threat Resource 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 Threats object
threats = tc.threats()

owner = 'Example Community'

# create a Threat with an updated name
threat = threats.add('Updated Threat', owner)
# set the ID of the new Threat to the ID of the existing Threat you want to update
threat.set_id(123456)

# you can update the Threat metadata as described here: https://docs.threatconnect.com/en/latest/python/groups/groups.html#group-metadata

try:
    # update the Threat
    threat.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 Threats

The example below demonstrates how to delete an Threat Resource 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 Threats object
threats = tc.threats()

owner = 'Example Community'

# create an empty Threat
threat = threats.add('', owner)
# set the ID of the new Threat to the ID of the Threat you would like to delete
threat.set_id(123456)

try:
    # delete the Threat
    threat.delete()
except RuntimeError as e:
    print(e)
    sys.exit(1)

Note

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

Group Associations

Retrieve Group Associations

The code snippet below demonstrates how to view Groups, Indicators, and Victims which are associated with a given Group in ThreatConnect. This example is designed to retrieve the associations from an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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)

# define the ID of the group we would like to retrieve
incident_id = 123456

# create an incidents object
incidents = tc.incidents()

# set a filter to retrieve the incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # iterate through all associated Groups
    for associated_group in incident.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 incident.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('')

    # iterate through all associated Victims
    for associated_victim in incident.victim_associations:
        # print details about the associated Victim
        print(associated_victim.id)
        print(associated_victim.name)
        print(associated_victim.description)
        print(associated_victim.owner_name)
        print(associated_victim.nationality)
        print(associated_victim.org)
        print(associated_victim.suborg)
        print(associated_victim.work_location)
        print(associated_victim.weblink)
        print('')

Note

When the group_associations, indicator_associations, and victim_associations methods are called, an API request is invoked immediately.

Create Group Associations

The code snippet below demonstrates how to create an association between an Incident and another Group, Indicator, and Victim in ThreatConnect. This example is designed to create associations with an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

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)

# define the ID of the group we would like to retrieve
incident_id = 123456

# create an incidents object
incidents = tc.incidents()

# set a filter to retrieve the incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # create an association between this incident and the incident with the ID: 654321
    incident.associate_group(ResourceType.INCIDENTS, 654321)

    # create an association between this incident and the URL indicator: http://example.com/
    incident.associate_indicator(ResourceType.URLS, 'http://example.com/')

    # create an association between this incident and the victim with the ID: 333333
    incident.associate_victim(333333)

    # commit the changes to ThreatConnect
    incident.commit()

Note

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

Delete Group Associations

The code snippet below demonstrates how to remove an association between an Incident and another Group, Indicator, and Victim. This example is designed to remove the associations from an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

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)

# define the ID of the group we would like to retrieve
incident_id = 123456

# create an incidents object
incidents = tc.incidents()

# set a filter to retrieve the incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # remove the association between this incident and the incident with the ID: 654321
    incident.disassociate_group(ResourceType.INCIDENTS, 654321)

    # remove the association between this incident and the URL indicator: http://example.com/
    incident.disassociate_indicator(ResourceType.URLS, 'http://example.com/')

    # remove the association between this incident and the victim with the ID: 333333
    incident.disassociate_victim(333333)

    # commit the changes to ThreatConnect
    incident.commit()

Note

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

Group Metadata

Group Attributes

Retrieve Group Attributes

The code snippet below demonstrates how to retrieve the attributes from an Incident. This example is designed to delete attributes from an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # load the Incident's attributes
    incident.load_attributes()

    # iterate through the attributes and print out their properties
    for attribute in incident.attributes:
        print(attribute.id)
        print(attribute.type)
        print(attribute.value)
        print(attribute.date_added)
        print(attribute.last_modified)
        print(attribute.displayed)
        print('')

Create Group Attributes

The code snippet below demonstrates how to create an attribute on an Incident. This example is designed to create attributes on an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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 Incidents object
incidents = tc.incidents()

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# set a filter to retrieve the Incidents with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

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

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

    # commit the changes
    incident.commit()

Note

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

Update Group Attributes

The code snippet below demonstrates how to update an Incident’s attribute. This example assumes there is an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # load the Incident's attributes
    incident.load_attributes()

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

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

    # commit the changes
    incident.commit()

Note

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

Delete Group Attributes

The code snippet below demonstrates how to delete an Incident’s attribute. This example is designed to delete attributes from an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # load the Incident's attributes
    incident.load_attributes()

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

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

    # commit the changes
    incident.commit()

Note

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

Group Security Labels

Retrieve Group Security Labels

The code snippet below demonstrates how to retrieve the security label from an Incident. This example assumes there is an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # load the Incident's security label
    incident.load_security_label()

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

Warning

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

Create Group Security Labels

The code snippet below demonstrates how to add a security label to an Incident. This example assumes there is an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>(). This snippet also assumes that the target owner has a ‘TLP Green’ 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

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

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

Note

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

Delete Group Security Labels

The code snippet below demonstrates how to delete a security label from an Incident. This example assumes there is an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>(). This snippet also assumes that the target owner has a ‘TLP Green’ 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

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

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

Note

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

Group Tags

Retrieve Group Tags

The code snippet below demonstrates how to retrieve the tags from an Incident. This example assumes there is an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # load the Incident's tags
    incident.load_tags()

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

Create Group Tags

The code snippet below demonstrates how to add a tag to an Incident. This example assumes there is an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # add the 'Test' tag to the Incident
    incident.add_tag('Test')

    # commit the Incident with the new tag to ThreatConnect
    incident.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 Group Tags

The code snippet below demonstrates how to delete a tag from an Incident. This example assumes there is an Incident with an ID of 123456. To test this code snippet, change the incident_id variable to the ID of an incident in your owner. This same process also applies to all group types. Simply change tc.incidents() to the group type you would like to retrieve. The available group types are: tc.<adversaries|campaigns|documents|emails|incidents|signatures|threats>().

# 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)

# define the ID of the Incident we would like to retrieve
incident_id = 123456

# create an Incidents object
incidents = tc.incidents()

# set a filter to retrieve the Incident with the id: 123456
filter1 = incidents.add_filter()
filter1.add_id(incident_id)

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

# iterate through the Incidents
for incident in incidents:
    print(incident.name)

    # remove the 'Test' tag from the Incident
    incident.delete_tag('Test')

    # commit the Incident with the removed tag to ThreatConnect
    incident.commit()

Note

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