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 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 Details screen for a Group, the URL should look 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 (123456 in this example) is the ID for the Group.

Available Fields¶

You can retrieve a list of available fields for the /v3/groups endpoint, including each field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/groups

Hint

To view all fields, including read-only fields, include the ?show=readonly query parameter.

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 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	A list of Attributes corresponding 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”
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	The type of Group being created	String	TRUE	FALSE	“Document”, “Email”

Accepted values for the type field include:

Adversary
Attack Pattern
Campaign
Course of Action
Document
Email
Event
Incident
Intrusion Set
Malware
Report
Signature
Tactic
Task
Threat
Tool
Vulnerability

Note

A list of available Attribute Types can be retrieved with the following query:

GET /v3/attributeTypes

Hint

To associate an existing Artifact, Case, Group, or Victim Asset to a Group, use the object’s ID when setting the associatedArtifacts, associatedCases, associatedGroups, or associatedVictimAssets field, respectively (e.g., {"data": [{"id": 12345}]}). To associate an existing Indicator to a Group, use the Indicator’s ID, or the Indicator’s type and name (e.g., for a Host Indicator, use its hostName), when setting the associatedIndicators field.

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

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	Indicates whether the Document is malware	Boolean	FALSE	TRUE
password	The password associated with the Document	String	FALSE*	TRUE

Note

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

To upload the contents of a Document to ThreatConnect or update the contents of an existing Document in ThreatConnect, see the Upload a Document or Report and Update a Document or Report 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

Event¶

Field	Description	Type	Required for Creation?	Updatable?
eventDate	The date and time when the Event took place	Date	FALSE	TRUE
status	The status of the Event	String	FALSE	TRUE

Accepted values for an Event’s status include:

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	The status of the Incident	String	FALSE	TRUE

Accepted values for an Incident’s status include:

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 the contents of a Report to ThreatConnect or update the contents of an existing Report in ThreatConnect, see the Upload a Document or Report and Update a Document or Report sections, respectively.

Signature¶

Field	Description	Type	Required for Creation?	Updatable?
fileName	The file name of the Signature	String	TRUE	TRUE
fileText	The file text of the Signature	String	TRUE	TRUE
fileType	The file type of the Signature	String	TRUE	TRUE

Accepted values for a Signature’s fileType include:

Bro
ClamAV
CybOX
Iris Search Hash
OpenIOC
Regex
SPL
Sigma
Snort
Suricata
YARA

Note

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

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	The status of the Task	String	FALSE	FALSE	“In Progress”, “Not Started”

Accepted values for a Task’s status include:

Not Started
In Progress
Completed
Waiting on Someone
Deferred

Create Groups¶

The basic format for creating a Group is:

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 for the groups object.

Note

You can add multiple Attributes, Tags, and Security Labels to the Group being created in a single POST request. Similarly, you can associate multiple Artifacts, Cases, Indicators, and Groups to the Group being created in a single POST request.

Example POST Request¶

The following query will create an Incident Group for an Incident that took place on Nov. 3, 2021. The Incident will be assigned a status of New, and Targeted Attack and Robbery Tags will be created and applied to it.

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

JSON Response

{
    "data": {
        "id": 3,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3",
        "tags": {
            "data": [
                {
                    "id": 11,
                    "name": "Targeted Attack",
                    "lastUsed": "2021-11-02T15:01:44Z"
                },
                {
                    "id": 12,
                    "name": "Robbery",
                    "lastUsed": "2021-11-02T15:01:44Z"
                }
            ]
        },
        "securityLabels": {},
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "associatedGroups": {},
        "associatedIndicators": {},
        "associatedCases": {},
        "associatedArtifacts": {},
        "attributes": {},
        "status": "New",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2021-11-03T11:04:12Z"
    },
    "message": "Created",
    "status": "Success"
}

Note

When creating or updating a Group, you can apply Tags that do not yet exist in ThreatConnect to it. To do so, fill out all required fields for each new Tag. Upon creation of the new Group, any Tags included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Similarly, you can associate Artifacts, Cases, Indicators, and Groups that do not yet exist in ThreatConnect to the Group. In this scenario, you would need to fill out all required fields for the type of object being associated to the Group. Upon creation of the new Group, any associated objects included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Retrieve Groups¶

Retrieve All Groups¶

To retrieve all Groups, use the following query:

GET /v3/groups

JSON Response

{
    "data": [
        {
            "id": 10,
            "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",
                "role": "Api User"
            },
            "fileName": "indicators.txt",
            "fileSize": 36,
            "status": "Success",
            "documentType": "Text",
            "documentDateAdded": "2021-10-21T19:54:59Z",
            "lastModified": "2022-03-09T12:44:04Z"
        },
        {
            "id": 9,
            "type": "Email",
            "ownerName": "Demo Organization",
            "dateAdded": "2021-09-17T12:52:49Z",
            "webLink": "https://app.threatconnect.com//auth/email/email.xhtml?email=9",
            "name": "Your Amazon.com order for [email protected]",
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "JMS"
            },
            "to": "[email protected]",
            "from": "[email protected]",
            "subject": "Your Amazon.com order for [email protected]",
            "header": "Delivered-To: [MY EMAIL ADDRESS]\r\nReceived: by 10.182.3.66 with SMTP id a2csp104490oba;\r\nFri, 17 Sep 2021 08:50:19 -0400\r\n\r\nReceived: by 10.14.212.72 with SMTP id x48mr8232338eeo.40.1344724334578;\r\n\r\nFri, 17 Sep 2021 08:50:19 -0400\r\n\r\nReturn-Path: <[email protected]>\r\n\r\nReceived: from 72-255-12-30.client.stsn.net (72-255-12-30.client.stsn.net. [72.255.12.30])\r\n\r\nby mx.google.com with ESMTP id c41si1698069eem.38.2012.08.11.15.32.13;\r\n\r\nFri, 17 Sep 2021 08:50:19 -0400\r\n\r\nReceived-SPF: neutral (google.com: 72.255.12.30 is neither permitted nor denied by best guess record for domain of [email protected]) client-ip=72.255.12.30;\r\n\r\nAuthentication-Results: mx.google.com; spf=neutral (google.com: 72.255.12.30 is neither permitted nor denied by best guess record for domain of [email protected]) [email protected]\r\n\r\nReceived: by vwidxus.net id hnt67m0ce87b for <[MY EMAIL ADDRESS]>; Fri, 17 Sep 2021 08:50:19 -0400 (envelope-from <[email protected]>)\r\n\r\nReceived: from vwidxus.net by web.vwidxus.net with local (Mailing Server 4.69)\r\n\r\nid 34597139-886586-27/./PV3Xa/WiSKhnO+7kCTI+xNiKJsH/rC/\r\n\r\nfor [email protected]; Fri, 17 Sep 2021 08:50:19 -0400",
            "body": "Please visit bad.com to see your order and give us all your money. Muahahahaha!\r\n\r\n",
            "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"
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Single Group¶

To retrieve a specific Group, use a query in the following format:

GET /v3/groups/{groupId}

For example, the following query will return information about the Group with ID 3:

GET /v3/groups/3

JSON Response

{
    "data": {
        "id": 3,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com//auth/incident/incident.xhtml?incident=3",
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "status": "New",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2022-02-16T18:54:23Z"
    },
    "status": "Success"
}

Request Additional Fields¶

To request additional fields not automatically included with each returned object, refer to Include Additional Fields for Returned Objects.

Filter Results¶

To filter returned objects using ThreatConnect Query Language (TQL), refer to Filter Results with TQL.

Update Groups¶

The basic format for updating a Group is:

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 for the groups object.

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 query will complete the following actions for the Incident Group with ID 3:

Associate an Email Address Indicator (verybadguy@bad.com) and a Host Indicator (ultrabadguy.com) to the Group
Add an Additional Analysis and Context Attribute to the Group
Update the status of the Incident
Remove the Robbery Tag applied to the Group.

PUT /v3/groups/3
{
    "associatedIndicators": {"data": [{"id": 15}, {"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": "Robbery"}], "mode": "delete"}
}

JSON Response

{
    "data": {
        "id": 3,
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "https://app.threatconnect.com/auth/incident/incident.xhtml?incident=3",
        "tags": {
            "data": [{
                "id": 11,
                "name": "Targeted Attack",
                "lastUsed": "2021-11-04T18:52:29Z"
            }],
        },
        "securityLabels": {},
        "type": "Incident",
        "name": "Bad Incident",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "associatedGroups": {},
        "associatedIndicators": {
            "data": [
                {
                    "id": 15,
                    "type": "EmailAddress",
                    "ownerName": "Demo Organization",
                    "dateAdded": "2021-10-26T16:26:19Z",
                    "webLink": "https://app.threatconnect.com/auth/indicators/details/emailaddress.xhtml?emailaddress=verybadguy%40bad.com",
                    "lastModified": "2021-11-04T19:07:01Z",
                    "summary": "[email protected]",
                    "privateFlag": false,
                    "active": true,
                    "activeLocked": false,
                    "address": "[email protected]"
                },
                {
                    "id": 9,
                    "type": "Host",
                    "ownerName": "Demo Organization",
                    "dateAdded": "2021-10-26T12:40:00Z",
                    "webLink": "https://app.threatconnect.com/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
                    "lastModified": "2021-11-04T13:00:29Z",
                    "rating": 4.0,
                    "confidence": 85,
                    "summary": "ultrabadguy.com",
                    "privateFlag": false,
                    "active": true,
                    "activeLocked": false,
                    "hostName": "ultrabadguy.com",
                    "dnsActive": true,
                    "whoisActive": true
                }
            ],
        },
        "associatedCases": {},
        "associatedArtifacts": {},
        "attributes": {
            "data": [{
                "id": 10,
                "type": "Additional Analysis and Context",
                "value": "Based on internal analysis, this incident was very severe.",
                "source": "Example Source",
                "createdBy": {
                    "id": 3,
                    "userName": "11112222333344445555",
                    "firstName": "John",
                    "lastName": "Smith",
                    "pseudonym": "jsmithAPI",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-04T19:07:01Z",
                "lastModified": "2021-11-04T19:07:01Z",
                "default": false
            }],
        },
        "status": "Incident Reported",
        "eventDate": "2021-11-03T00:00:00Z",
        "lastModified": "2022-03-09T08:14:23Z"
    },
    "message": "Updated",
    "status": "Success"
}

Delete Groups¶

The basic format for deleting a Group is:

DELETE /v3/groups/{groupId}

For example, the following query will delete the Group with ID 1:

DELETE /v3/groups/1

JSON Response

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

Retrieve, Upload, and Update a Document¶

Retrieve a Document, Report, or Signature¶

To download the contents of a Document, Report, or Signature in ThreatConnect, use a query in the following format:

GET /v3/groups/{groupId}/download

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.

Upload a Document or Report¶

To upload the contents of a Document or Report in ThreatConnect, use a query in the following format:

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

<raw report contents>

If uploading a document to the Malware Vault, the following steps must be completed before uploading the document:

Create a password-protected zip file on your computer that contains the document.
Create a new Document Group with the additional fields malware set to true and password set to the zip file’s password.

Attention

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

Update a Document or Report¶

To update the contents of an existing Document or Report in ThreatConnect, use a query in the following format:

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

New Document contents go here.

Retrieve a PDF Report for Groups¶

To retrieve a PDF report for a Group, use a query in the following format:

GET /v3/groups/{groupId}/pdf

PDF reports can only be retrieved for the following Group types:

Adversary
Attack Pattern
Campaign
Course of Action
Event
Incident
Intrusion Set
Malware
Report
Tactic
Threat
Tool
Vulnerability