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

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

OPTIONS /v3/victims

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/victims endpoint.

Field

Description

Type

Required for Creation?

Updatable?

Example Value(s)

assets [1]

A list of Victim Assets added to the Victim

Victim Asset Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“phone”: “0123456789”, “type”: “Phone”}]}

associatedGroups

A list of Groups associated to the Victim

Group Object

FALSE

TRUE

{“data”: [{“id”: 12345}]}

{“data”: [{“name”: “Bad Adversary”, “type”: “Adversary”}]}

attributes [2], [3]

A list of Attributes added to the Victim

Victim Attribute Object

FALSE

TRUE

{“data”: [{“type”: “Description”, “value”: “Member of Finance department”, “default”: true}]}

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”

securityLabels

A list of Security Labels applied to the Victim

Security Label Object

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

Tag Object

FALSE

TRUE

{“data”: [{“name”: “Targeted Attack”}]}

workLocation

The Victim’s work location

String

FALSE

TRUE

“Washington, D.C.”

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

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

OPTIONS /v3/victims/tql

Create Victims

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

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

{
    "name": "John Doe"
}

For example, the following request will create a Victim named John Doe. It will also perform the following actions for the Victim:

  • Create a new Email Address Victim Asset and add it to the Victim

  • Associate an existing Group to the Victim, and create a new Bad Guy Adversary Group and associate it to the Victim

  • Add a Description (i.e., a default Description Attribute) to the Victim

  • Apply the Targeted Attack standard Tag and the T1566 - Phishing ATT&CK® Tag to the Victim

  • Configure the Victim’s nationality, organization, suborganization, and work location

Attention

When applying ATT&CK Tags to a Victim, do not include the corresponding technique/sub-technique ID in the Tag’s name. For example, to apply the T1566 - Phishing ATT&CK Tag to a Victim, use Phishing as the Tag name.

Also, if you applied a new Tag to a Victim and that Tag matches a synonymous Tag listed in a Tag normalization rule, it will be converted to the main Tag listed in the rule. Similarly, if you applied a new Tag to a Victim and that Tag matches an ATT&CK Tag, it will be converted to that ATT&CK Tag.

Hint

To include the assets, associatedGroups, attributes, and tags fields in the API response, append ?fields=assets&fields=associatedGroups&fields=attributes&fields=tags to the end of the request URL.

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

{
    "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": "Description",
                "value": "John Doe works in the Company ABC's HR Department.",
                "default": true
            }
        ]
    },
    "nationality": "American",
    "org": "Company ABC",
    "suborg": "HR Department",
    "tags": {
        "data": [
            {
                "name": "Targeted Attack"
            },
            {
                "name": "Phishing"
            }
        ]
    },
    "workLocation": "Washington, D.C."
}

JSON Response

{
    "data": {
        "id": 2,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=2",
        "name": "John Doe",
        "org": "Company ABC",
        "suborg": "HR Department",
        "workLocation": "Washington, D.C.",
        "nationality": "American"
    },
    "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/victims endpoint.

Note

By default, Victims will be created in the Organization in which your API user account resides. To create a Victim in a Community or Source, use the owner query parameter to specify the owner in which to create the Victim.

Note

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

Retrieve Victims

Retrieve All Victims

Send the following request to retrieve data for all Victims:

GET /v3/victims

JSON Response

{
    "data": [
        {
            "id": 1,
            "ownerId": 1,
            "ownerName": "Demo Organization",
            "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=1",
            "name": "Bob Loblaw"
        },
        {
            "id": 2,
            "ownerId": 1,
            "ownerName": "Demo Organization",
            "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=2",
            "name": "John Doe",
            "org": "Company ABC",
            "suborg": "HR Department",
            "workLocation": "Washington, D.C.",
            "nationality": "American"
        },
        {...}
    ],
    "status": "Success"
}

Hint

Use the owner query parameter to limit the results to a specific owner.

Retrieve a Specific Victim

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

GET /v3/victims/{victimId}

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

GET /v3/victims/3

JSON Response

{
    "data": {
        "id": 3,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=3",
        "name": "Bill Smith",
        "org": "Company XYZ",
        "suborg": "Finance Department",
        "workLocation": "Pittsburgh, Pennsylvania",
        "nationality": "American"
    },
    "status": "Success"
}

Update Victims

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

PUT /v3/victims/{victimId}
Content-Type: application/json

{
    {updatedField}: {updatedValue}
}

For example, the following request will perform the following actions for the Victim whose ID is 2:

  • Add a WebSite Victim Asset to the Victim

  • Update the Victim’s name

  • Replace any Security Labels applied to the Victim with the TLP: RED Security Label

Hint

To include the assets and securityLabels fields in the API response, append ?fields=assets&fields=securityLabels to the end of the request URL.

PUT /v3/victims/2
Content-Type: application/json

{
    "assets": {
        "data": [
            {
                "website": "evilll.com",
                "type": "WebSite"
            }
        ]
    },
    "name": "Jane Doe",
    "securityLabels": {
        "data": [
            {
                "name": "TLP:RED"
            }
        ],
        "mode": "replace"
    }
}

JSON Response

{
    "data": {
        "id": 2,
        "ownerId": 1,
        "ownerName": "Demo Organization",
        "webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=2",
        "name": "Jane Doe",
        "org": "Company ABC",
        "suborg": "HR Department",
        "workLocation": "Washington, D.C.",
        "nationality": "American"
    },
    "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/victims endpoint.

Hint

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.

Delete Victims

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

DELETE /v3/victims/{victimId}

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

DELETE /v3/victims/1

JSON Response

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

Associations

For instructions on creating and managing associations for Victims, see Create and Manage Associations.


MITRE ATT&CK® and ATT&CK® are registered trademarks of The MITRE Corporation.