Evidence integrity & auditability¶
Audit-ready evidence has three properties: it is traceable (every claim points at what it was verified against), structured (a machine can collect and diff it), and tamper-evident (you can tell when a file changed after it was produced). This page inventories what CodeNavi gives you for each — and, in the honesty section at the end, what it deliberately does not.
Everything below is produced and stored on your hardware. No evidence artifact leaves the box unless you move it.
Traceable — every claim cites the line it was verified against¶
- Compliance gap reports record one verdict per rule with
file:linecitations verified by reading the actual source — search hits alone are never cited. The header records the codebase revision the run was made against; re-runs diff against it and mark any carried verdict as carried, with its original date. - Search results carry
file:linecitations down to the chunk — the provenance of anything your agent tells you is one click away. - Investigation notes are anchored to the code they describe and automatically marked stale when the anchored code changes on reindex — a note can't silently outlive its evidence.1
- Scanner decisions name their cause: every quarantined file and retrieval-time flag is tagged with the rule ID and the secret-pattern version that fired, and allowlist entries require a written reason.
Structured — artifacts a machine can collect¶
All of these are plain files in the data and reports volumes — collect them into your SIEM or evidence locker as they are:
| Artifact | Where | What it records |
|---|---|---|
| Scan ledger | data/scan_history.json |
One row per file SHA-256: filename, first/last seen, passed/blocked, pattern version, report reference |
| Threat reports | reports/*.md |
Per-blocked-file: rules that fired, severity, confidence, matched samples (truncated), summary counts |
| Quarantine refs | data/quarantine/*.blocked |
Blocked path, file hash, report reference |
| Retrieval flags | reports/retrieval_flags.log |
Timestamped log of chunks blocked at retrieval time, with rule IDs |
| Query log | logs/queries.log |
What was asked of the index and what came back — summarized on demand by the search_analytics tool |
| Compliance reports | where you write them | Rule-by-rule verdicts with citations, summary rollup, revision header |
The Security screen is the console over the scanner artifacts; the files remain the source of truth. For the runtime side — Prometheus metrics, a Grafana dashboard, and container log collection — see Observability.
Tamper-evident — hashes at every layer¶
Evidence inputs are content-addressed. The scan ledger is keyed by each file's SHA-256, quarantine refs record the hash of the blocked file, wiki compile decisions key on document hashes, and note anchors are hashes of the anchored code. An evidence row is tied to the exact bytes it judged, not to a filename that may have changed since.
Evidence reports hash themselves (from release 1.3.23).2 Every report CodeNavi writes — scan threat reports, wiki block reports, and compliance gap reports produced by the bundled plugin — ends with a footer line containing the SHA-256 of everything above it:
<!-- report-sha256: 9f8a…c41d -->
Verify any report with standard tooling, no CodeNavi required:
head -n -1 report.md | sha256sum # must equal the hex in the footer
A report that fails this check was modified (or corrupted) after it was written. Record the footer hash in your audit trail at collection time and the file is pinned from that moment on.
The supply chain behind the evidence is signed. Release images and update manifests are cosign-signed and verified fail-closed by the installer and updater; update manifests pin every artifact by SHA-256 digest; a CycloneDX SBOM ships per release; license keys are signature-verified. The security features page has the mechanisms and the verification commands.
Pipeline health — catching stale data before it reaches a report¶
The data-quality layer runs before evidence is produced, not after:
- Index freshness is reported on every search response, and the compliance checker refuses to run a doomed pass — it checks freshness first and reindexes if the index is stale.
- Wiki pages carry a staleness badge when the docs they were compiled from have changed.
- Stored-index integrity is checked against a fingerprint recorded at the last reindex — row counts, Lance version and fragment layout of the tables, contents of the call-graph sidecar — after start-up and on a timer;
/healthreportsok,mismatchorunverifiedper codebase and thecodenavi_index_integritygauge carries it to your dashboards.3 A mismatch is a warning with the differences named, never a silent rebuild. - Note anchors are revalidated on every reindex; stale notes are flagged, not silently served.
- Scanner dry-run shows a persistent banner until you choose blocking mode — the UI never lets you mistake "tagging" for "enforcing".
- Query analytics surface zero-result queries and retry patterns, the early signal that an index and the questions being asked of it are drifting apart.
What this page does not claim¶
Integrity is not authenticity
The report footer detects modification and gives auditors a citable fingerprint. It is not a cryptographic signature — someone who can edit the file can recompute the hash. What is cryptographically signed today is the supply chain (images, update manifests, license keys), not individual report files. If your audit regime requires signed evidence artifacts, tell us — it is a roadmap conversation we want to have.
- No approval chains. CodeNavi produces evidence; it does not route it for sign-off. Feed the structured artifacts above into your GRC or ticketing system — approval workflows belong where your auditors already look.
- A gap analysis is not a certification. The compliance report says so on its face, and marks what a static check cannot decide as
cannot check from coderather than guessing.