Spec

Evidence Pack v0

The evidence pack is Surety's central artifact. Every governed task or PR produces one. It is a schema-versioned, content-hashed, optionally Sigstore-signed JSON document that composes existing standards rather than inventing a new one.

Top-level fields

• schema_version — surety-evidence-pack-v0
• evidence_pack_id — ULID
• generated_at — RFC 3339 UTC timestamp
• repository — provider, owner, name, base/head SHA, PR
• task — id, source, objective, risk tier, mode, acceptance criteria
• provenance — author type, declared agent, observed signals, confidence score
• runtime — runtime type, image, workspace, network/secret policy, allowed/forbidden paths
• executor — type, version, model provider/name/version, cost, duration
• plan — task plan and budget caps
• changes — file change manifest, additions/deletions, sensitive paths
• commands — command log with start, exit, duration
• tests — typecheck, unit, integration results
• scanners — secrets, dependency vulns, SAST, SBOM, with maturity labels
• policy — policy hash, mode, verdict, gate results, missing evidence
• approvals — identity, role, decision, timestamp, signature
• waivers — control id, reason, expiry, signature, scope
• artifacts — content-addressed artifact index
• outcomes — PR, merge commit, deployment, CI, incident, rollback links
• signatures — Sigstore bundle and payload hashes

Standards mapping

• in-toto / SLSA — provenance, build/run attestation patterns
• SARIF — scanner findings, native attached as artifacts
• CycloneDX — SBOM section
• Sigstore — signing patterns for the pack and per-artifact signatures

Validation

surety evidence validate path/to/evidence-pack.json

The validator runs offline, requires no network, and reports missing required fields with remediation hints.

Rendering

surety evidence render path/to/evidence-pack.json --format md > evidence.md

Renders to Markdown, HTML, or a concise PR comment template. Output is deterministic for the same input.