Create risk scenario

Create a new risk scenario.

POST /risk-scenarios

Create risk scenario

cURL

curl --request POST \
  --url https://api.vanta.com/v1/risk-scenarios \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "description": "<string>",
  "riskId": "<string>",
  "isSensitive": true,
  "likelihood": 123,
  "impact": 123,
  "residualLikelihood": 123,
  "residualImpact": 123,
  "categories": [
    "<string>"
  ],
  "ciaCategories": [
    "Confidentiality"
  ],
  "treatment": "Mitigate",
  "owner": "<string>",
  "note": "<string>",
  "riskRegister": "<string>",
  "customFields": [
    {
      "label": "<string>",
      "value": "<string>"
    }
  ],
  "type": "Risk Scenario"
}
'

200

{
  "riskId": "assets-not-identified-and-protected",
  "description": "Assets are not identified and protected according to company requirements.",
  "isSensitive": false,
  "likelihood": 4,
  "impact": 4,
  "residualLikelihood": 2,
  "residualImpact": 1,
  "categories": [
    "Access control"
  ],
  "ciaCategories": [
    "Confidentiality"
  ],
  "treatment": "Avoid",
  "owner": null,
  "note": null,
  "riskRegister": "Default",
  "customFields": [],
  "isArchived": false,
  "reviewStatus": "DRAFT",
  "requiredApprovers": [],
  "type": "Risk Scenario",
  "identificationDate": "2024-03-07T18:46:05.944Z"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

description · string · required

This describes an actual or potential risk to your organization's people, processes, technology, data, and facilities. Document actual issues or likely scenarios based on your specific environment or a potential vulnerability.

riskId · string

The unique ID of the risk. Used to reference and update existing risks. We will auto-generate one if one isn't specified.

isSensitive · boolean · deprecated

If set to true this risk can only be seen by its owner or users with Admin, RiskSensitiveManage or RiskSensitiveView permissions.

likelihood · integer<int32>

Represents the probability of an incident occurring due to this risk or vulnerability, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater likelihood. The range can be customized in the Risk Management settings.

impact · integer<int32>

Represents the potential severity of harm to your organization’s operations if this risk is exploited, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater impact. The range can be customized in the Risk Management settings.

residualLikelihood · integer<int32>

Represents the adjusted probability of this risk being exploited or affecting operations after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings.

residualImpact · integer<int32>

Represents the adjusted severity of harm to your organization’s operations if this risk is exploited after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings.

categories · string[]

The list of categories this risk scenario belongs to. Each element in the list will become a new custom category if it doesn't match an existing one. You can reference the current category options in the Risk Management settings and/or enter new values.

ciaCategories · enum<string>[]

Enter a list of the following for the type of risk documented:

• Confidentiality: Risk to data stores, customer/sensitive information, etc.
• Integrity: Risk to accuracy or integrity of system settings and/or data
• Availability: Risk to normal service operations and critical system functionality

Available options: Confidentiality, Integrity, Availability

treatment · enum<string>

Indicate how your leadership team wants to address an identified risk. Please note: not all risks need to be addressed immediately (or at all). Your Risk Treatment decision will depend on multiple factors, such as your organization's risk tolerance and the value of the asset that the risk is associated with. The options are:

• Mitigate: Identify controls to put in place or tasks to be done that will reduce the risk score.
• Transfer: Move risk outside of your organization's set of responsibilities e.g. get cyber liability insurance.
• Avoid: Stop doing the activity which is causing the risk to your organization and its assets.
• Accept: Decide to live with the risk and take no further actions. - Accept: decide to live with the risk; this may be because it is highly unlikely, has a low financial or operational impact, or the cost and effort to treat the risk far exceeds the value of the asset

Available options: Mitigate, Transfer, Avoid, Accept

owner · string

The person responsible for tracking and mitigating this risk scenario. This should be the email address of a valid Vanta user.

note · string

Additional context about the risk scenario and why it has specific impact and likelihood scores.

riskRegister · string

Name of the risk register to associate with this scenario.

This field must be set if the organization has multiple registers.

customFields · object[]

The list of custom attributes. You can reference existing custom attributes in the Risk Management settings and/or create new ones. The format is:

• {label: "field-name", value: "string-representation"} for text, date, number and currency fields
• {label: "field-name", value: ["option1", "option2"]} for picklist fields

Show child attributes

type · enum<string>

The type of risk scenario to create.

• "Risk Scenario": Standard risk scenario (default)
• "Enterprise Risk": Enterprise-level risk (requires Enterprise Risk Management SKU)

Enterprise risks cannot be associated with a risk register. Defaults to "Risk Scenario" if not specified.

Available options: Risk Scenario, Enterprise Risk

Response

200 - application/json

Ok

riskId · string · required

The unique ID of the risk specified by the user. Used to reference and update existing risks.

description · string · required

This describes an actual or potential risk to your organization's people, processes, technology, data, and facilities. Document actual issues or likely scenarios based on your specific environment or a potential vulnerability.

isSensitive · boolean | null · required · deprecated

If set to true this risk can only be seen by its owner or users with Admin, RiskSensitiveManage or RiskSensitiveView permissions.

likelihood · integer<int32> | null · required

Represents the probability of an incident occurring due to this risk or vulnerability, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater likelihood. The range can be customized in the Risk Management settings. A value of null indicates that no score has been assigned.

impact · integer<int32> | null · required

Represents the potential severity of harm to your organization’s operations if this risk is exploited, expressed as a numerical score. Defaults to a range of 1-5, where higher values indicate greater impact. The range can be customized in the Risk Management settings. A value of null indicates that no score has been assigned.

residualLikelihood · integer<int32> | null · required

Represents the adjusted probability of this risk being exploited or affecting operations after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings. A value of null indicates that no score has been assigned.

residualImpact · integer<int32> | null · required

Represents the adjusted severity of harm to your organization’s operations if this risk is exploited after implementing risk treatments, such as controls or mitigations. Expressed as a numerical score, defaulting to a range of 1-5. The range can be customized in the Risk Management settings. A value of null indicates that no score has been assigned.

categories · string[] · required

The list of categories this risk scenario belongs to.

ciaCategories · enum<string>[] · required

A list of the following for the type of risk documented:

• Confidentiality: Risk to data stores, customer/sensitive information, etc.
• Integrity: Risk to accuracy or integrity of system settings and/or data
• Availability: Risk to normal service operations and critical system functionality

Available options: Confidentiality, Integrity, Availability

treatment · enum<string> · required

Indicate how your leadership team wants to address an identified risk. Please note: not all risks need to be addressed immediately (or at all). Your Risk Treatment decision will depend on multiple factors, such as your organization's risk tolerance and the value of the asset that the risk is associated with. The options are:

• Mitigate: Identify controls to put in place or tasks to be done that will reduce the risk score.
• Transfer: Move risk outside of your organization's set of responsibilities e.g. get cyber liability insurance.
• Avoid: Stop doing the activity which is causing the risk to your organization and its assets.
• Accept: Decide to live with the risk and take no further actions. - Accept: decide to live with the risk; this may be because it is highly unlikely, has a low financial or operational impact, or the cost and effort to treat the risk far exceeds the value of the asset

Available options: Mitigate, Transfer, Avoid, Accept

owner · string | null · required

The email of the person responsible for tracking and mitigating this risk scenario.

note · string | null · required

Additional context about the risk scenario and why it has specific impact and likelihood scores.

riskRegister · string | null · required

Name of the risk register associated with this scenario.

customFields · object[] · required

The list of custom fields. You can reference existing custom fields in the Risk Management settings and/or create new ones. The format is:

• {label: "field-name", value: "string-representation"} for text, date, number and currency fields
• {label: "field-name", value: ["option1", "option2"]} for picklist fields

Show child attributes

isArchived · boolean · required

Whether this scenario is archived.

reviewStatus · enum<string> · required

The current review status of this risk scenario

Available options: APPROVED, DRAFT, NOT_REVIEWED, AWAITING_SUBMISSION, PENDING_APPROVAL, REQUESTED_CHANGES

requiredApprovers · string[] · required

The list of required approvers for this risk scenario.

type · enum<string> · required

The type of risk scenario.

• "Risk Scenario": Standard risk scenario
• "Enterprise Risk": Enterprise-level risk

Available options: Risk Scenario, Enterprise Risk

identificationDate · string<date-time> · required

The date this risk was identified. Matches the "Identified Date" field in the Vanta UI. Set by the customer when a risk is created; defaults to the scenario's creation time when not explicitly provided.