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	`<`, `>`

Hint

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

Note

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

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

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

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",
        "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
events
incidents
intrusionSets
reports
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"
    }
  }
}

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",
        "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
events
incidents
intrusionSets
reports
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
events
incidents
intrusionSets
reports
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 Fields¶

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
	status†	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
reports	fileName	TRUE	FALSE
	name	TRUE	FALSE
	malware	FALSE	FALSE
	password	FALSE	FALSE
threats	name	TRUE	FALSE
signatures	name	TRUE	TRUE
	fileName	TRUE	TRUE
	fileType*	TRUE	TRUE
	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 Document’s status are:

Success
Awaiting Upload
In Progress
Failed
None

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

Create a password-protected zip file on your local machine containing the sample.
Create a new Document Group including the additional fields malware set to True and password set to the zip file’s password.
Upload the Document contents .

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

Note

The length of a tag is limited to 128 characters.

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
events
incidents
intrusionSets
reports
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
	status†	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
reports	fileName	TRUE	FALSE
	name	TRUE	FALSE
	malware	FALSE	FALSE
	password	FALSE	FALSE
threats	name	TRUE	FALSE
signatures	name	TRUE	TRUE
	fileName	TRUE	TRUE
	fileType*	TRUE	TRUE
	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 Document’s status are:

Success
Awaiting Upload
In Progress
Failed
None

* 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
events
incidents
intrusionSets
reports
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.