Evidence Pack

The Evidence Pack is vybdocs' audit artifact. It is produced automatically on every passing vyb check run. It proves — cryptographically — that a specific set of code changes was evaluated against your constraint spec at a specific point in time, and that all constraints passed.

What the Evidence Pack contains

Each Evidence Pack consists of two files:

.vyb/evidence/
  2026-05-18T14-03-22Z.pdf    ← Human-readable audit report
  2026-05-18T14-03-22Z.json   ← Machine-readable signed payload

The PDF

The PDF is a formatted audit report designed to be presented to:

• SOC 2 auditors requesting evidence of technical controls
• EU AI Act compliance reviewers
• HIPAA Business Associate Agreement parties
• DORA operational resilience auditors
• Internal security teams

It includes:

• Project name, timestamp, git commit SHA, branch
• Full list of rules evaluated with pass/fail status
• Severity breakdown (block / warn / info)
• Per-framework compliance mapping table
• Ed25519 signature and verification instructions
• Chain link to the previous Evidence Pack (hash)

The JSON

The JSON payload is the authoritative data source. The PDF is rendered from it.

{
  "version": "1",
  "timestamp": "2026-05-18T14:03:22Z",
  "project": "acme-platform",
  "spec": {
    "path": ".vyb/spec.yaml",
    "sha256": "e3b0c44298fc..."
  },
  "diff": {
    "base": "origin/main",
    "head": "abc123def456",
    "sha256": "a948904f2f..."
  },
  "rules": [
    {
      "id": "sec-001",
      "name": "no-eval",
      "severity": "block",
      "status": "pass",
      "filesScanned": 12,
      "linesScanned": 847,
      "maps-to": [
        { "framework": "soc2", "control": "CC7.1" }
      ]
    }
  ],
  "summary": {
    "rulesEvaluated": 31,
    "violations": 0,
    "result": "pass"
  },
  "chain": {
    "previous": "2026-05-18T10-22-41Z.json",
    "previousSha256": "c98c24b677..."
  },
  "signature": {
    "algorithm": "Ed25519",
    "publicKey": "MCowBQYDK2V...",
    "value": "3d4a5b6c7d8e..."
  }
}

Hash chaining

Evidence Packs are hash-chained. Each pack's JSON payload includes the SHA-256 hash of the previous pack. This creates a tamper-evident chain:

Pack #1                Pack #2                Pack #3
┌────────────┐        ┌────────────┐        ┌────────────┐
│ timestamp  │        │ timestamp  │        │ timestamp  │
│ rules:pass │        │ rules:pass │        │ rules:pass │
│ chain:null │──hash──│ chain:#1   │──hash──│ chain:#2   │
│ sig        │        │ sig        │        │ sig        │
└────────────┘        └────────────┘        └────────────┘

If any pack in the chain is altered after the fact, the SHA-256 hash will not match, and the chain is broken. This is detectable by running:

vyb evidence --verify

Which checks every pack in .vyb/evidence/ for chain integrity and signature validity.

Ed25519 signatures

Each Evidence Pack JSON is signed with an Ed25519 keypair. The private key is:

• Generated locally on first vyb check run, or
• Provided by your organization (Pro/Business plans support custom key injection)

The public key is embedded in the JSON payload. Anyone with the public key can verify the signature:

vyb evidence --verify --pack .vyb/evidence/2026-05-18T14-03-22Z.json

Output:

Signature: VALID
Chain:     INTACT (12 packs, no gaps)
Rules:     31 evaluated, 0 violations

Compliance value

SOC 2 Type II
Evidence Packs cover the continuous monitoring requirement — a signed record for every PR mergedEU AI Act Art. 12
Record-keeping obligation for high-risk AI systems — automatically satisfied for every AI-assisted commitHIPAA §164.312(b)
Audit controls requirement — log of all constraint evaluations touching PHI-adjacent codeDORA Art. 9
ICT risk management — documented evidence of automated code quality controls

Retention

Evidence Packs should be retained according to your compliance requirements:

Framework	Recommended retention
SOC 2	1 year
EU AI Act	Duration of system deployment + 10 years
HIPAA	6 years
DORA	5 years

Store packs in a compliant location: AWS S3 with Object Lock, Azure Blob with immutability, or an on-premise archival system.

---

Next: PDF Format