Generic Findings Import

Generic Findings Import can be used to import any report in CSV or JSON format.

Choosing CSV or JSON#

DefectDojo picks the format from the file name:

• A file whose name ends in .csv (any case) is read as CSV.
• Every other file is read as JSON, whatever its extension.

JSON supports far more fields than CSV (components, SAST data, tags, endpoint objects, attached files, report metadata). Use JSON when you can.

CSV format#

File rules#

• The first row is a header row naming the columns. Column order does not matter.
• Column names are case-sensitive and must match the names below exactly. Title works, title does not.
• Values are separated by commas. Wrap a value in double quotes if it contains a comma or a line break, and write a literal double quote as two double quotes ("").
• Save the file as UTF-8 without a byte order mark (BOM). Some spreadsheet tools add a BOM by default (“CSV UTF-8” in Excel). The BOM becomes part of the first column name, so DefectDojo no longer recognizes that column and the import fails.
• Each row is one finding. Rows with the same Severity, Title and Description are merged into a single finding: their Url values are combined, their vulnerability IDs and CWEs are combined, and the finding’s occurrence count goes up by one for each extra row. Use this to report one issue found at several URLs.
• Columns not listed below are ignored.

Required columns#

Date, Title, Description and Severity must be present in the header, and every row needs a value for Date. A file missing one of these columns fails to import.

Supported columns#

Boolean values in CSV#

Active, Verified, FalsePositive, Duplicate, IsMitigated, known_exploited, ransomware_used and fix_available are true when the value starts with t or T (TRUE, True, true, t). Every other value is false, including yes and 1. An empty cell is false for the first five columns; for known_exploited, ransomware_used and fix_available it leaves the field at its default (false, false, and unknown).

An empty cell in the numeric and date columns (CweId, epss_score, epss_percentile, CVSSV3_score, CVSSV4_score, MitigatedDate, kev_date) leaves that field unset, so rows can mix filled and empty cells. A value that is not a number or date, such as N/A, still fails the import.

Example CSV#

Date,Title,CweId,Url,Severity,Description,Mitigation,References,Active,Verified,CVE,CVSSV3
2024-05-01,SQL Injection in login form,89,https://app.example.com/login,High,"The username parameter is concatenated into a SQL query.
An attacker can bypass authentication.",Use parameterized queries.,https://owasp.org/Top10/A03_2021-Injection/,TRUE,FALSE,,CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H
2024-05-01,SQL Injection in login form,89,https://app.example.com/admin/login,High,"The username parameter is concatenated into a SQL query.
An attacker can bypass authentication.",Use parameterized queries.,https://owasp.org/Top10/A03_2021-Injection/,TRUE,FALSE,,CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H
2024-05-02,Outdated xz-utils package,506,build.example.com,Critical,xz-utils 5.6.0 contains a backdoor.,Upgrade to 5.6.2 or later.,https://nvd.nist.gov/vuln/detail/CVE-2024-3094,TRUE,TRUE,CVE-2024-3094,CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H

The first two rows share a severity, title and description, so they import as one finding with two endpoints and an occurrence count of 2.

JSON format#

A JSON report is an object with a findings array and, optionally, report-level metadata.

Report-level fields#

Test Type metadata#

static_tool, dynamic_tool and soc describe the tool, not the report, so they are stored on the Test Type rather than on the Test. A CSV import never sets them.

• They apply to every Test of that Test Type. A Test Type is shared across all Products, so the flags are instance-wide for that tool. Each import that includes a flag overwrites it, and the last import wins.
• An omitted flag keeps its current value. null is treated the same as omitting the key. To clear a flag, send false.
• Set type before you set these flags. A report without type imports into the built-in Generic Findings Import Test Type, so its flags change that Test Type for every generic import on the instance, including CSV imports. Give each tool its own type so its flags stay with that tool.
• Send JSON booleans. true and false work. A quoted "false" is rejected and the whole import fails with a 400 error.

What the flags drive:

Finding fields#

Every finding must have title, severity and description. A finding with a key that is not in this table stops the import with a Not allowed fields are present error naming the key, so check spelling carefully (for example false_p, not false_positive).

Value rules#

• Booleans must be JSON true or false, not quoted strings. The parser does not convert "true" or "false", and a quoted lowercase value such as "false" stops the import when the finding is saved.
• Numbers (cwe, line, thread_id, nb_occurences, scanner_confidence, sast_source_line, epss_score, epss_percentile, cvssv3_score, cvssv4_score) may be given as a number or a quoted number (42 or "42"). A value that holds no number, such as "N/A" for a line number the tool could not determine, is ignored and the field keeps its default. true and false are not treated as numbers.
• Dates: date and mitigated accept most formats. publish_date, planned_remediation_date and kev_date accept only YYYY-MM-DD (or YYYYMMDD).

Endpoints#

endpoints is a list. Each item is either a string or an object.

• A string is a URL or a host. The scheme is optional: "https://app.example.com:8443/login?next=1", "app.example.com".
• An object names the URL parts. Supported keys: protocol (string), host (string), port (integer), path (string), query (string), fragment (string).

"endpoints": [
    "app.example.com",
    "https://app.example.com:8443/login?next=1",
    {
        "protocol": "https",
        "host": "api.example.com",
        "port": 443,
        "path": "v1/users"
    }
]

Attached files#

files is a list of objects, each with a title (string) and data (the file’s contents, Base64-encoded). The files are attached to the finding.

The title must end in an extension the instance allows for uploads. By default these are .txt, .pdf, .json, .xml, .csv, .yml, .png, .jpeg, .sarif, .xlsx, .doc, .html, .js, .nessus, .zip and .fpr; administrators can change the list with the DD_FILE_UPLOAD_TYPES setting. A title with another extension (including .jpg) or no extension stops the import.

"files": [
    {
        "title": "login-screenshot.png",
        "data": "iVBORw0KGgoAAAANSUhEUgAABWgAAAK0CAIAAAARSkPJAAAAA3N<...>TkSuQmCC"
    }
]

Example JSON#

{
    "name": "Nightly scan",
    "type": "Tool1",
    "version": "1.2.0",
    "description": "Authenticated scan of the staging environment",
    "findings": [
        {
            "title": "SQL Injection in login form",
            "description": "The username parameter is concatenated into a SQL query.\n\nAn attacker can bypass authentication.",
            "severity": "High",
            "date": "2024-05-01",
            "cwe": 89,
            "cvssv3": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
            "cvssv4": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N",
            "mitigation": "Use parameterized queries.",
            "references": "https://owasp.org/Top10/A03_2021-Injection/",
            "param": "username",
            "payload": "' OR 1=1 --",
            "active": true,
            "verified": false,
            "unique_id_from_tool": "tool1-4f2a9c",
            "endpoints": [
                "https://app.example.com/login",
                {
                    "protocol": "https",
                    "host": "app.example.com",
                    "path": "admin/login"
                }
            ],
            "tags": ["security", "pci"]
        },
        {
            "title": "Hard-coded credentials",
            "description": "A database password is committed to source control.",
            "severity": "critical",
            "cwes": ["CWE-798", "CWE-259"],
            "file_path": "src/settings.py",
            "line": 42,
            "static_finding": true,
            "dynamic_finding": false,
            "vuln_id_from_tool": "generic.secrets.password",
            "effort_for_fixing": "Low"
        },
        {
            "title": "Backdoor in xz-utils",
            "description": "xz-utils 5.6.0 and 5.6.1 contain malicious code.",
            "severity": "Critical",
            "cve": "CVE-2024-3094",
            "vulnerability_ids": ["GHSA-rxwq-x6h5-x525"],
            "cvssv3": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
            "epss_score": 0.85,
            "epss_percentile": 0.99,
            "component_name": "xz-utils",
            "component_version": "5.6.0",
            "fix_available": true,
            "fix_version": "5.6.2",
            "known_exploited": true,
            "kev_date": "2024-04-01",
            "publish_date": "2024-03-29"
        },
        {
            "title": "Reflected XSS in search",
            "description": "The q parameter is echoed without encoding.",
            "severity": "Medium",
            "date": "2024-01-04T11:02:11Z",
            "cwe": 79,
            "is_mitigated": true,
            "mitigated": "2024-01-24T11:02:11Z",
            "endpoints": ["app.example.com/search"]
        }
    ]
}

Test Type naming#

The Test Type for a JSON import comes from the report’s type field. A CSV import always uses the Test Type Generic Findings Import.

Each distinct type creates its own Test Type. Because deduplication settings are looked up by Test Type name, you can set custom HASHCODE_FIELDS_PER_SCANNER or DEDUPLICATION_ALGORITHM_PER_PARSER entries for a generic tool by using the resulting name as the key, for example Tool1 Scan (Generic Findings Import).

When you reimport into an existing Test, the report’s type has to resolve to that Test’s Test Type (or to plain Generic Findings Import). Otherwise the reimport is rejected with a Test type mismatch error.

Sample Scan Data#

Sample Generic Findings Import scans can be found here.

Default Deduplication Hashcode Fields#

By default, DefectDojo identifies duplicate Findings using these hashcode fields:

• title
• cwe
• line
• file path
• description