Auto-close vulnerabilities API

The Auto-close vulnerabilities API enables the system to automatically close the vulnerabilities for a particular asset that were fixed in the previous scan and are no longer present in the subsequent scan. The API selects the vulnerabilities for auto-closure based on the last observed date of those vulnerabilities as received from the scanner vendors. 

Related topics

Using-REST-APIs

Best practices

  • Make sure that the Vulnerability Asset Records do not overlap across policies so that vulnerabilities are not auto-closed incorrectly across policies.
    For more information, see Limitations.

  • Run the 

    POST

    ​/api​/v2​/violations​/close​/auto-closure​/vats​/preview API to generate a list of all Vulnerability Asset Records which are eligible for auto closure.
    If the list of vulnerability asset records that are eligible for auto closure is too long, it may generate a timeout error.

The Auto-close vulnerabilities API can be applied to vulnerabilities imported by using the following methods:

The scan policies generated by using these external scanner connectors automatically close the vulnerabilities.

  • Imported by using the following Vulnerability scan APIs:
    1. Run the POST/api/v2/policies/vulnerability-scans API to create a new vulnerability scan policy.
    2. Next, run the POST/api/v2/policies/vulnerability-scans/{policy_id}/vulnerabilities API to generate the list of vulnerabilities for the specified vulnerability scan policy.

    3. If the API from step 2 generates the header SKIP-RECONCILE = true, run the 

      POST

      /api/v2/policies/{policy_id}/reconcile API for post-processing of Vulnerability Asset Records.

To use the Auto-close vulnerabilities API

POST/api/v3/violations/close/auto-closure/vats

Description

Closes the vulnerabilities for assets based on the Last Observed Date.

Type of call

POST

Request Body

{
  "filters": {
    "asset_ids": [    ],
    "latest_scan_policy_id": "",
    "compare_against_policies": [    ],
    "use_modified_date": false
  },
  "data": {
    "reason": "Auto closed"
  }
}

Important  considerations

  • Access the Swagger host for API documentation to get detailed information about the request parameters.
  • use_modified_date is used to select the vulnerabilities for auto-closure.
    This API uses the last observed date of the vulnerabilities to determine select vulnerabilities for auto-closure, so the default value is false. If you set the value as true, then the vulnerabilities are selected for auto-closure based on the modified date of those vulnerabilities.
  • This API is asynchronous and all auto-closures are done in the background. On successful completion, the Activity Logs are updated.
    Check the status of the auto-closure by using the Activity status API.
Click here for a sample request
{
  "filters": {
    "asset_ids": [
      "3b3cfdf1-7485-4124-b792-911c820a9835",
      "43d7eeff-cda9-4587-9f21-e8b8ad3da5e2"
    ],
    "latest_scan_policy_id": "d41cedbb-a981-4a46-b658-29a5a38370c9",
    "compare_against_policies": [
      "413b236b-5ac2-4dda-99fd-f3dd9762eb07"
    ],
    "use_modified_date": false
  },
  "data": {
    "reason": "Auto closed"
  }
}


Click here for a sample response
Media type
Controls Accept header.
[
 {
   "task_id": 123,
   "status": "Created",
   "status_code": 201
 },
 {
   "vat_ids": 5,
   "status": "Accepted",
   "status_code": 202
 }
]

Activity status

get/automation-console/api/v1/activities/{id}

Description

Returns the activity status details.

Request Parameters

Specify the Task ID {id}.
The task_id is generated in the response to the auto-close vulnerabilities API.

Request Body

None

Execution response

The following table lists the responses returned by the API:

Code

Description

200

Returns the activity status (FAILED, IN_PROGRESS, and SUCCESS).

404

Indicates that no data is found for the given request.

Click here for a sample response
Media type
Controls Accept header.
{
 "id": 123,
 "activity": "VAT_CLOSURE",
 "context": "d41cedbb-a981-4a46-b658-29a5a38370c1",
 "start_time": 1590523411445,
 "end_time": 1590523429469,
 "status": "SUCCESS"
}

Limitations

Make sure that the Vulnerability Asset Records do not overlap across policies so that vulnerabilities are not auto-closed incorrectly across policies.

Examples

  • You create a vulnerability scan policy P1 which returns the following Vulnerability Asset Records:

    Policy

    Asset

    Violation

    Last Observed Date

    P1

    A1

    V1 

    Day1

    V2

    Day1 

    On the next day, you create a vulnerability scan policy P2. The scan policy returns the following Vulnerability Asset Records:

    Policy

    Asset

    Violation

    Last Observed Date

    P2

    A1

     V3

    Day2

    V4 

    Day2

    V1 

    Day2

    This scan policy recognizes the Vulnerability Asset Record V1, which was also present in policy P1. So the Last Observed Date of Vulnerability Asset Record V1 is changed to Day2. However, Vulnerability Asset Record V2 is not recognized, and its Last Observed Date remains Day1.

    Now, if you run the auto-close vulnerabilities API for scan policy P1, the API doesn't select Vulnerability Asset Record V1 for auto-closure as its Last Observed Date is updated to Day2 by policy P2. However, the API incorrectly closes Vulnerability Asset Record V2 without determining whether the vulnerability was actually fixed.


  • You create a vulnerability scan policy P1 which returns the following Vulnerability Asset Records for assets A1 and A2:

    Policy

    Assets

    Violation

    Last Observed Date

    P1

    A1

    V1 

    Day1

    V2

    A2

    V1

    V2

    V3

    V4

    The Vulnerability Asset Records V1 and V2 are tagged as high severity and you fix the vulnerabilities on the same day. On the next day, you run the vulnerability scan policy P1 again. The scan policy returns the following Vulnerability Asset Records:

    Policy

    Assets

    Violation

    Last Observed Date

    P1

    A1

    V1 

    Day1

    V2

    A2

    V1

    Day1

    V2

    V3

    Day2

    V4

    This scan policy notes that the Vulnerability Asset Records V3 and V4 were not fixed. So the Last Observed Date of Vulnerability Asset Records V3 and V4 is changed to Day2. However, Vulnerability Asset Records V1 and V2 are marked as fixed, and their Last Observed Date remains Day1.

Now, if you run the auto-close vulnerabilities API for scan policy P1,


    • The API correctly closes Vulnerability Asset Records V1 and V2 for Asset A2.
    • The API does not select Vulnerability Asset Records V3 and V4 for auto-closure as their Last Observed Date is updated to Day2.
    • For Asset A1, the API doesn't select Vulnerability Asset Records V1 and V2 for auto-closure as their Last Observed Date remains Day1.



 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*