Nullgap.dev Docs

Pentests

Reports

The three documents a pentest produces, exactly what the attestation letter states and does not state, and how to share or download a report.

When a pentest finishes, three reports are written for it: a full report, an executive summary and an attestation letter. A retest writes its own three.

#What you need first

  • Any member can open and download reports. An API key with the read scope can do the same.
  • Sharing a report by link, or switching sharing off, needs the admin or owner role, or an API key with the admin scope.

#Where to find them

  • On the pentest: the Reports tab.
  • Across all pentests: the Reports page, which lists Attestation letters and Pentest reports separately.
  • By API: GET /reports lists every report of the organisation, and GET /pentests/{id} includes that pentest's reports.
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reports"
[
  {
    "id": "rpt_7d1e4b9a0c52",
    "orgId": "org_2a6f0c81d3e9",
    "pentestId": "pen_4c1d9e7a2b60",
    "kind": "attestation",
    "title": "Attestation letter — acme/shop",
    "shareToken": null,
    "shared": false,
    "createdAt": "2026-11-16T14:02:11.000Z",
    "snapshotId": "rsn_5e2a8c1f9d47"
  }
]

The sample is abridged to one of the three reports.

#The three kinds

kindConsole labelFor whomWhat it holds
fullFull reportEngineers and security staffEverything: scope and method, every finding with its evidence, the threat model, dependency advisories, methodology and limitations
executiveExecutive summaryLeadership and auditorsThe overall posture, counts by severity, the top risks in business terms, remediation status
attestationAttestation letterCustomers, prospects and auditorsThat an assessment took place, its scope, and how many findings were reported and remain open. No finding is described.

#The full report

  • Cover: organisation, repository, revision, scope, lines of code, testing period, assessment id, and the number of findings by severity.
  • Scope and method: what was tested, what was not tested, and how to read each finding's status.
  • Summary of findings: a table by severity and triage state, then one line per finding.
  • Threat model: the application's threat model as it was used.
  • One section per finding: severity, assurance, triage state, location, weakness ids, confidence, description, the affected code, every evidence entry with the commands that were run and their output, the remediation advice, and the patch when a fix run produced one. Findings marked as false positives are included, with their triage note.
  • Appendix: dependency advisories: up to 200 published advisories against the packages the code pins. They are not findings and are not counted anywhere else in the report.
  • Appendix: methodology and limitations.

#Hardening notes and development files

Two kinds of result are handled by fixed rules before a report is written, so they do not crowd out the findings that matter:

  • Hardening notes. Hygiene remarks, such as a base image used by a moving tag, SHA-1 checksums for downloads, a response without Cache-Control, internal error text in a response or debug logging, are listed together in one finding titled Hardening notes with the number of items, at severity info. Every item keeps its title, location, weakness id and write-up inside that entry. A remark stays a finding of its own when it was rated high or critical, when proof reproduced it, when it also names a weakness that is not hygiene, or when it mentions a secret such as a password, key or token in the leaked text.
  • Development and example files. A finding located only in a development or example file (a Compose file for development or tests, examples/, samples/, demo/, docs/, hack/, scripts/dev*, .devcontainer/, test fixtures, *.example, *.sample) is kept with its severity capped at low and a note saying why. It keeps its original severity when a production Dockerfile, a deployment manifest or a CI job that deploys refers to the file.

#The executive summary

  • Overall posture: one paragraph. It says whether serious findings are still open.
  • Findings by severity: identified, and still open.
  • Top risks: up to five, open ones first, each with what it means for the business.
  • Remediation status and Retest status.
  • Scope: the folders, the line count, and whether a deployed instance was exercised.

Findings marked as false positives are left out of the executive summary.

#What the attestation letter states

The letter is one page. It states, and only states:

  • Who assessed what. That Nullgap performed a whitebox security assessment of the named repository, operated by your organisation, at the named revision, between the start and end dates of the pentest.
  • Scope. The folders in scope, or "Whole repository"; the number of lines of source code; and either that the assessment included dynamic testing of a deployed test instance, or that it was performed on source code and no deployed instance was exercised.
  • Method. That the source code was reviewed for exploitable weaknesses, and that each candidate issue was checked independently before being reported.
  • Results. How many findings the assessment reported, how many of them are open in your organisation's records, and a table of both figures by severity: critical, high, medium, low and info.
  • Where the detail is. That the detailed findings are in the full report for the assessment id, available from your organisation at its discretion.

#What it does not state

  • It does not describe any finding. No title, location, description or evidence appears in it.
  • It does not say the application is secure. In its own words: "An assessment cannot show that no weaknesses exist."
  • It is not a seal of approval. The letter's closing note says so about itself, and the letter makes no statement about conformance with any standard.
  • It does not cover anything outside the tested revision and scope. Later changes, code outside the stated scope, and your infrastructure and processes are named as not covered.
  • It does not count dependency advisories, because they are not findings.
  • It does not count findings marked as false positives. They are left out of both figures.
  • It does not say how each finding was checked. Proven and verified findings are counted together.
  • It does not say what one run covers. On a large codebase a single run examines the most exposed files in depth, not every file. See What one run covers. The letter gives the scope and the line count, not the number of files examined.

#The date and the open count

A report is a record. When a pentest finishes, everything its three reports are written from (the pentest, its findings with their triage state, the threat model) is copied and kept, and the reports are produced from that copy every time they are opened.

For the attestation letter this means:

  • The Issued date is the date the report was created, which is when the pentest finished.
  • The "open" figures are the triage state of the findings on that date. Fixing, accepting or dismissing a finding afterwards changes the finding in the console; it does not change a letter that was already issued.
  • A shared link shows the same record as the console does.

To get a letter that reflects fixes, run the retest. It is a new pentest with its own three reports, issued for the version with the fixes; the original reports stay as they were.

Two cases are stated at the top of the report itself:

  • Revised after researcher review. Where your agreement includes a review of each pentest finding by a Nullgap researcher, the reports are first issued when the pentest finishes and are revised once, when the last finding has been reviewed, so that they carry the reviewed severities and leave out what a researcher rejected. A revised report reads "Revised on" with the date, and its revisedAt is set. The version it replaces is not kept.
  • Issued before reports were kept as records. A report issued before this was introduced has no stored copy. It still opens, is written from the findings as they are today, and says so in its first line. Its snapshotId is absent or null.

An admin can give any report a public link.

  1. Open the pentest's Reports tab, or the Reports page.
  2. Switch on the share toggle on the report's row. The row then reads "anyone with the link can view it".
  3. Press Copy link and send the link.

By API:

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shared":true}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reports/rpt_7d1e4b9a0c52/share"

The answer is the report with shareToken set. The link is your console address followed by /share/reports/ and the token.

What to know about a shared link:

  • Anyone who has the link can read the report, without signing in. The token cannot be guessed, but the link can be forwarded. Share the attestation letter widely; think before sharing the full report, which contains the evidence for every finding.
  • The page asks search engines not to index it.
  • Sharing and unsharing are written to the audit log as report.shared and report.unshared.
  • Only admins and owners (and API keys with the admin scope) are given the link. Members and read-only keys see "shared": true with shareToken left null, and the console shows them a Shared badge without the copy button, so a person who leaves the organisation does not take a working link with them.

Switch the toggle off, or send {"shared":false} to the same address. shareToken becomes null and the link stops working at once: it answers 404 with "This link is not valid".

Sharing the report again creates a new link. The old one stays dead.

#Downloading the HTML

Each report is one self-contained HTML document: styles are inline, and it loads no scripts, images or fonts from anywhere.

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -o attestation.html \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reports/rpt_7d1e4b9a0c52/html"

In the console, Open shows the same document in a dialog.

The document is laid out for A4 paper. To get a PDF, open the HTML file in a browser and print it to PDF.

The download is the report as it is at that moment. Keep the file if you need a fixed record.

Nullgap documentation