Generating An Export File Through The API

How to export CSV or PDF files through API calls on Delve's public API.

Delve's public Open API provides functions allowing to export vulnerabilities and assets in different file formats (PDF, CSV).

✔️ 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>.wardenscanner.com/api/v2/spec
It can be tested by following the following How-To article.

Export types

There are three types of exports available: 

  • Vulnerability Assessment Export (PDF)
  • Asset List Export (CSV)
  • Vulnerability List Export (CSV)

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.

✔️ 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.

Step-by-step guide

Step 1: Request the generation of an export

Call any export request route as a POST. If the request is successful, the API will respond with a 303 see other redirect to the route containing the status of the export with the export id corresponding of the request (needed for the step 2).

Examples

Exporting a vulnerability assessment of the server id "42" 


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

 


Exporting all vulnerabilities in a .csv file for the websites of the 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"}
},
}

 


Exporting all the critical vulnerabilities in a .csv file

 

POST /api/v2/vulnerability-groups/export
// request data
{
"kind": "export",
"fileFormat": "csv",
"query": {
"severity": { "level": "critical" }
},
}

Step 2: Check the export status

Call /api/v2/export/<id> to retrieve the status of the requested export. 

✔️ 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 will change to "done" and the response will contain the download URL.

Step 3: Download the export file

Once the export status is "done", call /api/v2/export/<id>/download ; the API response will contains the export files. The response mime-type will depend of the requested file format.