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.