Groups¶
Groups represent a collection of related behavior and intelligence.
Endpoint: /api/v3/groups
Note
When working with Groups using the ThreatConnect REST API, you may need to specify the ID of the Group with which you would like to work. While the ID of a Group can be retrieved from the API, it can also be found in the URL of each Group.
If you navigate to the Details screen for a Group, the URL should look 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 (123456
in this example) is the ID for the Group.
Available Fields¶
You can retrieve a list of available fields for the /v3/groups
endpoint, including each field’s name, description, and accepted data type, by using the following query:
OPTIONS /v3/groups
Hint
To view all fields, including read-only fields, include the ?show=readonly
query parameter.
Alternatively, refer to the following table for a list of available fields that can be included in the body of a POST or PUT request for all Group types.
Field | Description | Type | Required for Creation? | Updatable? | Example Value(s) |
---|---|---|---|---|---|
associatedArtifacts | A list of Artifacts associated to the Group | Artifact Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{ “caseId”: 1, “summary”: “badguy@bad.com”, “type”: “Email Address”}]}
|
associatedCases | A list of Cases associated to the Group | Case Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“name”: “Hacker Investigation”, “status”: “Open”, “severity”: “Low” }]}}
|
associatedGroups | A list of Groups associated to the Group | Group Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
|
associatedIndicators | A list of Indicators associated to the Group | Indicator Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“hostName”:”badguy.com”, “type”: “Host”}]}
|
associatedVictimAssets | A list of Victim Assets associated to the Group | Victim Asset Object | FALSE | TRUE | {“data”: [{“id”: 12345}]}
{“data”: [{“phone”: “0123456789”, “type”: “Phone”}]}
|
attributes | A list of Attributes corresponding to the Group | Group Attribute Object | FALSE | TRUE | {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”]}} |
name | The Group’s name | String | TRUE | TRUE | “21-0043847: Threat Actor Capabilities” |
securityLabels | A list of Security Labels applied to the Group | Security Label Object | FALSE | TRUE | {“data”: [{“name”: “TLP:AMBER”}]} |
tags | A list of Tags applied to the Group | Tag Object | FALSE | TRUE | {“data”: [{“name”: “Targeted Attack”}]} |
type | The type of Group being created | String | TRUE | FALSE | “Document”, “Email” |
Accepted values for the type
field include:
Adversary
Attack Pattern
Campaign
Course of Action
Document
Email
Event
Incident
Intrusion Set
Malware
Report
Signature
Tactic
Task
Threat
Tool
Vulnerability
Note
A list of available Attribute Types can be retrieved with the following query:
GET /v3/attributeTypes
Hint
To associate an existing Artifact, Case, Group, or Victim Asset to a Group, use the object’s ID when setting the associatedArtifacts
, associatedCases
, associatedGroups
, or associatedVictimAssets
field, respectively (e.g., {"data": [{"id": 12345}]}
). To associate an existing Indicator to a Group, use the Indicator’s ID, or the Indicator’s type and name (e.g., for a Host Indicator, use its hostName
), when setting the associatedIndicators
field.
Group-Specific Fields¶
Based on the type of Group being created, you may need to include additional fields in the body of a POST request. Similarly, some Group types include additional fields that may be updated via a PUT request.
The following tables lists valid fields that can be included in the body of a POST or PUT request for Campaign
, Document
, Email
, Event
, Incident
, Report
, Signature
, and Task
Group types.
Campaign¶
Field | Description | Type | Required for Creation? | Updatable? |
---|---|---|---|---|
firstSeen | The date and time when the Campaign was created | Date | FALSE | TRUE |
Document¶
Field | Description | Type | Required for Creation? | Updatable? |
---|---|---|---|---|
fileName | The file name of the Document | String | TRUE | TRUE |
malware | Indicates whether the Document is malware | Boolean | FALSE | TRUE |
password | The password associated with the Document | String | FALSE* | TRUE |
Note
*If malware
is set to true
, then the password
field will be required
To upload the contents of a Document to ThreatConnect or update the contents of an existing Document in ThreatConnect, see the Upload a Document or Report and Update a Document or Report sections, respectively.
Email¶
Field | Description | Type | Required for Creation? | Updatable? |
---|---|---|---|---|
body | The Email’s body | String | FALSE | TRUE |
from | The Email’s From: field | String | FALSE | TRUE |
header | The Email’s header | String | FALSE | TRUE |
subject | The Email’s subject | String | FALSE | TRUE |
Event¶
Field | Description | Type | Required for Creation? | Updatable? |
---|---|---|---|---|
eventDate | The date and time when the Event took place | Date | FALSE | TRUE |
status | The status of the Event | String | FALSE | TRUE |
Accepted values for an Event’s status
include:
Needs Review
False Positive
No Further Action
Escalated
Incident¶
Field | Description | Type | Required for Creation? | Updatable? |
---|---|---|---|---|
eventDate | The date when the Incident took place | Date | FALSE | TRUE |
status | The status of the Incident | String | FALSE | TRUE |
Accepted values for an Incident’s status
include:
New
Open
Stalled
Containment Achieved
Restoration Achieved
Incident Reported
Closed
Rejected
Deleted
Report¶
Field | Description | Type | Required for Creation? | Updatable? |
---|---|---|---|---|
fileName | The file name of the Report | String | TRUE | TRUE |
publishDate | The date and time when the Report was published | Date | FALSE | TRUE |
To upload the contents of a Report to ThreatConnect or update the contents of an existing Report in ThreatConnect, see the Upload a Document or Report and Update a Document or Report sections, respectively.
Signature¶
Field | Description | Type | Required for Creation? | Updatable? |
---|---|---|---|---|
fileName | The file name of the Signature | String | TRUE | TRUE |
fileText | The file text of the Signature | String | TRUE | TRUE |
fileType | The file type of the Signature | String | TRUE | TRUE |
Accepted values for a Signature’s fileType
include:
Bro
ClamAV
CybOX
Iris Search Hash
OpenIOC
Regex
SPL
Sigma
Snort
Suricata
YARA
Note
*The fileText
field contains the Signature itself, which must be properly escaped and encoded when creating or updating the Signature Group.
Task¶
Field | Description | Type | Required for Creation? | Updatable? | Example Value(s) |
---|---|---|---|---|---|
assignments | A list of users assigned to the Task or to whom the Task will be escalated. Valid values for the type of assignment are “Assigned” and “Escalate” | Assignee Object | FALSE | TRUE | {“data”: [{“type”: “Assigned”, “user”: {“id”: 12}}]}
{“data”: [{“type”: “Escalate”, “user”: {“id”: 8}}]}
|
dueDate | The date and time when the Task is due | Date | FALSE | TRUE | “2021-04-30T00:00:00Z” |
escalationDate | The date and time when the Task should be escalated | String | FALSE | TRUE | “2021-04-30T00:00:00Z” |
reminderDate | The date and time when a reminder about the Task will be sent | String | FALSE | TRUE | “2021-04-30T00:00:00Z” |
status | The status of the Task | String | FALSE | FALSE | “In Progress”, “Not Started” |
Accepted values for a Task’s status
include:
Not Started
In Progress
Completed
Waiting on Someone
Deferred
Create Groups¶
The basic format for creating a Group is:
POST /v3/groups
{
"name": "Group name goes here",
"type": "Group type goes here"
//required fields for the selected Group type go here, if applicable
}
Refer to the Available Fields and Group-Specific Fields sections for a list of available fields that can be included in the body of a POST request for the groups
object.
Note
You can add multiple Attributes, Tags, and Security Labels to the Group being created in a single POST request. Similarly, you can associate multiple Artifacts, Cases, Indicators, and Groups to the Group being created in a single POST request.
Example POST Request¶
The following query will create an Incident
Group for an Incident that took place on Nov. 3, 2021. The Incident will be assigned a status of New
, and Targeted Attack
and Robbery
Tags will be created and applied to it.
POST /v3/groups
{
"type": "Incident",
"name": "Bad Incident",
"eventDate": "2021-11-03",
"status": "New",
"tags": {"data": [{"name": "Targeted Attack"}, {"name": "Robbery"}]}
}
JSON Response
{
"data": {
"id": 3,
"ownerName": "Demo Organization",
"dateAdded": "2021-11-03T14:57:45Z",
"webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3",
"tags": {
"data": [
{
"id": 11,
"name": "Targeted Attack",
"lastUsed": "2021-11-02T15:01:44Z"
},
{
"id": 12,
"name": "Robbery",
"lastUsed": "2021-11-02T15:01:44Z"
}
]
},
"securityLabels": {},
"type": "Incident",
"name": "Bad Incident",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"role": "Api User"
},
"associatedGroups": {},
"associatedIndicators": {},
"associatedCases": {},
"associatedArtifacts": {},
"attributes": {},
"status": "New",
"eventDate": "2021-11-03T00:00:00Z",
"lastModified": "2021-11-03T11:04:12Z"
},
"message": "Created",
"status": "Success"
}
Note
When creating or updating a Group, you can apply Tags that do not yet exist in ThreatConnect to it. To do so, fill out all required fields for each new Tag. Upon creation of the new Group, any Tags included in the body of the POST request that do not yet exist in ThreatConnect will also be created.
Similarly, you can associate Artifacts, Cases, Indicators, and Groups that do not yet exist in ThreatConnect to the Group. In this scenario, you would need to fill out all required fields for the type of object being associated to the Group. Upon creation of the new Group, any associated objects included in the body of the POST request that do not yet exist in ThreatConnect will also be created.
Retrieve Groups¶
Retrieve All Groups¶
To retrieve all Groups, use the following query:
GET /v3/groups
JSON Response
{
"data": [
{
"id": 10,
"ownerName": "Demo Organization",
"dateAdded": "2021-10-21T19:54:59Z",
"webLink": "https://app.threatconnect.com//auth/document/document.xhtml?document=10",
"type": "Document",
"name": "Bad Document",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"role": "Api User"
},
"fileName": "indicators.txt",
"fileSize": 36,
"status": "Success",
"documentType": "Text",
"documentDateAdded": "2021-10-21T19:54:59Z",
"lastModified": "2022-03-09T12:44:04Z"
},
{
"id": 9,
"type": "Email",
"ownerName": "Demo Organization",
"dateAdded": "2021-09-17T12:52:49Z",
"webLink": "https://app.threatconnect.com//auth/email/email.xhtml?email=9",
"name": "Your Amazon.com order for [email protected]",
"createdBy": {
"id": 1,
"userName": "[email protected]",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "JMS"
},
"to": "[email protected]",
"from": "[email protected]",
"subject": "Your Amazon.com order for [email protected]",
"header": "Delivered-To: [MY EMAIL ADDRESS]\r\nReceived: by 10.182.3.66 with SMTP id a2csp104490oba;\r\nFri, 17 Sep 2021 08:50:19 -0400\r\n\r\nReceived: by 10.14.212.72 with SMTP id x48mr8232338eeo.40.1344724334578;\r\n\r\nFri, 17 Sep 2021 08:50:19 -0400\r\n\r\nReturn-Path: <[email protected]>\r\n\r\nReceived: from 72-255-12-30.client.stsn.net (72-255-12-30.client.stsn.net. [72.255.12.30])\r\n\r\nby mx.google.com with ESMTP id c41si1698069eem.38.2012.08.11.15.32.13;\r\n\r\nFri, 17 Sep 2021 08:50:19 -0400\r\n\r\nReceived-SPF: neutral (google.com: 72.255.12.30 is neither permitted nor denied by best guess record for domain of [email protected]) client-ip=72.255.12.30;\r\n\r\nAuthentication-Results: mx.google.com; spf=neutral (google.com: 72.255.12.30 is neither permitted nor denied by best guess record for domain of [email protected]) [email protected]\r\n\r\nReceived: by vwidxus.net id hnt67m0ce87b for <[MY EMAIL ADDRESS]>; Fri, 17 Sep 2021 08:50:19 -0400 (envelope-from <[email protected]>)\r\n\r\nReceived: from vwidxus.net by web.vwidxus.net with local (Mailing Server 4.69)\r\n\r\nid 34597139-886586-27/./PV3Xa/WiSKhnO+7kCTI+xNiKJsH/rC/\r\n\r\nfor [email protected]; Fri, 17 Sep 2021 08:50:19 -0400",
"body": "Please visit bad.com to see your order and give us all your money. Muahahahaha!\r\n\r\n",
"scoreIncludesBody": true,
"emailDate": "2021-09-17T12:50:19Z",
"scoreBreakdown": "Rule SPF Neutral was matched against 'neutral'.\t100\nRule Host was matched against 'bad.com'.\t282\n",
"lastModified": "2022-03-09T20:39:52Z"
},
{...}
],
"status": "Success"
}
Retrieve a Single Group¶
To retrieve a specific Group, use a query in the following format:
GET /v3/groups/{groupId}
For example, the following query will return information about the Group with ID 3:
GET /v3/groups/3
JSON Response
{
"data": {
"id": 3,
"ownerName": "Demo Organization",
"dateAdded": "2021-11-03T14:57:45Z",
"webLink": "https://app.threatconnect.com//auth/incident/incident.xhtml?incident=3",
"type": "Incident",
"name": "Bad Incident",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"role": "Api User"
},
"status": "New",
"eventDate": "2021-11-03T00:00:00Z",
"lastModified": "2022-02-16T18:54:23Z"
},
"status": "Success"
}
Request Additional Fields¶
To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.
Filter Results¶
To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.
Update Groups¶
The basic format for updating a Group is:
PUT /v3/groups/{groupId}
{
{updatedField}: {updatedValue}
}
Refer to the Available Fields and Group-Specific Fields sections for a list of available fields that can be included in the body of a PUT request for the groups
object.
Hint
When updating a Group, you can use the mode
field to add or remove the following metadata:
associatedArtifacts
associatedCases
associatedGroups
associatedIndicators
associatedVictimAssets
attributes
securityLabels
tags
See Update an Object’s Metadata for instructions on using the mode
field.
Example PUT Request¶
The following query will complete the following actions for the Incident
Group with ID 3:
- Associate an Email Address Indicator (
verybadguy@bad.com
) and a Host Indicator (ultrabadguy.com
) to the Group - Add an
Additional Analysis and Context
Attribute to the Group - Update the
status
of the Incident - Remove the
Robbery
Tag applied to the Group.
PUT /v3/groups/3
{
"associatedIndicators": {"data": [{"id": 15}, {"hostName": "ultrabadguy.com", "type": "Host"}]},
"attributes": {"data": [{"type": "Additional Analysis and Context", "value": "Based on internal analysis, this incident was very severe.", "source": "Example Source"}]},
"status": "Incident Reported",
"tags": {"data": [{"name": "Robbery"}], "mode": "delete"}
}
JSON Response
{
"data": {
"id": 3,
"ownerName": "Demo Organization",
"dateAdded": "2021-11-03T14:57:45Z",
"webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3",
"tags": {
"data": [{
"id": 11,
"name": "Targeted Attack",
"lastUsed": "2021-11-04T18:52:29Z"
}],
},
"securityLabels": {},
"type": "Incident",
"name": "Bad Incident",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"role": "Api User"
},
"associatedGroups": {},
"associatedIndicators": {
"data": [
{
"id": 15,
"type": "EmailAddress",
"ownerName": "Demo Organization",
"dateAdded": "2021-10-26T16:26:19Z",
"webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=verybadguy%40bad.com",
"lastModified": "2021-11-04T19:07:01Z",
"summary": "[email protected]",
"privateFlag": false,
"active": true,
"activeLocked": false,
"address": "[email protected]"
},
{
"id": 9,
"type": "Host",
"ownerName": "Demo Organization",
"dateAdded": "2021-10-26T12:40:00Z",
"webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
"lastModified": "2021-11-04T13:00:29Z",
"rating": 4.0,
"confidence": 85,
"summary": "ultrabadguy.com",
"privateFlag": false,
"active": true,
"activeLocked": false,
"hostName": "ultrabadguy.com",
"dnsActive": true,
"whoisActive": true
}
],
},
"associatedCases": {},
"associatedArtifacts": {},
"attributes": {
"data": [{
"id": 10,
"type": "Additional Analysis and Context",
"value": "Based on internal analysis, this incident was very severe.",
"source": "Example Source",
"createdBy": {
"id": 3,
"userName": "11112222333344445555",
"firstName": "John",
"lastName": "Smith",
"pseudonym": "jsmithAPI",
"role": "Api User"
},
"dateAdded": "2021-11-04T19:07:01Z",
"lastModified": "2021-11-04T19:07:01Z",
"default": false
}],
},
"status": "Incident Reported",
"eventDate": "2021-11-03T00:00:00Z",
"lastModified": "2022-03-09T08:14:23Z"
},
"message": "Updated",
"status": "Success"
}
Delete Groups¶
The basic format for deleting a Group is:
DELETE /v3/groups/{groupId}
For example, the following query will delete the Group with ID 1:
DELETE /v3/groups/1
JSON Response
{
"message": "Deleted",
"status": "Success"
}
Retrieve, Upload, and Update a Document¶
Retrieve a Document, Report, or Signature¶
To download the contents of a Document, Report, or Signature in ThreatConnect, use a query in the following format:
GET /v3/groups/{groupId}/download
The contents of a Document will be returned as Content-Type: application/octet-stream
. The contents of a Signature will be returned as Content-Type: text/plain
.
Upload a Document or Report¶
To upload the contents of a Document or Report in ThreatConnect, use a query in the following format:
PUT /v3/groups/{groupId}/upload
Content-Type: application/octet-stream
<raw report contents>
If uploading a document to the Malware Vault, the following steps must be completed before uploading the document:
- Create a password-protected zip file on your computer that contains the document.
- Create a new Document Group with the additional fields
malware
set totrue
andpassword
set to the zip file’s password.
Attention
If you’re uploading a file larger than 5GB, contact your System Administrator about increasing the allowed file size for uploads.
Update a Document or Report¶
To update the contents of an existing Document or Report in ThreatConnect, use a query in the following format:
PUT /v3/groups/{groupId}/upload
Content-Type: application/octet-stream
New Document contents go here.
Retrieve a PDF Report for Groups¶
To retrieve a PDF report for a Group, use a query in the following format:
GET /v3/groups/{groupId}/pdf
PDF reports can only be retrieved for the following Group types:
Adversary
Attack Pattern
Campaign
Course of Action
Event
Incident
Intrusion Set
Malware
Report
Tactic
Threat
Tool
Vulnerability