Nullgap.dev Docs

Findings

Exports

Export findings as CSV, JSON or SARIF, with the same filters as the findings list, and upload SARIF to a code host.

An export is every finding that matches your filters, in one file. CSV is for spreadsheets, JSON is the full records, and SARIF is for code-scanning tools.

#Who may export

WhereWho
The consoleAdmins and owners. Members do not see the Export menu, and the request is refused for them with 403 forbidden.
The APIAny API key of the organisation, whatever its scope. Reading findings is what a read key is for.

Every export is written to the audit log as findings.exported, with the format.

#In the console

  1. Open Findings.
  2. Set the filters: state, priority, severity, source, repository, and the search box.
  3. Press Export and choose CSV, JSON or SARIF.

The export holds every finding that matches the filters, not only the page you are looking at.

#By API

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -o findings.csv \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/export?format=csv&state=open&severity=high"

The answer is the file itself, sent as an attachment and streamed, so a large organisation's export does not have to fit in memory on either side.

formatContent typeFile name
csv (the default)text/csvnullgap-<organisation>-findings.csv
jsonapplication/jsonnullgap-<organisation>-findings.json
sarifapplication/sarif+jsonnullgap-<organisation>-findings.sarif

#Filters

The filters are the same as on the findings list. There is no paging: an export is always complete.

QueryValuesDefault
stateopen, patched, accepted_risk, false_positive, allall
severitycritical, high, medium, low, infoAny
priorityP0, P1, P2, P3Any
sourcereview, pentestAny
repoIdA repository idEvery repository
qText, matched without regard to case against the title, the rule, the file, the repository name and the weakness idsNone
sortseverity (most severe first), priority (most urgent first)severity

A format, severity, priority or sort that is not one of its values is refused with 400 bad_request.

Findings that were held back because of an earlier decision are not findings and are not in any export. See Memory of dismissals.

#CSV

One header row, then one row per finding. Rows end with a carriage return and a line feed. There are 18 columns, always in this order.

ColumnContent
idThe finding id
severitycritical, high, medium, low or info
stateopen, patched, accepted_risk or false_positive
assuranceproven, verified or unverified
titleThe finding's title
weaknessThe weakness ids, such as CWE-89, separated by spaces
repositoryThe repository, as owner/name
sourcereview or pentest: the kind of run that first reported it
pull_requestThe pull request number, for a finding from a review
fileThe file of the flagged code. For a dependency finding, the manifest or lockfile.
lineThe first flagged line
first_seenWhen the finding was first reported, as an ISO date and time
resolved_atWhen it left the open state
resolved_inThe commit in which the flagged code was no longer present, when a review closed it
state_reasonThe reason given for the state
decided_byWho set the state
fix_pull_requestThe address of the fix pull request, when a fix run opened one
issueThe address of the linked Jira or Linear issue
fix_provenWhat the pull request in fix_pull_request is: yes for a fix proven by reproducing the flaw, no for a fix proposed without proof. Empty when there is none.

Two things to know when you open the file in a spreadsheet:

  • A cell that contains a comma, a quotation mark or a line break is wrapped in quotation marks, with quotation marks inside it doubled.
  • A cell whose text starts with =, +, -, @, a tab or a carriage return has a single quote put in front of it. This stops a spreadsheet from running a title or a reason as a formula. Strip the leading quote if you process the file with a program.

The description, the evidence and the patch are not in the CSV. Use JSON for those.

#JSON

One object with the time of the export and the findings.

{
  "exportedAt": "2026-11-16T15:20:04.512Z",
  "findings": [
    {
      "id": "fnd_8f3a2c9d1b4e",
      "repoFullName": "acme/shop",
      "source": "pentest",
      "state": "open",
      "priority": { "level": "P0", "fromSeverity": "P1", "proven": true, "reasons": ["Severity high gives P1."] },
      "finding": { "title": "SQL injection in order lookup", "severity": "high", "status": "proven", "cwe": ["CWE-89"] }
    }
  ]
}

The sample is abridged. Each entry of findings is the whole record, exactly as GET /findings/{id} returns it: the description, every evidence entry, the proof record, the patch, the sightings and the notes. The fields are described on Reading a finding.

The file can be large, because evidence includes command output and probe files. For one finding in a form whose integrity can be checked later, use an evidence bundle.

#SARIF

SARIF version 2.1.0, with one run.

{
  "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
  "version": "2.1.0",
  "runs": [
    {
      "tool": { "driver": { "name": "Nullgap", "rules": [
        { "id": "pentest/injection/sql-injection", "shortDescription": { "text": "SQL injection in order lookup" },
          "properties": { "tags": ["security", "CWE-89"], "security-severity": "8.0" } }
      ] } },
      "results": [
        {
          "ruleId": "pentest/injection/sql-injection",
          "level": "error",
          "message": { "text": "SQL injection in order lookup\n\nThe order id from the URL is concatenated into the query." },
          "locations": [ { "physicalLocation": { "artifactLocation": { "uri": "src/orders.js" }, "region": { "startLine": 42 } } } ],
          "partialFingerprints": { "nullgapFingerprint": "5c0e9a7d2b1f48a6c3d0e7f1" },
          "properties": { "findingId": "fnd_8f3a2c9d1b4e", "state": "open", "assurance": "proven", "repository": "acme/shop", "pullRequest": null }
        }
      ]
    }
  ]
}

The sample is abridged.

#Rules

tool.driver.rules has one entry per rule id that appears in the results. Each has id, name, shortDescription, fullDescription, help, and properties with:

  • tags: security, then the finding's weakness and CVE ids;
  • security-severity: a number as text, from the severity.

When several findings share a rule id, the first one in the export supplies the rule's descriptions.

#Results

FieldContent
ruleIdThe finding's rule id
levelFrom the severity. See the table below.
message.textThe title, a blank line, the description, and the remediation after "Fix:" when there is one
locations[0].physicalLocation.artifactLocation.uriThe file, relative to the repository root. For a dependency finding, the manifest.
locations[0].physicalLocation.regionstartLine, and endLine when the finding spans lines
partialFingerprints.nullgapFingerprintThe finding's fingerprint
propertiesfindingId, state, assurance, repository, pullRequest, and the engine's status, confidence, source and module
suppressionsOnly on dismissed findings. See below.
Severitylevelsecurity-severity
Criticalerror9.5
Higherror8.0
Mediumwarning5.5
Lownote3.0
Infonote1.0

#Dismissed and fixed findings

A finding in the state false_positive or accepted_risk is still exported, marked as suppressed:

{ "suppressions": [ { "kind": "external", "status": "accepted", "justification": "The id is cast to an integer in parseOrderId." } ] }

justification is the reason your team gave. A tool that understands SARIF suppressions shows the result as dismissed.

A patched finding has no suppression. It is exported as an ordinary result, with properties.state set to patched. If you upload the file to a tool that treats every unsuppressed result as an open alert, export with state=open.

#Uploading SARIF to a code host

Most code hosts can show SARIF results next to the code. Two rules make an upload useful:

  • One repository per file. Paths in the export are relative to each finding's own repository. Filter with repoId, or the tool cannot place the results.
  • Open findings only, unless the tool handles suppressions and you want fixed findings shown: add state=open.

As an example, this GitHub Actions job uploads the open findings of one repository to GitHub code scanning. It expects NULLGAP_URL, NULLGAP_ORG and NULLGAP_API_KEY as repository secrets or variables, and the job needs the security-events: write permission.

jobs:
  nullgap-sarif:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    env:
      NULLGAP_URL: ${{ vars.NULLGAP_URL }}
      NULLGAP_ORG: ${{ vars.NULLGAP_ORG }}
      NULLGAP_API_KEY: ${{ secrets.NULLGAP_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Export open findings
        run: |
          curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
            -o nullgap.sarif \
            "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/export?format=sarif&state=open&repoId=repo_5b2e8a1c9d3f"
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: nullgap.sarif

Use a key with the read scope for this. The results appear under the tool name "Nullgap".

Other code hosts and dashboards that import SARIF 2.1.0 take the same file. See your tool's documentation for how to upload.

Nullgap documentation