Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Evidence for auditors

    View as Markdown

    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.

    • 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.
    • jq for the inspection steps.

    One scan can write every format an auditor might ask for. Write them outside the scanned checkout:

    Terminal window
    keryn init
    keryn 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:

    Terminal window
    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 findings

    Rules 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.

    Terminal window
    keryn bundle . --out ../keryn-out/evidence --timestamp 2026-11-07T09:00:00Z
    wrote evidence bundle -> ../keryn-out/evidence.bundle.json

    The 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.

    Terminal window
    jq -r '.SHA256SUMS | keys[]' ../keryn-out/evidence.bundle.json
    jq '{schemaVersion, exportMode, publicSafety}' ../keryn-out/evidence.bundle.json
    coverage.json
    cyclonedx.json
    items.json
    policy.json
    result.json
    sarif.json
    suppressions.json
    versions.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.

    The check recomputes every digest and exits 0 only when all of them match:

    Terminal window
    keryn verify-bundle ../keryn-out/evidence.bundle.json
    OK: 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:

    Terminal window
    sed 's/gpt-4o/gpt-4o-mini/' ../keryn-out/evidence.bundle.json > ../keryn-out/edited.bundle.json
    keryn verify-bundle ../keryn-out/edited.bundle.json > ../keryn-out/verdict.txt || true
    head -1 ../keryn-out/verdict.txt
    FAIL: 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.

    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.

    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.