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 you would like to work with. 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 page for a group, the URL should look something 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 <, >

Note

=, <, >, and ^ operators need to be escaped in the API query URL as: %3D, %3C, %3E, and %5E respectively.

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

For example, 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 like ?owner={ownerName}. For example, the following query will return all Incidents in the Common Community:

GET /v2/groups/incidents/?owner=Common%20Community

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",
        "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",
        "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:

  • adversaries
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

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",
        "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",
        "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 wanted 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",
      "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 wanted 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": "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 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": "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 Group Tags

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

GET /v2/groups/{groupType}/{groupId}/tags

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

GET /v2/groups/threats/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 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=1157242"
      },
      {
        "id": "54322",
        "name": "http://facebook.com/therealbadguy",
        "type": "URL",
        "webLink": "https://app.threatconnect.com/auth/adversary/adversary.xhtml?adversary=1157242"
      }
    ]
  }
}

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"
      },
      "dateAdded": "2017-07-13T18:15:49Z",
      "webLink": "https://app.threatconnect.com/tc/auth/incident/incident.xhtml?incident=12345",
      "eventDate": "2017-06-21T18:15:49Z",
      "status": "Open"
    }
  }
}

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",
        "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:

  • adversaries
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

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

GET /v2/groups/threats/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/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,
        "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, we 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": "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/groups/{groupType}/{groupId}/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 Threat with ID 12345:

GET /v2/groups/threats/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/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"
      }
    ]
  }
}

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

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:

  • adversaries
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

Some group types require additional fields when being created. Refer to the table below for the fields required to create each group type:

Group Type Valid Fields Required for Group Creation Required for Group Update
adversaries name TRUE FALSE
campaigns name TRUE FALSE
  firstSeen FALSE 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
incidents name TRUE FALSE
  eventDate TRUE FALSE
  status† FALSE FALSE
threats name TRUE FALSE
signatures name TRUE FALSE
  fileName TRUE FALSE
  fileType* TRUE FALSE
  fileText** TRUE FALSE

† 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:

  • Snort ®
  • Suricata
  • YARA
  • ClamAV ®
  • OpenIOC
  • CybOX™
  • Bro
  • Regex
  • Splunk ® Search Processing Language (SPL)

** 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",
      "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:

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%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 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%20Amber

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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 Group Tags

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

POST /v2/groups/{groupType}/{groupId}/tags/{tagName}

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

POST /v2/groups/threats/12345/tags/Nation%20State

JSON Response:

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

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
Content-type: application/json; charset=utf-8

{
  "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:

  • adversaries
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

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:

  • adversaries
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

When updating the fields on a Group itself, 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
campaigns name TRUE FALSE
  firstSeen FALSE 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
incidents name TRUE FALSE
  eventDate TRUE FALSE
  status† FALSE FALSE
threats name TRUE FALSE
signatures name TRUE FALSE
  fileName TRUE FALSE
  fileType* TRUE FALSE
  fileText** TRUE FALSE

† 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:

  • Snort ®
  • Suricata
  • YARA
  • ClamAV ®
  • OpenIOC
  • CybOX™
  • Bro
  • Regex
  • Splunk ® Search Processing Language (SPL)

** 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",
      "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=12345",
      "eventDate": "2017-7-13T00:00:00-04:00"
    }
  }
}

Update Document Contents

To update the contents of a Document in ThreatConnect, use a query in the following format:

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",
}

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:

  • adversaries
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

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

DELETE /v2/groups/threats/12345

JSON Response:

{
    "apiCalls": 1,
    "resultCount": 0,
    "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:

{
  "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/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%20Amber

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%20Amber

JSON Response:

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

Delete Group Tags

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

DELETE /v2/groups/{groupType}/{groupId}/tags/{tagName}

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

DELETE /v2/groups/threats/12345/tags/Nation%20State

JSON Response:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

  • adversaries
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

{
  "apiCalls": 1,
  "resultCount": 0,
  "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:

  • adversaries
  • campaigns
  • documents
  • emails
  • incidents
  • signatures
  • threats

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 report PDF for a Group in ThreatConnect from the API. The general format for this request is as follows:

GET /v2/groups/{type}/{id}/pdf

This endpoint is available for all of the following Group types:

  • Adversaries
  • Campaigns
  • Emails
  • Incidents
  • Signatures
  • Threats

Note

This endpoint applies to all Groups except for Documents.