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], [2]	A list of Attributes added to the Group	Group Attribute Object	FALSE	TRUE	{“data”: [{“type”: “Description”, “value”: “A dangerous Group”, “default”: true}]}
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 [3]	The ID of the owner to which the Group belongs	Integer	FALSE	FALSE	1, 2, 3,…100
ownerName [3]	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 [4]	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	FALSE	TRUE
malware [5]	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
eventType [6]	The Event’s type	String	FALSE	TRUE
status [7]	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 [8]	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 [9]	The file text of the Signature	String	TRUE	TRUE
fileType [10]	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 [11]	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
Content-Type: application/json

{
    "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
Content-Type: application/json

{
    "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}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

Example Request (Group XID)

PUT /v3/groups/{groupXid}?owner={ownerName}
Content-Type: application/json

{
    {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 a Description (i.e., a default Description 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
Content-Type: application/json

{
    "associatedIndicators": {
        "data": [
            {
                "address": "[email protected]",
                "type": "EmailAddress",
                "ownerName": "Demo Community"
            },
            {
                "hostName": "ultrabadguy.com",
                "type": "Host"
            }
        ]
    },
    "attributes": {
        "data": [
            {
                "type": "Description",
                "value": "A very severe incident",
                "default": true
            }
        ]
    },
    "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
Content-Type: application/json

{
    "type": "Document",
    "fileName": "example_document.pdf",
    "name": "Example Document Group"
}

Request (Report)

POST /v3/groups
Content-Type: application/json

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