Universal Importer & DefectDojo-CLI (Pro)

Note: The following external tools are DefectDojo Pro-only features. These binaries will not work unless they are connected to an instance with a DefectDojo Pro license.

About External Tools

defectdojo-cli and universal-importer are command-line tools designed to streamline both the import and re-import processes of Findings and associated objects, making it ideal for users who want to quickly set up these interactions with the DefectDojo API.

DefectDojo-CLI has the same functionality as Universal Importer, but also includes the ability to export Findings from DefectDojo to JSON or CSV.

Installation

1. Locate “External Tools” from your User Profile menu:

2. Download the appropriate binary for your operating system from the platform.

3. Extract the downloaded archive within a directory of your choice. Optionally, add the directory containing the extracted binary to your system’s $PATH for repeat access.

Note that Macintosh users may be blocked from running DefectDojo-CLI or Universal Importer as they are apps from an unidentified developer. See Apple Support for instructions on how to override the block from Apple.

Windows Users: If you receive the “Couldn’t download - virus detected” error, disabling Smartscreen may work. Otherwise, use a different browser to download the tool from the Cloud portal.

Configuration

Universal Importer & DefectDojo-CLI can be configured using flags, environment variables, or a configuration file. The most important configuration is the API token, which must be set as an environment variable:

1. Add your API key to your environment variables. You can retrieve your API key from: https://YOUR_INSTANCE.cloud.defectdojo.com/api/key-v2

or

Via the DefectDojo user interface in the user dropdown in the top-right corner:

2. Set your environment variable for the API token:

   For DefectDojo-CLI: export DD_CLI_API_TOKEN=YOUR_API_KEY

   For Universal Importer: export DD_IMPORTER_DOJO_API_TOKEN=YOUR_API_KEY

Note: On Windows, use set instead of export.

Windows: Using PowerShell

1. Open PowerShell (Windows Key, then search for “PowerShell”).

2. Set the environment variables:

   • Temporary:

     $env:DD_IMPORTER_DOJO_API_TOKEN = "[VALUE_FROM_DEFECTDOJO_API]"
     $env:DD_IMPORTER_DEFECTDOJO_URL=”[e.g. http://localhost:8080/defectdojo]”
     

   • Permanent:

     [Environment]::SetEnvironmentVariable("DD_IMPORTER_DOJO_API_TOKEN", "[VALUE_FROM_DEFECTDOJO_API]", "Machine")
     

3. Restart your PowerShell session.

4. Verify the setting:

   echo $env:DD_IMPORTER_DOJO_API_TOKEN
   echo $env:DD_IMPORTER_DEFECTDOJO_URL
   

Windows: Using Command Prompt (Administrative Accounts)

1. Open Command Prompt (Windows Key, then search for “Command Prompt”).
2. Set the environment variables:

   • Temporary:

     set DD_IMPORTER_DOJO_API_TOKEN = "[VALUE_FROM_DEFECTDOJO_API]"
     set DD_IMPORTER_DEFECTDOJO_URL=”[e.g. http://localhost:8080/defectdojo]”
     

   • Permanent:

     setx DD_IMPORTER_DOJO_API_TOKEN = "[VALUE_FROM_DEFECTDOJO_API]"
     setx DD_IMPORTER_DEFECTDOJO_URL=”[e.g. http://localhost:8080/defectdojo]"
     

Windows Settings (Non-Administrative Accounts)

1. Press Win + I to open the system settings dialog.

2. In the search box, type “environment”.

3. Choose “Edit Environment variables for your account”.

4. Under “User variables for [username]”, click the “New…” button.

5. Set the variable:

   • Variable name: DD_IMPORTER_DOJO_API_TOKEN
   • Variable value: [VALUE_FROM_DEFECTDOJO_API]

6. Click “OK”.

7. Repeat steps 4 through 6 for the DD_IMPORTER_DEFECTDOJO_URL variable.

8. Restart any open command windows.

9. Verify the settings:

   echo %DD_IMPORTER_DOJO_API_TOKEN%
   echo %DD_IMPORTER_DEFECTDOJO_URL%
   

DefectDojo-CLI

defectdojo-cli seamlessly integrates scan results into DefectDojo, streamlining the import and reimport processes of Findings and associated objects. Designed for ease of use, the tool supports various endpoints, catering to both initial imports and subsequent reimports — ideal for users requiring robust and flexible interaction with the DefectDojo API. DefectDojo-CLI can perform the same functions as universal-importer, and adds export functionality for Findings.

Commands

• import Imports findings into DefectDojo.
• reimport Reimports findings into DefectDojo.
• export Exports findings from DefectDojo.
• interactive Starts an interactive mode to configure the import and reimport process.

Global Options

--help, -h

• show help

--version, -v

• print the version

CLI Formatting

--no-color

• Disable color output. (default: false)

--no-emojis, --no-emoji

• Disable emojis in the output. (default: false)

--verbose

• Enable verbose output. (default: false)

Import

Use the import command to import new findings into DefectDojo.

Usage

defectdojo-cli [global options] import <required flags> [optional flags]
    or: defectdojo-cli [global options] import  --config ./config-file-path
    or: defectdojo-cli import [-h | --help]
    or: defectdojo-cli import example [subcommand options]
    or: defectdojo-cli import example [-h | --help]

>> The API token must be set in the environment variable `DD_CLI_API_TOKEN`.

import can import Findings in two ways:

By ID:

• Create a Product (or use an existing product)
• Create an Engagement inside the product
• Provide the id of the Engagement in the engagement parameter

In this scenario, a new Test will be created inside the Engagement.

By Name:

• Create a Product (or use an existing product)
• Create an Engagement inside the product
• Provide product-name
• Provide engagement-name
• Optionally provide product-type-name

In this scenario, DefectDojo will look up the Engagement by the provided details.

When using names you can let the importer automatically create Engagements, Products and Product-types by using auto-create-context=true. You can use deduplication-on-engagement to restrict deduplication for imported Findings to the newly created Engagement.

Import Basic syntax:

defectdojo-cli import [options]

Import Example:

defectdojo-cli import \
--defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" \
--scan-type "burp scan" \
--report-path "./examples/burp_findings.xml" \
--product-name "dev" \
--engagement-name "dev" \
--product-type-name "Research and Development" \
--test-name "burp-test-dev" \
--verified \
--active \
--minimum-severity "info" \
--tag "dev" --tag "tools" --tag "burp" --tag "test-dev" \
--test-version "0.0.1" \
--auto-create-context

Commands

example, x

• Shows an example of required and optional flags for import operation

Options

--active, -a

• Dictates whether Findings should be forced to Active or Inactive on import. A value of True forces Findings to Active, while a value of False forces all Findings to Inactive. If no value is set, Active status will instead rely on the incoming report file. (default: unset)

--api-scan-configuration value, --asc value

• The ID of the API Scan Configuration object to use when importing or reimporting. (default: 0)

--apply-tags-endpoints, --te

• If set to true, the tags (from the option –tag) will be applied to the endpoints (default: false)

--apply-tags-findings, --tf

• If set to true, the tags (from the option –tag) will be applied to the findings (default: false)

--auto-create-context, --acc

• If set to true, the importer automatically creates Engagements, Products, and Product_Types (default: false)

--close-old-findings, --cof

• If True, old Findings no longer present in the report will be Closed as Mitigated when importing. If Service has been set, only the Findings for this Service will be closed.

--close-old-findings-product-scope, --cofps

• Select if –close-old-findings applies to all Findings of the same type in the Product. By default, this is set to false, meaning that only old Findings of the same type in the Engagement are in scope (and will be closed by Close Old Findings).

--deduplication-on-engagement, --doe

• If set to true, the importer restricts deduplication for imported findings to the newly created Engagement. (default: false)

--engagement-id value, --ei value

• The ID of the Engagement to import findings into. (default: 0)

--engagement-name value, -e value

• The name of the Engagement to import findings into.

--minimum-severity value, --ms value

• Dictates the lowest level severity that should be imported. Valid values are: Critical, High, Medium, Low, Info. (default: "Info")

--product-name value, -p value

• The name of the Product to import findings into.

--product-type-name value, --pt value

• The name of the Product Type to import findings into.

--report-path value, -r value

• The path to the report to import. (required).

--scan-type value, -s value

• The scan type of the tool (required).

--tag value, -t value [ --tag value, -t value ]

• Any tags to be applied to the Test object

--test-name value, --tn value

• The name of the Test to import findings into - Defaults to the name of the scan type.

--test-version value, -V value

• The version of the test.

--verified, -v

• Dictates whether Findings should be set to Verified on import. A value of True forces Findings to Verified. If no value is set, Verified status will instead rely on the incoming report file.

Settings:

--config value, -c value

• The path to the TOML configuration file is used to set values for the options. If the option is set in the configuration file and the CLI, the option will take the value set from the CLI.

--defectdojo-url value, -u value

• The URL of the DefectDojo instance to import findings into. (required).

--insecure-tls, --no-tls

• ignore TLS validation errors when connecting to the provided DefectDojo instance. Most users should not enable this flag. (default: false)

Reimport

Use the reimport command to extend an existing Test with Findings from a new report in one of two ways:

By ID:

• Create a Product (or use an existing product)
• Create an Engagement inside the product
• Import a scan report and find the id of the Test
• Provide this in the test-id parameter

By Names:

• Create a Product (or use an existing product)
• Create an Engagement inside the product)
• Import a report which will create a Test
• Provide product-name
• Provide engagement-name
• Optional: Provide test-name

In this scenario, DefectDojo will look up the Test by the provided details. If no test-name is provided, the latest test inside the engagement will be chosen based on scan-type.

Usage

defectdojo-cli [global options] reimport <required flags> [optional flags]
   or: defectdojo-cli [global options] reimport  --config ./config-file-path
   or: defectdojo-cli reimport [-h | --help]
   or: defectdojo-cli reimport example [subcommand options]
   or: defectdojo-cli reimport example [-h | --help]

>> The API token must be set in the environment variable `DD_CLI_API_TOKEN`.

Reimport Example:

defectdojo-cli reimport \
--defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" \
--scan-type "Nancy Scan" \
--report-path "./examples/nancy_findings.json" \
--test-id 11 \
--verified \
--active \
--minimum-severity "info" \
--tag "dev" --tag "tools" --tag "nancy" --tag "test-dev" \
--test-version "1.0" \
--auto-create-context

Commands

example, x

• Shows an example of required and optional flags for reimport operation

Options

--active, -a

• Dictates whether Findings should be forced to Active or Inactive on import. A value of True forces Findings to Active, while a value of False forces all Findings to Inactive. If no value is set, Active status will instead rely on the incoming report file.

--api-scan-configuration value, --asc value

• The ID of the API Scan Configuration object to use when importing or reimporting.

--apply-tags-endpoints, --te

• If set to true, the tags (from the option –tag) will be applied to the endpoints.

--apply-tags-findings, --tf

• If set to true, the tags (from the option –tag) will be applied to the findings.

--auto-create-context, --acc

• If set to true, the importer automatically creates Engagements, Products, and Product_Types.

--close-old-findings, --cof

• If True, old Findings no longer present in the report will be Closed as Mitigated when importing.

Export

Usage

defectdojo-cli export <required options> [optional options]
    or: defectdojo-cli [global options] export --defectdojo-url <https://YOUR_INSTANCE.cloud.defectdojo.com/> --json ./output_file_path.json [optional filters]
    or: defectdojo-cli [global options] export --defectdojo-url <https://YOUR_INSTANCE.cloud.defectdojo.com/> --csv ./output_file_path.csv [optional filters]
    or: defectdojo-cli [global options] export --defectdojo-url <https://YOUR_INSTANCE.cloud.defectdojo.com/> --json ./output_file_path.json --csv ./output_file_path.csv [optional filters]
    or: defectdojo-cli [global options] export --config ./config-file-path
    or: defectdojo-cli [global options] export --config ./config-file-path --json ./output_file_path.json
    or: defectdojo-cli [global options] export --config ./config-file-path --csv ./output_file_path.csv
    or: defectdojo-cli export [-h | --help]
    or: defectdojo-cli export example [subcommand options]
    or: defectdojo-cli export example [-h | --help]

>> The API token must be set in the environment variable `DD_CLI_API_TOKEN`.

To export Findings from DefectDojo-CLI, you will need to supply a configuration file which contains details explaining which Findings you wish to export. This is similar to the GET Findings method via the API.

For assistance use defectdojo-cli export --help.

Export Example

This example specifies the URL, export format and a few filter parameters to create a list of Findings.

defectdojo-cli export \
--defectdojo-url "https://your-dojo-instance.cloud.defectdojo.com/"
--json "./path/to/findings.json" \
--active "true" \
--created "Past 90 days"

Commands

example, x

• Shows an example of required and optional flags for export operation

help, h

• Shows a list of commands or help for one command

Options

Findings Filters:

--active true|false, -a true|false

• Findings by active status.

--created value

• Findings by created date. Supported values: None, Today, Past 7 days, Past 30 days, Current month, Current year, Past year

--cvssv3-score value

• Findings by CVSS v3 score. (default: ignored)

--cwe value

• Findings by CWE ID. (default: ignored)

--date value

• Findings by date.

--discovered-after value

• Findings by discovered after the specified date. Format: YYYY-MM-DD

--discovered-before value

• Findings by discovered before the specified date. Format: YYYY-MM-DD

--discovered-on value

• Findings by discovered date. Format: YYYY-MM-DD

--duplicate true|false

• Findings by duplicated status.

--engagement-ids value [ --engagement-ids value ]

• Findings by engagement IDs. This flag can be used multiple times or as a comma-separated list.

--epss-percentile value

• Findings by EPSS percentile.

--epss-score value

• Findings by EPSS score.

--false-positive true|false

• Findings by false positive status.

--is-mitigated true|false

• Findings by mitigation status.

--mitigated value

• Findings by the date range in which they were marked mitigated.

--mitigated-after value

• Findings by mitigation after the specified date. Format: YYYY-MM-DD

--mitigated-before value

• Findings by mitigation before the specified date. Format: YYYY-MM-DD

--mitigated-by-ids value [ --mitigated-by-ids value ]

• Findings by mitigated_by user IDs.

--mitigated-by-names value [ --mitigated-by-names value ]

• Findings by mitigated_by user names.

--mitigated-on value

• Findings by mitigation date. Format: YYYY-MM-DD

--not-tags value [ --not-tags value ]

• Findings by tags that should not be present.

--out-of-scope true|false

• Findings by out of scope or in scope status.

--out-of-sla true|false

• Findings by outside or inside SLA status.

--product-name value

• Findings by product name.

--product-name-contains value

• Findings by product name contains.

--product-type-ids value [ --product-type-ids value ]

• Findings by product type IDs.

--product-type-names value [ --product-type-names value ]

• Findings by product type names.

--risk-accepted true|false

• Findings by risk accepted status.

--severity value [ --severity value ]

• Findings by severity.

--tags value [ --tags value ]

• Findings by tags that should be present.

--test-id value

• Findings by test ID.

--title-contains value

• Findings by containing the given string in their title.

--under-review true|false

• Findings by under review status.

--verified true|false

• Findings by verified status.

Findings Output

--csv value

• Path of the file where the CSV file of the findings will be written.

--json value

• Path of the file where the JSON file of the findings will be written.

Settings

--config value, -c value

• The path to the TOML configuration file is used to set values for the options.

--defectdojo-url value, -u value

• The URL of the DefectDojo instance to import findings into.

--insecure-tls, --no-tls

• ignore TLS validation errors when connecting to the provided DefectDojo instance.

Interactive

Interactive mode allows you to configure import and reimport process, step-by-step.

Usage

defectdojo-cli interactive
    or: defectdojo-cli interactive  [--skip-intro] [--no-full-screen] [--log-path]
    or: defectdojo-cli interactive [-h | --help]

Options

--skip-intro

• Skip the intro screen (default: false)

--no-full-screen

• Disable full screen mode (default: false)

--log-path value

• Path to the log file

--help, -h

• show help

Universal Importer

universal-importer seamlessly integrates scan results into DefectDojo, streamlining both the import and reimport processes of findings and associated objects. Designed for ease of use, the tool supports various endpoints, catering to both initial imports and subsequent reimports — ideal for users requiring robust and flexible interaction with the DefectDojo API.

While similar to DefectDojo-CLI, Universal Importer does not have the Export functionality, and environment variables are encoded differently.

Commands

• import Imports findings into DefectDojo.
• reimport Reimports findings into DefectDojo.
• interactive Starts an interactive mode to configure the import and reimport process.

Global Options

--help, -h

• show help

--version, -v

• print the version

CLI Formatting

--no-color

• Disable color output. (default: false)

--no-emojis, --no-emoji

• Disable emojis in the output. (default: false)

--verbose

• Enable verbose output. (default: false)

Import

Use the import command to import new findings into DefectDojo.

Usage

universal-importer [global options] import <required flags> [optional flags]
    or: universal-importer [global options] import  --config ./config-file-path
    or: universal-importer import [-h | --help]
    or: universal-importer import example [subcommand options]
    or: universal-importer import example [-h | --help]

>> The API token must be set in the environment variable `DD_IMPORTER_DOJO_API_TOKEN`.

import can import Findings in two ways:

By ID:

• Create a Product (or use an existing product)
• Create an Engagement inside the product)
• Provide the id of the Engagement in the engagement parameter

By Name:

• Create a Product (or use an existing product)
• Create an Engagement inside the product)
• Provide product-name
• Provide engagement-name
• Optionally provide product-type-name

When using names you can let the importer automatically create Engagements, Products and Product-types by using auto-create-context=true.

Import Basic syntax:

universal-importer import [options]

Import Example:

universal-importer import \
--defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" \
--scan-type "burp scan" \
--report-path "./examples/burp_findings.xml" \
--product-name "dev" \
--engagement-name "dev" \
--product-type-name "Research and Development" \
--test-name "burp-test-dev" \
--verified \
--active \
--minimum-severity "info" \
--tag "dev" --tag "tools" --tag "burp" --tag "test-dev" \
--test-version "0.0.1" \
--auto-create-context

Reimport

Use the reimport command to extend an existing Test with Findings from a new report in one of two ways:

By ID:

By Names:

In this scenario, DefectDojo will look up the Test by the provided details.

Usage

universal-importer [global options] reimport <required flags> [optional flags]
   or: universal-importer [global options] reimport  --config ./config-file-path
   or: universal-importer reimport [-h | --help]
   or: universal-importer reimport example [subcommand options]
   or: universal-importer reimport example [-h | --help]

>> The API token must be set in the environment variable `DD_IMPORTER_DOJO_API_TOKEN`.

Reimport Example:

universal-importer reimport \
--defectdojo-url "https://YOUR_INSTANCE.cloud.defectdojo.com/" \
--scan-type "Nancy Scan" \
--report-path "./examples/nancy_findings.json" \
--test-id 11 \
--verified \
--active \
--minimum-severity "info" \
--tag "dev" --tag "tools" --tag "nancy" --tag "test-dev" \
--test-version "1.0" \
--auto-create-context

Troubleshooting

If you encounter any issues with these tools, please check the following:

• Ensure you’re using the correct binary for your operating system and CPU architecture.
• Verify that the API key is set correctly in your environment variables.
• Check that the DefectDojo URL is correct and accessible.
• When importing, confirm that the report file exists and is in the supported format for the specified scan type.