🌐 Universal Parser (Pro)

Note: The Universal Parser is only available in DefectDojo Pro.

The Universal Parser is currently in Beta. See our announcement presentation for more information.

About Universal Parser

DefectDojo has a large, regularly updated library of parsers to help security teams ingest data. However, sometimes users have a tool that’s unsupported by the parsers, or they may want to import data into the DefectDojo model differently from the way the parser does.

DefectDojo’s Universal Parser is meant to give our users with unsupported report types a path forward, to import and map any JSON, CSV or XML file.

The Universal Parser is:

• A quick way to support file formats for which we do not have Community parsers, such as reports produced by internal tools
• A tool to help you ingest data, even if a Community parser is out-of-date or doesn’t structure findings the way you would like
• An alternative to custom scripting to transform tool reports into the CSV/JSON format expected by the “Generic Findings Import” scan type
• Designed to be easy to use for anyone, with no coding and minimal configuration required

The Universal Parser is not:

• A comprehensive replacement for open source parsers, Connectors, or carefully-massaged “Generic Findings Import” reports
• Capable of handling nuanced, branching logic to structure findings

The Universal Parser configuration is only available in the Pro UI, though you can still import scans using a Universal Parser via the old UI or API.

Step 1: Creating a new Universal Parser

You can create a new Universal Parser by clicking the “New Universal Parser” button in the navigation bar under the “Import” section, or from the link on the “Add Findings” page.

The first screen will ask you for a scan file and a parser name.

The file should:

• Have a recognized extension (see supported file extensions below)
• Contain enough finding-like objects to be representative of real reports - i.e., one that includes values in all optional fields
• Not be larger than about 1-2MB - beyond this point it will generally just take longer to parse the file, without any benefit

The parser name will be used when creating the Test_Type for this new parser. You’ll find your newly-created Universal Parser in the scan types drop-down on the “Add Findings” page with a name like “Universal Parser - MyCustomParser”. Parser names must be unique to prevent confusion when selecting a scan type for imports.

Step 2: Mapping your Finding fields

After uploading an example scan file, selecting a parser name, and clicking “Next”, the following page will let you configure the way this Universal Parser will populate finding fields when using this configuration to perform imports. On the right, you will find a selection of DefectDojo finding fields (output fields). Drop-down menus to the left of each output field allow you to select which item(s) (input fields) from your scan file’s structure should be used to populate them.

Example:

If you’ve uploaded a scan file in JSON format that looks like this:

{
    "findings": [
        {
            "title": "Finding 1 Title",
            "description": "Finding 1 Description",
            "severity": "CRITICAL",
            "CVE": "CVE-2025-12345",
            ...
        },
        {
            "title": "Finding 2 Title",
            "description": "Finding 2 Description",
            "severity": "LOW",
            "CVE": "CVE-2025-54321",
            ...
        },
        ...
    ]
}

You’ll see a hierarchical representation of the unique fields we detected based on the structure of the input file, with icons indicating the type of each field (if we can determine this). You can then select the “title” input field in the drop-down menu that populates the “Title” output field, the “description” input field can go with the “Description” output field, and so on.

Required fields

The following output fields require an input field mapping:

• Title
• Severity
• Description

About severities

A Universal Parser will accept any case variation of the DefectDojo severities - “CRITICAL”, “Critical”, “cRiTiCaL”, etc. - and apply it to your findings. Any value that doesn’t match a DefectDojo severity will be replaced with “Info”. This mirrors how parsers and Connectors work today: unknown values are generally mapped to “Info”.

Multi-select fields

Some output fields will accept multiple input fields. If you decide to select more than one input field, we will provide that field’s value under a header with that input field’s name.

Example

description

This was pulled from a field called “description” in the input file

detailed_description

This was pulled from a field called “detailed_description” in the input file

Step 3: Previewing your Findings

Once you’ve selected your mappings from input fields to output fields, you can click the “Next” button to see a preview of what the Findings from your input file will look like once they are imported to DefectDojo with your chosen configuration. Some fields will have an “expand” button next to them to allow you to see the full, rendered MarkDown of what that field will look like. We will only render previews of the first 25 Findings from your input file, but you can also see how many findings were detected in the whole scan file.

If the previews don’t look like you expected, you can hit the “Back” button to tweak the mappings. Once you are satisfied with your configuration, click the “Submit” button to create your new Universal Parser. This will not perform an import automatically.

Once your Universal Parser is created, you’ll be redirected to the “Add Findings” page where you can upload and import a scan file matching the structure of the example file you provided in Step 1.

Additional notes about Universal Parser configuration

Choosing the right input fields

Each vendor may produce very different scan report formats, some of which will map more closely to DefectDojo’s finding model than others. We allow for significant flexibility in what we will accept, but we must impose some structure to ensure that findings don’t get garbled in the translation from input to output. While we can accommodate optional input fields, we don’t accept “global” fields, or fields that occur a different number of times than the number of finding objects.

Example

{
    "scan_type": "MyToolScan", // <- There is only one instance of this field, which doesn't match the number of findings
    "findings": [
        {
            "title": "Finding 1 Title",
            "description": "Finding 1 Description",
            "severity": "CRITICAL",
            "CVE": "CVE-2025-12345", // <- This optional field only appears in Finding 1 - that's okay!
            ...
        },
        {
            "title": "Finding 2 Title",
            "description": "Finding 2 Description",
            "severity": "CRITICAL",
            ...  // <- While there is no "CVE" field here, we can still query for it and simply default to a null value
        },
        ... 5 more findings ...
    ],
    "global_details": [
        {
            "nested_detail": "Global detail 1"
        },
        {
            "nested_detail": "Global detail 2" // <- The number of "global_details" objects (2) does not match the number of individual finding objects (7)
        }
    ]
}

After saving a Universal Parser

You can edit the Test_Type associated with your Universal Parser to change:

• Whether it is “active” or not. If not, it will not appear as an option in the “Scan Type” drop-down on the “Add Findings” page
• Whether its findings should be marked “static” or “dynamic”
• You can tweak the same-tool and cross-tool deduplication hash codes, as well as the reimport hash codes, for your Universal Parser under “Enterprise Settings”. By default, only same-tool deduplication and reimport hash codes are populated, with the required values Title, Severity, and Description.

Lifecycle: create, deactivate, reactivate

A Universal Parser’s lifecycle is create-only, with no in-UI edit or delete. Once a parser has been created, the field-mapping configuration cannot be modified, and the parser itself cannot be removed from the UI — this is by design, because Universal Parser configurations are tied to Test_Type records that may be referenced by existing Findings, Tests, and import history.

What you can do from the UI:

• Deactivate a parser to hide it from the “Scan Type” drop-down on import. Open Import → Universal Parser in the sidebar to see all of your Universal Parsers, and toggle “Active” off. (Alternatively, you can edit the underlying Test_Type and uncheck “active”.) Deactivated parsers no longer appear as a Scan Type option on the Add Findings page, but existing Tests that were imported with this parser are unaffected and continue to work.
• Reactivate a parser from the same screen by toggling “Active” back on.
• Edit the Test_Type fields described in the section above (active/inactive, static/dynamic, deduplication hash codes).

Recommended workflow when a scanner’s report format changes

Because the field-mapping configuration is locked once a parser is created, the standard workflow for handling a format change in the underlying scanner is to roll forward to a new parser rather than try to edit the old one:

1. Create a new Universal Parser using a sample of the new report format (see Step 1). Give it a distinct name — e.g. append v2 or a date to the original name.
2. Switch new imports in your CI/CD pipeline or UI workflow to use the new parser’s scan type.
3. Deactivate the old parser once you’ve confirmed the new one is producing the findings you expect. Tests already imported under the old parser remain in DefectDojo and can still be triaged; only new imports route to the new parser.

If you need a parser configuration permanently removed (for example, because it contains sensitive field names), contact DefectDojo Support.

A note about severity mapping

The Universal Parser does not have a configurable severity-mapping field. Severity is mapped automatically with these rules:

• Any case variation of a DefectDojo severity is accepted — CRITICAL, Critical, cRiTiCaL, critical all map to Critical. The same applies to High, Medium, Low, and Info.
• Any value that does not match one of DefectDojo’s five severities is mapped to Info.

This behavior is the same for all parsers in DefectDojo (built-in parsers, Connectors, and Universal Parsers).

If a scanner you’re trying to ingest uses severity labels that don’t line up with DefectDojo’s (e.g. “warning”, “note”, or numeric CVSS scores), the Universal Parser will map all of those non-matching values to Info. If you need a different mapping, the best workaround today is to transform the severity values upstream — for example, in your CI pipeline before uploading — so the values DefectDojo receives are already one of the five DefectDojo severity names.