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.
What it holds
- every diagram as an SVG;
- the Check results, as SARIF and as text;
- the recorded scenario and DMN test results, with rule coverage;
- the AI receipts, as names and hashes only;
- with
--since, the diagrams that changed since a git ref, drawn in diagram terms with the before and after pictures marked; - the connections findings, by name only;
- the migration report, if the project has one;
- an inventory with the SHA-256 of every diagram, and an
index.html; - with the Team plan, the identity and pin status of the policy pack and the declared environments.
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.
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|dir | The container: a zip (the default) or a folder. |
--since <git-ref> | Adds what changed since the ref. |
--force | Replaces 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.
- Penstock Web and Desktop: Create evidence pack… in the More menu and the command palette of the BPMN, DMN and form editors. A dialog asks for an optional git ref, zip or folder, and whether to replace an earlier pack. It shows progress, then the path of the pack and what the seal is.
- MCP: the
evidence_buildtool, which writes only inside the project.
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--forceto replace the pack. - Verify says a file was changed.
- The pack does not match its seal any more. Build it again from the source.