Import from API

DefectDojo’s API allows for robust pipeline solutions, which automatically ingest new scans to your instance. Automation like this can take a few different forms:

• A daily import which scans your environment on a daily basis, and then imports the results of the scan to DefectDojo (similar to our Connectors feature)
• A CI/CD pipeline which scans new code as it is deployed, and imports the results to DefectDojo as a triggered action

These pipelines can be created by directly calling our API /reimport endpoint with an attached scan file in a way that closely resembles our Import Scan Form.

DefectDojo’s API

DefectDojo’s API is documented in-app using the OpenAPI framework. You can access this documentation from the User Menu in the top right-hand corner, under ‘API v2 OpenAPI3’.

• The documentation can be used to test API calls with various parameters, and does so using your own user’s API Token.

If you need to access an API token for a script or another integration, you can find that information under the API v2 Token option from the same menu.

General API Considerations

• Although our OpenAPI documentation is detailed regarding the parameters that can be used with each endpoint, it assumes that the reader has a solid understanding of DefectDojo’s key concepts. (Product Hierarchy, Findings, Deduplication, etc).
• Users who want a working import integration but are less familiar with DefectDojo as a whole should consider our Universal Importer.
• DefectDojo’s API can sometimes create unintended data objects, particularly if ‘Auto-Create Context’ is used on the /import or /reimport endpoint.
• Fortunately, it is very difficult to accidentally delete data using the API. Most objects can only be removed using a dedicated DELETE call to the relevant endpoint.

Specific notes on /import and /reimport endpoints

The /reimport endpoint can be used for both an initial Import, or a “Reimport” which extends a Test with additional Findings. You do not need to first create a Test with /import before you can use the /reimport endpoint. As long as ‘Auto Create Context’ is enabled, the /reimport endpoint can create a new Test, Engagement, Product or Product Type. In almost all cases, you can use the /reimport endpoint exclusively when adding data via API.

However, the /import endpoint can instead be used for a pipeline where you always want to store each scan result in a discrete Test object, rather than using /reimport to handle the diff within a single Test object. Either option is acceptable, and the endpoint you choose depends on your reporting structure, or whether you need to inspect an isolated run of a Pipeline.

Using the Scan Completion Date (API: scan_date) field

DefectDojo offers a plethora of supported scanner reports, but not reports them contain the information most important to a user. The scan_date field is a flexible smart feature that allows users to set the completion date of the a given scan report, and have it propagate down to all the findings imported.

This field is not mandatory, but the default value for this field is the date of import (whenever the request is processed and a successful response is returned).

Here are the following use cases for this field, and the results applied to the Test:

1. If the report does not set the date, and scan_date is not set at import
   • Finding date will be the default value of scan_date
2. If the report sets the date, and the scan_date is not set at import
   • Finding date will be whatever the report sets
3. If the report does not set the date, and the scan_date is set at import
   • Finding date will be whatever the user set for scan_date
4. If the report sets the date, and the scan_date is set at import
   • Finding date will be whatever the user set for scan_date