ADR 0024: Separate exploit manifest and catalog contracts from execution

  • Status: Accepted
  • Date: 2026-09-01

Context

The scanner retains an historical post_exploitation module behind the non-default platform-models feature. That surface is deliberately inert: it has no runtime caller, authorization authority, registry, cleanup lifecycle, or bounded/redacted field ownership. Expanding it into an exploit repository would mix an old caller-owned metadata scaffold with substantially stronger future authority.

Venom needs a durable home for versioned exploit metadata before it can safely review any real implementation. The foundation must distinguish applicability, risk, manifest authorization requirements, and lifecycle vocabulary without making catalog membership or maturity executable. It also needs deterministic identity, bounded parsing, repository validation, and room for future packs without pulling exploit behavior into the default scanner.

Decision

  • Create venom-exploit as a separate, publish = false, Preview workspace crate. It is independent of platform-models and does not replace or import venom_scanner::post_exploitation.
  • V1 owns strict venom.exploit-manifest/v1 metadata, checked bounded IDs and budgets, collision-resistant canonical manifest/catalog digests, deterministic immutable catalog queries, declarative applicability, closed risk/maturity vocabularies, authorization requirements, and legal lifecycle transitions. The lightweight semver crate is used only after bounded syntax checks for a manifest explicitly tagged with the semantic-version requirement scheme; arbitrary vendor version strings are never inferred to be SemVer.
  • A manifest describes requirements and limits. It is never execution authority, cannot mint an authorization grant, and contains no shell command, executable code, raw HTTP body, payload, credential, target URL, or binary blob. Applicability and maturity likewise grant no authority.
  • The library parses only bounded bytes supplied by its host. Neither the default crate nor its non-default orchestration feature owns filesystem discovery or mutation, a network client, process launcher, shell, browser, production target adapter, or external callback. xtask alone discovers and validates the repository-owned exploit-packs metadata tree.
  • The initial repository pack is a lab-only canary lifecycle manifest with no real product, CVE, payload, or target. The non-default orchestration feature binds that exact manifest to a five-step, wholly in-memory integration fixture. The fixture is the only executable demonstration and is not a real exploit module or target adapter.
  • Keep the default crate model/catalog-focused. The non-default Preview orchestration API adds deterministic plans, a sealed source-linked implementation registry, host-minted non-deserializable grants, one-run authorized plans, narrow step permits, validated receipts, lifecycle accounting, and the redaction-safe venom.exploit-run/v1 report. A manifest, applicability assessment, prepared plan, or implementation binding is still not authority.
  • Keep lifecycle facts separate: attempt delivery is not trigger evidence, trigger evidence is not verified impact, and verified impact is not verified cleanup. Reversible mutation creates a cleanup obligation, and successful completion requires cleanup verification.
  • Treat source-linked implementations and host executors as cooperative trusted Rust code. Panic containment is a fail-closed callback boundary, not a process/WASM sandbox or a third-party code trust mechanism.
  • venom-scanner, venom-cli, venom-api, and venom-proxy do not depend on venom-exploit. Default venom scan, decision-scan/v1, existing assessment semantics, and the old platform-model quarantine remain unchanged.
  • The manifest SHA-256 digest is deterministic integrity identity over explicit semantic fields and domain-separated boundaries. It is not publisher authenticity, package signing, or trust in an implementation.

Consequences

  • Future manifests can share one strict schema, deterministic catalog, and policy vocabulary instead of becoming an unstructured collection of scripts and prose.
  • Catalog membership, applicability, and lifecycle modeling remain useful before any production execution boundary exists, while architecture checks prevent the new domain from silently acquiring transport or process authority.
  • The optional orchestration contract can coordinate reviewed host code, but it remains disconnected from all products. A future real module must separately add a reviewed transport/target adapter, vulnerable and negative fixtures, exact applicability and authorization policy, bounded trigger and impact evidence, mandatory cleanup behavior where applicable, cancellation and exhaustion handling, report redaction, and exact-head CI.
  • SHA-256 detects semantic manifest changes but does not authenticate a pack author. External loading, signatures, distribution, dynamic code, and process/WASM isolation remain separate decisions.

Alternatives considered

  • Expand venom_scanner::post_exploitation. Rejected because its quarantined caller-owned strings, compatibility feature, and absent execution/lifecycle contracts are the wrong authority boundary.
  • Store executable payloads in generic manifests. Rejected because metadata parsing would become a generic operational-material channel and blur review, authorization, and implementation identity.
  • Add scanner or CLI integration immediately. Rejected because the disconnected in-memory orchestration fixture is not production transport, implementation isolation, or authority to act on scanner findings.
  • Treat a digest as a signature. Rejected because deterministic integrity and publisher authenticity solve different problems.