pentr-verify 0.1.0__py3-none-any.whl

pentr_verify/__init__.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "0.1.0"

pentr_verify/cli.py

@@ -0,0 +1,130 @@
+"""`pentr-verify` — verify an exported Pentr evidence locker, offline.
+
+This command needs no network, no database, and no Pentr credentials. It is the
+whole point of the evidence locker: an auditor who has never heard of us can
+check the evidence with the same code that sealed it.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from pentr_verify.locker import LockerFormatError, VerifyReport, open_locker, verify_locker
+
+EXIT_PASS = 0
+EXIT_FAIL = 1
+EXIT_USAGE = 2
+
+_UNPINNED_WARNING = """
+UNPINNED: this locker was verified against the public key inside it. That proves
+the locker is internally consistent and unmodified since it was signed — it does
+NOT prove who signed it. To prove provenance, obtain the organization's public
+key through a channel you trust and re-run with --key <file>.
+""".strip()
+
+
+def load_public_key_file(path: str) -> bytes:
+    """Read a public key as PEM, 64 hex chars, or 32 raw bytes -> raw 32 bytes."""
+    raw = Path(path).read_bytes()
+    text = raw.strip()
+    if text.startswith(b"-----BEGIN"):
+        from cryptography.hazmat.primitives import serialization
+        from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+        key = serialization.load_pem_public_key(text)
+        if not isinstance(key, Ed25519PublicKey):
+            raise ValueError("only Ed25519 public keys are supported")
+        return key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+    if len(text) == 64:
+        try:
+            return bytes.fromhex(text.decode("ascii"))
+        except (ValueError, UnicodeDecodeError):
+            pass
+    if len(raw) == 32:
+        return raw
+    raise ValueError(f"{path} is not an Ed25519 public key (PEM, 64 hex, or 32 bytes)")
+
+
+def render_text(report: VerifyReport, quiet: bool = False) -> str:
+    lines: list[str] = []
+    if not quiet:
+        for e in report.entries:
+            status = "OK  " if e.ok else "BAD "
+            name = e.filename or "-"
+            lines.append(f"{status} {e.seq:>4}  {e.kind:<16} {e.sha256[:12]}  {name}")
+        if report.entries:
+            lines.append("")
+
+    if report.ok:
+        lines.append("PASS — evidence locker verified")
+    else:
+        lines.append("FAIL — evidence locker did NOT verify")
+        for f in report.failures:
+            subject = f" [{f.subject}]" if f.subject else ""
+            lines.append(f"  FAIL {f.code}{subject}: {f.message}")
+
+    lines.append("")
+    lines.append(
+        f"  run          {report.run_id}\n"
+        f"  artifacts    {report.entry_count}\n"
+        f"  chain head   {report.chain_head}\n"
+        f"  signed by    {report.key_id}\n"
+        f"  signed at    {report.signed_at}"
+    )
+    if report.ok and not report.pinned:
+        lines.append("")
+        lines.append(_UNPINNED_WARNING)
+    return "\n".join(lines)
+
+
+def run(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="pentr-verify",
+        description="Verify an exported Pentr evidence locker offline.",
+    )
+    parser.add_argument("locker", help="Path to a locker directory or .zip")
+    parser.add_argument("--key", default=None,
+                        help="Public key to pin (PEM, hex, or raw). Without it, "
+                             "verification proves consistency but not provenance.")
+    parser.add_argument("--json", action="store_true", dest="as_json",
+                        help="Emit the verification report as JSON")
+    parser.add_argument("--quiet", action="store_true",
+                        help="Suppress the per-artifact listing")
+    args = parser.parse_args(argv)
+
+    pinned: bytes | None = None
+    if args.key is not None:
+        try:
+            pinned = load_public_key_file(args.key)
+        except (OSError, ValueError) as exc:
+            print(f"pentr-verify: cannot read --key: {exc}", file=sys.stderr)
+            return EXIT_USAGE
+
+    try:
+        locker = open_locker(args.locker)
+        report = verify_locker(locker, pinned_public_key=pinned)
+    except LockerFormatError as exc:
+        # Not a verification failure: the input is not a locker at all. Reporting
+        # this as exit 1 would tell an auditor their evidence was tampered with
+        # when they actually just mistyped a path.
+        print(f"pentr-verify: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+
+    if args.as_json:
+        print(json.dumps(report.to_dict(), indent=2))
+    else:
+        print(render_text(report, quiet=args.quiet))
+    return EXIT_PASS if report.ok else EXIT_FAIL
+
+
+def main() -> None:
+    sys.exit(run())
+
+
+if __name__ == "__main__":
+    main()

pentr_verify/hash_chain.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+
+GENESIS_PREFIX = "pentr-evidence-locker-v1|"
+
+
+@dataclass(frozen=True)
+class EntryInput:
+    seq: int
+    kind: str
+    phase: str
+    size: int
+    sha256: str
+    control_ids: list[str]
+    finding_ids: list[str]
+    filename: str | None
+    created_at: str
+
+
+def _canon(obj) -> str:
+    return json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":"))
+
+
+def genesis(run_id: str) -> str:
+    return hashlib.sha256((GENESIS_PREFIX + run_id).encode("utf-8")).hexdigest()
+
+
+def entry_metadata(entry: EntryInput) -> str:
+    return _canon({
+        "seq": entry.seq,
+        "kind": entry.kind,
+        "phase": entry.phase,
+        "size": entry.size,
+        "control_ids": sorted(entry.control_ids),
+        "finding_ids": sorted(entry.finding_ids),
+        "filename": entry.filename,
+        "created_at": entry.created_at,
+    })
+
+
+def entry_hash(prev_hex: str, artifact_sha256: str, metadata_json: str) -> str:
+    payload = prev_hex + artifact_sha256 + metadata_json
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def compute_chain(run_id: str, entries: list[EntryInput]) -> tuple[list[str], str]:
+    prev = genesis(run_id)
+    hashes: list[str] = []
+    for entry in entries:
+        prev = entry_hash(prev, entry.sha256, entry_metadata(entry))
+        hashes.append(prev)
+    head = hashes[-1] if hashes else genesis(run_id)
+    return hashes, head

pentr_verify/locker.py

@@ -0,0 +1,556 @@
+"""Offline reader and verifier for an exported evidence locker.
+
+PURE MODULE — imports nothing from server/, scheduler/, or SQLAlchemy. It must
+run on an auditor's machine that has never seen the Pentr database. Every hash
+here is recomputed with the exact same primitives that produced the seal
+(pentr_verify.hash_chain, pentr_verify.manifest, pentr_verify.signing), which is what makes a PASS
+mean something: the verifier cannot drift from the sealer.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pentr_verify import hash_chain, signing
+from pentr_verify import manifest as manifest_mod
+from pentr_verify.hash_chain import EntryInput
+
+# The locker *packaging* format version, independent of pentr_verify.manifest.VERSION
+# and pentr_verify.signing.SIGNATURE_VERSION even though all three read "pentr-locker-1"
+# today. These are three separately-versioned concerns that happened to ship
+# together in Phase 4: the manifest schema, the signature block schema, and the
+# container format. Aliasing to either would mean bumping the schema version
+# silently changes what the locker advertises, making them unable to move
+# independently.
+LOCKER_FORMAT = "pentr-locker-1"
+
+MANIFEST_NAME = "manifest.json"
+SIGNATURE_BLOCK_NAME = "signature_block.json"
+SIGNATURE_NAME = "signature.bin"
+PUBLIC_KEY_NAME = "public_key.pem"
+SEAL_NAME = "seal.json"
+README_NAME = "README.txt"
+
+ROOT_FILES = frozenset({
+    MANIFEST_NAME, SIGNATURE_BLOCK_NAME, SIGNATURE_NAME,
+    PUBLIC_KEY_NAME, SEAL_NAME, README_NAME,
+})
+# `\Z`, not `$`: `$` also matches just before a trailing newline, so
+# "artifacts/<64 hex>\n" would satisfy a guard written to reject it.
+_ARTIFACT_MEMBER = re.compile(r"^artifacts/[0-9a-f]{64}\Z")
+_PATH_SEPARATOR = re.compile(r"[\\/]")
+
+# Every member is read whole into memory, so each read is bounded by the same
+# per-artifact cap (10 MiB) the Pentr platform's artifact store enforces at seal
+# time. No legitimate locker is affected: manifest.json, the signature block and
+# every blob are all stored through that store, so none of them can exceed it. Without the cap,
+# a signed locker can be recompressed with one member as a zip bomb -- the
+# signature covers the manifest, not the compressed blob -- and pentr-verify is
+# precisely the component designed to be pointed at files from untrusted parties.
+MAX_MEMBER_BYTES = 10 * 1024 * 1024
+
+# Fields verify_locker's stage 7 indexes directly (not via .get()) when
+# rebuilding EntryInput/EntryResult. A manifest entry missing any of these is
+# not tamper — it's a malformed locker — so it is rejected with
+# LockerFormatError before any indexing happens, rather than surfacing as a
+# raw KeyError.
+_REQUIRED_ENTRY_FIELDS = ("seq", "kind", "phase", "size", "sha256", "created_at")
+
+
+def _escapes_locker_root(name: str) -> bool:
+    """True if a member name is absolute or walks out of the locker root."""
+    if name.startswith("/") or name.startswith("\\"):
+        return True
+    return ".." in _PATH_SEPARATOR.split(name)
+
+
+def _validate_member_name(name: str) -> None:
+    """Validate that a member name is in the locker allowlist.
+
+    Raises LockerFormatError if the name is not one of the root files or a
+    valid artifact path. This guards against path traversal attacks and
+    unexpected members.
+    """
+    if name in ROOT_FILES or _ARTIFACT_MEMBER.match(name):
+        return
+    raise LockerFormatError(f"not a valid locker member: {name!r}")
+
+
+class LockerFormatError(Exception):
+    """The locker is unreadable or structurally malformed.
+
+    Distinct from a verification failure: this is "you gave me something that
+    is not a locker", which the CLI reports as exit 2, not as tampering.
+    """
+
+
+FAILURE_CODES = frozenset({
+    "unknown_format",
+    "unsupported_algorithm",
+    "manifest_binding_mismatch",
+    "key_id_mismatch",
+    "key_not_pinned_match",
+    "signature_invalid",
+    "genesis_mismatch",
+    "entry_hash_mismatch",
+    "chain_head_mismatch",
+    "blob_missing",
+    "blob_hash_mismatch",
+    "blob_size_mismatch",
+    "unlisted_blob",
+    "seal_claim_mismatch",
+})
+
+
+@dataclass
+class Failure:
+    code: str
+    message: str
+    subject: str | None = None
+
+    def __post_init__(self) -> None:
+        # FAILURE_CODES is the wire contract Phase 5's viewer and every --json
+        # consumer switch on. Enforcing it here means an invented or misspelled
+        # code fails loudly at construction instead of shipping silently.
+        assert self.code in FAILURE_CODES, f"unregistered failure code: {self.code!r}"
+
+    def to_dict(self) -> dict:
+        return {"code": self.code, "message": self.message, "subject": self.subject}
+
+
+@dataclass
+class EntryResult:
+    seq: int
+    sha256: str
+    kind: str
+    filename: str | None
+    ok: bool
+    reason: str | None = None
+
+    def to_dict(self) -> dict:
+        return {
+            "seq": self.seq, "sha256": self.sha256, "kind": self.kind,
+            "filename": self.filename, "ok": self.ok, "reason": self.reason,
+        }
+
+
+@dataclass
+class VerifyReport:
+    ok: bool
+    pinned: bool
+    key_id: str | None = None
+    run_id: str | None = None
+    chain_head: str | None = None
+    entry_count: int = 0
+    signed_at: str | None = None
+    entries: list[EntryResult] = field(default_factory=list)
+    failures: list[Failure] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "ok": self.ok,
+            "pinned": self.pinned,
+            "key_id": self.key_id,
+            "run_id": self.run_id,
+            "chain_head": self.chain_head,
+            "entry_count": self.entry_count,
+            "signed_at": self.signed_at,
+            "entries": [e.to_dict() for e in self.entries],
+            "failures": [f.to_dict() for f in self.failures],
+        }
+
+
+class Locker:
+    """Read-only view over a locker directory or zip."""
+
+    def __init__(self, source: str) -> None:
+        self.source = source
+
+    def read(self, name: str) -> bytes:
+        """Read a locker member by name.
+
+        Validates that the name is in the allowlist (root files or artifacts)
+        before delegating to the backend, guarding against path traversal
+        attacks in both directory and zip lockers.
+        """
+        _validate_member_name(name)
+        return self._read_member(name)
+
+    def _read_member(self, name: str) -> bytes:
+        """Read a locker member (implemented by subclasses)."""
+        raise NotImplementedError
+
+    def list_artifact_names(self) -> set[str]:
+        raise NotImplementedError
+
+    def read_artifact(self, sha256: str) -> bytes:
+        return self.read(f"artifacts/{sha256}")
+
+
+class _DirLocker(Locker):
+    def __init__(self, root: Path) -> None:
+        super().__init__(str(root))
+        self._root = root
+
+    def _read_member(self, name: str) -> bytes:
+        path = self._root / name
+        if not path.is_file():
+            raise LockerFormatError(f"locker is missing {name}")
+        size = path.stat().st_size
+        if size > MAX_MEMBER_BYTES:
+            raise LockerFormatError(
+                f"{name} is {size} bytes, above the {MAX_MEMBER_BYTES}-byte "
+                f"per-member cap; refusing to read it"
+            )
+        return path.read_bytes()
+
+    def list_artifact_names(self) -> set[str]:
+        # Deliberately does not filter by hex name. Stage 9 of verify_locker
+        # must be able to see a smuggled file (e.g., artifacts/secret.txt) in
+        # order to fail on it as unlisted_blob. If we filtered here, a smuggled
+        # file would be invisible and the locker would pass, silently breaking
+        # the strict both-way check.
+        adir = self._root / "artifacts"
+        if not adir.is_dir():
+            return set()
+        return {p.name for p in adir.iterdir() if p.is_file()}
+
+
+class _ZipLocker(Locker):
+    def __init__(self, path: Path) -> None:
+        super().__init__(str(path))
+        try:
+            self._zf = zipfile.ZipFile(path)
+        except (zipfile.BadZipFile, OSError) as exc:
+            raise LockerFormatError(f"not a readable zip: {path}") from exc
+        self._names = {i.filename for i in self._zf.infolist() if not i.is_dir()}
+        # Validate every member up front. Nothing is extracted to disk, but an
+        # absolute or traversing path is a hostile archive, not a typo, and an
+        # unexpected *root* name means this is not a locker we understand.
+        #
+        # A flat artifacts/<anything> member is deliberately NOT rejected here,
+        # even when the name is not 64 hex: the directory reader can see such a
+        # file and stage 9 reports it as unlisted_blob (exit 1, "your evidence
+        # was tampered with"). Rejecting it at open time would make the same
+        # smuggled byte-for-byte tree exit 2 ("you gave me a broken path") in
+        # zip form — the more serious finding getting the less serious code, in
+        # the container auditors actually receive. read() still refuses the
+        # name (see _validate_member_name): stage 9 only lists it.
+        for name in self._names:
+            if _escapes_locker_root(name):
+                raise LockerFormatError(
+                    f"hostile member path in locker zip: {name!r}")
+            if name in ROOT_FILES:
+                continue
+            rest = name[len("artifacts/"):] if name.startswith("artifacts/") else None
+            if rest is not None and rest and "/" not in rest:
+                continue
+            raise LockerFormatError(f"unexpected member in locker zip: {name!r}")
+
+    def _read_member(self, name: str) -> bytes:
+        if name not in self._names:
+            raise LockerFormatError(f"locker is missing {name}")
+        declared = self._zf.getinfo(name).file_size
+        if declared > MAX_MEMBER_BYTES:
+            raise LockerFormatError(
+                f"{name} declares {declared} bytes, above the "
+                f"{MAX_MEMBER_BYTES}-byte per-member cap; refusing to read it"
+            )
+        # The declared size lives in the central directory and is entirely
+        # attacker-controlled, so the header check above is not on its own a
+        # guard: read through a bounded stream as well and never ask for more
+        # than the cap plus one byte.
+        try:
+            with self._zf.open(name) as fh:
+                data = fh.read(MAX_MEMBER_BYTES + 1)
+        except (zipfile.BadZipFile, EOFError, OSError) as exc:
+            raise LockerFormatError(
+                f"{name} is not readable in this zip: {exc}") from exc
+        if len(data) > MAX_MEMBER_BYTES:
+            raise LockerFormatError(
+                f"{name} expands past the {MAX_MEMBER_BYTES}-byte per-member cap "
+                f"(it declared {declared} bytes); refusing to read it"
+            )
+        return data
+
+    def list_artifact_names(self) -> set[str]:
+        return {n.split("/", 1)[1] for n in self._names if n.startswith("artifacts/")}
+
+
+def open_locker(path: str | Path) -> Locker:
+    p = Path(path)
+    if p.is_dir():
+        return _DirLocker(p)
+    if p.is_file():
+        return _ZipLocker(p)
+    raise LockerFormatError(f"no such locker: {p}")
+
+
+def _load_public_key(pem_bytes: bytes) -> bytes:
+    """PEM -> raw 32-byte Ed25519 public key."""
+    from cryptography.hazmat.primitives import serialization
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+    try:
+        key = serialization.load_pem_public_key(pem_bytes)
+    except Exception as exc:
+        raise LockerFormatError(f"unreadable {PUBLIC_KEY_NAME}: {exc}") from exc
+    if not isinstance(key, Ed25519PublicKey):
+        raise LockerFormatError("only Ed25519 public keys are supported")
+    return key.public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+
+
+def _parse_json(raw: bytes, name: str) -> dict:
+    try:
+        doc = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise LockerFormatError(f"{name} is not valid JSON: {exc}") from exc
+    if not isinstance(doc, dict):
+        raise LockerFormatError(f"{name} must be a JSON object")
+    return doc
+
+
+def verify_locker(locker: Locker, *,
+                  pinned_public_key: bytes | None = None) -> VerifyReport:
+    """Verify an exported locker offline. Never raises on tamper — returns a report.
+
+    Raises LockerFormatError only when the input is not a readable locker at all
+    (missing files, bad JSON, unparseable key, or a manifest entry missing a
+    required field). That distinction is what lets the CLI say "you gave me a
+    broken path" (exit 2) rather than reporting tampering (exit 1) for an
+    operator error.
+
+    Stages 1-6 short-circuit: if the signature does not verify there is no value
+    in enumerating a hundred blobs, so the report names the signature failure and
+    stops. Stages 7-10 do the opposite and accumulate — once the locker is known
+    to be a well-formed, signed locker, every remaining check runs so an auditor
+    sees every problem (bad chain, missing blobs, smuggled blobs, a lying seal)
+    in one pass instead of fixing failures one at a time.
+    """
+    report = VerifyReport(ok=False, pinned=pinned_public_key is not None)
+
+    # --- Stage 1: seal.json + format ---
+    seal = _parse_json(locker.read(SEAL_NAME), SEAL_NAME)
+    report.run_id = seal.get("run_id")
+    report.signed_at = seal.get("signed_at")
+    if seal.get("format") != LOCKER_FORMAT:
+        report.failures.append(Failure(
+            "unknown_format",
+            f"locker format {seal.get('format')!r} is not {LOCKER_FORMAT!r}",
+            SEAL_NAME,
+        ))
+        return report
+
+    # --- Stage 2: manifest bytes, verbatim, hashed as read ---
+    manifest_bytes = locker.read(MANIFEST_NAME)
+    manifest_sha256_actual = hashlib.sha256(manifest_bytes).hexdigest()
+    manifest = _parse_json(manifest_bytes, MANIFEST_NAME)
+    report.chain_head = manifest.get("chain_head")
+    report.entry_count = len(manifest.get("entries") or [])
+    # Re-source the run id from the manifest. seal.json is an unsigned header,
+    # so the value read at stage 1 is attacker-controlled; stage 10 cross-checks
+    # it on a PASS, but a stage-3-to-6 short-circuit would otherwise print the
+    # attacker's run id back to the auditor.
+    run = manifest.get("run") or {}
+    if run.get("engagement_id") is not None:
+        report.run_id = str(run["engagement_id"])
+
+    if manifest.get("version") != manifest_mod.VERSION:
+        report.failures.append(Failure(
+            "unknown_format",
+            f"manifest version {manifest.get('version')!r} is not "
+            f"{manifest_mod.VERSION!r}",
+            MANIFEST_NAME,
+        ))
+        return report
+    if manifest.get("algorithm") != manifest_mod.ALGORITHM:
+        # A future merkle-v1 locker must fail loudly on an old verifier rather
+        # than be checked with the wrong rules and reported as sound.
+        report.failures.append(Failure(
+            "unsupported_algorithm",
+            f"manifest algorithm {manifest.get('algorithm')!r} is not supported by "
+            f"this version of pentr-verify (expected {manifest_mod.ALGORITHM!r})",
+            MANIFEST_NAME,
+        ))
+        return report
+
+    # --- Stage 3: the signature block must bind THESE manifest bytes ---
+    block_bytes = locker.read(SIGNATURE_BLOCK_NAME)
+    block = _parse_json(block_bytes, SIGNATURE_BLOCK_NAME)
+    report.key_id = block.get("key_id")
+    report.signed_at = block.get("signed_at") or report.signed_at
+
+    if (block.get("version") != signing.SIGNATURE_VERSION
+            or block.get("algorithm") != signing.SIGNATURE_ALGORITHM):
+        report.failures.append(Failure(
+            "unknown_format",
+            f"signature block is {block.get('version')!r}/{block.get('algorithm')!r}, "
+            f"expected {signing.SIGNATURE_VERSION!r}/{signing.SIGNATURE_ALGORITHM!r}",
+            SIGNATURE_BLOCK_NAME,
+        ))
+        return report
+    if block.get("manifest_sha256") != manifest_sha256_actual:
+        report.failures.append(Failure(
+            "manifest_binding_mismatch",
+            f"signature covers manifest {block.get('manifest_sha256')} but this "
+            f"locker's manifest hashes to {manifest_sha256_actual}",
+            MANIFEST_NAME,
+        ))
+        return report
+    if block.get("chain_head") != manifest.get("chain_head"):
+        report.failures.append(Failure(
+            "manifest_binding_mismatch",
+            f"signature covers chain head {block.get('chain_head')} but the manifest "
+            f"records {manifest.get('chain_head')}",
+            SIGNATURE_BLOCK_NAME,
+        ))
+        return report
+
+    # --- Stage 4: key identity (content-derived, so it self-verifies) ---
+    public_raw = _load_public_key(locker.read(PUBLIC_KEY_NAME))
+    derived_key_id = signing.key_id_for(public_raw)
+    if derived_key_id != block.get("key_id"):
+        report.failures.append(Failure(
+            "key_id_mismatch",
+            f"{PUBLIC_KEY_NAME} has key id {derived_key_id} but the signature block "
+            f"names {block.get('key_id')}",
+            PUBLIC_KEY_NAME,
+        ))
+        return report
+    if pinned_public_key is not None and pinned_public_key != public_raw:
+        report.failures.append(Failure(
+            "key_not_pinned_match",
+            f"locker is signed by key {derived_key_id} but you pinned "
+            f"{signing.key_id_for(pinned_public_key)}",
+            PUBLIC_KEY_NAME,
+        ))
+        return report
+
+    # --- Stage 5: the signature itself ---
+    signature = locker.read(SIGNATURE_NAME)
+    if not signing.verify_signature(public_raw, block_bytes, signature):
+        report.failures.append(Failure(
+            "signature_invalid",
+            f"signature does not verify against key {derived_key_id}",
+            SIGNATURE_NAME,
+        ))
+        return report
+
+    # --- Stage 6: genesis binds the run id (anti cross-run splicing) ---
+    expected_genesis = hash_chain.genesis(str(run.get("engagement_id")))
+    if expected_genesis != manifest.get("genesis"):
+        report.failures.append(Failure(
+            "genesis_mismatch",
+            f"manifest genesis {manifest.get('genesis')} does not match the genesis "
+            f"derived from run {run.get('engagement_id')}",
+            MANIFEST_NAME,
+        ))
+        return report
+
+    # --- Stage 7: recompute the chain from the manifest's own entries ---
+    # Recompute, never trust. A valid signature already implies the manifest is
+    # unmodified, so this catches a *self-inconsistent* manifest — and, more to
+    # the point, it is the step that proves the shipped chain algorithm
+    # reproduces the sealed head, which is what an auditor is actually checking.
+    raw_entries = manifest.get("entries") or []
+    for idx, e in enumerate(raw_entries):
+        missing = [f for f in _REQUIRED_ENTRY_FIELDS if f not in e]
+        if missing:
+            raise LockerFormatError(
+                f"{MANIFEST_NAME} entry {idx} is missing required field(s): "
+                f"{', '.join(missing)}"
+            )
+    inputs = [
+        EntryInput(
+            seq=e["seq"], kind=e["kind"], phase=e["phase"], size=e["size"],
+            sha256=e["sha256"], control_ids=list(e.get("control_ids") or []),
+            finding_ids=list(e.get("finding_ids") or []),
+            filename=e.get("filename"), created_at=e["created_at"],
+        )
+        for e in raw_entries
+    ]
+    recomputed, recomputed_head = hash_chain.compute_chain(
+        str(run.get("engagement_id")), inputs
+    )
+    for e, h in zip(raw_entries, recomputed, strict=True):
+        if e.get("entry_hash") != h:
+            report.failures.append(Failure(
+                "entry_hash_mismatch",
+                f"entry {e['seq']} records hash {e.get('entry_hash')} but recomputes "
+                f"to {h}",
+                e["sha256"],
+            ))
+    if recomputed_head != manifest.get("chain_head"):
+        report.failures.append(Failure(
+            "chain_head_mismatch",
+            f"manifest records chain head {manifest.get('chain_head')} but the chain "
+            f"recomputes to {recomputed_head}",
+            MANIFEST_NAME,
+        ))
+
+    # --- Stage 8: every entry's blob must be present and hash correctly ---
+    present = locker.list_artifact_names()
+    for e in raw_entries:
+        sha = e["sha256"]
+        result = EntryResult(seq=e["seq"], sha256=sha, kind=e["kind"],
+                             filename=e.get("filename"), ok=True)
+        if sha not in present:
+            result.ok, result.reason = False, "blob missing from locker"
+            report.failures.append(Failure(
+                "blob_missing", f"artifacts/{sha} is listed in the manifest but "
+                                f"absent from the locker", sha))
+        else:
+            data = locker.read_artifact(sha)
+            actual = hashlib.sha256(data).hexdigest()
+            if actual != sha:
+                result.ok, result.reason = False, "content does not match its hash"
+                report.failures.append(Failure(
+                    "blob_hash_mismatch",
+                    f"artifacts/{sha} hashes to {actual} — the evidence has been "
+                    f"modified", sha))
+            elif len(data) != e["size"]:
+                result.ok, result.reason = False, "size does not match the manifest"
+                report.failures.append(Failure(
+                    "blob_size_mismatch",
+                    f"artifacts/{sha} is {len(data)} bytes, manifest says {e['size']}",
+                    sha))
+        report.entries.append(result)
+
+    # --- Stage 9: nothing may be present that the manifest does not list ---
+    # "Evidence present but not sealed" is the smuggling case this locker exists
+    # to prevent, so an extra blob is a hard failure, not a warning.
+    listed = {e["sha256"] for e in raw_entries}
+    for extra in sorted(present - listed):
+        report.failures.append(Failure(
+            "unlisted_blob",
+            f"artifacts/{extra} is present in the locker but is not sealed in the "
+            f"manifest", extra))
+
+    # --- Stage 10: seal.json is an unsigned header; every claim is cross-checked ---
+    claims = [
+        ("run_id", seal.get("run_id"), str(run.get("engagement_id"))),
+        ("chain_head", seal.get("chain_head"), manifest.get("chain_head")),
+        ("manifest_sha256", seal.get("manifest_sha256"), manifest_sha256_actual),
+        ("entry_count", seal.get("entry_count"), len(raw_entries)),
+        ("algorithm", seal.get("algorithm"), manifest.get("algorithm")),
+        ("signature_algorithm", seal.get("signature_algorithm"),
+         block.get("algorithm")),
+        ("signing_key_id", seal.get("signing_key_id"), block.get("key_id")),
+        ("signed_at", seal.get("signed_at"), block.get("signed_at")),
+    ]
+    for name, claimed, actual_value in claims:
+        if claimed != actual_value:
+            report.failures.append(Failure(
+                "seal_claim_mismatch",
+                f"{SEAL_NAME} claims {name}={claimed!r} but the signed material says "
+                f"{actual_value!r}", SEAL_NAME))
+
+    report.ok = not report.failures
+    return report

pentr_verify/manifest.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import hashlib
+import json
+
+from pentr_verify.hash_chain import EntryInput, compute_chain, genesis
+
+VERSION = "pentr-locker-1"
+ALGORITHM = "sha256-linear-v1"
+
+
+def _canon_bytes(obj) -> bytes:
+    return json.dumps(obj, sort_keys=True, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+
+
+def scope_digest(scope_in: list[str], scope_out: list[str], rules: dict) -> str:
+    payload = _canon_bytes({"scope_in": scope_in, "scope_out": scope_out, "rules": rules})
+    return hashlib.sha256(payload).hexdigest()
+
+
+def build_manifest(*, run_id: str, engagement_id: str, framework: str,
+                   scope_in: list[str], scope_out: list[str], rules: dict,
+                   started_at: str | None, ended_at: str | None,
+                   entries: list[EntryInput]) -> tuple[bytes, str]:
+    entry_hashes, chain_head = compute_chain(run_id, entries)
+    manifest = {
+        "version": VERSION,
+        "algorithm": ALGORITHM,
+        "genesis": genesis(run_id),
+        "run": {
+            "engagement_id": engagement_id,
+            "framework": framework,
+            "scope_digest": scope_digest(scope_in, scope_out, rules),
+            "started_at": started_at,
+            "ended_at": ended_at,
+        },
+        "entries": [
+            {
+                "seq": e.seq,
+                "sha256": e.sha256,
+                "kind": e.kind,
+                "phase": e.phase,
+                "control_ids": sorted(e.control_ids),
+                "finding_ids": sorted(e.finding_ids),
+                "size": e.size,
+                "filename": e.filename,
+                "created_at": e.created_at,
+                "entry_hash": h,
+            }
+            for e, h in zip(entries, entry_hashes, strict=True)
+        ],
+        "chain_head": chain_head,
+        "entry_count": len(entries),
+    }
+    manifest_bytes = _canon_bytes(manifest)
+    return manifest_bytes, hashlib.sha256(manifest_bytes).hexdigest()

pentr_verify/signing.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Protocol
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+SIGNATURE_VERSION = "pentr-locker-1"
+SIGNATURE_ALGORITHM = "ed25519-v1"
+
+
+class InvalidKeyError(Exception):
+    """Raised when key material is unparseable, encrypted, or the wrong algorithm."""
+
+
+class Signer(Protocol):
+    """Produces a detached signature over canonical bytes.
+
+    SEAM — read this before believing any marketing copy: the only implementation
+    today is SoftwareSigner, which means the platform holds the org's private key
+    (encrypted at rest under PENTR_KEK). That is *software key custody*, not
+    "the platform never sees your private key". A KmsSigner or HsmSigner
+    implementing this same protocol is the honest upgrade path. It is
+    deliberately NOT implemented in Phase 3.
+    """
+
+    key_id: str
+    algorithm: str
+
+    def sign(self, payload: bytes) -> bytes: ...
+
+
+class SoftwareSigner:
+    """Ed25519 signer over an in-process raw private key."""
+
+    algorithm = SIGNATURE_ALGORITHM
+
+    def __init__(self, private_key_bytes: bytes, key_id: str) -> None:
+        self._key = Ed25519PrivateKey.from_private_bytes(private_key_bytes)
+        self.key_id = key_id
+
+    def sign(self, payload: bytes) -> bytes:
+        return self._key.sign(payload)
+
+
+def _raw_private(key: Ed25519PrivateKey) -> bytes:
+    return key.private_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PrivateFormat.Raw,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+
+
+def generate_private_key() -> bytes:
+    """Fresh Ed25519 private key as 32 raw bytes."""
+    return _raw_private(Ed25519PrivateKey.generate())
+
+
+def raw_public_key_from_private(private_key_bytes: bytes) -> bytes:
+    return Ed25519PrivateKey.from_private_bytes(private_key_bytes).public_key().public_bytes(
+        encoding=serialization.Encoding.Raw,
+        format=serialization.PublicFormat.Raw,
+    )
+
+
+def private_key_from_pem(pem: str) -> bytes:
+    """Parse an unencrypted PKCS#8 Ed25519 private key PEM into 32 raw bytes."""
+    try:
+        key = serialization.load_pem_private_key(pem.encode("utf-8"), password=None)
+    except Exception as exc:
+        raise InvalidKeyError(f"unparseable or password-protected PEM: {exc}") from exc
+    if not isinstance(key, Ed25519PrivateKey):
+        raise InvalidKeyError("only Ed25519 private keys are supported")
+    return _raw_private(key)
+
+
+def key_id_for(raw_public_key: bytes) -> str:
+    """Derive the key id from the key material itself, so it is self-verifying."""
+    return hashlib.sha256(raw_public_key).hexdigest()
+
+
+def public_key_pem(raw_public_key: bytes) -> str:
+    return Ed25519PublicKey.from_public_bytes(raw_public_key).public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode("utf-8")
+
+
+def signature_block(*, chain_head: str, manifest_sha256: str, key_id: str,
+                    signed_at: str) -> bytes:
+    """Canonical bytes that get signed.
+
+    Signing this block rather than the raw manifest binds the key identity and
+    the seal time into the signed material: a signature cannot be replayed onto
+    another manifest, and a mislabeled key_id is a detected failure rather than
+    a confusing one. Serialization rules match pentr_verify/manifest.py exactly.
+    """
+    block = {
+        "version": SIGNATURE_VERSION,
+        "algorithm": SIGNATURE_ALGORITHM,
+        "chain_head": chain_head,
+        "manifest_sha256": manifest_sha256,
+        "key_id": key_id,
+        "signed_at": signed_at,
+    }
+    return json.dumps(
+        block, sort_keys=True, ensure_ascii=False, separators=(",", ":")
+    ).encode("utf-8")
+
+
+def verify_signature(public_key_bytes: bytes, block_bytes: bytes,
+                     signature: bytes) -> bool:
+    """Check a detached signature. Returns False on any failure; never raises.
+
+    Phase 4's `pentr verify` is the main consumer; it runs offline against an
+    exported locker using this exact function. `run_seals.signature` is
+    nullable by design (pre-signing seals have no signature block), so a
+    verifier reading an old seal WILL call this with `signature=None` — that
+    raises TypeError from the underlying library, not InvalidSignature, so it
+    must be caught here too.
+    """
+    try:
+        Ed25519PublicKey.from_public_bytes(public_key_bytes).verify(signature, block_bytes)
+        return True
+    except (InvalidSignature, ValueError, TypeError):
+        return False

pentr_verify-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.5
+Name: pentr-verify
+Version: 0.1.0
+Summary: Offline verifier for Pentr evidence lockers
+Project-URL: Homepage, https://github.com/PentrAI/pentr-verify
+Author: PentrAI
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=42
+Description-Content-Type: text/markdown
+
+# pentr-verify
+
+Offline verifier for [Pentr](https://github.com/PentrAI) evidence lockers.
+
+When Pentr finishes a penetration test, it seals all the evidence it captured
+(command logs, HTTP requests and responses, screenshots) into a hash chain and
+signs the result with the organization's Ed25519 key. The exported locker is a
+directory or `.zip` that anyone can check with this tool. You don't need
+network access, a database or a Pentr account.
+
+The platform seals lockers with this same code, so a PASS here uses exactly the
+checks the platform's own seal is built on.
+
+## Install
+
+```bash
+pipx install git+https://github.com/PentrAI/pentr-verify
+# or
+uv tool install git+https://github.com/PentrAI/pentr-verify
+```
+
+The only runtime dependency is `cryptography`. Python 3.12 or newer is required.
+
+## Usage
+
+```bash
+pentr-verify locker.zip                     # verify against the key inside the locker
+pentr-verify locker.zip --key org-key.pem   # pin the signer's public key
+pentr-verify locker/ --json                 # machine-readable report
+pentr-verify locker.zip --quiet             # skip the per-artifact listing
+```
+
+`--key` accepts a PEM public key, 64 hex characters, or 32 raw bytes.
+
+| Exit code | Meaning |
+|-----------|---------|
+| `0` | PASS: the locker verified |
+| `1` | FAIL: the locker did not verify (tampered, incomplete, or signed by a different key) |
+| `2` | Usage error: the input is not a readable locker, or `--key` is unreadable |
+
+### Pinned and unpinned verification
+
+Without `--key`, the locker is checked against the public key it carries. That
+proves the locker is internally consistent and has not been modified since it
+was signed. It does **not** prove who signed it. To prove provenance, get the
+organization's public key through a channel you trust and pass it with `--key`.
+
+## Locker layout
+
+```
+manifest.json          # canonical run manifest: every entry, its hash and chain hash
+signature_block.json   # the signed bytes: chain head, manifest hash, key id, signed_at
+signature.bin          # detached Ed25519 signature over signature_block.json
+public_key.pem         # the signer's public key
+seal.json              # run id, counts and claims, cross-checked against the above
+README.txt             # human instructions
+artifacts/<sha256>     # one file per manifest entry, named by its SHA-256
+```
+
+## What is checked
+
+1. `seal.json` names a known locker format and algorithms.
+2. The signature block binds the exact bytes of `manifest.json`.
+3. The key id is the SHA-256 of the public key, and matches the pinned key when `--key` is given.
+4. The Ed25519 signature over the signature block verifies.
+5. The chain's genesis matches the run id.
+6. Every entry hash and the chain head recompute from the entry metadata.
+7. Every artifact exists, has the listed size, and hashes to its name.
+8. No artifact is present that the manifest does not list.
+9. Every claim in `seal.json` matches the signed manifest.
+
+Every failure is reported with a stable code (`signature_invalid`,
+`chain_head_mismatch`, `blob_hash_mismatch`, `unlisted_blob`, ...). The full set
+is `FAILURE_CODES` in `pentr_verify/locker.py`.
+
+## Limits
+
+- **Key custody.** The Pentr platform holds each organization's private key,
+  encrypted at rest.
+- **Timestamp.** `signed_at` is recorded by the platform's own clock.
+- **Revocation check.** A locker signed with a key that was later retired
+  still verifies.
+
+## Releasing
+
+Publishing a GitHub release builds the package, runs the tests and uploads it
+to PyPI (`.github/workflows/release.yml`, PyPI trusted publishing). The release
+tag must match the version in `pyproject.toml`, e.g. `v0.1.0`.
+
+## Development
+
+```bash
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

pentr_verify-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pentr_verify/__init__.py,sha256=C52JK4KMjf9MnPZNJ_yYBD0f49c1qgMV5818fiDNO7Y,58
+pentr_verify/cli.py,sha256=EQc99qfK8JfgNexryx1choz_SAPSNa5u0jnVUaJEfYY,4730
+pentr_verify/hash_chain.py,sha256=bJ6AJL6FlDxs0J1bV1UcVT1QpEforq7CCY5KMDK2xv4,1491
+pentr_verify/locker.py,sha256=9YJx0iKDUikaM-JObEGwZWlpG4DXoWDMT-maJQKsPSs,23282
+pentr_verify/manifest.py,sha256=beKCoBUM6nyxlj9lWZCHWLA2hDcewqQTkmv0GWNyyUQ,1961
+pentr_verify/signing.py,sha256=gDxzU9YolhGqN3N_mFsgekLD4dKbydqUGx2mX58WjW4,4739
+pentr_verify-0.1.0.dist-info/METADATA,sha256=z2kmVbSd47DYv9SvKKcGYZn-o9CxwzOhbUITZ31GwP4,4243
+pentr_verify-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pentr_verify-0.1.0.dist-info/entry_points.txt,sha256=CSutsjOKA83Hn_LbKDCyZrxjiFQs20d6IKpKap_wWtU,55
+pentr_verify-0.1.0.dist-info/licenses/LICENSE,sha256=KhgYMYuPp9Dmuq3M9jU_vos6vlLQzmXqvDNa40UiFeY,1064
+pentr_verify-0.1.0.dist-info/RECORD,,

pentr_verify-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pentr_verify-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pentr-verify = pentr_verify.cli:main

pentr_verify-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PentrAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.