Indicator Attributes

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

Endpoint: /api/v3/indicatorAttributes

Available Fields

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

OPTIONS /v3/indicatorAttributes

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

Field	Description	Type	Required for Creation?	Updatable?
default	Indicates whether the Attribute is the default Attribute of its type within the object (this field applies on to certain Attribute and data types)	Boolean	FALSE	TRUE
indicatorId	The ID of the Indicator 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 Indicator to which the Attribute is being added. To retrieve a list of available Attribute Types, use the following query:

GET /v3/attributeTypes

Create Indicator Attributes

The basic format for creating an Indicator Attribute is:

POST /v3/indicatorAttributes
{
    "indicatorId": 12345,
    "type": "Attribute type goes here",
    "value": "Attribute value goes here"
}

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

POST /v3/indicatorAttributes
{
    "indicatorId": 20,
    "source": "Phase of Intrusion",
    "type": "Additional Analysis and Context",
    "value": "Host used by hacker conglomerate traced to Iran."
}

JSON Response

{
    "data": {
        "id": 10,
        "type": "Additional Analysis and Context",
        "value": "Host used by hacker conglomerate traced to Iran.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "dateAdded": "2021-11-09T13:32:37Z",
        "lastModified": "2021-11-09T13:32:37Z",
        "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 for the indicatorAttributes object.

Hint

Indicator Attributes can also be created when creating an Indicator. See the “Create Indicators” section of Indicators for more information.

Retrieve Indicator Attributes

The following section describes how to retrieve Indicator Attributes via the /v3/indicatorAttributes endpoint. In addition to the methods described in this section, you can retrieve Attributes added to a specific Indicator by using the following query:

GET /v3/indicators/{indicatorId}?fields=attributes

Retrieve All Indicator Attributes

To retrieve all Indicator Attributes, use the following query:

GET /v3/indicatorAttributes

JSON Response

{
    "data": [
        {
            "id": 10,
            "type": "Additional Analysis and Context",
            "value": "Host used by hacker conglomerate traced to Iran.",
            "source": "Phase of Intrusion",
            "createdBy": {
                "id": 39,
                "userName": "62693284927610908885",
                "firstName": "API",
                "lastName": "User",
                "pseudonym": "APIUserNFmof",
                "role": "Api User"
            },
            "dateAdded": "2021-11-09T13:32:37Z",
            "lastModified": "2021-11-09T13:32:37Z",
            "default": false
        },
        {
            "id": 9,
            "type": "First Seen",
            "value": "2021-11-07T04:00:35Z",
            "createdBy": {
                "id": 2,
                "userName": "[email protected]",
                "firstName": "Pat",
                "lastName": "Jones",
                "pseudonym": "patjones",
                "role": "User"
            },
            "dateAdded": "2021-11-09T06:03:54Z",
            "lastModified": "2021-11-09T06:03:54Z",
            "default": false
        },
        {
            "id": 8,
            "type": "Description",
            "value": "At the time of Analysis, the host of this URL resolved to Address 199.34.228.53",
            "dateAdded": "2021-11-09T06:03:54Z",
            "lastModified": "2021-11-09T06:03:54Z",
            "default": false
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Single Indicator Attribute

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

GET /v3/indicatorAttributes/{indicatorAttributeId}

For example, the following query will return information about the Indicator Attribute with ID 9:

GET /v3/indicatorAttributes/9

JSON Response

{
    "data": {
      "id": 9,
      "type": "First Seen",
      "value": "2021-11-07T04:00:35Z",
            "createdBy": {
          "id": 2,
          "userName": "[email protected]",
          "firstName": "Pat",
          "lastName": "Jones",
          "pseudonym": "patjones",
          "role": "User"
      },
      "dateAdded": "2021-11-09T06:03:54Z",
      "lastModified": "2021-11-09T06:03:54Z",
      "default": false
    },
    "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 Indicator Attributes

The basic format for updating an Indicator Attribute is:

PUT /v3/indicatorAttributes/{indicatorAttributeId}
{
    {updatedField}: {updatedValue}
}

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

PUT /v3/indicatorAttributes/10
{
    "default": true,
    "value": "Host used by hacker conglomerate traced to China."
}

JSON Response

{
    "data": {
        "id": 10,
        "type": "Additional Analysis and Context",
        "value": "Host used by hacker conglomerate traced to China.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "role": "Api User"
        },
        "dateAdded": "2021-11-09T13:32:37Z",
        "lastModified": "2021-11-09T13:38:12Z",
        "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 for the indicatorAttributes object.

Delete Indicator Attributes

The basic format for deleting an Indicator Attribute is:

DELETE /v3/indicatorAttributes/{indicatorAttributeId}

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

DELETE /v3/indicatorAttributes/10

JSON Response

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

Hint

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