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 the field’s name, description, and accepted data type, by using the following query:

OPTIONS /v3/groups

Note

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

Alternatively, refer to the following tables 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)
associatedGroups A list of Groups associated to the Group String FALSE TRUE {“data”: [{“id”: 12345}]}, {“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
associatedIndicators A list of Indicators associated to the Group String FALSE TRUE {“data”: [{“id”: 12345}]}, {“data”: [{“hostName”:”badguy.com”, “type”: “Host”}]}
associatedVictimAssets A list of Victim Assets associated to the Group String FALSE TRUE {“data”: [{“id”: 12345}]}, {“data”: [{“phone”: “0123456789”, “type”: “Phone”}]}
attributes A list of Attributes corresponding to the Group String 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”
ownerName The name of the Organization, Community, or Source to which the Group belongs String FALSE FALSE “Demo Community”
securityLabels A list of Security Labels applied to the Group String FALSE TRUE {“data”: [{“name”: “TLP:AMBER”}]}
tags A list of Tags applied to the Group String FALSE TRUE {“data”: [{“name”: “Targeted Attack”}]}
type The type of Group being created String TRUE FALSE “Document”, “Email”

Available 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

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
to The Email’s To: field String FALSE TRUE

Event

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

Valid 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 and time when the Incident was created Date FALSE TRUE
status The status of the Incident String FALSE TRUE

Valid 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 created 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

Valid values for a Signature’s fileType include:

  • Bro
  • ClamAV
  • CybOX
  • Irish 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” String 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”

Valid values for an 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 included in the body of a POST request for the groups object.

Warning

If you submit a POST request to create a new Group but the Group already exists in ThreatConnect, the existing Group will be updated based on the fields included in the POST request.

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 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-03T10:50:00Z",
    "status": "New",
    "tags": {"data": [{"name": "Targeted Attack"}, {"name": "Robbery"}]}
}

JSON Response

{
    "data": {
        "id": 3,
        "type": "Incident",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "/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"
            }],
            "count": 2
        },
        "securityLabels": {
            "count": 0
        },
        "name": "Bad Incident",
        "createdBy": "API User",
        "associatedGroups": {
            "count": 0
        },
        "associatedIndicators": {
            "count": 0
        },
        "attributes": {
            "count": 0
        },
        "status": "New",
        "eventDate": "2021-11-03T00:00:00Z"
    },
    "message": "Created",
    "status": "Success"
}

Note

When creating an Group, you can apply Tags that do not yet exist in ThreatConnect to it. In this scenario, you would need to 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 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 Indicator or Group 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,
            "type": "Document",
            "ownerName": "Demo Organization",
            "dateAdded": "2021-10-21T19:54:59Z",
            "webLink": "/auth/document/document.xhtml?document=181449",
            "name": "Bad Document",
            "createdBy": "John Smith",
            "fileName": "indicators.txt",
            "fileSize": 36,
            "status": "Success",
            "documentType": "Text",
            "documentDateAdded": "2021-10-21T19:54:59Z"
        },
        {
            "id": 9,
            "type": "Email",
            "ownerName": "Demo Organization",
            "dateAdded": "2021-09-17T12:52:49Z",
            "webLink": "/auth/email/email.xhtml?email=181443",
            "name": "Your Amazon.com order for [email protected]",
            "createdBy": "John Smith",
            "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"
        },
        {...}
    ],
    "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,
        "type": "Incident",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "/auth/incident/incident.xhtml?incident=3",
        "name": "Bad Incident",
        "createdBy": "API User",
        "status": "New",
        "eventDate": "2021-11-03T00:00:00Z"
    },
    "status": "Success"
}

Request Additional Fields

To request additional fields not automatically provided 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 included in the body of a PUT request for the groups object.

Note

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

  • 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}, {"name": "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,
        "type": "Incident",
        "ownerName": "Demo Organization",
        "dateAdded": "2021-11-03T14:57:45Z",
        "webLink": "/auth/incident/incident.xhtml?incident=3",
        "tags": {
            "data": [{
                "id": 11,
                "name": "Targeted Attack",
                "lastUsed": "2021-11-04T18:52:29Z"
            }],
            "count": 1
        },
        "securityLabels": {
            "count": 0
        },
        "name": "Bad Incident",
        "createdBy": "API User",
        "associatedGroups": {
            "count": 0
        },
        "associatedIndicators": {
            "data": [{
                "id": 15,
                "type": "EmailAddress",
                "ownerName": "Demo Organization",
                "dateAdded": "2021-10-26T16:26:19Z",
                "webLink": "/auth/indicators/details/emailaddress.xhtml?emailaddress=verybadguy%40bad.com",
                "lastModified": "2021-11-04T19:07:01Z",
                "description": "Sample Email Address Indicator created via API",
                "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": "/auth/indicators/details/host.xhtml?host=ultrabadguy.com",
                "lastModified": "2021-11-04T13:00:29Z",
                "rating": 4.0,
                "confidence": 85,
                "description": "The worst kind of bad guy.",
                "summary": "ultrabadguy.com",
                "privateFlag": false,
                "active": true,
                "activeLocked": false,
                "hostName": "ultrabadguy.com",
                "dnsActive": true,
                "whoisActive": true
            }],
            "count": 2
        },
        "attributes": {
            "data": [{
                "id": 10,
                "type": "Additional Analysis and Context",
                "value": "Based on internal analysis, this incident was very severe.",
                "source": "Example Source",
                "createdBy": {
                    "id": 39,
                    "userName": "62693284927610908885",
                    "firstName": "API",
                    "lastName": "User",
                    "pseudonym": "APIUserNFmof",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-04T19:07:01Z",
                "lastModified": "2021-11-04T19:07:01Z",
                "default": false
            }],
            "count": 1
        },
        "status": "Incident Reported",
        "eventDate": "2021-11-03T00:00:00Z"
    },
    "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:

POST /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.

Warning

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