Group Attributes

Attributes are key/value data sets that can be added to any Group. This type of metadata provides an excellent way to organize, categorize, and integrate Groups into an organization’s analytic workflow.

Endpoint: /api/v3/groupAttributes

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/groupAttributes endpoint:

OPTIONS /v3/groupAttributes

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/groupAttributes endpoint.

Field	Description	Type	Required for Creation?	Updatable?
default	Indicates whether the Attribute is the default Attribute of its type for the Group to which it is added (this field applies to certain Attribute and data types only)	Boolean	FALSE	TRUE
groupId	The ID of the Group to which the Attribute is added	Integer	TRUE	FALSE
pinned	Indicates whether the Attribute is to be displayed as a Pinned Attribute on the Details screen for the Group to which the Attribute is added	Boolean	FALSE	TRUE
securityLabels	A list of Security Labels applied to the Attribute	Security Label Object	TRUE	FALSE
source	The Attribute’s source	String	FALSE	TRUE
type [1]	The Attribute’s type	String	TRUE	FALSE
value	The Attribute’s value	String	TRUE	TRUE

[1]

When setting the type field, you must enter a valid Attribute Type that applies to the type of Group to which the Attribute is being added. To retrieve a list of available Attribute Types, send the following request: GET /v3/attributeTypes.

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/groupAttributes endpoint:

OPTIONS /v3/groupAttributes/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/groupAttributes endpoint:

OPTIONS /v3/groupAttributes/tql

Create Group Attributes

The following example illustrates the basic format for creating a Group Attribute:

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

{
    "groupId": 12345,
    "type": "Attribute type goes here",
    "value": "Attribute value goes here"
}

For example, the following request will create an Attribute and add it to the Group whose ID is 20:

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

{
    "groupId": 20,
    "source": "Phase of Intrusion",
    "type": "Additional Analysis and Context",
    "value": "This is a very dangerous adversary."
}

JSON Response

{
    "data": {
        "id": 10,
        "dateAdded": "2021-11-09T14:42:13Z",
        "type": "Additional Analysis and Context",
        "value": "This is a very dangerous adversary.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2021-11-09T14:42:13Z",
        "pinned": false,
        "default": false
    },
    "message": "Created",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a POST request to the /v3/groupAttributes endpoint.

Hint

Group Attributes can also be created and added to a Group when creating the Group. See the “Create Groups” section of Groups for more information.

Retrieve Group Attributes

The following section describes how to retrieve Group Attributes via the /v3/groupAttributes endpoint. In addition to the methods described in this section, you can send the following request to retrieve Attributes added to a specific Group: GET /v3/groups/{groupId}?fields=attributes.

Retrieve All Group Attributes

Send the following request to retrieve data for all Group Attributes:

GET /v3/groupAttributes

JSON Response

{
    "data": [
        {
            "id": 10,
            "dateAdded": "2023-03-29T14:42:13Z",
            "type": "Aliases",
            "value": "APT28, Fancy Bear, Threat Group-4127, TG-4127",
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "owner": "Demo Organization"
            },
            "lastModified": "2023-03-29T14:42:13Z",
            "settings": {
                "associable": true,
                "pinnedByDefault": true,
                "message": "Enter the Group's aliases."
            },
            "pinned": true,
            "default": true
        },
        {
            "id": 9,
            "dateAdded": "2023-03-28T15:56:46Z",
            "type": "Source",
            "value": "https://examplesite.com",
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "owner": "Demo Organization"
            },
            "lastModified": "2023-03-28T15:56:46Z",
            "pinned": true,
            "default": true
        },
        {
            "id": 8,
            "dateAdded": "2023-03-08T15:55:59Z",
            "type": "Description",
            "value": "This malware is written in a new programming language and has the potential of targeting millions of routers and IOT devices.",
            "source": "Internal analysis",
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "owner": "Demo Organization"
            },
            "lastModified": "2023-03-08T15:55:59Z",
            "pinned": false,
            "default": true
        },
        {...}
    ],
    "status": "Success"
}

Note

If an Attribute Type is configured as a default, pinned, or association Attribute Type, then the settings field will be included in the response for Attributes of that Attribute Type.

Retrieve a Specific Group Attribute

Send a request in the following format to retrieve data for a specific Group Attribute:

GET /v3/groupAttributes/{groupAttributeId}

For example, the following request will retrieve data for the Group Attribute whose ID is 7:

GET /v3/groupAttributes/7

JSON Response

{
    "data": {
        "id": 7,
        "dateAdded": "2023-03-08T15:55:59Z",
        "type": "Description",
        "value": "This Incident is related to a recent ransomware attack.",
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmith",
            "owner": "Demo Organization"
        },
        "lastModified": "2023-03-08T15:55:59Z",
        "pinned": false,
        "default": true
    },
    "status": "Success"
}

Update Group Attributes

The following example illustrates the basic format for updating a Group Attribute:

PUT /v3/groupAttributes/{groupAttributeId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

For example, the following request will update the value of the Group Attribute whose ID is 10 and and add a source to the Attribute:

PUT /v3/groupAttributes/10
Content-Type: application/json

{
    "source": "CAL",
    "value": "APT28, IRON TWILIGHT, SNAKEMACKEREL, Swallowtail, Group 74, Sednit, Sofacy, Pawn Storm, Fancy Bear, STRONTIUM, Tsar Team, Threat Group-4127, TG-4127"
}

JSON Response

{
    "data": {
        "id": 10,
        "dateAdded": "2023-03-29T14:42:13Z",
        "type": "Aliases",
        "value": "APT28, IRON TWILIGHT, SNAKEMACKEREL, Swallowtail, Group 74, Sednit, Sofacy, Pawn Storm, Fancy Bear, STRONTIUM, Tsar Team, Threat Group-4127, TG-4127",
        "source": "CAL",
        "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "owner": "Demo Organization"
        },
        "lastModified": "2023-03-30T07:16:29Z",
        "settings": {
            "associable": true,
            "pinnedByDefault": true,
            "message": "Enter any aliases for the Group object."
        },
        "pinned": true,
        "default": true
    },
    "message": "Updated",
    "status": "Success"
}

Refer to the Available Fields section for a list of available fields that can be included in the body of a PUT request to the /v3/groupAttributes endpoint.

Delete Group Attributes

Send a request in the following format to delete a Group Attribute:

DELETE /v3/groupAttributes/{groupAttributeId}

For example, the following request will delete the Group Attribute whose ID is 10:

DELETE /v3/groupAttributes/10

JSON Response

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

Hint

You can also remove Group Attributes from a Group by using the mode field on the /v3/groups endpoint. See Update an Object’s Metadata for more information.