🌙
 

Subscribe to the Taegis™ VDR Documentation RSS Feed at .

Learn more about RSS readers or RSS browser extensions.

Getting Asset Result Scans via Swagger

This article reviews how to use Secureworks® Taegis™ VDR’s Swagger interface in order to query the public API to fetch the latest scan results on specific assets.

If you need to consume Secureworks® Taegis™ VDR’s public OpenAPI-compatible API to monitor the ongoing status of scans and their results, this article guides you through the steps necessary to get Secureworks® Taegis™ VDR’s data through OAUTH2 authentication mechanism.

Create a Public API Client in Secureworks® Taegis™ VDR

Follow the instruction found at Creating Public API Clients.

Note

For Secureworks® Taegis™ VDR’s own Swagger UI, use https://<YOUR INSTANCE>.vdr.secureworks.com/assets/api-doc/oauth2-redirect.html as a redirect URI (also named a callback URI).

Authorize through the Public Swagger Interface

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

  2. 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.

Swagger API

Swagger API

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

Available Authorizations

Available Authorizations

  1. The Secureworks® Taegis™ VDR’s login screen displays to authorize this client for a predetermined period of time.
  2. You will 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.

Get an Authentication Token from the Swagger Interface

  1. Use any simple request to execute an API call and get an authentication token.
  2. Select GET /false-positive-groups.
  3. Select Try it out.
  4. Leave settings as they are and select Execute.
  5. Copy the authentication bearer token from the curl command seen directly under the Execute button (Select all characters following "Bearer" in the command).

Authentication Bearer Token

Authentication Bearer Token

Get the Asset List for Which You Want the Scan Results

This example reviews how to get the entire Server and Website list for a specific team in Swagger.

  1. Note the Team ID that is required to filter your asset list. The team ID is present in the URL when you consult a specific team context in Secureworks® Taegis™ VDR; e.g., in the URL https://<YOUR INSTANCE>.vdr.secureworks.com/view/team123/servers, the team ID is 123.
  2. In the Swagger page, navigate to the GET /api/v2/servers section to execute the query for the servers of this specific team.
  3. Change the "Limit" parameter to the number of assets you want to get for each request.
  4. Change the "Offset" parameter if you want to look for the next page/group of assets.
  5. Change the "Sort" parameter if you want the assets to arrive pre-sorted upon certain criteria.
  6. Use the "q" (query) parameter to specify that you want the assets in a certain team; e.g., {"team": {"id": 643}}. For more information, see Using the Search Grammar with the API.

Note

Save the full curl request in order to use it programmatically.

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

Note

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

  1. To get the scan summary from the Swagger page, navigate to the GET /api/v2/scans/{id} section.

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

  3. Once you have set your parameters, select Execute to run the query, and download/browse the resulting JSON file. This request gives you a summarized vulnerability count for the critical, medium, warning, and info level of severity.

Note

Save 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.

  1. In the Swagger page, navigate to the GET /api/v2/vulnerability-groups section.
  2. Use the same lastScanId as a reference inside the q (query) parameter. Specify which vulnerabilities you would like to filter the data for, such as {"scan": {"id": 42}}.
  3. Once you have set your parameters, select Execute to run the query. Download or browse the resulting JSON file.

Note

Save the full curl request in order to use it programmatically.

 

On this page: