Integrate any VA tool with SAFE using APIs

About this document

This page describes the step-by-step procedure to integrate any Vulnerability Assessment (VA) tool like Qualys, Tenable.io, etc., with SAFE using SAFE REST APIs to post VA data for technology assets.

Prerequisites

1. The VA tool should have an API interface to be able to get Assets and their Vulnerabilities. These APIs should provide the following details for each vulnerability.
   1. Tool name (required) *
   2. Vulnerability Name (required)
   3. Vulnerability Description (required)
   4. a unique Vulnerability ID (required)
   5. CVSS score (required)
   6. CVSS vector
   7. Severity (required)
   8. Status (required)
   9. Impact
   10. Remediation Steps
   11. Remediation References
   12. CVE-ID, CWE-ID or OWASP-ID
2. For the Assets, the APIs should provide the following details.
   1. Asset Name
   2. Hostname or IP address
   3. Asset URL (in case of applications)
   4. Operating System
3. The corresponding assets should be present both in SAFE and the VA tool. There should also be a unique asset identifier like FQDN or IP address to match the assets between the two products.
4. A SAFE user with API credentials.
5. If the assessment tool name (tool_name) is not present in the list of tools that SAFE supports out of the box, a new tool name must be registered with SAFE using the /assessment_tools API, POST method.

Sequence Flow

1. Use VA tool APIs to get all the vulnerabilities for all assets or a selected set of assets.
2. Search for the assets in SAFE using the field that can be used for the asset matching criteria. This can be done using the GET /assets API and using the filter by Asset Name, which is usually used for storing the FQDN or the IP address attribute.
   1. When the asset is present in SAFE:
      1. Use the /asset/:id/assessment to post the Vulnerabilities. (asset ID is returned by GET /asset API)
   2. When the asset is not present in SAFE
      1. Onboard the asset into SAFE using POST /asset API. For this, the Asset-Type (e.g., Windows 11 or MySQL) needs to be determined. Use the GET /asset-types to get the list of supported Asset Types in SAFE.
      2. Use the /asset/:id/assessment to post the Vulnerabilities. (asset ID is returned by POST /asset API when it is successfully onboarded)
3. The attribute called shouldAppendVA in the Request body of the assessment API, controls the behavior - on whether the previously attached vulnerabilities should get marked as Qualified or remain unchanged as the new set of vulnerabilities is posted with the API request. It is recommended to use only one VA tool as the source of vulnerabilities for an asset at a time. SAFE does not de-duplicate the vulnerabilities if they are posted from more than one assessment tool for an asset.

Validate the VA data in SAFE

Once the vulnerabilities data is successfully submitted using the SAFE REST APIs, these can be checked in the UI under the Technology Vector. This may take a few minutes depending on the number of vulnerabilities being posted into SAFE, as the system processes them and updates the scores.

1. Go to Technology > Inside-Out
2. Select the Technology Vertical where the asset resides or search for the asset in SAFE using the top search bar.
3. Open the asset page and scrolls down to Control details for the Control Type as “Vulnerability Assessment and Penetration Testing Control”.

Posting Vulnerabilities in multiple integration runs

1. Adding vulnerabilities for an asset for the first time. Use the /asset/:id/assessment to post the vulnerabilities.
2. Adding or updating the list of vulnerabilities for an asset
   1. Adding a new vulnerabilities - Set the flag shouldAppendVA as true and post only the new vulnerabilities.
   2. Updating an existing vulnerability’s score, severity or any other field - use the /asset/:id/assessment/control/:controlId api.
   3. Removing or Qualifying an existing vulnerability - Set the flag shouldAppendVA as false and post a blank array in the "va_controls" request body, to set all existing vulnerabilities as qualified. For marking an individual vulnerability as qualified, use the /asset/:id/assessment/control/:controlId api with the "status" field.