Groups

Groups represent a collection of related behavior and intelligence.

Endpoint: /api/v3/groups

Note

When working with Groups using the ThreatConnect REST API, you may need to specify the ID of the Group with which you would like to work. 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.

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”}]}
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”
[1]To retrieve a list of available Attribute Types, send the following request: GET /v3/attributeTypes.
[2](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.
[3]

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 Campaign, Document, Email, Event, Incident, Report, Signature, and Task Groups.

Campaign

Field Description Type Required for Creation? Updatable?
firstSeen The date and time when the Campaign was created Date FALSE TRUE

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
[4]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?
eventDate The date and time when the Event took place Date FALSE TRUE
status [5] The status of the Event String FALSE TRUE
[5]

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

  • Needs Review
  • False Positive
  • No Further Action
  • Escalated

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
[6]

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?
fileName The file name of the Report String TRUE 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
[7]The fileText field contains the Signature itself, which must be properly escaped and encoded when creating or updating the Signature Group.
[8]

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 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”
[9]

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

Create Associations

You can create associations between Groups and Artifacts, Cases, Groups, Indicators, and Victim Assets that exist in the same owner. If cross-owner associations are enabled on your ThreatConnect instance, you can also create associations between Groups and Indicators and other Groups that exist in any owner to which you have access.

When creating associations for Groups using the ThreatConnect v3 API, follow these guidelines:

  • To create an association to a new Artifact, include all fields required to create an Artifact when setting the associatedArtifacts field.
  • To create an association to an existing Artifact, use the Artifact’s ID when setting the associatedArtifacts field (e.g., "associatedArtifacts": {"data": [{"id": 12345}]}).
  • To create an association to a new Case, include all fields required to create a Case when setting the associatedCases field.
  • To create an association to an existing Case, use the Case’s ID when setting the associatedCases field.
  • To create an association to a new Group, include all fields required to create the type of Group when setting the associatedGroups field. To create the Group in a Community or Source, include the ownerId or ownerName field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Group when setting the associatedGroups field.
  • To create an association to an existing Group, use the Group’s ID when setting the associatedGroups field.
  • To create an association to a new Indicator, include all fields required to create the type of Indicator when setting the associatedIndicators field. To create the Indicator in a Community or Source, include the ownerId or ownerName field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Indicator when setting the associatedIndicators field.
  • To create an association to an existing Indicator, use the Indicator’s ID, or use its summary and type (e.g., "associatedIndicators": {"data": [{"type": "Host", "hostname": "badguy.com"}]}), when setting the associatedIndicators field. To create association to an Indicator in a Community or Source using the Indicator’s summary and type, include the ownerId or ownerName field and specify the ID or name, respectively, of the Community or Source to which the Indicator belongs when setting the associatedIndicators field.
  • To create an association to a new Victim Asset, include all fields required to create a Victim Asset when setting the associatedVictimAssets field.
  • To create an association to an existing Victim Asset, use the Victim Asset’s ID when setting the associatedVictimAssets field.

Note

You can associate multiple Artifacts, Cases, Groups, Indicators, and Victim Assets to a Group in a single POST or PUT request.

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:

GET /v3/groups/{groupId}

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:

PUT /v3/groups/{groupId}
{
    {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:

DELETE /v3/groups/{groupId}

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:

GET /v3/groups/{groupId}/download

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

Upload a File to a Document or Report Group

Send a request in the following format to upload the contents of a file to an existing Document or Report Group:

POST /v3/groups/{groupId}/upload
Content-Type: application/octet-stream

<raw report contents>

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 for the Group, update the value of this field so that the extension matches that of the uploaded file.

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:

PUT /v3/groups/{groupId}/upload
Content-Type: application/octet-stream

<new document contents>

Retrieve a PDF Report for a Group

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

GET /v3/groups/{groupId}/pdf

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

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