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
|
[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 theownerId
orownerName
field in the request and specify the ID or name, respectively, of the Community or Source in which to create the Group when setting theassociatedGroups
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.