Groups

Groups represent a collection of related behavior and intelligence.

Endpoint: /api/v3/groups

Note

When targeting a specific Group in an API request, you can use the Group’s ID or, if one has been assigned, XID. In addition to the API, you can obtain a Group’s ID from the Group’s URL. On the Details screen, the URL looks like https://app.threatconnect.com/#/details/groups/123456/overview. The number between groups/ and /overview is the Group’s ID. On the legacy Details screen, the URL looks 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 you want to target 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. Accepts a valid date in ISO 8601 format or a null value.	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”
xid	The Group’s XID	String	FALSE	FALSE	“a1a1a1a1-a1a1-a1a1-a1a1-a1a1a1a1a1a1”

[1]

To retrieve a list of available Attribute Types, send the following request: GET /v3/attributeTypes.

[2]

To add a Description to a Group, use the attributes field to create a Description Attribute. Similarly, to add a Source to a Group, use the attributes field to create a Source Attribute.

[3] (1,2)

By default, Groups will be created in the Organization in which your API user account resides. To create a Group in a Community or Source, include the ownerId or ownerName field in your request. Alternatively, use the owner query parameter to specify the owner in which to create the Group.

[4]

The following are accepted values for the type field:

• Adversary

• Attack Pattern

• Campaign

• Course of Action

• Document

• Email

• Event

• Incident

• Intrusion Set

• Malware

• Report

• Signature

• Tactic

• Task

• Threat

• Tool

• Vulnerability

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?
customAiContent	An AI-generated summary of the Document. For more information, see the “AI Summaries” section.	Custom AI Content Object	FALSE	TRUE
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

[5]

If malware is set to true, then the password field will be required.

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?
customAiContent	An AI-generated summary of the Event. For more information, see the “AI Summaries” section.	Object	FALSE	TRUE
eventDate	The date when the Event took place. Accepts a valid date in ISO 8601 format or a null value.	DateTime	FALSE	TRUE
eventType [6]	The Event’s type. Accepts a valid Event type or a null value.	String	FALSE	TRUE
status [7]	The status of the Event. Accepts a valid Event status or a null value.	String	FALSE	TRUE

For more information on updating the status of Event Groups, see the Event Status section.

[6]

To retrieve a list of accepted values for the eventType field, send the following request: GET /v3/groups/eventTypeCategories. If you omit the eventType field from the request body or assign it a null value, the Event Group’s type will be set to None.

[7]

The following are accepted values for an Event Group’s status field:

• Completed

• Escalated

• False Positive

• In Progress

• Needs Review

• New

• No Further Action

• None

• Reopened

• null

If you omit the status field from the request body or assign it a null value, the Event Group’s status will be set to None.

Incident

Field	Description	Type	Required for Creation?	Updatable?
eventDate	The date when the Incident took place. Accepts a valid date in ISO 8601 format or a null value.	DateTime	FALSE	TRUE
status [8]	The status of the Incident	String	FALSE	TRUE

[8]

The following are accepted values for an Incident Group’s status field:

• New

• Open

• Stalled

• Containment Achieved

• Restoration Achieved

• Incident Reported

• Closed

• Rejected

• Deleted

Report

Field	Description	Type	Required for Creation?	Updatable?
customAiContent	An AI-generated summary of the Report. For more information, see the “AI Summaries” section.	Object	FALSE	TRUE
fileName	The file name of the Report	String	FALSE	TRUE
publishDate	The date when the Report was published. Accepts a valid date in ISO 8601 format or a null value.	DateTime	FALSE	TRUE
reviews	An Intelligence Review submitted for the Report. For more information, see the “Intelligence Reviews” section.	Intelligence Review Object	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

[9]

The fileText field contains the Signature itself, which must be properly escaped and encoded when creating or updating the Signature Group.

[10]

The following are accepted values for a Signature Group’s fileType field:

• Bro

• ClamAV

• CybOX

• Iris Search Hash

• KQL

• OpenIOC

• Regex

• SPL

• Sigma

• Snort

• Suricata

• TQL Query

• YARA

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	DateTime	FALSE	TRUE	“2021-04-30T00:00:00Z”
escalationDate	The date and time when the Task should be escalated	DateTime	FALSE	TRUE	“2021-04-30T00:00:00Z”
reminderDate	The date and time when a reminder about the Task will be sent	DateTime	FALSE	TRUE	“2021-04-30T00:00:00Z”
status [11]	The status of the Task	String	FALSE	FALSE	“In Progress”, “Not Started”

[11]

The following are accepted values for a Task Group’s status field:

• Not Started

• In Progress

• Completed

• Waiting on Someone

• Deferred

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

To apply an ATT&CK Tag to a Group, use either the corresponding technique ID or name. For example, to apply the T1566 - Phishing ATT&CK Tag to a Group, either set name to "Phishing" or techniqueId to "T1566" when defining the ATT&CK Tag object in the request body.

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"
            },
            {
                "techniqueId": "T1566"
            }
        ]
    }
}

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"