Nullgap.dev Docs

Findings

Evidence bundles

Download everything that backs one finding as a single document, understand each part, and recompute its SHA-256 to show it has not been altered.

An evidence bundle is everything that backs one finding in one document: the finding, how far it was checked, the reasoning, the proof when there is one, the patch, and how the code was processed. It carries a SHA-256 of its own contents, so you can show later that the copy you kept has not been altered.

Use it to hand a finding to an auditor, attach it to a ticket, or keep a record outside Nullgap.

#Getting a bundle

Any member can download a bundle, and so can an API key with the read scope.

In the console, open the finding and go to Evidence bundle. Press Download JSON or Download Markdown.

By API:

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -o bundle.json \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/evidence"

Add ?format=md for the Markdown form.

A bundle is built when you ask for it, from the finding as it is at that moment. It is not stored by Nullgap. Two downloads of the same finding are two bundles, each with its own generatedAt and so its own sha256.

#The parts

The schema is nullgap.evidence/1.

{
  "schema": "nullgap.evidence/1",
  "generatedAt": "2026-11-16T15:20:04.512Z",
  "finding": {
    "id": "fnd_8f3a2c9d1b4e",
    "title": "SQL injection in order lookup",
    "severity": "high",
    "cwe": ["CWE-89"],
    "description": "The order id from the URL is concatenated into the query.",
    "remediation": "Pass the id as a query parameter instead of building the statement from it.",
    "location": { "file": "src/orders.js", "startLine": 42, "snippet": "return db.query(\"SELECT * FROM orders WHERE id = \" + id);" },
    "repository": "acme/shop",
    "source": "pentest",
    "pullRequest": null,
    "state": "open",
    "stateReason": null,
    "firstSeenAt": "2026-11-16T14:01:58.000Z",
    "resolvedAt": null,
    "resolvedInSha": null
  },
  "assurance": {
    "level": "proven",
    "statement": "A probe was run against this code in an isolated sandbox and reproduced the flaw. The command, its output and the probe files are in the Proof section."
  },
  "evidence": [
    { "kind": "reasoning", "summary": "Path reported by the finder (unverified)", "detail": "GET /orders/:id -> getOrder -> db.query" },
    { "kind": "verification", "summary": "Independent review (Nullgap AI) could not refute it", "detail": "The id reaches the query unchanged." },
    { "kind": "probe", "summary": "Probe reproduced the vulnerability", "detail": null }
  ],
  "proof": {
    "command": "node .nullgap-probe/probe.js",
    "exitCode": 0,
    "output": "VULNERABLE: 3 rows returned for id \"1 OR 1=1\"",
    "files": "--- .nullgap-probe/probe.js\n..."
  },
  "patch": null,
  "run": {
    "id": "pen_4c1d9e7a2b60",
    "kind": "pentest",
    "commit": "main",
    "finishedAt": "2026-11-16T14:02:11.000Z",
    "privacy": { "zeroRetention": true, "identifiersMasked": 12 }
  },
  "notes": [],
  "sha256": "9f2b6c1d0e7a4f3b8c5d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b"
}

The sample is illustrative: its sha256 is not the real hash of the text shown.

PartContent
schemaAlways nullgap.evidence/1.
generatedAtWhen this bundle was built.
findingThe finding: id, title, severity, cwe, description, remediation, location, repository, source (review or pentest), pullRequest, and its triage record: state, stateReason, firstSeenAt, resolvedAt, resolvedInSha.
assurancelevel is proven, verified or unverified. statement says in a sentence or two what that level means for this finding.
evidenceEvery evidence entry of the finding, in order: kind, summary, detail. For probe entries detail is null: the probe's material is under proof.
proofOnly when the finding is proven and a sandbox probe is on record: the command that was run, its exitCode, its output, and files, the probe's own source. Otherwise null.
patchWhen a fix run wrote one: diff, verified and description. Otherwise null.
runThe run that first reported the finding: id, kind, commit, finishedAt, and privacy. null when that run is no longer stored.
notesThe notes on the finding, oldest first.
sha256The hash of everything above.

Details worth knowing:

  • assurance.statement is explicit about what was not done. For a verified finding it says that the finding was not reproduced by running a probe, and for an unverified one that it should be treated as a lead to confirm.
  • proof is about the sandbox. A finding proven only against a running deployment has proof: null. Its demonstration is in the evidence entry of kind dynamic, whose detail holds the requests and the outcome of the live proof standard.
  • run.commit is the head commit for a pull request review. For a pentest it is the version the pentest was started with, which is a branch name if you gave a branch.
  • run.privacy records how the AI processing of that run was protected: zeroRetention is true when every AI call in the run was confirmed as zero data retention, and identifiersMasked counts identifiers that were swapped for synthetic values before the AI saw them. See AI processing. It is null for a run that made no AI call.
  • What is not in a bundle: the priority and exposure facts, the sightings, the fingerprint, and anything about which AI model answered or what the run used. For the complete record, use GET /findings/{id} or a JSON export.

#The sha256

sha256 is the SHA-256, in lower-case hexadecimal, of the bundle's canonical JSON with the sha256 field itself removed.

Canonical JSON means:

  • object keys sorted, at every level;
  • no whitespace between tokens;
  • strings, numbers, true, false and null written as standard JSON, with non-ASCII characters left as they are (not escaped) and the result encoded as UTF-8;
  • arrays kept in their order.

#What the hash does and does not show

The hash shows that a bundle has not changed since it was generated. If one character of the description, the proof output or the state is edited, the recomputed hash no longer matches.

It is a checksum, not a signature. Someone who alters a bundle can also recompute the hash and replace it. Nullgap does not keep a copy of the hashes it has issued. So, to rely on a bundle later:

  1. Download it.
  2. Record its sha256 somewhere the bundle's holder cannot change: your ticket system, a signed commit, your own evidence store.
  3. Later, recompute the hash of the file and compare it with the value you recorded.

#Recomputing it with Node.js

Save as verify-bundle.mjs and run node verify-bundle.mjs bundle.json.

import { createHash } from 'node:crypto';
import { readFileSync } from 'node:fs';

function canonical(value) {
  if (value === null || typeof value !== 'object') return JSON.stringify(value);
  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonical(value[k])}`).join(',')}}`;
}

const { sha256, ...rest } = JSON.parse(readFileSync(process.argv[2], 'utf8'));
const computed = createHash('sha256').update(canonical(rest)).digest('hex');
console.log(computed === sha256 ? `OK ${computed}` : `MISMATCH: the bundle says ${sha256}, computed ${computed}`);
process.exit(computed === sha256 ? 0 : 1);

#Recomputing it with Python

Save as verify_bundle.py and run python3 verify_bundle.py bundle.json.

import hashlib
import json
import sys

with open(sys.argv[1], encoding="utf-8") as f:
    bundle = json.load(f)

claimed = bundle.pop("sha256")
canonical = json.dumps(bundle, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
computed = hashlib.sha256(canonical.encode("utf-8")).hexdigest()

print(f"OK {computed}" if computed == claimed else f"MISMATCH: the bundle says {claimed}, computed {computed}")
sys.exit(0 if computed == claimed else 1)

Both programs print OK and the hash, and exit with status 0, when the bundle is unaltered. They exit with status 1 on a mismatch.

Three things that cause a false mismatch:

  • Hashing the file's bytes. The hash is over the canonical form, not over the file as saved. The console saves the JSON indented, and curl saves it compact; both verify, because both are parsed first.
  • ensure_ascii. In Python it must be False. The default escapes non-ASCII characters, which changes the text that is hashed.
  • A tool that rewrote the file. An editor or a formatter that changes a number's form, or drops a null, changes the hash. That is the hash doing its job.

#The Markdown form

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -o evidence.md \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/evidence?format=md"

The same bundle as a readable document, sent as text/markdown with the file name nullgap-evidence-<finding id>.md. Its sections:

SectionContent
Title and assurance"Evidence:" and the title, then the level in capitals with what it means, and the statement
FindingReference, severity, weakness, repository, where it was found, location, state and reason, first seen, the description, the flagged line, and the recommended fix
Evidence chainEach evidence entry, numbered, with its detail
ProofThe command, exit code, output and probe files; or a sentence in bold saying the finding was not reproduced
PatchWhen there is one: verified or not, the description and the diff
How the code was processedThe run, its commit, and the privacy record
NotesWhen there are any
IntegrityWhen it was generated, and the SHA-256 of the JSON bundle

Use the Markdown form for reading and the JSON form for record-keeping:

  • Long passages are shortened in the Markdown: the description, each evidence detail, the proof output, the probe files and the diff each have a maximum length. The JSON is complete.
  • The hash printed under Integrity is the hash of the JSON bundle built for that same request. It cannot be recomputed from the Markdown file, and a JSON bundle you download separately has a different generatedAt and therefore a different hash. If you need a Markdown document and a verifiable record, keep the JSON and record its hash.

Text from the finding is escaped in the Markdown and code is fenced, so the file is safe to render.

Nullgap documentation