audit-labs/audit-labs.dev
The website for Audit Labs.
clone: git clone https://gitbay.org/audit-labs/audit-labs.dev.git
main: evidence-seal/index.html · raw
1<!DOCTYPE html>
2<html lang="en">
3<head>
4 <meta charset="UTF-8">
5 <meta name="viewport" content="width=device-width, initial-scale=1.0">
6 <title>evidence-seal | Audit Labs</title>
7 <meta name="description" content="Tamper-evident seals and chain of custody for audit evidence. SHA-256 Merkle manifests, seal chaining, optional ed25519 signing and RFC 3161 timestamping.">
8 <link rel="preconnect" href="https://fonts.googleapis.com">
9 <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;700&family=DM+Serif+Display:ital@0;1&family=DM+Sans:wght@400;500;600&display=swap" rel="stylesheet">
10 <link rel="stylesheet" href="../assets/site.css">
11</head>
12<body>
13
14<nav>
15 <div class="nav-inner">
16 <a href="/" class="logo">AUDIT<span>LABS</span></a>
17 <ul class="nav-links">
18 <li><a href="https://github.com/audit-labs/evidence-seal" class="btn-github">View on GitHub →</a></li>
19 </ul>
20 </div>
21</nav>
22
23<header class="hero split">
24 <div class="hero-inner">
25 <div>
26 <div class="crumb"><a href="/">Audit Labs</a> / evidence-seal</div>
27 <h1>Prove your evidence<br><em>hasn’t changed.</em></h1>
28 <p class="hero-desc">
29 A command-line tool that seals a directory of audit evidence into a tamper-evident
30 manifest. Later, it proves the package is byte-for-byte what was collected — and
31 names anything that moved. Signing and trusted timestamps prove <em>who</em> and <em>when</em>.
32 </p>
33 <div class="hero-actions">
34 <a href="https://github.com/audit-labs/evidence-seal" class="btn-primary">View on GitHub</a>
35 <a href="#install" class="btn-secondary">Install & quickstart</a>
36 </div>
37 </div>
38 <div class="terminal">
39 <div class="terminal-bar"><div class="dot dot-red"></div><div class="dot dot-yellow"></div><div class="dot dot-green"></div></div>
40 <div class="terminal-body">
41 <span class="t-comment"># Seal an evidence package</span><br>
42 <span class="t-prompt">$</span> <span class="t-cmd">evidence-seal seal ./aws_audit_prod_2026-08</span><br>
43 <span class="t-out"> sealed 8 files</span><br>
44 <span class="t-out"> root </span><span class="t-hash">1265ef6f…</span><span class="t-out"> id </span><span class="t-hash">d096c7ed…</span><br>
45 <span class="t-dim">──────────────────────────────</span><br>
46 <span class="t-comment"># Months later — prove nothing changed</span><br>
47 <span class="t-prompt">$</span> <span class="t-cmd">evidence-seal verify ./aws_audit_prod_2026-08</span><br>
48 <span class="t-out"> ✓ intact — 8 files match the seal</span><br>
49 <span class="t-comment"># One byte edited after the fact?</span><br>
50 <span class="t-prompt">$</span> <span class="t-cmd">evidence-seal verify ./aws_audit_prod_2026-08</span><br>
51 <span class="t-bad"> ✗ TAMPERED — MODIFIED iam_users.csv</span>
52 </div>
53 </div>
54 </div>
55</header>
56
57<section>
58 <div class="section-inner">
59 <div class="eyebrow">Three guarantees</div>
60 <h2>Integrity, custody, and proof of origin.</h2>
61 <p class="lede">Each layer is optional and composes with the others — the core needs no dependencies at all.</p>
62 <div class="guarantees">
63 <div class="card">
64 <div class="num">01 · INTEGRITY</div>
65 <h3>Nothing changed</h3>
66 <p>Every file is hashed with SHA-256 and folded into a single Merkle <span class="mono">root</span>. Any change to any file, name, or byte flips the root — and <span class="mono">verify</span> names exactly what was modified, added, or removed.</p>
67 </div>
68 <div class="card">
69 <div class="num">02 · CHAIN OF CUSTODY</div>
70 <h3>In order, unbroken</h3>
71 <p>Seal each new package against the last and every manifest links to the previous by hash. A reordered, missing, or spliced-out link is detectable — an append-only history of a package over time.</p>
72 </div>
73 <div class="card">
74 <div class="num">03 · ATTRIBUTION & TIME</div>
75 <h3>Who and when</h3>
76 <p>Sign a seal with an <span class="mono">ed25519</span> key to attest who collected it. Add an <span class="mono">RFC 3161</span> timestamp from an independent authority to prove it existed by a certain time — not backdated.</p>
77 </div>
78 </div>
79 </div>
80</section>
81
82<section class="cmds">
83 <div class="section-inner">
84 <div class="eyebrow">The commands</div>
85 <h2>Five verbs, one contract.</h2>
86 <p class="lede">Every command exits <span class="mono">0</span> when all is well, <span class="mono">1</span> on tamper, and <span class="mono">2</span> on a usage error — so a pipeline can gate on the difference.</p>
87 <div class="cmd-list">
88 <div class="cmd-row"><div class="cmd-name">seal</div><div class="cmd-desc">Hash a directory into a canonical <span class="mono">manifest.json</span> — with provenance metadata, ignore globs, and an optional <span class="mono">--prev</span> link for chaining.</div></div>
89 <div class="cmd-row"><div class="cmd-name">verify</div><div class="cmd-desc">Recompute and compare. Reports every <span class="mono">MODIFIED</span>, <span class="mono">ADDED</span>, and <span class="mono">REMOVED</span> file, and catches a doctored manifest itself.</div></div>
90 <div class="cmd-row"><div class="cmd-name">chain</div><div class="cmd-desc">Verify a sequence of seals links oldest → newest, catching reordering or a removed link.</div></div>
91 <div class="cmd-row"><div class="cmd-name">sign</div><div class="cmd-desc">Attach an <span class="mono">ed25519</span> signature; <span class="mono">verify --pubkey</span> requires a named signer, proving identity, not just integrity.</div></div>
92 <div class="cmd-row"><div class="cmd-name">timestamp</div><div class="cmd-desc">Request, submit, apply, and verify an <span class="mono">RFC 3161</span> token — with <span class="mono">--tsa-cert</span> for full CMS signature verification.</div></div>
93 </div>
94 </div>
95</section>
96
97<section class="install" id="install">
98 <div class="section-inner">
99 <div class="eyebrow">Get started</div>
100 <h2>Install & quickstart.</h2>
101 <div class="install-grid">
102 <div>
103 <pre><span class="c"># Core is pure standard library.</span>
104<span class="c"># Extras add signing + timestamping:</span>
105pip install <span class="p">"evidence-seal[sign,timestamp]"</span>
106
107<span class="c"># Seal, then verify</span>
108evidence-seal seal ./evidence
109evidence-seal verify ./evidence</pre>
110 <div class="badges">
111 <span class="badge">Python 3.10+</span>
112 <span class="badge">GPL-3.0</span>
113 <span class="badge">stdlib core · 0 deps</span>
114 <span class="badge">SHA-256 · Merkle</span>
115 </div>
116 </div>
117 <div>
118 <p class="lede">The exit-code contract, at a glance:</p>
119 <div class="exit">
120 <div class="e"><span class="code g">0</span><span>Intact / valid — the package matches its seal.</span></div>
121 <div class="e"><span class="code r">1</span><span>Tamper detected, chain broken, or an invalid signature.</span></div>
122 <div class="e"><span class="code a">2</span><span>Usage error, or an optional dependency isn’t installed.</span></div>
123 </div>
124 <p class="lede" style="margin-top:1.4rem; font-size:.9rem;">
125 Distinguishing <span class="mono">1</span> from <span class="mono">2</span> lets CI separate
126 “the evidence was tampered with” from “the job is misconfigured.”
127 </p>
128 </div>
129 </div>
130 </div>
131</section>
132
133<footer>
134 <div class="footer-inner">
135 <div class="footer-left">
136 <a href="/" class="footer-logo">AUDIT<span>LABS</span></a>
137 <p>© 2026 Audit Labs — a two-person team building for the community.</p>
138 </div>
139 <div class="footer-links">
140 <a href="/">Home</a>
141 <a href="https://github.com/audit-labs">GitHub</a>
142 </div>
143 </div>
144</footer>
145
146</body>
147</html>