Using the Public API through Swagger UI to get the Latest Scan Results of Assets

How to use Delve's Swagger interface in order to query the public API to fetch the latest scan results on specific assets.

If you need to consume Delve's public OpenAPI-compatible API to monitor the ongoing status of scans and their results, this quick howto will guide you through the steps necessary to get Delve's data through OAUTH2 authentication mechanism.

Step-by-step guide

Create a Public API Client in Delve

Follow the appropriate User Guide Section on Creating Public API Clients.

⚠️ For Delve's own Swagger UI, do use https://<YOUR INSTANCE>.wardenscanner.com/assets/api-doc/oauth2-redirect.html as a redirect URI (also named "callback URI").

Navigate & Authorize the public Swagger Documentation

Direct your Web browser to the public API Swagger Documentation of your instance at https://<YOUR INSTANCE>.wardenscanner.com/api/v2/spec#/

You will then be directed to the entire API documentation in a dynamic format allowing you to create the API requests needed to extract the required information.

 

583335946

 

Authorize the Swagger page to make requests by using the "Authorize" button at the top right corner, and enter your previously saved Client ID and Client Secret.

You will then be redirected to Delve's login screen to authorize this client for a predetermined period of time.

You should then be redirected to Swagger where you will see that the authorization is now active, and that the "Authorize" button now shows a locked icon.

 

583237650

 

Get the Asset List for Which you Want the Scan Results

In this example, we'll discuss how to get the entire Server and Website list for a specific team in Swagger.

First, note down the Team ID that will be required to filter your asset list. The team ID is present in the URL when you consult a specific team context in Delve, e.g. in the URL https://<YOUR INSTANCE>.wardenscanner.com/view/team123/servers here, the team ID is "123".

In the Swagger page, navigate to the "GET /api/v2/servers" section to execute the query for the servers of this specific team:

  • Change the "Limit" parameter to the number of assets you want to get for each request.
  • Change the "Offset" parameter if you want to look for the next page/group of assets.
  • Change the "Sort" parameter if you want the assets to arrive pre-sorted upon certain criteria.
  • Use the "q" (query) parameter to specify that you want the assets in a certain team, eg.: {"team": {"id": 643}} The query language is documented in its own article.

Once you have set your parameters, you can press the "Execute" button to run the query, and download/browse the resulting JSON file.

✔️ You can also note down the full "curl" request in order to use it programmatically.

For every asset for which you want to consult the scan results, note down the "lastScanId" number.

The exact same procedure can be done for the Websites, by using the "GET /api/v2/websites" API call.

Get the Latest Scan Results for an Asset

Get the Scan Summary

In the Swagger page, navigate to the "GET /api/v2/scans/{id}" section.

Use the "lastScanId" number as the "id" parameter, to query the last scan summary.

Once you have set your parameters, you can press the "Execute" button to run the query, and download/browse the resulting JSON file.

This request will give you a summarized vulnerability count for the critical, medium, warning and info level of severity.

⚠️ You can also note down the full "curl" request in order to use it programmatically.

Get the Full Vulnerabilities List

In order to get the full vulnerabilities list for a specific scan ID, you need to filter the entire list of vulnerabilities for a certain scan ID.

In the Swagger page, navigate to the "GET /api/v2/vulnerability-groups" section.

Using the same "lastScanId" as a reference inside the "q" (query) parameter, specify which vulnerabilities you would like to filter the data for, e.g.:

{"scan": {"id": 42}}

 

Once you have set your parameters, you can press the "Execute" button to run the query, and download/browse the resulting JSON file.

⚠️ You can also note down the full "curl" request in order to use it programmatically.