evidence
Export, verify and replay a versioned evidence bundle for a stored audit
An audit keeps its findings, but the crawl behind them is pruned over time, and fetching the site again later is a different observation: the page may have changed or gone. The evidence command writes one stored audit to a directory that stands on its own, so you can check a finding months later without the site or the crawl store.
The command reads what the audit already stored. It fetches nothing and costs no credits.
Usage
squirrel evidence export -o <dir> [--crawl <id>] [--shareable]
squirrel evidence verify <dir>
squirrel evidence replay <dir> [--json]export
| Option | Alias | Description | Default |
|---|---|---|---|
--output | -o | Directory to write. It must not exist or must be empty | required |
--crawl | Audit ID (or prefix) to export | latest audit | |
--shareable | Redact credentials, cookies, account data and sensitive URL parameters | false |
Export is opt-in and never overwrites. It verifies the bundle it just wrote and exits 1 if that fails. An audit that was already retired has no findings left to archive and is refused.
Raw and shareable bundles
| Kind | Contents | Permissions |
|---|---|---|
| raw (default) | Exactly what the site sent: response bodies, headers, cookies, URLs. Restricted: it can hold credentials and account data | directory 0700, files 0600, with a README.txt warning |
shareable (--shareable) | Every file passes through redaction on the way out: every artifact body, and every string and key in every JSON file. Only exporter-made fields (hashes, artifact paths, enums, format markers, the crawl id) are exempt | normal |
Shareable redaction covers cookie and authorization headers and any other value whose key names a credential (in headers, rule observations or configuration), credential-looking query parameters (token, key, password, session, email and similar), URL userinfo (including URLs inside other header values such as Location, Link and Refresh), JWTs, provider API keys, bearer tokens, email addresses, CSRF meta tags, hidden token inputs, credential assignments in scripts, and header lines quoted as plain text inside a body or a message. In a header map, a header is a credential when its name (trimmed, any case, _ read as -) is on that list or contains token, secret, session, auth, key, cookie, jwt, signature, credential or password, so X-Goog-Api-Key, Private-Token and CF-Access-Client-Secret are blanked too. The exact list also names well-known credential headers that have no X-, CF- or Private- prefix: API-Key, APIKey, Ocp-Apim-Subscription-Key, Auth-Token, Access-Token, ID-Token, Refresh-Token, Session-ID, Session-Token, Secret-Key, Client-Secret and Authentication. A few names that contain one of those words but carry no secret keep their values: Access-Control-Allow-Credentials, Public-Key-Pins, Public-Key-Pins-Report-Only and the HTTP/2 :authority pseudo-header.
A header line is recognised for every credential header (Cookie, Set-Cookie, Authorization, X-API-Key, API-Key, Session-ID and the rest, plus any X-, CF- or Private- name containing one of the words above) in any case, with - or _ in the name and an optional CGI HTTP_ prefix. The separator is :, =, => or ->. The name may be wrapped in quotes or backticks, escaped quotes (\", JSON inside a JSON string), HTML entities (", ", ') or print_r brackets. Examples: Cookie: sid=..., {"Authorization": "Token ..."}, HTTP_COOKIE=..., [HTTP_COOKIE] => ..., {"Authorization": "Basic ..."}. A quoted value is redacted to its closing quote, where an escaped quote does not close it, but only when that quote ends the line (and the next line is not a folded continuation) or is followed by , } or ]. Otherwise the value runs to the end of the line, plus up to 16 folded continuation lines that start with a space or tab. When nothing follows the separator on its line (Cookie: then sid=... on the next line), the whole next line is the value, whatever it starts with, plus its folded continuation lines. Each line of an unquoted value is capped at 16 KB, so x.cookie=... in a minified script removes at most 16 KB of that line, not the whole file.
Not recognised (stated limits): header names and values in separate cells of HTML or Markdown tables (<td>HTTP_COOKIE</td><td>...</td> on phpinfo, Django and Symfony debug pages, or | Cookie | sid=... |), a blank line between a header name and its value (Cookie: then an empty line, then sid=...), a lone CR (\r with no \n) as the line break, header names with no credential word (X-Pass, X-Otp, X-Sig, X-CSRF, X-XSRF and similar: only the exact list and the words token, secret, session, auth, key, cookie, jwt, signature, credential and password are recognised), URL-encoded text, separators encoded as %3A, :, \u003a or \x3a, header names followed only by a space or tab (Set-Cookie<tab>sid=...), more than 16 folded continuation lines (the 17th and later are kept), an unquoted name with a quoted first value followed by a comma (Cookie: "a", sid=... keeps everything after the comma), lookalike (homoglyph) colons or letters, base64-encoded text, bare Basic or Token values with no header name, secrets in URL paths or fragments other than the token parameters above, curl -u user:password, and the part of an unquoted value beyond 16 KB on one line. The redactor does not scrub the run’s own configured credentials (auth cookies or header values from the audit config or profile) by exact value: they are blanked where they appear under a credential key, but an echo of the same value anywhere else is caught only if one of the patterns matches. The patterns are conservative but cannot prove a body holds no secret. The manifest lists the patterns and how often each matched. Share the raw bundle with nobody.
What a bundle contains
| File | Holds |
|---|---|
manifest.json | Format and version, scanner version, rules revision, every file with its sha256 and size, and a bundle hash. Written last: a directory without it is an interrupted export |
audit.json | Audit configuration, scanner and rules revision, crawl stats, completion status, whether the page limit was hit, and the crawl limits |
pages.json | Per page: source and final URL, capture time, status, request and response headers, fetch mode (http or render), redirect hops, and its artifacts |
findings.json | Per finding: rule, check, status, message, and evidence references |
failures.json | URLs that were never stored (failed or skipped) with the reason |
scripts.json | External scripts with the pages that referenced them |
inline-scripts.json | Inline scripts and inline data blocks with byte ranges into the page artifact |
artifacts/<type>/<sha256> | The bytes, content addressed |
Artifact types are kept apart. response-body is what an HTTP fetch returned and rendered-dom is what a render produced. Each page lists both, and the one that does not exist says why (fetched without rendering, or fetched through a renderer: the original response bytes were not retained). Stored text is the decoded body re-encoded as UTF-8, and byte ranges are relative to those bytes.
Evidence references
Every finding carries a list of references. Each has the page, the artifact type and sha256, and a locator: a CSS selector path and/or a byte range with the sha256 of the snippet. The state is explicit:
| State | Meaning |
|---|---|
located | A selector and/or byte range is recorded |
page-only | The page is archived but the rule gave no location |
truncated | The rule’s snippet was clipped, so the range covers only a prefix, or the list of pages was capped |
unavailable | No artifact to point at (body evicted or never stored), with a reason |
verify
Checks the bundle against its manifest with no network and no crawl store: every file’s size and sha256, files the manifest does not list, the bundle hash, the format version, and that every evidence reference points at an artifact in the bundle. A bundle whose format version is newer than your squirrel asks you to update. Exits 1 on any problem.
replay
Verifies the bundle, then re-checks every finding’s evidence against the archived artifacts: the byte range must still hash to the recorded snippet, and the selector must still resolve in the archived DOM. It reports confirmed, mismatched, unavailable and unlocated references and exits 1 on a mismatch. Replay re-checks evidence, not rule logic: it does not re-run the rules.
Cleanup
Set [storage] evidence_archive_dir to a directory that holds bundles at <dir>/<audit id>. Automatic retention then retires an audit only when its bundle there verifies, so cleanup cannot destroy the only copy of the evidence. See storage. squirrel self disk --prune is an explicit command and is not gated.