🌙☀
 

Subscribe to the Taegis™ VDR Documentation RSS Feed at .

Learn more about RSS readers or RSS browser extensions.

Generating an Export File through the API

This article reviews how to export CSV or PDF files through API calls using Secureworks® Taegis™ VDR’s public API. VDR’s public Open API provides functions allowing you to export vulnerabilities and assets in different file formats (PDF, CSV).

Note

Use the API testing interface to try the different routes described in this guide. The API testing interface is available alongside the API reference under the URL: https://<your-instance>.vdr.secureworks.com/api/v2/spec. For information on testing, see Get Asset Result Scans Via Swagger.

Export Types ⫘

There are three types of exports available:

Vulnerability Assessment Export ⫘

File format: pdf

Request routes: /api/v2/vulnerability-groups/export, /api/v2/websites/export, and /api/v2/servers/export

A vulnerability assessment is a report containing all vulnerabilities and related information (assets, documentation, etc.) for a given set of data.

Note

Since a vulnerability assessment report contains dates and times, it is possible to provide a UTC offset in minutes (positive or negative integer) to avoid any confusion to the reader.

Asset List Export ⫘

File format: csv (RFC-4180)

Request routes: /api/v2/websites/export and /api/v2/servers/export

An asset list is a tabular data file containing all information related to a given set of assets.

Vulnerability List Export ⫘

File format: csv (RFC-4180)

Request routes: /api/v2/vulnerability-groups/export, /api/v2/websites/export, and /api/v2/servers/export

A vulnerability list is a tabular data file containing all vulnerabilities for a given set of data.

Export ⫘

  1. Request the generation of an export by calling any export request route as a POST. If the request is successful, the API responds with a 303 see other redirect to the route containing the status of the export with the export id corresponding to the request.

Examples ⫘

Export a Vulnerability ⫘

Export a vulnerability assessment of server id 42:

POST /api/v2/servers/export
// request data
{
   "kind": "export",
   "fileFormat": "pdf",
   "query": {
      "id": { "match": "42" }
   },
}

Export All Vulnerabilities ⫘

Export all vulnerabilities in a .csv file for the websites of team id 53 containing the text XSS:

POST /api/v2/websites/export
// request data
{
   "kind": "export",
   "fileFormat": "csv",
   "content": "vulnerability_group",
   "query": {
      "team": { "id": "53" },
      "global": {"text": "XSS"}
   },
}

Export Critical Vulnerabilities ⫘

Export all the critical vulnerabilities in a .csv file:

POST /api/v2/vulnerability-groups/export
// request data
{
   "kind": "export",
   "fileFormat": "csv",
   "query": {
      "severity": { "level": "critical" }
   },
}
  1. Check the export status with a call to /api/v2/exports/<id> to retrieve the status of the requested export.

Note

It is possible to pull the export status route to periodically check the status of the requested export. Once the export file is available, the status changes to done. The response contains the download URL.

  1. Download the export file. Once the export status is done, call /api/v2/exports/<id>/download, and the API response contains the export files. The response mime-type depends on the requested file format.

 

On this page: