Tasks

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

Retrieve Tasks

Filtering Tasks

When retrieving Tasks from ThreatConnect, it is possible to filter the results. Results can be filtered on the following data points:

Filter Data Type Operator(s)
name string =, ^
dateAdded date <, >
status string =, !
assignee string =
escalatee string =
overdue boolean =
escalated boolean =
dueDate date <, >
reminded boolean =

Hint

The “^” character means “starts with”. For example, this character would be used to find all URL Indicators that start with http://xn-- or all Groups whose name starts with APT.

Note

The =, <, >, and ^ operators in any filters must URL encoded as follows:

Character URL Encoded Form
= %3D
< %3C
> %3E
^ %5E

The following query will return all Tasks that start with “Test” (name^Test):

GET /v2/tasks/?filters=name%5ETest

The following query will return all Tasks whose name is “Test” (name=Test):

GET /v2/tasks/?filters=name%3DTest

The following query will return all Tasks whose status is “Not Started” (status=Not Started):

GET /v2/tasks/?filters=status%3DNot%20Started

The following query will return all Tasks assigned to the user with the username “johndoe@example.com” (assignee=johndoe@example.com):

GET /v2/tasks/?filters=assignee%3Djohndoe%40example.com

The following query will return all Tasks that will be escalated to the user with the username “manager@example.com” (escalatee=manager@example.com):

GET /v2/tasks/?filters=escalatee%3Dmanager%40example.com

The following query will return all overdue Tasks (overdue=true):

GET /v2/tasks/?filters=overdue%3Dtrue

The following query will return all escalated Tasks (escalated=true):

GET /v2/tasks/?filters=escalated%3Dtrue

The following query will return all Tasks with a due date after 2017-07-25 (dueDate>2017-07-25):

GET /v2/tasks/?filters=dueDate%3E2017-07-25

The following query will return all Tasks for which a reminder has been sent (reminded=true):

GET /v2/tasks/?filters=reminded%3Dtrue

Retrieve Multiple Tasks

To retrieve all Tasks in the default owner, use the following query:

GET /v2/tasks

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "task": [
      {
        "id": "54321",
        "name": "Send Domains to IR Team",
        "ownerName": "Example Organization",
        "dateAdded": "2017-07-13T17:50:17",
        "webLink": "https://app.threatconnect.com/auth/workflow/task.xhtml?task=54321",
        "status": "Not Started",
        "escalated": false,
        "reminded": false,
        "overdue": false,
        "dueDate": "2017-07-24T00:00:00Z"
      }
    ]
  }
}

Retrieve a Single Task

To retrieve a single Task, use a query in the following format:

GET /v2/tasks/{taskId}

For example, if you wanted to retrieve the Task with ID 12345, you would use the following query:

GET /v2/tasks/12345

JSON Response:

{
  "status": "Success",
  "data": {
    "task": {
      "id": "54321",
      "name": "Test",
      "owner": {
        "id": 5,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "webLink": "https://app.threatconnect.com/auth/workflow/task.xhtml?task=54321",
      "status": "Not Started",
      "escalated": false,
      "reminded": false,
      "overdue": false,
      "dueDate": "2017-07-24T00:00:00Z",
      "assignee": [
        {
          "userName": "johndoe@example.com",
          "firstName": "John",
          "lastName": "Doe"
        }
      ]
    }
  }
}

Retrieve Task Metadata

Retrieve Task Attributes

To retrieve a Task’s Attributes, use the following format:

GET /v2/tasks/{taskId}/attributes

For example, if you wanted to retrieve the attributes on the Task with ID 12345, you would use the following query:

GET /v2/tasks/12345/attributes

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "attribute": [
      {
        "id": "54321",
        "type": "Description",
        "dateAdded": "2016-07-13T17:50:17",
        "lastModified": "2017-05-02T18:40:22Z",
        "displayed": true,
        "value": "Description Example"
      },
      {
        "id": "54322",
        "type": "Source",
        "dateAdded": "2016-07-13T17:51:17",
        "lastModified": "2017-05-02T18:40:22Z",
        "displayed": true,
        "value": "Source Example"
      }
    ]
  }
}

To retrieve the Security Labels that are on an Attribute, use the following format:

GET /v2/tasks/{taskId}/attributes/{attributeId}/securityLabels

Here is an example query:

GET /v2/tasks/12345/attributes/54321/securityLabels

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "securityLabel": [
      {
        "name": "TLP Amber",
        "description": "TLP Amber information requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
        "dateAdded": "2017-07-13T17:50:17"
      }
    ]
  }
}

Retrieve Task Security Labels

To retrieve the Security Labels for a Task, use a query in the following format:

GET /v2/tasks/{taskId}/securityLabels

For example, the query below will retrieve all Security Labels for the Task with ID 12345:

GET /v2/tasks/12345/securityLabels

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "securityLabel": [
      {
        "name": "TLP Amber",
        "description": "TLP Amber information requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
        "dateAdded": "2017-07-13T17:50:17"
      }
    ]
  }
}

Retrieve Task Tags

To retrieve the Tags for a Task, use a query in the following format:

GET /v2/tasks/{taskId}/tags

For example, the query below will retrieve all Tags for the Task with ID 12345:

GET /v2/tasks/12345/tags

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "tag": [
      {
        "name": "Nation State",
        "webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=Nation+State&owner=Common+Community"
      }
    ]
  }
}

Retrieve Task Associations

Group to Task Associations

To view Groups associated with a given Task, use a query in the following format:

GET /v2/tasks/{taskId}/groups

For example, the query below will retrieve all of the Groups associated with a Task with ID 12345:

GET /v2/tasks/12345/groups

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "task": [
      {
        "id": "54321",
        "name": "New Incident",
        "type": "Incident",
        "ownerName": "Example Organization",
        "dateAdded": "2017-07-13T17:50:17",
        "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=54321"
      }
    ]
  }
}

You can also find associated Groups of a given type using the following format:

GET /v2/tasks/{taskId}/groups/{associatedGroupType}

Replace {associatedGroupType} with one of the following Group types:

  • adversaries
  • campaigns
  • documents
  • emails
  • events
  • incidents
  • intrusionSets
  • reports
  • signatures
  • threats

For example, we could use the following query to find all Incidents associated with the Task with ID 12345:

GET /v2/tasks/12345/groups/incidents

We can also drill down even further by adding the ID of an associated Group to the end of the query like:

GET /v2/tasks/12345/groups/incidents/54321

Where 54321 is the ID of an Incident associated with Task 12345.

Indicator to Task Associations

To view Indicators associated with a given Task, use a query in the following format:

GET /v2/tasks/{taskId}/indicators

For example, the query below will retrieve all of the Indicators associated with a Task with ID 12345:

GET /v2/tasks/12345/indicators

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "indicator": [
      {
        "id": "54321",
        "ownerName": "Example Organization",
        "type": "Address",
        "dateAdded": "2016-07-13T17:50:17",
        "lastModified": "2017-05-01T21:32:54Z",
        "rating": 3.0,
        "confidence": 55,
        "threatAssessRating": 3.0,
        "threatAssessConfidence": 55.0,
        "webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=0.0.0.0&owner=Example+Organization",
        "summary": "0.0.0.0"
      }
    ]
  }
}

You can also find associated Indicators of a given type using the following format:

GET /v2/tasks/{taskId}/indicators/{associatedIndicatorType}

For example, we could use the following query to find all Address Indicators associated with the Task with ID 12345:

GET /v2/tasks/12345/indicators/addresses

Victim Asset to Task Associations

To view Victim Assets associated with a given Task, use a query in the following format:

GET /v2/tasks/{taskId}/victimAssets

For example, the query below will retrieve all of the Victim Assets associated with a Task with ID 12345:

GET /v2/tasks/12345/victimAssets

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 2,
    "victimAsset": [
      {
        "id": "54321",
        "name": "bad@badguys.com",
        "type": "EmailAddress",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=123"
      },
      {
        "id": "54322",
        "name": "nobody@gmail.com",
        "type": "EmailAddress",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=123"
      }
    ]
  }
}

You can also find associated Victim Assets of a given type using the following format:

GET /v2/tasks/{taskId}/victimAssets/{victimAssetType}

The available Victim Asset types are:

  • emailAddresses
  • networkAccounts
  • phoneNumbers
  • socialNetworks
  • webSites

For example, we could use the following query to find all Victim Assets that are Email Addresses which are associated with the Task with ID 12345:

GET /v2/tasks/12345/victimAssets/emailAddresses

We can also drill down even further by adding the ID of an associated Victim Asset to the end of the query like:

GET /v2/tasks/12345/victimAssets/emailAddresses/54321

Where 54321 is the ID of a Victim Asset associated with Task 12345.

Victim to Task Associations

To view Victims associated with a given Task, use a query in the following format:

GET /v2/tasks/{taskId}/victims

For example, the query below will retrieve all of the Victims associated with a Task with ID 12345:

GET /v2/tasks/12345/victims

JSON Response:

{
  "status": "Success",
  "data": {
    "resultCount": 1,
    "victim": [
      {
        "id": "54321",
        "name": "Bad Guy",
        "org": "Example Organization",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=54321"
      }
    ]
  }
}

We can also drill down even further by adding the ID of an associated Victim to the end of the query like:

GET /v2/tasks/12345/victims/54321

Where 54321 is the ID of a Victim associated with Task 12345.

Create Tasks

To create a Task, the most basic format is:

POST /v2/tasks/
Content-type: application/json; charset=utf-8

{
  "name": "Test Task"
}

Some task types require additional fields when being created. Refer to the table below for the available fields for Tasks:

Valid Fields Required Example Value
name TRUE “New Task”
assignee FALSE [ {“userName” : “analyst@threatconnect.com”} ]
escalatee FALSE [ {“userName” : “manager@threatconnect.com”} ]
dueDate FALSE “2018-03-20T13:36:53-04:00”
escalationDate FALSE “2018-07-13T13:36:53-04:00”
description FALSE “Send to IR team for triage.”

By way of example, the query below will create a Task in the default owner with the name Test Task that is due on 2017-07-13:

POST /v2/tasks/
Content-type: application/json; charset=utf-8

{
  "name": "Test Task",
  "dueDate": "2017-07-13T13:36:53-04:00"
}

JSON Response:

{
  "status": "Success",
  "data": {
    "task": {
      "id": "54321",
      "name": "Test Task",
      "owner": {
        "id": 1,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "webLink": "https://app.threatconnect.com/auth/task/task.xhtml?task=54321",
      "dueDate": "2017-07-13T13:36:53-04:00"
    }
  }
}

The code below will do the same thing as above, but it will also assign the task to the user with the username johndoe@example.com:

POST /v2/tasks/
Content-type: application/json; charset=utf-8

{
  "name": "Test Task",
  "dueDate": "2017-07-13T13:36:53-04:00",
  "assignee": [
    {
      "userName": "johndoe@example.com"
    }
  ]
}

JSON Response:

{
  "status": "Success",
  "data": {
    "task": {
      "id": "54321",
      "name": "Test Task",
      "owner": {
        "id": 1,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "webLink": "https://app.threatconnect.com/auth/task/task.xhtml?task=54321",
      "dueDate": "2017-07-13T13:36:53-04:00",
      "assignee": [
        {
          "userName": "johndoe@example.com",
          "firstName": "John",
          "lastName": "Doe"
        }
      ]
    }
  }
}

The code below will do the same thing as above, but it will also assign the task to the two users whose usernames are johndoe@example.com and janedoe@example.com:

POST /v2/tasks/
Content-type: application/json; charset=utf-8

{
  "name": "Test Task",
  "dueDate": "2017-07-13T13:36:53-04:00",
  "assignee": [
    {
      "userName": "johndoe@example.com"
    },
    {
      "userName": "janedoe@example.com"
    }
  ]
}

The code below will do the same thing as above, but instead of assigning the task to the users johndoe@example.com and janedoe@example.com, it will assign the task to johndoe@example.com and set janedoe@example.com as the escalatee:

POST /v2/tasks/
Content-type: application/json; charset=utf-8

{
  "name": "Test Task",
  "dueDate": "2017-07-13T13:36:53-04:00",
  "assignee": [
    {
      "userName": "johndoe@example.com"
    }
  ],
  "escalatee": [
    {
      "userName": "janedoe@example.com"
    }
  ]
}

Create Task Metadata

Create Task Attributes

To add an attribute to a Task, use the following format:

POST /v2/tasks/{taskId}/attributes
Content-type: application/json; charset=utf-8

{
  "type" : {attributeType},
  "value" : "Test Attribute",
  "displayed" : true
}

For example, if you wanted to add a Description attribute to the Task with ID 12345, you would use the following query:

POST /v2/tasks/12345/attributes
Content-type: application/json; charset=utf-8

{
  "type" : "Description",
  "value" : "Test Description",
  "displayed" : true
}

JSON Response:

{
  "status": "Success",
  "data": {
    "attribute": {
      "id": "54321",
      "type": "Description",
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-07-13T17:50:17",
      "displayed": true,
      "value": "Test Description"
    }
  }
}

To add a Security Label to an attribute, use the following format where {securityLabel} is replaced with the name of a Security Label that already exists in the owner:

POST /v2/tasks/{taskId}/attributes/{attributeId}/securityLabels/{securityLabel}

For example, the query below will add a TLP Amber Security Label to the attribute on the Task:

POST /v2/tasks/12345/attributes/54321/securityLabels/TLP%20Amber

Note

In order to add a Security Label to an attribute, the Security Label must already exist. The query above will not create a new Security Label. If you specify a Security Label that does not exist, it will return an error.

Create Task Security Labels

To add a Security Label to a Task, use the following format where {securityLabel} is replaced with the name of a Security Label that already exists in the owner:

POST /v2/tasks/{taskId}/securityLabels/{securityLabel}

For example, the query below will add a TLP Amber Security Label to the Task with ID 12345:

POST /v2/tasks/12345/securityLabels/TLP%20Amber

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

Note

In order to add a Security Label to a Task, the Security Label must already exist. The query above will not create a new Security Label. If you specify a Security Label that does not exist, it will return an error.

Create Task Tags

To add a Tag to a Task, use the following format where {tagName} is replaced with the name of the tag you wish to add to the Task:

POST /v2/tasks/{taskId}/tags/{tagName}

For example, the query below will add the Nation State tag to the Task with ID 12345:

POST /v2/tasks/12345/tags/Nation%20State

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

Note

The length of a tag is limited to 128 characters.

Create Task Associations

Associate Group to Task

To associate a Task with a Group, use a query in the following format:

POST /v2/tasks/{taskId}/groups/{associatedGroupType}/{associatedGroupId}

Replace {associatedGroupType} with one of the following Group types:

  • adversaries
  • campaigns
  • documents
  • emails
  • events
  • incidents
  • intrusionSets
  • reports
  • signatures
  • threats

For example, the query below will associate a Task with ID 12345 with an Incident with the ID 54321:

POST /v2/tasks/12345/groups/incidents/54321

JSON Response:

{
  "status": "Success"
}

Associate Indicator to Task

To associate a Task with an Indicator, use a query in the following format:

POST /v2/tasks/{taskId}/indicators/{associatedIndicatorType}/{associatedIndicator}

For example, the query below will associate the Task with ID 12345 with the IP Address 0.0.0.0:

POST /v2/tasks/12345/indicators/addresses/0.0.0.0

JSON Response:

{
  "status": "Success"
}

Associate Victim to Task

To associate a Task with a Victim, use a query in the following format:

POST /v2/tasks/{taskId}/victims/{victimId}

For example, the query below will associate the Task with ID 12345 with the Victim with ID 54321:

POST /v2/tasks/12345/victims/54321

JSON Response:

{
  "status": "Success"
}

Warning

In order to associate a Victim with any item, that Victim must have at least one Victim Asset.

Update Tasks

To update a Task, the basic format is:

PUT /v2/tasks/{taskId}
{
  {updatedField}: {updatedValue}
}

When updating the fields on a Task itself, you can change any of the following fields:

Valid Fields Example Value
name “New Task”
assignee { “userName” : [“analyst@threatconnect.com”] }
escalatee { “userName” : [“manager@threatconnect.com”] }
dueDate “2016-03-20T13:36:53-04:00”
description “Send to IR team for triage.”
status “Not Started”

Note

The available statuses for a Task are:

  • Not Started
  • In Progress
  • Completed
  • Waiting on Someone
  • Deferred

By way of example, the query below will update the name and due date of the Task with ID 12345:

PUT /v2/tasks/12345
{
  "name": "New Task Name",
  "dueDate": "2017-07-13T13:36:53-04:00"
}

JSON Response:

{
  "status": "Success",
  "data": {
    "task": {
      "id": "12345",
      "name": "New Task Name",
      "owner": {
        "id": 1,
        "name": "Example Organization",
        "type": "Organization"
      },
      "dateAdded": "2017-07-13T17:50:17",
      "webLink": "https://app.threatconnect.com/auth/task/task.xhtml?task=12345",
      "dueDate": "2017-07-13T13:36:53-04:00"
    }
  }
}

Update Task Metadata

Update Task Attributes

To update a Task’s attribute, use the following format:

PUT /v2/tasks/{taskId}/attributes/{attributeId}
{
  {updatedField}: {updatedValue}
}

When updating attributes, you can change the following fields:

Updatable Attribute Fields Required
value TRUE
displayed FALSE
source FALSE

For example, if you wanted to update the value of an attribute with ID 54321 on the Task with ID 12345, you would use the following query:

PUT /v2/tasks/12345/attributes/54321
{
  "value": "A new attribute value."
}

JSON Response:

{
  "status": "Success",
  "data": {
    "attribute": {
      "id": "54321",
      "type": "Description",
      "dateAdded": "2017-07-13T17:50:17",
      "lastModified": "2017-07-19T15:54:12Z",
      "displayed": true,
      "value": "A new attribute value."
    }
  }
}

Delete Tasks

To delete a Task, the most basic format is:

DELETE /v2/tasks/{taskId}

By way of example, the query below will delete the Task with ID 12345:

DELETE /v2/tasks/12345

JSON Response:

{
    "apiCalls": 1,
    "resultCount": 0,
    "status": "Success"
}

Delete Task Metadata

Delete Task Attributes

To delete an attribute from a Task, use the following format:

DELETE /v2/tasks/{taskId}/attributes/{attributeId}

For example, if you wanted to delete the attribute with ID 54321 from the Task with ID 12345, you would use the following query:

DELETE /v2/tasks/12345/attributes/54321

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

To delete a Security Label from an attribute, use the following format where {securityLabel} is replaced with the name of a Security Label that already exists in the owner:

DELETE /v2/tasks/{taskId}/attributes/{attributeId}/securityLabels/{securityLabel}

For example, the query below will remove the TLP Amber Security Label from the attribute with ID 54321 on the Task:

DELETE /v2/tasks/12345/attributes/54321/securityLabels/TLP%20Amber

Delete Task Security Labels

To delete a Security Label from a Task, use the following format where {securityLabel} is replaced with the name of a Security Label:

DELETE /v2/tasks/{taskId}/securityLabels/{securityLabel}

For example, the query below will delete the TLP Amber Security Label to the Task with ID 12345:

DELETE /v2/tasks/12345/securityLabels/TLP%20Amber

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

Delete Task Tags

To delete a tag from a Task, use the following format where {tagName} is replaced with the name of the tag you wish to remove from the Task:

DELETE /v2/tasks/{taskId}/tags/{tagName}

For example, the query below will delete the Nation State tag to the Task with ID 12345:

DELETE /v2/tasks/12345/tags/Nation%20State

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

Delete/Disassociate Task Associations

Disassociate Group from Task

To disassociate a Task from a Group, use a query in the following format:

DELETE /v2/tasks/{taskId}/groups/{associatedGroupType}/{associatedGroupId}

Replace {associatedGroupType} with one of the following Group types:

  • adversaries
  • campaigns
  • documents
  • emails
  • events
  • incidents
  • intrusionSets
  • reports
  • signatures
  • threats

For example, the query below will disassociate a Task with ID 12345 from an Incident with the ID 54321:

DELETE /v2/tasks/12345/groups/incidents/54321

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

Disassociate Indicator from Task

To disassociate a Task from an Indicator, use a query in the following format:

DELETE /v2/tasks/{taskId}/indicators/{associatedIndicatorType}/{associatedIndicator}

For example, the query below will disassociate the Task with ID 12345 from the IP Address 0.0.0.0:

DELETE /v2/tasks/12345/indicators/addresses/0.0.0.0

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

Disassociate Victim Asset from Task

To disassociate a Task from a Victim Asset, use a query in the following format:

DELETE /v2/tasks/{taskId}/victimAssets/{victimAssetType}/{victimAssetId}

For example, the query below will disassociate the Task with ID 12345 from the Victim Asset with ID 54321:

DELETE /v2/tasks/12345/victimAssets/emailAddresses/54321

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}

Disassociate Victim from Task

To disassociate a Task from a Victim, use a query in the following format:

DELETE /v2/tasks/{taskId}/victims/{victimId}

For example, the query below will disassociate the Task with ID 12345 from the Victim with ID 54321:

DELETE /v2/tasks/12345/victims/54321

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "status": "Success"
}