Victim Attributes

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

Endpoint: /api/v3/victimAttributes

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

OPTIONS /v3/victimAttributes

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

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 to the /v3/victimAttributes endpoint.

Field	Description	Type	Required for Creation?	Updatable?
default	Indicates whether the Attribute is the default Attribute of its type for the Victim to which it is added (this field applies to certain Attribute and data types only)	Boolean	FALSE	TRUE
securityLabels	A list of Security Labels applied to the Attribute	Security Label Object	FALSE	TRUE
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
victimId	The ID of the Victim to which the Attribute is added	Integer	TRUE	FALSE

[1]

When setting the type field, you must enter a valid Attribute Type that applies to Victims. 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/victimAttributes endpoint:

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

OPTIONS /v3/victimAttributes/tql

Create Victim Attributes

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

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

{
    "victimId": 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 Victim whose ID is 2:

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

{
    "victimId": 2,
    "source": "Phase of Intrusion",
    "type": "Additional Analysis and Context",
    "value": "Based on additional analysis, it was determined that this victim's bank account was hacked."
}

JSON Response

{
    "data": {
        "id": 10,
        "dateAdded": "2021-11-09T15:43:06Z",
        "type": "Additional Analysis and Context",
        "value": "Based on additional analysis, it was determined that this victim's bank account was hacked.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2021-11-09T15:43:06Z",
        "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/victimAttributes endpoint.

Hint

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

Retrieve Victim Attributes

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

Retrieve All Victim Attributes

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

GET /v3/victimAttributes

JSON Response

{
    "data": [
        {
            "id": 2,
            "dateAdded": "2021-11-09T15:49:22Z",
            "type": "Description",
            "value": "Ransomware attack victim.",
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "owner": "Demo Organization"
            },
            "lastModified": "2021-11-09T15:49:22Z",
            "pinned": false,
            "default": true
        },
        {
            "id": 1,
            "dateAdded": "2021-11-09T15:43:06Z",
            "type": "Additional Analysis and Context",
            "value": "Based on additional analysis, it was determined that this victim's bank account was hacked.",
            "source": "Phase of Intrusion",
            "createdBy": {
                "id": 3,
                "userName": "11112222333344445555",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmithAPI",
                "owner": "Demo Organization"
            },
            "lastModified": "2021-11-09T15:43:06Z",
            "pinned": false,
            "default": false
        }
    ],
    "status": "Success"
}

Retrieve a Specific Victim Attribute

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

GET /v3/victimAttributes/{victimAttributeId}

For example, the following request will retrieve data for the Victim Attribute whose ID is 2:

GET /v3/victimAttributes/2

JSON Response

{
    "data": {
        "id": 2,
        "dateAdded": "2021-11-09T15:49:22Z",
        "type": "Description",
        "value": "Ransomware attack victim.",
        "createdBy": {
            "id": 1,
            "userName": "[email protected]",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmith",
            "owner": "Demo Organization"
        },
        "lastModified": "2021-11-09T15:49:22Z",
        "pinned": false,
        "default": true
    },
    "status": "Success"
}

Update Victim Attributes

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

PUT /v3/victimAttributes/{victimAttributeId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

For example, the following request will update the value of the Victim Attribute whose ID is 1 and make it the default Attribute of its type:

PUT /v3/victimAttributes/1
Content-Type: application/json

{
    "default": true,
    "value": "Based on additional analysis, it was determined that this victim's social media, bank, and email accounts were hacked as the result of a phishing attack."
}

JSON Response

{
    "data": {
        "id": 1,
        "dateAdded": "2021-11-09T15:43:06Z",
        "type": "Additional Analysis and Context",
        "value": "Based on additional analysis, it was determined that this victim's social media, bank, and email accounts were hacked as the result of a phishing attack.",
        "source": "Phase of Intrusion",
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2021-11-09T15:43:06Z",
        "pinned": false,
        "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/victimAttributes endpoint.

Delete Victim Attributes

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

DELETE /v3/victimAttributes/{victimAttributeId}

For example, the following request will delete the Victim Attribute whose ID is 1:

DELETE /v3/victimAttributes/1

JSON Response

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

Hint

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