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()
events = tc.events()
incidents = tc.incidents()
intrusionSets = tc.intrusionSets()
reports = tc.reports()
signatures = tc.signatures()
threats = tc.threats()
The following, high-level actions can be performed on Group objects:
retrieve()- retrieve Group/Groups from ThreatConnectcommit()- commit a new or updated Group to ThreatConnectdelete()- 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 |
|---|---|---|
|
int |
Filter Groups by ID. |
|
int |
Filter Groups on associated Adversary ID. |
|
int |
Filter Groups on associated Campaign ID. |
|
int |
Filter Groups on associated Document ID. |
|
int |
Filter Groups on associated Email ID. |
|
int |
Filter Groups on associated Incident ID. |
|
str |
Filter Groups on associated Indicator. |
|
list or str |
Filter Groups on Owner. |
|
str |
Filter Groups on applied Security Label. |
|
int |
Filter Groups on associated Signature ID. |
|
str |
Filter Groups on applied Tag. |
|
int |
Filter Groups on associated Task ID. |
|
int |
Filter Groups on associated Threat 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 |
|---|---|---|
|
str |
Filter Groups on name. |
|
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 groups 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('[email protected]') # OPTIONAL
email.set_header('This is an improper email header.') # REQUIRED
email.set_subject('This is an email subject.') # REQUIRED
email.set_to('[email protected]') # 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.
Note
The API accepts customized Signature types.
# 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.