Groups
Groups represent a collection of related behavior and/or intelligence.
Hint
When working with Groups using the ThreatConnect REST API, it is often necessary to specify the ID corresponding to 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 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 is the ID for the Group. (In both of the previous examples, the ID of the Group is 123456.)
Retrieve Groups
Filtering Groups
Filters Parameter
When retrieving Groups 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 |
|
Campaign Specific Filters |
||
firstSeen |
date |
|
Document Specific Filters |
||
fileType |
string |
|
Incident Specific Filters |
||
eventDate |
date |
|
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 |
|---|---|
= |
|
< |
|
> |
|
^ |
|
Examples
The following query will return all Groups that start with “Fancy” (name^Fancy):
GET /v2/groups/?filters=name%5EFancy
The following query will return all Groups whose name is “Fancy” (name=Fancy):
GET /v2/groups/?filters=name%3DFancy
The following query will return all Groups that have been added since 2017-07-13 (dateAdded>2017-07-13):
GET /v2/groups/?filters=dateAdded%3E2017-07-13
The following query will return all Campaigns that have an first-seen date after 2017-07-13 (firstSeen>2017-07-13T00:00):
GET /v2/groups/campaigns?filters=firstSeen%3E2017-07-13T00:00
The following query will return all Documents that are PDFs (fileType=PDF):
GET /v2/groups/documents?filters=fileType%3DPDF
The following query will return all Incidents that have an event date after 2017-07-13 (eventDate>2017-07-13T00:00):
GET /v2/groups/incidents?filters=eventDate%3E2017-07-13T00:00
Owner Parameter
By default, all API calls will operate in the API user account’s default organization. To specify a different Owner, use the owner URL parameter as in ?owner={ownerName}. For example, the following query will return all Incidents in the Common Community:
GET /v2/groups/incidents/?owner=Common%20Community
Additional Parameters
Group API paths will display XID when includes=additional or includeAdditional=true:
/api/v2/groups/adversaries/4?includeAdditional=True
/api/v2/groups/adversaries/4?includes=additional
Retrieve All Groups
To retrieve Groups of all types, use the following query:
GET /v2/groups
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 2,
"group": [
{
"id": 12345,
"name": "Likely Nation State Intrusion on Remote Server",
"type": "Document",
"ownerName": "Example Organization",
"dateAdded": "2017-07-13T16:43:19Z",
"lastModified": "2017-07-13T16:44:19Z",
"webLink": "https://app.threatconnect.com/auth/document/document.xhtml?document=12345"
},
{
"id": 12346,
"name": "Investment Status",
"type": "Email",
"ownerName": "Example Organization",
"dateAdded": "2017-07-13T19:28:10Z",
"lastModified": "2017-07-13T19:29:10Z"
"webLink": "https://app.threatconnect.com/auth/email/email.xhtml?email=12346"
}
]
}
}
Retrieve Multiple Groups
To retrieve multiple Groups of a certain type, use a query in the following format:
GET /v2/groups/{groupType}
The {groupType} can be any one of the available Group types:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
For example, the query below will retrieve a list of all Incidents in the default owner:
GET /v2/groups/incidents
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 2,
"incident": [
{
"id": "54321",
"name": "Test Incident",
"ownerName": "Wanna Cry Hits Stoic Department",
"dateAdded": "2017-07-13T17:50:17",
"lastModified": "2017-07-13T17:51:17",
"webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=54321",
"eventDate": "2017-03-21T00:00:00Z"
},
{
"id": "54322",
"name": "PoS Malware Detected at Denver Location",
"ownerName": "Example Organization",
"dateAdded": "2017-07-13T17:51:17",
"lastModified": "2017-07-13T17:52:17",
"webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=54322",
"eventDate": "2017-06-27T00:00:00Z"
}
]
}
}
Retrieve a Single Group
To retrieve a single Group, use a query in the following format:
GET /v2/groups/{groupType}/{groupId}
For example, if you want to retrieve the Threat with the ID 12345, you would use the following query:
GET /v2/groups/threats/12345
JSON Response:
{
"status": "Success",
"data": {
"threat": {
"id": 12345,
"name": "Bad Dude",
"owner": {
"id": 1,
"name": "Example Organization",
"type": "Organization"
},
"dateAdded": "2017-05-13T18:40:22Z",
"lastModified": "2017-05-13T18:41:22Z",
"webLink": "https://app.threatconnect.com/auth/threat/threat.xhtml?threat=12345"
}
}
}
Retrieve Document or Signature Contents
To download the contents of a Document or Signature in ThreatConnect, you can use a query in the following format:
GET /v2/groups/documents/{documentId}/download
GET /v2/groups/signatures/{signatureId}/download
For example, the query below downloads the contents of a Document with ID 12345:
GET /v2/groups/documents/12345/download
JSON Response:
This is the content of the document!
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.
Retrieve Group Metadata
Retrieve Group Attributes
To retrieve a Group’s Attributes, use the following format:
GET /v2/groups/{groupType}/{groupId}/attributes
For example, if you want to retrieve the Attributes on the Threat with the ID 12345, you would use the following query:
GET /v2/groups/threats/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/groups/{groupType}/{groupId}/attributes/{attributeId}/securityLabels
Here is an example query:
GET /v2/groups/threats/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 Group Security Labels
To retrieve the Security Labels for a Group, use a query in the following format:
GET /v2/groups/{groupType}/{groupId}/securityLabels
For example, the query below will retrieve all Security Labels for the Threat with ID 12345:
GET /v2/groups/threats/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 Adversary Assets
Adversary Assets are accounts or web resources that Adversaries leverage in support of their operations. They can be retrieved from a given Adversary using the following query format:
GET /v2/groups/adversaries/{adversaryId}/adversaryAssets
For example, the query below will return the Adversary Assets for the Adversary with ID 12345:
GET /v2/groups/adversaries/12345/adversaryAssets
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 2,
"bucketAsset": [
{
"id": "54321",
"name": "Real Bad Guy",
"type": "Handle",
"webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=12345"
},
{
"id": "54322",
"name": "http://facebook.com/therealbadguy",
"type": "URL",
"webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=12345"
}
]
}
}
To retrieve Adversary Assets of a particular type, use a query in the following format:
GET /v2/groups/adversaries/{adversaryId}/adversaryAssets/{assetType}
{assetType} can be replaced with the following Asset types:
handles
phoneNumbers
urls
To get details about a specific Adversary Asset, use a query in the following format:
GET /v2/groups/adversaries/{adversaryId}/adversaryAssets/{assetType}/{assetId}
Retrieve Incident Status
Incidents in ThreatConnect have a status that can be set and retrieved via API. Adding the includeAdditional parameter when requesting data about an Incident will return data which includes the Incident’s status. Use a query in the following format to find an Incident’s status:
GET /v2/groups/incidents/{incidentId}?includeAdditional=true
For example, the query below will return information about the Incident with ID 12345 as well as the Incident’s status.
GET /v2/groups/incidents/12345?includeAdditional=true
JSON Response:
{
"status": "Success",
"data": {
"incident": {
"id": 12345,
"name": "Test Incident",
"owner": {
"id": 1,
"name": "Example Organization",
"type": "Organization"
},
"createdBy": "John Smith"
"dateAdded": "2017-07-13T18:15:49Z",
"lastModified": "2017-07-13T18:16:49Z",
"webLink": "https://app.threatconnect.com/tc/auth/incident/incident.xhtml?incident=12345",
"xid": "b85ce129-cfd5-4c82-9814-37cf9f4d15c0:11",
"communityOrSource": false,
"additionalOwners": [],
"eventDate": "2017-06-21T18:15:49Z",
"status": "Open"
}
}
}
Note that using the ‘includes=additional’ parameter will also work. Likewise, ‘includes=tags’, ‘includes=attributes’, and ‘includes=labels’ are permitted for Groups.
Retrieve Group Associations
Group to Group Associations
To view Groups associated with a given Group, use a query in the following format:
GET /v2/groups/{groupType}/{groupId}/groups
For example, the query below will retrieve all of the Groups associated with a Threat with the ID 12345:
GET /v2/groups/threats/12345/groups
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 1,
"group": [
{
"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/groups/{groupType}/{groupId}/groups/{associatedGroupType}
Replace {associatedGroupType} with one of the following Group types:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
For example, you could use the following query to find all Incidents associated with the Threat with ID 12345:
GET /v2/groups/threats/12345/groups/incidents
You can also delve further by adding the ID of an associated Group to the end of the query:
GET /v2/groups/threats/12345/groups/incidents/54321
Where 54321 is the ID of an incident associated with Threat 12345.
Indicator to Group Associations
To view Indicators associated with a given Group, use a query in the following format:
GET /v2/groups/{groupType}/{groupId}/indicators
For example, the query below will retrieve all of the Indicators associated with a Threat with the ID 12345:
GET /v2/groups/threats/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": 406,
"calScore": 423,
"calIndicatorStatus": 1
"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/groups/{groupType}/{groupId}/indicators/{associatedIndicatorType}
For example, you could use the following query to find all Address Indicators associated with the Threat with ID 12345:
GET /v2/groups/threats/12345/indicators/addresses
Victim Asset to Group Associations
To view Victim Assets associated with a given Group, use a query in the following format:
GET /v2/groups/{groupType}/{groupId}/victimAssets
For example, the query below will retrieve all of the Victim Assets associated with a Threat with the ID 12345:
GET /v2/groups/threats/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/groups/{groupType}/{groupId}/victimAssets/{victimAssetType}
The available Victim Asset types are:
emailAddressesnetworkAccountsphoneNumberssocialNetworkswebSites
For example, you could use the following query to find all Victim Assets that are Email Addresses that are associated with the Threat with ID 12345:
GET /v2/groups/threats/12345/victimAssets/emailAddresses
You can delve further by adding the ID of an associated Victim Asset to the end of the query:
GET /v2/groups/threats/12345/victimAssets/emailAddresses/54321
Where 54321 is the ID of a Victim Asset associated with Threat 12345.
Victim to Group Associations
To view Victims associated with a given Group, use a query in the following format:
GET /v2/groups/{groupType}/{groupId}/victims
For example, the query below will retrieve all of the Victims associated with a Threat with the ID 12345:
GET /v2/groups/threats/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"
}
]
}
}
You can delve further by adding the ID of an associated Victim to the end of the query:
GET /v2/groups/threats/12345/victims/54321
Where 54321 is the ID of a Victim associated with Threat 12345.
Create Groups
To create a Group, the most basic format is:
POST /v2/groups/{groupType}
Content-type: application/json; charset=utf-8
{
"name": "Test Group"
}
The {groupType} can be any one of the available Group types:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
Some Group types require additional fields when being created. Refer to the table below for the fields required to create each Group type:
Group Fields
Group Type |
Valid Fields |
Required for Group Creation |
Required for Group Update |
|---|---|---|---|
adversaries |
name |
TRUE |
FALSE |
attackPatterns |
name |
TRUE |
FALSE |
campaigns |
name |
TRUE |
FALSE |
firstSeen |
FALSE |
FALSE |
|
coursesOfAction |
name |
TRUE |
FALSE |
documents |
fileName |
TRUE |
FALSE |
name |
TRUE |
FALSE |
|
malware |
FALSE |
FALSE |
|
password |
FALSE |
FALSE |
|
emails |
name |
TRUE |
FALSE |
to |
FALSE |
FALSE |
|
from |
FALSE |
FALSE |
|
subject |
TRUE |
FALSE |
|
header |
TRUE |
FALSE |
|
body |
TRUE |
FALSE |
|
events |
name |
TRUE |
FALSE |
eventDate |
TRUE |
FALSE |
|
status† |
FALSE |
FALSE |
|
incidents |
name |
TRUE |
FALSE |
eventDate |
TRUE |
FALSE |
|
status† |
FALSE |
FALSE |
|
intrusionSets |
name |
TRUE |
FALSE |
malware |
name |
TRUE |
FALSE |
reports |
fileName |
TRUE |
FALSE |
name |
TRUE |
FALSE |
|
tactics |
name |
TRUE |
FALSE |
threats |
name |
TRUE |
FALSE |
tools |
name |
TRUE |
FALSE |
signatures |
name |
TRUE |
TRUE |
fileName |
TRUE |
TRUE |
|
fileType* |
TRUE |
TRUE |
|
fileText** |
TRUE |
FALSE |
|
vulnerabilities |
name |
TRUE |
FALSE |
† The valid values for a Document’s status are:
Success
Awaiting Upload
In Progress
Failed
None
† The valid values for an Event’s status are:
Needs Review
False Positive
No Further Action
Escalated
† The valid values for an Incident’s status are:
New
Open
Stalled
Containment Achieved
Restoration Achieved
Incident Reported
Closed
Rejected
Deleted
* The valid values for a Signature’s fileType field are:
Bro
ClamAV®
CybOX™
Iris™ Search Hash
KQL
OpenIOC
Regex
Splunk® Search Processing Language (SPL)
Sigma
Snort®
Suricata
TQL Query
YARA
** A Signature’s fileText field contains the Signature itself, which must be properly escaped and encoded when submitting for creation or updating.
By way of example, the query below will create an incident in the default owner:
POST /v2/groups/incidents
Content-type: application/json; charset=utf-8
{
"name": "Test Incident",
"eventDate": "2017-7-13T00:00:00-04:00",
"status": "New"
}
JSON Response:
{
"status": "Success",
"data": {
"incident": {
"id": "54321",
"name": "Test Incident",
"owner": {
"id": 1,
"name": "Example Organization",
"type": "Organization"
},
"dateAdded": "2017-07-13T17:50:17",
"lastModified": "2017-07-13T17:50:17",
"webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=54321",
"eventDate": "2017-7-13T00:00:00-04:00"
}
}
}
Uploading Document Contents
If you are creating a Document in ThreatConnect that is a malware sample, refer to the the next section. If you are creating a benign Document and want to upload content into the Document via API, refer to the section on uploading Document contents for more details.
Creating a Malware Document
To create a Document that can be uploaded into ThreatConnect’s Malware Vault via API, include the malware and password fields when creating the Document as shown below.
POST /v2/groups/documents/
Content-type: application/json; charset=utf-8
{
"fileName" : "malwaresample.zip",
"name": "malwaresample.exe",
"malware": true,
"password": "TCinfected"
}
To upload a malware sample as a Document, the following steps must be taken:
Create a password-protected zip file on your local machine containing the sample.
Create a new Document Group, including the additional fields
malwareset to True andpasswordset to the zip file’s password.
Note
The API will validate that the malware Document is a password-protected zip file.
Warning
Uploading raw malware executables or weaponized Documents is strictly forbidden.
For malware uploads, An HTTP 400 - Bad Request error will be returned if the Document is not a password-protected zip file (as determined by file headers).
Create Group Metadata
Create Group Attributes
To add an Attribute to a Group, use the following format:
POST /v2/groups/{groupType}/{groupId}/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 threat with the ID 12345, you would use the following query:
POST /v2/groups/threats/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/groups/{groupType}/{groupId}/attributes/{attributeId}/securityLabels/{securityLabel}
For example, the query below will add a TLP:AMBER Security Label to the Attribute on the Threat:
POST /v2/groups/threats/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 Group Security Labels
To add a Security Label to a Group, use the following format, where {securityLabel} is replaced with the name of a Security Label that already exists in the Owner:
POST /v2/groups/{groupType}/{groupId}/securityLabels/{securityLabel}
For example, the query below will add a TLP:AMBER Security Label to the Threat with ID 12345:
POST /v2/groups/threats/12345/securityLabels/TLP%3AAMBER
JSON Response:
{
"status": "Success"
}
Note
In order to add a Security Label to a Group, 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 Adversary Assets
To create an Adversary Asset for an Adversary, use a query in the following format:
POST /v2/groups/adversaries/{adversaryId}/adversaryAssets/{assetType}
{assetType} can be replaced with the following Asset types:
handles
phoneNumbers
urls
For example, the query below will add Pierre Despereaux as a Handle to the Adversary with ID 12345:
POST /v2/groups/adversaries/12345/adversaryAssets/handles
{
"handle": "Pierre Despereaux"
}
JSON Response:
{
"status": "Success",
"data": {
"adversaryHandle": {
"id": 1,
"type": "Handle",
"webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=12345",
"handle": "Pierre Despereaux"
}
}
}
Create Group Associations
Associate Group to Group
To associate one Group with another, use a query in the following format:
POST /v2/groups/{groupType}/{groupId}/groups/{associatedGroupType}/{associatedGroupId}
Replace {associatedGroupType} with one of the following Group types:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
For example, the query below will associate a Threat with the ID 12345 with an Incident with the ID 54321:
POST /v2/groups/threats/12345/groups/incidents/54321
JSON Response:
{
"status": "Success"
}
Associate Indicator to Group
To associate a Group with an Indicator, use a query in the following format:
POST /v2/groups/{groupType}/{groupId}/indicators/{associatedIndicatorType}/{associatedIndicator}
For example, the query below will associate the Threat with the ID 12345 with the IP Address 0.0.0.0:
POST /v2/groups/threats/12345/indicators/addresses/0.0.0.0
JSON Response:
{
"status": "Success"
}
Associate Victim to Group
To associate a Group with a Victim, use a query in the following format:
POST /v2/groups/{groupType}/{groupId}/victims/{victimId}
For example, the query below will associate the Threat with the ID 12345 with the Victim with ID 54321:
POST /v2/groups/threats/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 Groups
To update a Group, the basic format is:
PUT /v2/groups/{groupType}/{groupId}
{
{updatedField}: {updatedValue}
}
The {groupType} can be any one of the available Group types:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
When updating the fields on a Group, you can change any of the fields available for the type of Group you are updating. Below is a table of available fields for each Group type:
Group Type |
Valid Fields |
Required for Group Creation |
Required for Group Update |
|---|---|---|---|
adversaries |
name |
TRUE |
FALSE |
attackPatterns |
name |
TRUE |
FALSE |
campaigns |
name |
TRUE |
FALSE |
firstSeen |
FALSE |
FALSE |
|
coursesOfAction |
name |
TRUE |
FALSE |
documents |
fileName |
TRUE |
FALSE |
name |
TRUE |
FALSE |
|
malware |
FALSE |
FALSE |
|
password |
FALSE |
FALSE |
|
emails |
name |
TRUE |
FALSE |
to |
FALSE |
FALSE |
|
from |
FALSE |
FALSE |
|
subject |
TRUE |
FALSE |
|
header |
TRUE |
FALSE |
|
body |
TRUE |
FALSE |
|
events |
name |
TRUE |
FALSE |
eventDate |
TRUE |
FALSE |
|
status† |
FALSE |
FALSE |
|
incidents |
name |
TRUE |
FALSE |
eventDate |
TRUE |
FALSE |
|
status† |
FALSE |
FALSE |
|
intrusionSets |
name |
TRUE |
FALSE |
malware |
name |
TRUE |
FALSE |
reports |
fileName |
TRUE |
FALSE |
name |
TRUE |
FALSE |
|
tactics |
name |
TRUE |
FALSE |
threats |
name |
TRUE |
FALSE |
tools |
name |
TRUE |
FALSE |
signatures |
name |
TRUE |
TRUE |
fileName |
TRUE |
TRUE |
|
fileType* |
TRUE |
TRUE |
|
fileText** |
TRUE |
FALSE |
|
vulnerabilities |
name |
TRUE |
FALSE |
† The valid values for a Document’s status are:
Success
Awaiting Upload
In Progress
Failed
None
† The valid values for an Event’s status are:
Needs Review
False Positive
No Further Action
Escalated
† The valid values for an Incident’s status are:
New
Open
Stalled
Containment Achieved
Restoration Achieved
Incident Reported
Closed
Rejected
Deleted
* The valid values for a Signature’s fileType field are:
Bro
ClamAV®
CybOX™
Iris™ Search Hash
KQL
OpenIOC
Regex
Splunk® Search Processing Language (SPL)
Sigma
Snort®
Suricata
TQL Query
YARA
** A Signature’s fileText field contains the Signature itself, which must be properly escaped and encoded when submitting for creation or updating.
By way of example, the query below will update the name of an Incident with ID 12345:
PUT /v2/groups/incidents/12345
{
"name": "New Incident Name"
}
JSON Response:
{
"status": "Success",
"data": {
"incident": {
"id": "12345",
"name": "New Incident Name",
"owner": {
"id": 1,
"name": "Example Organization",
"type": "Organization"
},
"dateAdded": "2017-07-13T17:50:17",
"lastModified": "2017-07-13T17:51:17",
"webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=12345",
"eventDate": "2017-7-13T00:00:00-04:00"
}
}
}
Uploading/Updating Document Contents
To update the contents of a Document in ThreatConnect, use a query in the following format:
Note
If you’re uploading a file larger than 5GB, contact your System Administrator about increasing the allowed file size for uploads.
Note
To upload the initial document, rather than updating the existing document, replace PUT with POST
PUT /v2/groups/documents/{documentId}/upload
Content-Type: application/octet-stream
<raw document contents>
The Content-Type header must be set to application/octet-stream for this query to work properly. The query below demonstrates how to upload some text into the Document with ID 12345:
PUT /v2/groups/documents/12345/upload
Content-Type: application/octet-stream
New Document contents here.
JSON Response:
{
"status": "Success",
}
Uploading/Updating Report Contents
To update the contents of a Report in ThreatConnect, use a query in the following format:
Note
If you’re uploading a file larger than 5GB, contact your System Administrator about increasing the allowed file size for uploads.
Note
To upload the initial report, rather than updating the existing report, replace PUT with POST
PUT /v2/groups/reports/{documentId}/upload
Content-Type: application/octet-stream
<raw report contents>
The Content-Type header must be set to application/octet-stream for this query to work properly. The query below demonstrates how to upload some text into the Document with ID 12345:
PUT /v2/groups/reports/12345/upload
Content-Type: application/octet-stream
New report contents here.
JSON Response:
{
"status": "Success",
}
Update Group Metadata
Update Group Attributes
To update a Group’s Attribute, use the following format:
PUT /v2/groups/{groupType}/{groupId}/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 Threat with ID 12345, you would use the following query:
PUT /v2/groups/threats/12345/attributes/54321
{
"value": "Bad... Very bad."
}
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": "Bad... Very bad."
}
}
}
Update Adversary Assets
To update an Adversary’s Asset, use the following format:
PUT /v2/groups/adversaries/{adversaryId}/adversaryAssets/{assetType}/{assetId}
{
{updatedField}: {updatedValue}
}
{assetType} can be replaced with the following Asset types:
handles
phoneNumbers
urls
When updating an Adversary Asset, you can change the following field:
Updatable Attribute Fields |
Required |
|---|---|
handle* |
FALSE |
phoneNumber** |
FALSE |
url*** |
FALSE |
* The handle field can only be updated for Adversary Assets of the handles type
** The phoneNumber field can only be updated for Adversary Assets of the phoneNumbers type
*** The url field can only be updated for Adversary Assets of the urls type
For example, if you wanted to update the URL of the Adversary Asset with ID 1 on the Adversary with ID 12345, you would use the following request:
PUT /v2/groups/adversaries/12345/adversaryAssets/urls/1
{
"url": "https://newsite.com/"
}
JSON Response:
{
"status": "Success",
"data": {
"adversaryUrl": {
"id": 1,
"type": "URL",
"webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=12345",
"url": "https://newsite.com/"
}
}
}
Delete Groups
To delete a Group, the most basic format is:
DELETE /v2/groups/{groupType}/{groupId}
The {groupType} can be any one of the available Group types:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
By way of example, the query below will delete the Threat with the ID 12345:
DELETE /v2/groups/threats/12345
JSON Response:
{
"status": "Success"
}
Delete Group Metadata
Delete Group Attributes
To delete an Attribute from a Group, use the following format:
DELETE /v2/groups/{groupType}/{groupId}/attributes/{attributeId}
For example, if you wanted to delete the Attribute with ID 54321 from the Threat with the ID 12345, you would use the following query:
DELETE /v2/groups/threats/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/groups/{groupType}/{groupId}/attributes/{attributeId}/securityLabels/{securityLabel}
For example, the query below will remove the TLP:AMBER Security Label from the Attribute with ID 54321 on the Threat:
DELETE /v2/groups/threats/12345/attributes/54321/securityLabels/TLP%3AAMBER
Delete Group Security Labels
To delete a Security Label from a Group, use the following format, where {securityLabel} is replaced with the name of a Security Label:
DELETE /v2/groups/{groupType}/{groupId}/securityLabels/{securityLabel}
For example, the query below will delete the TLP:AMBER Security Label to the Threat with ID 12345:
DELETE /v2/groups/threats/12345/securityLabels/TLP%3AAMBER
JSON Response:
{
"status": "Success"
}
Delete Adversary Assets
To delete an Adversary Asset, use a request in the following format:
DELETE /v2/groups/adversaries/{adversaryId}/adversaryAssets/{assetType}/{assetId}
For example, if you wanted to delete the Adversary Asset (which happens to be of type URL) with ID 1 on the Adversary with ID 12345, you would use the following request:
DELETE /v2/groups/adversaries/12345/adversaryAssets/urls/1
JSON Response:
{
"status": "Success"
}
Delete/Disassociate Group Associations
Disassociate Group from Group
To disassociate one Group from another, use a query in the following format:
DELETE /v2/groups/{groupType}/{groupId}/groups/{associatedGroupType}/{associatedGroupId}
Replace {associatedGroupType} with one of the following Group types:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
For example, the query below will disassociate a Threat with the ID 12345 from an Incident with the ID 54321:
DELETE /v2/groups/threats/12345/groups/incidents/54321
JSON Response:
{
"status": "Success"
}
Disassociate Indicator from Group
To disassociate a Group from an Indicator, use a query in the following format:
DELETE /v2/groups/{groupType}/{groupId}/indicators/{associatedIndicatorType}/{associatedIndicator}
For example, the query below will disassociate the Threat with the ID 12345 from the IP Address 0.0.0.0:
DELETE /v2/groups/threats/12345/indicators/addresses/0.0.0.0
JSON Response:
{
"status": "Success"
}
Disassociate Victim Asset from Group
To disassociate a Group from a Victim Asset, use a query in the following format:
DELETE /v2/groups/{groupType}/{groupId}/victimAssets/{victimAssetType}/{victimAssetId}
For example, the query below will disassociate the Threat with the ID 12345 from the Victim Asset with ID 54321:
DELETE /v2/groups/threats/12345/victimAssets/emailAddresses/54321
JSON Response:
{
"status": "Success"
}
Disassociate Victim from Group
To disassociate a Group from a Victim, use a query in the following format:
DELETE /v2/groups/{groupType}/{groupId}/victims/{victimId}
For example, the query below will disassociate the Threat with the ID 12345 from the Victim with ID 54321:
DELETE /v2/groups/threats/12345/victims/54321
JSON Response:
{
"status": "Success"
}
Publish Groups
As of ThreatConnect version 5.2, it is possible to publish intelligence for a specific Group. The general format for this request is as follows:
POST v2/groups/{groupType}/{groupId}/publish
Content-type: application/json; charset=utf-8
{
"securityLabelList": [],
"excludeUnlabeled": false
}
The {groupType} can be any one of the available Group types:
adversariesattackPatternscampaignscoursesOfActiondocumentsemailseventsincidentsintrusionSetsmalwarereportssignaturestacticsthreatstoolsvulnerabilities
The securityLabelList key of the request body allows you to provide the name(s) of the Security Label(s) that, if an item has this Label, you would like to exclude when publishing. The following example-request body would not publish any items (Groups or Indicators) that have the TLP Green or TLP Amber Labels:
{
"securityLabelList": [
"TLP Green",
"TLP Amber"
],
"excludeUnlabeled": false
}
The excludeUnlabeled key gives you the option to exclude all items that do not have a Security Label. The following example-request body would not publish any items that have the TLP Green or TLP Amber Labels or any items that do not have a Security Label:
{
"securityLabelList": [
"TLP Green",
"TLP Amber"
],
"excludeUnlabeled": true
}
The JSON response to any of these queries, assuming the query is successful, is as follows:
{
"status": "Success"
}
Create PDF Report for Groups
As of ThreatConnect version 5.4, it is possible to create a PDF Report for a Group in ThreatConnect from the API. The general format for this request is as follows:
GET /v2/groups/{type}/{id}/pdf
Note
This endpoint applies to all Groups except for Documents and Emails.
Batch Upload: Groups
You can use the V2 Batch API to create and modify Groups in bulk. See Batch API for instructions on using the Batch API.