Package an engagement's findings, scan outputs, evidence, and
signed ROE into a timestamped archive with a SHA-256 manifest
covering every file. Establishes chain of custody so legal
counsel, internal audit, or an outside SOC can verify the archive
hasn't been modified after closeout. Optionally signs the
manifest with GPG for cryptographic attestation.
Use when: closing an engagement, snapshotting evidence after
each scan day, before handing artifacts to customer, or after
an emergency-stop event.
Threshold: file in tree without a manifest entry, hash mismatch,
out-of-tree path referenced in findings, unsigned manifest when
signing was requested.
Trigger with: "record engagement", "archive evidence", "create
chain of custody", "package pentest artifacts".
Package an engagement's findings, scan outputs, evidence, and
signed ROE into a timestamped archive with a SHA-256 manifest
covering every file. Establishes chain of custody so legal
counsel, internal audit, or an outside SOC can verify the archive
hasn't been modified after closeout. Optionally signs the
manifest with GPG for cryptographic attestation.
Use when: closing an engagement, snapshotting evidence after
each scan day, before handing artifacts to customer, or after
an emergency-stop event.
Threshold: file in tree without a manifest entry, hash mismatch,
out-of-tree path referenced in findings, unsigned manifest when
signing was requested.
Trigger with: "record engagement", "archive evidence", "create
chain of custody", "package pentest artifacts".
A penetration test produces a lot of artifacts: scan outputs in
multiple formats, screenshots showing the state of vulnerable
pages, raw tool logs (nmap, Burp, custom scripts), the ROE and any
amendments, exec-summary docs, and the findings themselves. Six
months after the engagement closes, a question arises — sometimes
benign ("can you remind me what we found?"), sometimes adversarial
("the customer claims we accessed an out-of-scope system; show us
the logs"). The answer needs to be: "yes, here's the archive, and
here's cryptographic proof it hasn't been touched since the
engagement closed."
This skill packages the engagement directory into a single
timestamped archive with a SHA-256 manifest covering every file.
Optionally signs the manifest with GPG. The result is a portable,
self-verifying record of what the engagement produced.
The skill also surfaces inconsistencies that would weaken the
chain-of-custody claim: out-of-tree paths referenced in findings
(meaning the finding refers to a file not actually in the archive),
files in the directory not listed in the manifest, manifest
entries whose hashes don't match. These are HIGH findings — they
mean the archive is incomplete or has been modified after the
fact, neither of which is acceptable for evidence purposes.
When the skill produces findings
Finding
Severity
Threshold
Affected control
File in tree not in manifest
HIGH
Found during walk; manifest entry missing
(evidence integrity)
Manifest entry hash mismatch
CRITICAL
Computed SHA-256 differs from manifest
(evidence integrity)
Manifest entry without file
HIGH
Manifest lists a path that doesn't exist
(evidence integrity)
Findings reference out-of-tree path
MEDIUM
A finding's evidence field points to a file not in the archive
(evidence completeness)
Symlink in tree
MEDIUM
Symlinks break archive portability and integrity
(evidence integrity)
Empty file in tree
INFO
0-byte file; possibly an export error
(operational)
Archive package complete
INFO
All checks pass
(positive confirmation)
Manifest signed
INFO
GPG signature present and valid form
(positive confirmation)
Prerequisites
Python 3.9+
An engagement directory laid out as recommended (see structure
below)
The skill walks the directory recursively, builds a SHA-256
manifest, and produces a chain-of-custody report.
Step 2 — Run the packager
Options:
Usage: record_engagement.py PATH [OPTIONS]
Options:
--output FILE Findings output
--format FMT json | jsonl | markdown (default: markdown)
--min-severity SEV default info
--manifest FILE Manifest output path (default: PATH/manifest.sha256)
--tar FILE Also create a .tar.gz archive at this path
--sign Sign the manifest with GPG (uses default identity)
--signer KEY GPG key ID to sign with
--exclude GLOB Skip files matching glob (repeatable)
Step 3 — Verify the manifest
The skill emits a SHA-256 manifest in standard sha256sum format
(one line per file: hash + two-space + path). The manifest is
verifiable independent of the skill:
Daily snapshots build a time-series of the engagement's state
which can be useful in incident-investigation contexts.
Example 3 — Pre-handoff integrity check
# Customer claims the archive is incomplete; verify before disputing
python3 ./scripts/record_engagement.py engagements/acme-2026-q2/ --min-severity high
If exit code is 0, the archive is internally consistent.
Path doesn't exist → exits 2 with operational error.
Permission denied reading a file → emits HIGH finding,
continues walking other files.
GPG not installed with --sign requested → emits HIGH
finding, manifest written unsigned, exits 1.
GPG signing fails (no default identity, etc.) → emits HIGH
finding, manifest written unsigned, exits 1.
tar command fails with --tar requested → manifest still
written; archive creation failure surfaces as HIGH finding.
Resources
references/THEORY.md — Chain of custody as a legal concept,
evidence-integrity standards (NIST SP 800-86), SHA-256 vs
SHA-3 vs SHA-512 tradeoffs, GPG detached-signature semantics,
archive format choices (tar vs zip vs WORM), retention horizons
per jurisdiction
references/PLAYBOOK.md — Engagement directory templates per
engagement type, daily-snapshot cron pattern, customer-handoff
protocol, dispute-resolution playbook (when the customer
challenges the archive), long-term storage and access-control
patterns
