Penstock

Guide / Share and move

Evidence pack

One reviewable package for an audit: every diagram as a picture, the check results, the recorded test results, the AI receipts and a SHA-256 of every file. Building it is Pro; verifying it is free.

Pro Building a pack: Pro, and Team in a pipeline. The policy and environments sections: Team. Verifying a pack: free.

What it holds

evidence.json lists every file with its SHA-256, beside the tool version, the time, and the git commit and author name (never an e-mail address). evidence.sha256 is the SHA-256 of evidence.json.

Not a signature

The seal is an integrity checksum. It shows that the pack was changed afterwards. It is not a signature and not a legal attestation: someone who can rewrite the whole pack can write a new seal, so keep the pack where it cannot be rewritten.

Build a pack

penstock evidence build --since origin/main --out audit.zip
[folder]The project. The current folder by default.
--out <dir|file.zip>Where the pack goes. A file name ending in .zip, or the folder of the pack. By default under .penstock of the project.
--format zip|dirThe container: a zip (the default) or a folder.
--since <git-ref>Adds what changed since the ref.
--forceReplaces a pack that is already there. An existing pack is never replaced without it.

A pack never holds a secret value and never reads a file outside the project. A diagram that is a link, is too large or cannot be drawn, or more than 500 diagrams, stops the pack with the reason instead of leaving the diagram out. The zip is written beside its place and renamed into it. Exit 0 means the pack was written and verified; 1 means it was refused or the licence does not allow it.

In the editors

Evidence pack, by tool

JetBrains

Evidence Pack… among the command line commands of the project view. The terminal shows the path of the pack.

VS Code

Evidence Pack… among the command line commands of the project view. The terminal shows the path of the pack.

Command line

penstock evidence build and penstock evidence verify. See evidence.

Verify a pack

Free

penstock evidence verify audit.zip

It recomputes the hash of every file of a zip or a folder, and names the file that was changed, is missing or was added. It refuses, and exits 1 on, an entry that climbs out of the pack (.., an absolute path, a backslash), a link or special file, an encrypted or oddly compressed entry, a duplicate, and a decompression that would pass its cap. --format json is for a pipeline.

Common problems

The build stops and names a diagram.
That diagram is a link, is too large or cannot be drawn. Fix or remove it. Penstock does not leave it out silently.
"Already exists".
Use another --out, or --force to replace the pack.
Verify says a file was changed.
The pack does not match its seal any more. Build it again from the source.