Evidence for auditors
Hand an auditor, a customer or your own risk team a small set of files that answers three questions: what AI is in this code, what did the scan find, and what was accepted on purpose. And let them check that the files are the ones you produced, with nothing to install but Keryn itself.
Before you start
Section titled “Before you start”- The Keryn CLI (install) and the repository at the commit you want to attest. Scan a clean checkout of that commit, not your working tree.
- A policy and your accepted risks written down, if you have them: policies and suppressions. The audit trail is only as good as the reasons you wrote.
jqfor the inspection steps.
1. Produce the package
Section titled “1. Produce the package”One scan can write every format an auditor might ask for. Write them outside the scanned checkout:
keryn initkeryn scan . --policy .keryn/policy.yml --subject help-desk --revision "$(git rev-parse HEAD)" \ --json ../keryn-out/result.json --sarif ../keryn-out/keryn.sarif --aibom ../keryn-out/keryn.cdx.json --markdown ../keryn-out/summary.md \ --summary-by owasp_llm --quiet--subject and --revision put the name and the commit into the AI-BOM and the result, so the files say which code they describe. --summary-by owasp_llm groups findings by a framework, as a reading aid. keryn init is here only to get a starting policy.
The Markdown summary holds the sections an auditor reads first: the result, the changes against a base if you gave one, the findings, the waivers with owner, ticket, expiry and reason, and the coverage statement. How much of the rule library ran is never implied; it is printed:
grep "^\*\*Coverage" ../keryn-out/summary.md | sed -E 's/(/(/g; s/)/)/g; s/; 1 left out.*//'**Coverage:** 1598/1598 rules executed (0 unsupported, 0 partial, 0 timed out); 5 files scanned, 0 skipped; 2 absence findings collapsed into 12 repo-level findingsRules the engine could not run for a language are counted there and make the scan exit 3. An auditor should read that line before any finding.
2. Seal it in an evidence bundle
Section titled “2. Seal it in an evidence bundle”keryn bundle . --out ../keryn-out/evidence --timestamp 2026-11-07T09:00:00Zwrote evidence bundle -> ../keryn-out/evidence.bundle.jsonThe bundle is one JSON file that embeds the result, the SARIF, the CycloneDX AI-BOM and (when you scanned with one) the policy, and carries a SHA-256 for each, plus a content digest for every finding that is anchored to a place in the code. Use --timestamp now for a real creation time in a real attestation; the default is a fixed date so the same input gives the same bytes, and the example above pins one for the same reason.
jq -r '.SHA256SUMS | keys[]' ../keryn-out/evidence.bundle.jsonjq '{schemaVersion, exportMode, publicSafety}' ../keryn-out/evidence.bundle.jsoncoverage.jsoncyclonedx.jsonitems.jsonpolicy.jsonresult.jsonsarif.jsonsuppressions.jsonversions.json{ "schemaVersion": "seceng.evidence_bundle.v2", "exportMode": "internal", "publicSafety": { "containsSecrets": false, "safeToSharePublicly": false }}Read publicSafety before you share it. A bundle quotes the lines of code around each finding as evidence, so it is marked for internal use; it contains no secrets that Keryn recognised, and it says it is not safe to publish. Share it with the people who may see your code, under the terms you already have with them.
3. Check it
Section titled “3. Check it”The check recomputes every digest and exits 0 only when all of them match:
keryn verify-bundle ../keryn-out/evidence.bundle.jsonOK: 18 verified anchor(s), 2 unanchored, 0 digest mismatch(es)An anchor is a finding tied to a file and lines with a content digest. Unanchored entries are repo-level findings, such as an absence of a control, which have no single line to hash; they are covered by the digest of the document that lists them.
Now change one character, as someone editing the evidence would, and check again:
sed 's/gpt-4o/gpt-4o-mini/' ../keryn-out/evidence.bundle.json > ../keryn-out/edited.bundle.jsonkeryn verify-bundle ../keryn-out/edited.bundle.json > ../keryn-out/verdict.txt || truehead -1 ../keryn-out/verdict.txtFAIL: 13 verified anchor(s), 2 unanchored, 9 digest mismatch(es)The command exits 1 (|| true keeps this page’s test going), and the lines after the first, which the page leaves out, name each mismatching document. Any edit to an embedded document, to a quoted line or to a digest fails. The auditor needs only keryn verify-bundle: no account, no network, no trust in the person who sends the file.
4. What to hand over
Section titled “4. What to hand over”| File | Answers |
|---|---|
evidence.bundle.json |
Is this the scan you say it is? (keryn verify-bundle) |
keryn.cdx.json |
What AI is in the code: providers, models, agents, MCP servers, prompts. CycloneDX 1.6, readable by any SBOM tool. |
summary.md |
The result, the audit trail of waivers and the coverage line, in prose |
keryn.sarif |
The findings, with accepted ones kept and marked as suppressed with their justification |
the policy file and .keryn.yml |
The rules you held yourself to, and the accepted risks, in version control |
Archive them with the release: a pipeline that runs keryn bundle on every tag gives an auditor a bundle per release.
What you just proved
Section titled “What you just proved”An auditor cannot take your word for a security result, and should not have to. Here the claim travels with its own proof: the digests tie each finding to the code it quoted, the coverage line states what was not checked, the audit table shows who accepted what, and the check is something they run on their own machine. The boundary it defends is the one between your claim and their trust. What it does not defend is the scan itself: a bundle proves the file was not altered after it was written, not that the right code was scanned. Scan a clean checkout of a known commit and record the revision.
- Accept risks with a reason and an expiry: suppressions.
- Keep the evidence from every release: CI.
- Do it where nothing touches the internet: air-gapped use.
- Format details: formats.