Tasks

The Task Group represents an assignment given to a ThreatConnect user.

Filtering Tasks

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

Retrieve Tasks

Retrieving a Single Task

# 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 Tasks object
tasks = tc.tasks()

owner = 'Example Community'
task_id = 123456

# set a filter to retrieve only the Task with ID: 123456
filter1 = tasks.add_filter()
filter1.add_owner(owner)
filter1.add_id(task_id)

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

try:
    # prove there is only one Task retrieved
    assert len(tasks) == 1
except AssertionError as e:
    # if the Task doesn't exist in the given owner, raise an error
    print('AssertionError: The task with id {0} was not found in the "{1}" owner. '.format(task_id, owner) +
          'Try changing the `owner` variable to the name of an owner in your instance of ThreatConnect ' +
          'and/or set the `task_id` variable to the ID of a task that exists in the given owner.')
    sys.exit(1)

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

Note

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

Retrieving Multiple Tasks

# 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 Tasks object
tasks = tc.tasks()

# set a filter to retrieve only Tasks with the tag: "Nation State"
filter1 = tasks.add_filter()
filter1.add_tag('Nation State')

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

# iterate through the retrieved Tasks and print their properties
for task in tasks:
    print(task.id)
    print(task.name)
    print(task.date_added)
    print(task.weblink)
    print('')

Create Tasks

The example below demonstrates how to create a Task 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 Tasks object
tasks = tc.tasks()

# create a new Task
task = tasks.add('New Task')

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

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

Note

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

Note

Other task-specific data such as Assignee or Escalation Date can be modified using built-in library functions

Update Tasks

The example below demonstrates how to update a Task 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 Tasks object
tasks = tc.tasks()

# create a new Task object with an updated name
task = tasks.add('Updated Task')
# set the ID of the new Task to the ID of the existing Task you want to update
task.set_id(123456)

# you can update the Task metadata as described here: https://docs.threatconnect.com/en/latest/python/tasks/tasks.html#task-metadata

try:
    # update the Task
    task.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 Tasks

The example below demonstrates how to delete a Task 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 Tasks object
tasks = tc.tasks()

owner = 'Example Community'

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

try:
    # delete the Task
    task.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.

Task Associations

Retrieve Task Associations

The code snippet below demonstrates how to view Groups, Indicators, and Victims which are associated with a given Task in ThreatConnect. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# instantiate Tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks and print their associations
for task in tasks:
    print(task.name)

    # iterate through all associated groups
    for associated_group in task.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 task.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 task.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 Task Associations

The code snippet below demonstrates how to create an association between a Task and another Group, Indicator, and Victim in ThreatConnect. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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 task we would like to retrieve
task_id = 123456

# instantiate Tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

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

    # commit the changes to ThreatConnect
    task.commit()

Note

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

Delete Task Associations

The code snippet below demonstrates how to remove an association between a Task and another Group, Indicator, and Victim. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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 task we would like to retrieve
task_id = 123456

# instantiate Tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

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

    # commit the changes to ThreatConnect
    task.commit()

Note

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

Task Metadata

Task Attributes

Retrieve Task Attributes

The code snippet below demonstrates how to retrieve the attributes from a Task. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

Create Task Attributes

The code snippet below demonstrates how to create an attribute on a Task. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

    # commit the changes
    task.commit()

Note

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

Update Task Attributes

The code snippet below demonstrates how to update a Task’s attribute. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

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

    # commit the changes
    task.commit()

Note

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

Delete Task Attributes

The code snippet below demonstrates how to delete a Task’s attribute. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

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

    # commit the changes
    task.commit()

Note

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

Task Security Labels

Retrieve Task Security Labels

The code snippet below demonstrates how to retrieve the security label from a Task. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

Warning

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

Create Task Security Labels

The code snippet below demonstrates how to add a security label to a Task. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

Note

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

Delete Task Security Labels

The code snippet below demonstrates how to delete a security label from a Task. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

Note

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

Task Tags

Retrieve Task Tags

The code snippet below demonstrates how to retrieve the tags from a Task. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

Create Task Tags

The code snippet below demonstrates how to add a tag to a Task. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

    # commit the task with the new tag to ThreatConnect
    task.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 Task Tags

The code snippet below demonstrates how to delete a tag from a Task. This example assumes there is a Task with an ID of 123456 in the target owner. To test this code snippet, change the task_id variable to the ID of a task in your owner.

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

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

# define the ID of the task we would like to retrieve
task_id = 123456

# create a tasks object
tasks = tc.tasks()

# set a filter to retrieve the task with the id: 123456
filter1 = tasks.add_filter()
filter1.add_id(task_id)

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

# iterate through the Tasks
for task in tasks:
    print(task.name)

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

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

Note

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