Victims

Victims are used to describe a specific organization or group that has been targeted or whose Assets have been exploited.

Endpoint: /api/v3/victims

Available Fields

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

OPTIONS /v3/victims

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 victims object.

Field Description Type Required for Creation? Updatable? Example value(s)
assets A list of Victim Assets corresponding to the Victim String FALSE TRUE {“data”: [{“id”: 12345}]}, {“data”: [{“phone”: “0123456789”, “type”: “Phone”}]}
associatedGroups A list of Groups associated to the Victim String FALSE TRUE {“data”: [{“id”: 12345}]}, {“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}
attributes A list of Attributes corresponding to the Victim String FALSE TRUE {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”]}}
description The Victim’s description String FALSE TRUE “This Victim’s bank account was hacked.”
name The Victim’s name String TRUE TRUE “Bob Loblaw”
nationality The Victim’s nationality String FALSE TRUE “American”
org The Victim’s organization String FALSE TRUE “Company ABC”
ownerName The name of the Organization, Community, or Source to which the Victim belongs String FALSE FALSE “Demo Community”
securityLabels A list of Security Labels applied to the Victim String FALSE TRUE {“data”: [{“name”: “TLP:AMBER”}]}
suborg The Victim’s suborganization String FALSE TRUE “HR Department”
tags A list of Tags applied to the Victim String FALSE TRUE {“data”: [{“name”: “Targeted Attack”}]}
type The type of Victim being created. The only valid value is “Victim” String TRUE FALSE “Victim”
workLocation The Victim’s work location String FALSE TRUE “Washington, D.C.”

Note

The following Victim Asset types can be added to a Victim via the assets field:

  • EmailAddress
  • NetworkAccount
  • Phone
  • SocialNetwork
  • WebSite

Note

A list of available Attribute types can be retrieved with the following query:

GET /v3/attributeTypes

Create Victims

The basic format for creating a Victim is:

POST /v3/victims/
{
    "name": "Victim name goes here",
    "type": "Victim"
}

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

Note

You can add multiple Attributes, Tags, and Security Labels to the Victim being created in a single POST request. Similarly, you can associate multiple Groups to the Victim being created in a single POST request.

Example POST Request

The following query will create a Victim. Note that all optional fields available for the victims object are included in this request.

POST /v3/victims/
{
    "name": "John Doe",
    "assets": {"data": [{"address": "[email protected]", "addressType": "Corporate email", "type": "EmailAddress"}]},
    "associatedGroups": {"data": [{"id": 12345}], [{"name": "Bad Adversary", "type": "Adversary"},
    "attributes": {"data": [{"type": "Additional Analysis and Context", "value": "Example value", "source": "Example Source"}]},
    "description": "This victim’s bank account was hacked.",
    "nationality": "American",
    "org": "Company ABC",
    "securityLabels": {"data": [{"name": "TLP:AMBER"}]},
    "suborg": "HR Department",
    "tags": {"data": [{"name": "Targeted Attack"}]},
    "workLocation": "Washington, D.C."
}

JSON Response

{
    "data": {
        "id": 2,
        "type": "Victim",
        "ownerName": "Demo Organization",
        "webLink": "/auth/victim/victim.xhtml?victim=2",
        "tags": {
            "data": [{
                "id": 11,
                "name": "Targeted Attack",
                "lastUsed": "2021-11-05T19:16:52Z"
            }],
            "count": 1
        },
        "securityLabels": {
            "data": [{
                "id": 3,
                "name": "TLP:AMBER",
                "description": "This security label is used for information that requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
                "color": "FFC000",
                "owner": "System",
                "dateAdded": "2016-08-31T00:00:00Z"
            }],
            "count": 1
        },
        "name": "John Doe",
        "description": "This victim’s bank account was hacked.",
        "org": "Company ABC",
        "suborg": "HR Department",
        "workLocation": "Washington, D.C.",
        "nationality": "American",
        "assets": {
            "data": [{
                "id": 2,
                "type": "EmailAddress",
                "victimId": 2,
                "address": "[email protected]",
                "addressType": "Corporate email"
            }],
            "count": 1
        },
        "attributes": {
            "data": [{
                "id": 1,
                "type": "Additional Analysis and Context",
                "value": "Example value",
                "source": "Example Source",
                "createdBy": {
                    "id": 39,
                    "userName": "62693284927610908885",
                    "firstName": "API",
                    "lastName": "User",
                    "pseudonym": "APIUserNFmof",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-05T19:16:52Z",
                "lastModified": "2021-11-05T19:16:52Z",
                "default": false
            }],
            "count": 1
        }
    },
    "message": "Created",
    "status": "Success"
}

Note

When creating a Victim, you can apply Tags that do not yet exist in ThreatConnect to it. In this scenario, you would need to fill out all required fields for each new Tag. Upon creation of the new Victim, any Tags included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Similarly, you can associate Groups that do not yet exist in ThreatConnect to the Victim. In this scenario, you would need to fill out all required fields for the type of Group being associated to the Victim. Upon creation of the new Victim, any associated Groups included in the body of the POST request that do not yet exist in ThreatConnect will also be created.

Retrieve Victims

Retrieve All Victims

To retrieve all Victims, use the following query:

GET /v3/victims/

JSON Response

{
    "data": [{
        "id": 1,
        "type": "Victim",
        "ownerName": "Demo Organization",
        "webLink": "/auth/victim/victim.xhtml?victim=1",
        "name": "Bob Loblaw"
    }, {
        "id": 2,
        "type": "Victim",
        "ownerName": "Demo Organization",
        "webLink": "/auth/victim/victim.xhtml?victim=2",
        "name": "John Doe",
        "description": "This victim’s bank account was hacked.",
        "org": "Company ABC",
        "suborg": "HR Department",
        "workLocation": "Washington, D.C.",
        "nationality": "American"
    },
    {...}
    ],
    "status": "Success"
}

Retrieve a Single Victim

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

GET /v3/victims/{victimId}

For example, the following query will return information about the Victim with ID 3:

GET /v3/victims/3

JSON Response

{
    "data": {
        "id": 3,
        "type": "Victim",
        "ownerName": "Demo Organization",
        "webLink": "/auth/victim/victim.xhtml?victim=3",
        "name": "Bill Smith",
        "description": "This victim got hacked.",
        "org": "Company XYZ",
        "suborg": "Finance Department",
        "workLocation": "Pittsburgh, Pennsylvania",
        "nationality": "American"
    },
    "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 Victims

The basic format for updating a Victim is:

PUT /v3/victims/{victimId}
{
    {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 victims object.

Note

When updating a Victim, you can use the mode field to add or remove the following metadata:

  • associatedGroups
  • attributes
  • securityLabels
  • tags

See Update an Object’s Metadata for instructions on using the mode field.

Example PUT Request

The following query will complete the following actions for a Victim with ID 2:

  • Add a WebSite Victim Asset to the Victim
  • Update the Victim’s description
  • Replace the TLP: AMBER Security Label applied to the Victim with a TLP: RED Security Label.
PUT /v3/victims/2
{
    "assets": {"data": [{"website": "evilll.com", "type": "WebSite"}]},
    "description": "This individual was the victim of a company-wide phishing attack.",
    "securityLabels": {"data": [{"name": "TLP:RED"}], "mode": "replace"}
}

JSON Response

{
    "data": {
        "id": 2,
        "type": "Victim",
        "ownerName": "Demo Organization",
        "webLink": "/auth/victim/victim.xhtml?victim=2",
        "tags": {
            "data": [{
                "id": 11,
                "name": "Targeted Attack",
                "lastUsed": "2021-11-05T19:16:52Z"
            }],
            "count": 1
        },
        "securityLabels": {
            "data": [{
                "id": 4,
                "name": "TLP:RED",
                "description": "This security label is used for information that cannot be effectively acted upon by additional parties, and could lead to impacts on a party"s privacy, reputation, or operations if misused.",
                "color": "FF0033",
                "owner": "System",
                "dateAdded": "2016-08-31T00:00:00Z"
            }],
            "count": 1
        },
        "name": "John Doe",
        "description": "This individual was the victim of a company-wide phishing attack.",
        "org": "Company ABC",
        "suborg": "HR Department",
        "workLocation": "Washington, D.C.",
        "nationality": "American",
        "assets": {
            "data": [{
                "id": 3,
                "type": "WebSite",
                "victimId": 2,
                "website": "evilll.com"
            }, {
                "id": 2,
                "type": "EmailAddress",
                "victimId": 2,
                "address": "[email protected]"
            }],
            "count": 2
        },
        "attributes": {
            "data": [{
                "id": 1,
                "type": "Additional Analysis and Context",
                "value": "Example value",
                "source": "Example Source",
                "createdBy": {
                    "id": 39,
                    "userName": "62693284927610908885",
                    "firstName": "API",
                    "lastName": "User",
                    "pseudonym": "APIUserNFmof",
                    "role": "Api User"
                },
                "dateAdded": "2021-11-05T19:16:52Z",
                "lastModified": "2021-11-05T19:16:52Z",
                "default": false
            }],
            "count": 1
        }
    },
    "message": "Updated",
    "status": "Success"
}

Delete Victims

The basic format for deleting a Victim is:

DELETE /v3/victims/{victimId}

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

DELETE /v3/victims/1

JSON Response

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