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 be 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 want 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": "[email protected]",
"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 want 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": "This security label is used for information that requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved. Information with this label can be shared with members of an organization and its clients.",
"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": "This security label is used for information that requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved. Information with this label can be shared with members of an organization and its clients.",
"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 whose ID is 12345:
GET /v2/tasks/12345/tags
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 2,
"tag": [
{
"name": "Nation State",
"webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=12&owner=Example+Organization"
},
{
"name": "Phishing",
"webLink": "https://app.threatconnect.com/auth/tags/tag.xhtml?tag=339"
}
]
}
}
Note
If a Tag object in the response represents an ATT&CK® Tag, then the &owner=
portion of the URL will not be included in the webLink
field. This is because ATT&CK Tags do not belong to an owner.
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",
"lastModified": "2017-07-13T17:51: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}/{associatedGroupType}
Replace {associatedGroupType}
with one of the following Group types:
adversaries
attackPatterns
campaigns
coursesOfAction
documents
emails
events
incidents
intrusionSets
malware
reports
signatures
tactics
threats
tools
vulnerabilities
For example, you could use the following query to find all Incidents associated with the Task with ID 12345:
GET /v2/tasks/12345/incidents
You can also delve further by adding the ID of an associated Group to the end of the query:
GET /v2/tasks/12345/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,
"threatAssessScore": 389,
"calIndicatorStatus": 2,
"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, you 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": "[email protected]",
"type": "EmailAddress",
"webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=123"
},
{
"id": "54322",
"name": "[email protected]",
"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, you 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
You can delve further by adding the ID of an associated Victim Asset to the end of the query:
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",
"suborg": "HR Department",
"workLocation": "Washington, D.C.",
"nationality": "American",
"webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=54321"
}
]
}
}
You can delve further by adding the ID of an associated Victim to the end of the query:
GET /v2/tasks/12345/victims/54321
Where 54321
is the ID of a Victim associated with Task 12345.
Create Tasks¶
The most basic format used for creating a Task 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.” |
For 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",
"status": "Not Started",
"escalated": false,
"reminded": false,
"overdue": false,
"dueDate": "2017-07-13T13:36:53-04:00"
}
}
}
The code below will function as the code 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": "[email protected]"
}
]
}
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",
"status": "Not Started",
"escalated": false,
"reminded": false,
"overdue": false,
"dueDate": "2017-07-13T13:36:53-04:00",
"assignee": [
{
"userName": "[email protected]",
"firstName": "John",
"lastName": "Doe"
}
]
}
}
}
The code below will function as the code 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": "[email protected]"
},
{
"userName": "[email protected]"
}
]
}
The code below will function as the code 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": "[email protected]"
}
],
"escalatee": [
{
"userName": "[email protected]"
}
]
}
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%3AAMBER
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%3AAMBER
JSON Response:
{
"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 want 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 whose ID is 12345:
POST /v2/tasks/12345/tags/Nation%20State
JSON Response:
{
"status": "Success"
}
Note
The length of a Tag is limited to 128 characters.
Attention
When applying ATT&CK Tags to an object, do not include the corresponding technique/sub-technique ID in the Tag’s name. For example, to apply the T1566 - Phishing
ATT&CK Tag to an object, use Phishing
as the Tag name.
Also, if you applied a new Tag to an object and that Tag matches a synonymous Tag listed in a Tag normalization rule, it will be converted to the main Tag listed in the rule. Similarly, if you applied a new Tag to an object and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.
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
attackPatterns
campaigns
coursesOfAction
documents
emails
events
incidents
intrusionSets
malware
reports
signatures
tactics
threats
tools
vulnerabilities
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¶
The basic format used to update a Task is:
PUT /v2/tasks/{taskId}
{
{updatedField}: {updatedValue}
}
When updating the fields on a Task, 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
For 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-15T13: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",
"lastModified": "2017-07-13T18:12:39"
"webLink": "https://app.threatconnect.com/auth/task/task.xhtml?task=12345",
"dueDate": "2017-07-15T13:36:53-04:00"
}
}
}
Update Task Metadata¶
Update Task Attributes¶
To update a Task’s Attributes, 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}
For example, the query below will delete the Task with ID 12345:
DELETE /v2/tasks/12345
JSON Response:
{
"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 want 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:
{
"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%3AAMBER
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%3AAMBER
JSON Response:
{
"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:
{
"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
attackPatterns
campaigns
coursesOfAction
documents
emails
events
incidents
intrusionSets
malware
reports
signatures
tactics
threats
tools
vulnerabilities
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:
{
"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:
{
"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:
{
"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:
{
"status": "Success"
}