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.