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

Available Fields

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

OPTIONS /v3/groupAttributes

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 the groupAttributes object.

Field Description Type Required for Creation? Updatable?
default A flag indicating whether an Attribute is the default Attribute of its type within the object. This field applies on to certain Attribute and data types Boolean FALSE TRUE
groupId The ID of the Group associated with the Attribute Integer TRUE FALSE
source The Attribute’s source String FALSE TRUE
type The Attribute’s type String TRUE FALSE
value The Attribute’s value String TRUE TRUE

Note

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, use the following query:

GET /v3/attributeTypes

Create Group Attributes

The basic format for creating a Group Attribute is:

POST /v3/groupAttributes/
{
    "groupId": 12345,
    "type": "Attribute type goes here",
    "value": "Attribute value goes here"
}

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

For example, the following query will create an Attribute and add it to the Group with ID 20:

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

JSON Response

{
    "data": {
        "id": 10,
        "type": "Additional Analysis and Context",
        "value": "This is a very dangerous adversary.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 39,
            "userName": "62693284927610908885",
            "firstName": "API",
            "lastName": "User",
            "pseudonym": "APIUserNFmof",
            "role": "Api User"
        },
        "dateAdded": "2021-11-09T14:42:13Z",
        "lastModified": "2021-11-09T14:42:13Z",
        "default": false
    },
    "message": "Created",
    "status": "Success"
}

Note

Group Attributes can also be created when creating a 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 retrieve Attributes added to a specific Group by using the following query:

GET /v3/groups/{groupId}?fields=attributes

Retrieve All Group Attributes

To retrieve all Group Attributes, use the following query:

GET /v3/groupAttributes/

JSON Response

{
    "data": [{
        "id": 10,
        "type": "Additional Analysis and Context",
        "value": "This is a very dangerous adversary.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 39,
            "userName": "62693284927610908885",
            "firstName": "API",
            "lastName": "User",
            "pseudonym": "APIUserNFmof",
            "role": "Api User"
        },
        "dateAdded": "2021-11-09T14:42:13Z",
        "lastModified": "2021-11-09T14:42:13Z",
        "default": false
    },
    {
        "id": 9,
        "type": "Source",
        "value": "https://examplesite.com",
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmith",
            "role": "Administrator"
        },
        "dateAdded": "2021-11-08T15:56:46Z",
        "lastModified": "2021-11-08T15:56:46Z",
        "default": true
    },
    {
        "id": 8,
        "type": "Description",
        "value": "This malware is written in a new programming language and has the potential of targeting millions of routers and IOT devices.",
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmith",
            "role": "Administrator"
        },
        "dateAdded": "2021-11-08T15:56:46Z",
        "lastModified": "2021-11-08T15:56:46Z",
        "default": true
    },
    {...}
    ],
    "status": "Success"
}

Retrieve a Single Group Attribute

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

GET /v3/groupAttributes/{groupAttributeId}

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

GET /v3/groupAttributes/7

JSON Response

{
    "data": {
        "id": 7,
        "type": "Description",
        "value": "This Incident is related to a recent ransomware attack.",
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmith",
            "role": "Administrator"
        },
        "dateAdded": "2021-11-08T15:56:46Z",
        "lastModified": "2021-11-08T15:56:46Z",
        "default": true
    },
    "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 Group Attributes

The basic format for updating a Group Attribute is:

PUT /v3/groupAttributes/{groupAttributeId}
{
    {updatedField}: {updatedValue}
}

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

For example, the following query will update the value of the Group Attribute with ID 10 and make it the default Attribute of its type:

PUT /v3/groupAttributes/10
{
    "default": true,
    "value": "This is an extremely dangerous adversary"
}

JSON Response

{
    "data": {
        "id": 10,
        "type": "Additional Analysis and Context",
        "value": "This is an extremely dangerous adversary.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 39,
            "userName": "62693284927610908885",
            "firstName": "API",
            "lastName": "User",
            "pseudonym": "APIUserNFmof",
            "role": "Api User"
        },
        "dateAdded": "2021-11-09T14:42:13Z",
        "lastModified": "2021-11-09T14:42:13Z",
        "default": true
    },
    "message": "Updated",
    "status": "Success"
}

Delete Group Attributes

The basic format for deleting a Group Attribute is:

DELETE /v3/groupAttributes/{groupAttributeId}

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

DELETE /v3/groupAttributes/10

JSON Response

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

Note

Group Attributes can be removed from a Group via the mode field. See Update an Object’s Metadata for more information.