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] A list of Attributes added to the Victim Victim Attribute Object FALSE TRUE {“data”: [{“type”: “Attribute Type”, “value”: “Attribute Value”, “source”: “Attribute Source”}]}
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”
ownerId [3] The ID of the owner to which the Victim belongs Integer FALSE FALSE 1, 2, 3,…100
ownerName [3] The name of the owner to which the Victim belongs String FALSE FALSE “American”
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.”
[1]

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

  • EmailAddress
  • NetworkAccount
  • Phone
  • SocialNetwork
  • WebSite
[2]To retrieve a list of available Attribute Types, send the following request: GET /v3/attributeTypes.
[3](1, 2) 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, include the ownerId or ownerName field in your request. Alternatively, Alternatively, use the owner query parameter to specify the owner in which to create the Victim.

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
{
    "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 an Additional Analysis and Context 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
{
    "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"
            }
        ]
    },
    "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

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

Create Associations

You can create associations between Victims and Groups that exist in the same owner only. When creating associations for Victims using the ThreatConnect v3 API, follow these guidelines:

  • To create an association to a new Group, include all fields required to create the type of Group when setting the associatedGroups field. To create the Group in a Community or Source, include the ownerId or ownerName field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Group when setting the associatedGroups field.
  • To create an association to an existing Group, use the Group’s ID when setting the associatedGroups field (e.g., "associatedGroups": {"data": [{"id": 12345}]}).

Note

You can associate multiple Groups to a Victim in a single POST or PUT 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}
{
    {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
{
    "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"
}

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