Groups

Groups represent a collection of related behavior and intelligence.

Endpoint: /api/v3/groups

Note

When working with Groups using the ThreatConnect v3 API, you can target a specific Group by its ID or, if one has been assigned to it, XID. While you can use the API to retrieve a Group’s ID, you can also find it in the URL of each Group. If you navigate to the new Details screen, the URL should look like https://app.threatconnect.com/#/details/groups/123456/overview. The number between groups/ and /overview is the Group’s ID. Similarly, if you navigate to the legacy Details screen for a Group, the URL should look like https://app.threatconnect.com/auth/<GROUP-TYPE>/<GROUP-TYPE>.xhtml?<GROUP-TYPE>=123456. The number following <GROUP-TYPE>= is the Group’s ID.

If targeting a Group by its XID, you must use the owner query parameter to specify the owner in which the Group exists.

Endpoint Options

Available Fields

Send the following request to retrieve a list of available fields, including each field’s name, description, and accepted data type, that can be included in the body of a POST or PUT request to the /v3/groups endpoint:

OPTIONS /v3/groups

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

Alternatively, refer to the following table for a list of available fields that can be included in the body of a POST or PUT request to the /v3/groups endpoint for all Group types.

Field

Description

Type

Required for Creation?

Updatable?

Example Value(s)

associatedArtifacts

A list of Artifacts associated to the Group

Artifact Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{ “caseId”: 1, “summary”: “badguy@bad.com”, “type”: “Email Address”}]}

associatedCases

A list of Cases associated to the Group

Case Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Hacker Investigation”, “status”: “Open”, “severity”: “Low” }]}

associatedGroups

A list of Groups associated to the Group

Group Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}

associatedIndicators

A list of Indicators associated to the Group

Indicator Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“hostName”:”badguy.com”, “type”: “Host”}]}

associatedVictimAssets

A list of Victim Assets associated to the Group

Victim Asset Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“phone”: “0123456789”, “type”: “Phone”}]}

attributes [1]

A list of Attributes added to the Group

Group Attribute Object

FALSE

TRUE

{“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”}]}

externalDateAdded

The date and time when the Group was created externally

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

externalDateExpires

The date and time when the Group expires externally

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

externalLastModified

The date and time when the Group was last modified externally

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

firstSeen

The date and time when the Group was first seen

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

lastSeen

The date and time when the Group was last seen

DateTime

FALSE

TRUE

“2023-10-04T12:34:56Z”

name

The Group’s name

String

TRUE

TRUE

“21-0043847: Threat Actor Capabilities”

ownerId [2]

The ID of the owner to which the Group belongs

Integer

FALSE

FALSE

1, 2, 3,…100

ownerName [2]

The name of the owner to which the Group belongs

String

FALSE

FALSE

“Demo Community”

securityLabels

A list of Security Labels applied to the Group

Security Label Object

FALSE

TRUE

{“data”: [{“name”: “TLP:AMBER”}]}

tags

A list of Tags applied to the Group

Tag Object

FALSE

TRUE

{“data”: [{“name”: “Targeted Attack”}]}

type [3]

The type of Group being created

String

TRUE

FALSE

“Document”, “Email”

upVote

Use this field to update the Group’s Intel Rating

Boolean

FALSE

TRUE

0 (to submit a Downvote Intel Rating) or 1 (to submit an Upvote Intel Rating)

xid

The Group’s XID

String

FALSE

FALSE

“a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1”

Group-Specific Fields

Based on the type of Group being created, you may need to include additional fields in the body of a POST request. Similarly, some Group types include additional fields that may be updated via a PUT request.

The following tables lists valid fields that can be included in the body of a POST or PUT request Document, Email, Event, Incident, Report, Signature, and Task Groups.

Document

Field

Description

Type

Required for Creation?

Updatable?

fileName

The file name of the Document

String

TRUE

TRUE

malware [4]

Indicates whether the Document is malware

Boolean

FALSE

TRUE

password

The password associated with the Document

String

FALSE*

TRUE

To upload a file to a Document Group or update the contents of a file uploaded to a Document Group, see the Upload a File to a Document or Report Group and Update a Document or Report Group’s File sections, respectively.

Email

Field

Description

Type

Required for Creation?

Updatable?

body

The Email’s body

String

FALSE

TRUE

from

The Email’s From: field

String

FALSE

TRUE

header

The Email’s header

String

FALSE

TRUE

subject

The Email’s subject

String

FALSE

TRUE

Note

The to field for Email Groups is a read-only field. However, associating an Email Address Victim Asset to an Email Group will populate the Email Group’s to field with that Victim Asset’s email address automatically.

Event

Field

Description

Type

Required for Creation?

Updatable?

eventDate

The date and time when the Event took place

Date

FALSE

TRUE

status [5]

The status of the Event

String

FALSE

TRUE

Incident

Field

Description

Type

Required for Creation?

Updatable?

eventDate

The date when the Incident took place

Date

FALSE

TRUE

status [6]

The status of the Incident

String

FALSE

TRUE

Report

Field

Description

Type

Required for Creation?

Updatable?

fileName

The file name of the Report

String

FALSE

TRUE

publishDate

The date and time when the Report was published

Date

FALSE

TRUE

To upload a file to a Report Group or update the contents of a file uploaded to a Report Group, see the Upload a File to a Document or Report Group and Update a Document or Report Group’s File sections, respectively.

Signature

Field

Description

Type

Required for Creation?

Updatable?

fileName

The file name of the Signature

String

TRUE

TRUE

fileText [7]

The file text of the Signature

String

TRUE

TRUE

fileType [8]

The file type of the Signature

String

TRUE

TRUE

Note

Accepted values for a Signature Group’s fileType field may also include custom Signature types created by a System Administrator.

Task

Field

Description

Type

Required for Creation?

Updatable?

Example Value(s)

assignments

A list of users assigned to the Task or to whom the Task will be escalated. Valid values for the type of assignment are “Assigned” and “Escalate”

Assignee Object

FALSE

TRUE

{“data”: [{“type”: “Assigned”, “user”: {“id”: 12}}]}

{“data”: [{“type”: “Escalate”, “user”: {“id”: 8}}]}

dueDate

The date and time when the Task is due

Date

FALSE

TRUE

“2021-04-30T00:00:00Z”

escalationDate

The date and time when the Task should be escalated

String

FALSE

TRUE

“2021-04-30T00:00:00Z”

reminderDate

The date and time when a reminder about the Task will be sent

String

FALSE

TRUE

“2021-04-30T00:00:00Z”

status [9]

The status of the Task

String

FALSE

FALSE

“In Progress”, “Not Started”

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/groups endpoint:

OPTIONS /v3/groups/fields

Filter Results

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can use when including the tql query parameter in a request to the /v3/groups endpoint:

OPTIONS /v3/groups/tql

Create Groups

The following example illustrates the basic format for creating a Group:

POST /v3/groups
{
    "name": "Group name goes here",
    "type": "Group type goes here"
    //required fields for the selected Group type go here, if applicable
}

Refer to the Available Fields and Group-Specific Fields sections for a list of available fields that can be included in the body of a POST request to the /v3/groups endpoint.

Note

You can add multiple Attributes, Tags, and Security Labels to a Group in a single POST or PUT request.

Example POST Request

The following request will create an Incident Group for an Incident that took place on Nov. 3, 2021. The Incident will be assigned a status of New, two Tags will be applied to it: the Targeted Attack standard Tag and the T1566 - Phishing ATT&CK® Tag.

Attention

When applying ATT&CK Tags to a Group, do not include the corresponding technique/sub-technique ID in the Tag’s name. For example, to apply the T1566 - Phishing ATT&CK Tag to a Group, use Phishing as the Tag name.

Also, if you applied a new Tag to a Group and that Tag matches a synonymous Tag listed in a Tag normalization rule, it will be converted to the main Tag listed in the rule. Similarly, if you applied a new Tag to a Group and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.

Hint

To include the tags field in the API response, append ?fields=tags to the end of the request URL.

POST /v3/groups
{
    "type": "Incident",
    "name": "Bad Incident",
    "eventDate": "2021-11-03",
    "status": "New",
    "tags": {
        "data": [
            {
                "name": "Targeted Attack"
            },
            {
                "name": "Phishing"
            }
        ]
    }
}

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com/#/details/groups/3/overview",
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "upVoteCount":"0",
        "downVoteCount":"0",
        "status": "New",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2021-11-03T14:57:4511:04:12Z",
        "legacyLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3"
    },
    "message": "Created",
    "status": "Success"
}

Retrieve Groups

Retrieve All Groups

Send the following request to retrieve data for all Groups:

GET /v3/groups

JSON Response

{
    "data": [
        {
            "id": 10,
            "ownerId": 1,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-10-21T19:54:59Z",
            "webLink": "https://app.threatconnect.com/auth/document/document.xhtml?document=10",
            "type": "Document",
            "name": "Bad Document",
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "owner": "Demo Organization"
            },
            "upVoteCount":"0",
            "downVoteCount":"0",
            "fileName": "indicators.txt",
            "fileSize": 36,
            "status": "Success",
            "documentType": "Text",
            "documentDateAdded": "2021-10-21T19:54:59Z",
            "lastModified": "2022-03-09T12:44:04Z",
            "legacyLink": "https://app.threatconnect.com/auth/document/document.xhtml?document=10"
        },
        {
            "id": 9,
            "ownerId": 1,
            "ownerName": "Demo Organization",
            "dateAdded": "2021-09-17T12:52:49Z",
            "webLink": "https://app.threatconnect.com/auth/email/email.xhtml?email=9",
            "type": "Email",
            "name": "Your Amazon.com order for [email protected]",
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "owner": "Demo Organization"
            },
            "upVoteCount":"0",
            "downVoteCount":"0",
            "to": "[email protected]",
            "from": "[email protected]",
            "subject": "Your Amazon.com order for [email protected]",
            "header": "<email header goes here>",
            "body": "Please visit bad.com to see your order and give us all your money. Muahahahaha!",
            "scoreIncludesBody": true,
            "emailDate": "2021-09-17T12:50:19Z",
            "scoreBreakdown": "Rule SPF Neutral was matched against 'neutral'.\t100\nRule Host was matched against 'bad.com'.\t282\n",
            "lastModified": "2022-03-09T20:39:52Z",
            "legacyLink": "https://app.threatconnect.com/auth/email/email.xhtml?email=9"
        },
        {...}
    ],
    "status": "Success"
}

Hint

Use the owner query parameter to limit the results to a specific owner.

Retrieve a Specific Group

Send a request in the following format to retrieve data for a specific Group:

Example Request (Group ID)

GET /v3/groups/{groupId}

Example Request (Group XID)

GET /v3/groups/{groupXid}?owner={ownerName}

For example, the following request will retrieve data for the Group whose ID is 3:

GET /v3/groups/3

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com/#/details/groups/3/overview",
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "upVoteCount":"0",
        "downVoteCount":"0",
        "status": "New",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2021-11-03T14:57:45Z2022-02-16T18:54:23Z",
        "legacyLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3",
    },
    "status": "Success"
}

Update Groups

The following example illustrates the basic format for updating a Group:

Example Request (Group ID)

PUT /v3/groups/{groupId}
{
    {updatedField}: {updatedValue}
}

Example Request (Group XID)

PUT /v3/groups/{groupXid}?owner={ownerName}
{
    {updatedField}: {updatedValue}
}

Refer to the Available Fields and Group-Specific Fields sections for a list of available fields that can be included in the body of a PUT request to the /v3/groups endpoint.

Hint

When updating a Group, you can use the mode field to add or remove the following metadata:

  • associatedArtifacts

  • associatedCases

  • associatedGroups

  • associatedIndicators

  • associatedVictimAssets

  • attributes

  • securityLabels

  • tags

See Update an Object’s Metadata for instructions on using the mode field.

Example PUT Request

The following request will make the following updates to the Incident Group whose ID is 3:

  • Associate an Email Address Indicator (verybadguy@bad.com) that exists in Demo Community to the Group

  • Create a new Host Indicator (ultrabadguy.com) in the API user’s Organization and associate it to the Group

  • Add an Additional Analysis and Context Attribute to the Group

  • Update the status of the Incident

  • Remove the Targeted Attack Tag applied to the Group

Hint

To include the associatedIndicators, attributes, and tags fields in the API response, append ?fields=associatedIndicators&fields=attributes&fields=tags to the end of the request URL.

PUT /v3/groups/3
{
    "associatedIndicators": {
        "data": [
            {
                "address": "[email protected]",
                "type": "EmailAddress",
                "ownerName": "Demo Community"
            },
            {
                "hostName": "ultrabadguy.com",
                "type": "Host"
            }
        ]
    },
    "attributes": {
        "data": [
            {
                "type": "Additional Analysis and Context",
                "value": "Based on internal analysis, this incident was very severe.",
                "source": "Example Source"
            }
        ]
    },
    "status": "Incident Reported",
    "tags": {
        "data": [
            {
                "name": "Targeted Attack"
            }
        ],
        "mode": "delete"
    }
}

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com/#/details/groups/3/overview",
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "upVoteCount":"0",
        "downVoteCount":"0",
        "status": "Incident Reported",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2022-03-09T08:14:23Z",
        "legacyLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3"
    },
    "message": "Updated",
    "status": "Success"
}

Delete Groups

Send a request in the following format to delete a Group:

Example Request (Group ID)

DELETE /v3/groups/{groupId}

Example Request (Group XID)

DELETE /v3/groups/{groupXid}?owner={ownerName}

For example, the following request will delete the Group whose ID is 1:

DELETE /v3/groups/1

JSON Response

{
    "message": "Deleted",
    "status": "Success"
}

Retrieve, Upload, and Update Files for Document and Report Groups

Retrieve a Document or Report Group’s File

Send a request in the following format to download the contents of the file uploaded to a Document or Report Group:

Example Request (Group ID)

GET /v3/groups/{groupId}/download

Example Request (Group XID)

GET /v3/groups/{groupXid}/download?owner={ownerName}

The contents of the file will be returned as Content-Type: application/octet-stream.

Upload a File to a Document or Report Group

Before you can upload a file to a Document or Report Group, the Group must exist in one of your ThreatConnect owners. The following examples demonstrate how to create a Document and Report Group.

Request (Document)

POST /v3/groups
{
    "type": "Document",
    "fileName": "example_document.pdf",
    "name": "Example Document Group"
}

Request (Report)

POST /v3/groups
{
    "type": "Report",
    "fileName": "example_report.pdf",
    "name": "Example Report Group"
}

Send a request in the following format to upload the contents of a file to an existing Document or Report Group. Note that the filename query parameter is only required if the fileName field was not assigned a value when the Group was created.

Example Request (Group ID)

POST /v3/groups/{groupId}/upload?filename={fileName.extension}
Content-Type: application/octet-stream

<raw file contents>

Example Request (Group XID)

POST /v3/groups/{groupXid}/upload?filename={fileName.extension}&owner={ownerName}
Content-Type: application/octet-stream

<raw file contents>

Hint

When uploading a file to a Group via a POST request, set the updateIfExists query parameter to true to replace any existing file uploaded to the Group. Alternatively, use a PUT request to update the file uploaded to the Group, as described in the `"Update a Document or Report Group's File"<#id27>`_ section.

If uploading a file to the Malware Vault, complete the following steps before performing the upload:

  • Create a password-protected zip file on your computer that contains the file.

  • Create a new Document Group with the additional fields malware set to true and password set to the zip file’s password.

Attention

If uploading a file larger than 5GB, contact your System Administrator about increasing the allowed file size for uploads.

Note

If you upload a file whose extension differs from the one specified in the fileName field when the Group was created, use the filename query parameter to update the value of this field so that the extension matches that of the uploaded file.

The following request will upload a file named report.pdf to the Report Group whose ID is 25. In this example, the filename query parameter is included in the request URI because the fileName field was not defined when the Group was created. If the fileName field had been defined when the Group was created, then the filename query parameter would not be required.

Request (HTTP)

POST /v3/groups/25/upload?filename=report.pdf
Content-Type: application/octet-stream

<raw file contents>

Request (cURL)

curl --location --request POST 'https://app.threatconnect.com/api/v3/groups/25/upload?filename=report.pdf' \
--header 'Timestamp: $UNIX_EPOCH_TIMESTAMP' \
--header 'Authorization: TC $ACCESS_ID:$SIGNATURE' \
--header 'Content-Type: application/octet-stream' \
--data '@/Users/jsmith/Desktop/report.pdf'

Response

{
    "message": "Upload successful",
    "status": "Success"
}

Update a Document or Report Group’s File

Send a request in the following format to update the contents of a file uploaded to a Document or Report Group:

Example Request (Group ID)

PUT /v3/groups/{groupId}/upload?filename={fileName.extension}
Content-Type: application/octet-stream

<new file contents>

Example Request (Group XID)

PUT /v3/groups/{groupXid}/upload?filename={fileName.extension}&owner={ownerName}
Content-Type: application/octet-stream

<new file contents>

The following request will update the contents of the file named report.pdf uploaded to the Report Group whose ID is 25:

Request (HTTP)

PUT /v3/groups/25/upload?filename=report.pdf
Content-Type: application/octet-stream

<new file contents>

Request (cURL)

curl --location --request PUT 'https://app.threatconnect.com/api/v3/groups/25/upload?filename=report.pdf' \
--header 'Timestamp: $UNIX_EPOCH_TIMESTAMP' \
--header 'Authorization: TC $ACCESS_ID:$SIGNATURE' \
--header 'Content-Type: application/octet-stream' \
--data '@/Users/jsmith/Desktop/report.pdf'

Response

{
    "message": "Upload successful",
    "status": "Success"
}

Retrieve a PDF Report for a Group

Send a request in the following format to retrieve a PDF report for a Group:

Example Request (Group ID)

GET /v3/groups/{groupId}/pdf

Example Request (Group XID)

GET /v3/groups/{groupXid}/pdf?owner={ownerName}

You can retrieve PDF reports for the following Group types:

  • Adversary

  • Attack Pattern

  • Campaign

  • Course of Action

  • Event

  • Incident

  • Intrusion Set

  • Malware

  • Report

  • Tactic

  • Threat

  • Tool

  • Vulnerability

Associations

For instructions on creating and managing associations for Groups, see Create and Manage Associations.


MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.