mantis-reproduce

Reproducer (/mantis-reproduce)

System Goal

Integration Test Engineer. Designs crash reproducers or inputs and executes them inside isolated sandbox environments to empirically verify bugs.

Command Definition

• Command: /mantis-reproduce [--reattack] [--finding_id=<uuid>] [--force] [--target_root=<path>] [--state_root=<path>] [--snapshot_root=<path>] [--snapshot_id=<SNAPSHOT_ID>] [--snapshot_pinned=<true|false>]
• Description: Generates and runs crash reproducers to verify security flaws.
• Parameters:
  • --reattack: When executing as part of patch verification to isolate re-attack outcomes.
  • --finding_id: The specific finding UUID to reproduce. Must be provided and is required when --reattack is specified.
  • --force: Override/bypass eligibility checks for targeted normal runs.
  • --target_root: Path to the root of the target codebase under test (defaults to .). AUTHORITATIVE when supplied — overrides --snapshot_root (Block A step 1a); the sentinel check is skipped for this tree (e.g. a patched shadow during re-attack verification).
  • --state_root: Path to the root of the Mantis state directory containing workspace/ (defaults to .).
  • --snapshot_root: Root of the pinned immutable code snapshot for this pass. Consumed by Block A (Step 0) when --target_root is not supplied.
  • --snapshot_id: The SNAPSHOT_ID string of the pinned snapshot, consumed by Block A (sentinel) and Block B (snapshot match check) in Step 0.
  • --snapshot_pinned: When false (set by mantis-patch during re-attack on a patched shadow), the reproduce sub-agent MUST skip the snapshot sentinel/match check for this invocation — the --target_root tree is authoritative and sentinel-exempt (Block A step 1a).

Input/Output Contract

• Reads:
  • state_root/workspace/findings/ (viable/conditional findings).
  • target_root/ (Repository source files to analyze trigger paths).
  • state_root/workspace/archive/.repro_attempts.json.
  • state_root/workspace/.mantis_state.json (to track current loop pass).
• Writes:
  • PoC reproduction files (e.g. poc_[uuid].py or crash_[uuid].payload inside state_root/workspace/reproducers/).
  • If run normally: updates findings in-place under state_root/workspace/findings/ (sets "repro_status", "repro_file_path", "run_command", "repro_output", and appends history). Updates status to "VALID" if provisionally valid.
  • If run with --reattack: updates findings in-place under state_root/workspace/findings/ (sets "reattack_status", "reattack_file_path", "reattack_run_command", "reattack_output", "reattack_variants", and appends history with stage "reattack"). Does not modify "repro_*" fields or "status". Exception: may atomically downgrade patch_status per INV-1 in Step 6 (never persist VERIFIED_SECURE alongside a non-failed_to_bypass reattack_status).
  • Updates state_root/workspace/archive/.repro_attempts.json atomically.
  • Stamps "repro_snapshot_id" / "reattack_snapshot_id" on updated findings and stores .repro_attempts.json values as {count,last_snapshot} objects (bare integers still read correctly).
• Preconditions:
  • Findings must exist in state_root/workspace/findings/.
  • Sandbox/container runtime environment must be available.
• Idempotency Guarantee:
  • Updates findings in place. Uses state_root/workspace/archive/.repro_attempts.lock file locking and atomic temporary file swaps (os.replace on state_root/workspace/archive/.repro_attempts.json.tmp) to guarantee concurrency safety and retry stability.
  • Snapshot-aware: regenerates the PoC when the finding's snapshot no longer matches; refuses to emit a negative verdict without reached-sink evidence. Re-attack verdicts on a snapshot mismatch are governed by the C5 unpatched-baseline re-run (Step 6), which supersedes the legacy blanket refusal — a failed_to_bypass verdict is only written after C5 has confirmed the unpatched baseline still triggers on the current snapshot.

Instructions

Step 0: Locator Resolution + Snapshot Match (run first)

LOCATOR RESOLUTION (before reading ANY target code or artifact):
0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
   you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
   state for provenance/annotation; NEVER stop merely because a code root is unset.
1. Determine CODE_ROOT, in this priority order:
   a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
      It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
      (used when a caller hands you a prepared tree, e.g. a patched shadow).
   b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
   c. Else read state_root/workspace/.mantis_state.json (state_root from
      --state_root if passed, else ./workspace/... relative to the current dir)
      -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
   d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
      treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
   verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
   or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
   deliberately mutated and is sentinel-EXEMPT.)
3. PATH FIELDS:
   - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
     that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
     containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
     NOT of the form <existing-path>:<integer> is a non-source LOCATOR
     (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
     line-range and line-existence logic.
   - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
     kb_references, repro_file_path, reattack_file_path, helper scripts, report
     files, and all state/findings JSON.
4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
   compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
   (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
   cd into CODE_ROOT.
5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
   run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
   (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
   lacks .git/.hg/.repo.
6. Every shell command uses ABSOLUTE paths and sets its own working directory on
   that call. Do NOT assume the working directory persists between calls.

[!NOTE] CURRENT-PASS CHECK (defensive; the binding guarantee is on the harness per mantis-pipeline-adapter Scenario 2): if active_snapshot is present AND active_snapshot.pass != state.pass_number, treat the snapshot as STALE for this pass — STOP "stale active_snapshot: pass mismatch" or degrade as HALT (snapshot_pinned effectively false: no authoritative verdicts, Block B NOT_MATCHED, reproduce not_attempted). This catches a custom harness that preserved active_snapshot across the Stage 15 pass increment without re-pinning. The reference meta-agent re-pins every pass, so this check never fires there. Block B itself cannot detect this (it is snapshot_id-only, not pass-aware).

SNAPSHOT MATCH CHECK for finding F (decides MATCHED vs NOT_MATCHED):
1. If snapshot_pinned is false -> NOT_MATCHED. Stop.
2. Read F.discovery_commit:
   - missing OR empty OR the literal "MIXED" -> NOT_MATCHED.
   - not exactly equal to SNAPSHOT_ID          -> NOT_MATCHED.
   - exactly equal to SNAPSHOT_ID              -> MATCHED.
There is no other route to MATCHED; never fuzzy-compare. The global "default the
field and proceed" backward-compat rule does NOT apply to discovery_commit:
absent = NOT_MATCHED. (There is NO separate "dirty" gate: a dirty tree's
SNAPSHOT_ID already embeds the working-tree content hash, so within-pass findings
MATCH and cross-pass bare-commit findings do not.)

Notes: When invoked by the patcher with --target_root=<shadow> (a patched copy), Block A step 1a makes that shadow the authoritative CODE_ROOT and SKIPS the sentinel check (the shadow is deliberately mutated). Otherwise CODE_ROOT is the pinned snapshot and the sentinel MUST match. Stamp repro_snapshot_id (normal run) or reattack_snapshot_id (--reattack) = the current SNAPSHOT_ID (from --snapshot_id or state active_snapshot.snapshot_id) on every finding you update.

Write a Proof-of-Concept Reproduction Script (Repro) or raw input payload file that reproduces a confirmed security flaw.

Execute the reproduction stage under these constraints:

1. Load Viable Findings:

   • If --finding_id is supplied:
     • Load only that finding's file (state_root/workspace/findings/<uuid>.json). Exit if it does not exist.
     • If --reattack is specified: Enforce the expected patch workflow state for the loaded finding:
       • The finding's "status" must be "VALID" or "PROVISIONALLY_VALID".
       • The finding's "repro_status" must be "reproduced".
       • The finding's "patch_status" must NOT be "MITIGATION_PROPOSED". (VERIFIED_SECURE IS allowed: C5 below atomically downgrades it when the re-attack outcome is not failed_to_bypass.)
       • Exit with an error if these conditions are not met, explaining the invalid state.
     • If --reattack is NOT specified (Targeted Normal Run):
       • If --force is NOT specified, enforce standard eligibility filters:
         • The finding's "status" must be "VALID" or "PROVISIONALLY_VALID".
         • The finding's "production_viability" must be "VIABLE", "SAMPLE_OR_TEST", or "CONDITIONAL_VIABLE".
         • Exit with an error if these conditions are not met, explaining the invalid state.
       • If --force is specified, bypass these eligibility checks.
   • If --finding_id is not supplied:
     • Constraint: Exit if --reattack is specified (it requires --finding_id).
     • Read the JSON files in the state_root/workspace/findings/ directory.
     • Strict Eligibility Filter (Normal Runs): Include only findings where:
       • "status" is "VALID" or "PROVISIONALLY_VALID".
       • "production_viability" is "VIABLE", "SAMPLE_OR_TEST", or "CONDITIONAL_VIABLE" (or skip this viability filter if not checking viability, but always check status).
     • If no applicable findings exist, notify the user and exit.

   Tier 0 — Structural Reachability Pre-Check (Advisory Queue Sorting): If a structural code index (mantis-structural-index) is available, you MAY query query_structural_index.py (find_callers) before authoring code to check whether an AST call path exists from a public entrypoint to the vulnerable sink. Use this query to prioritize candidate execution order (process findings with verified AST reachability first).

   • CRITICAL HINT-ONLY GUARDRAIL: AST reachability is a ranking HINT ONLY. Call graphs miss macros, function pointers, dynamic dispatch, and interface tables. An absent call path MUST NEVER reject a finding, skip reproduction, or set failed_to_reproduce.

   Snapshot drift check: For each loaded finding, if it already has a repro_snapshot_id and Block B (Step 0) returns NOT_MATCHED, treat any stored PoC/offsets as STALE: regenerate the reproducer from scratch against the current CODE_ROOT (do not reuse old line numbers/addresses). If Block B is MATCHED you may reuse an existing PoC.

2. Strict Host Isolation Constraint:

   • Host command execution is strictly prohibited. Do not run commands directly on your parent host terminal using terminal/shell execution tools.
   • All reproducer executions must run isolated. Use the containerization or sandbox execution tools provided by your environment. For memory-safety PoCs, restrict network access and file system writes as much as possible. For logic/auth functional tests, you may enable local network services as needed, but never expose the environment to the external internet.

3. Writing and Launching the Reproducer: Write a self-contained test script (e.g., poc_[uuid].py or a C reproducer file in the same directory) or write a raw crash input data payload (e.g., crash_[uuid].payload) that triggers the target bug. All generated PoC/re-attack scripts and payloads MUST be written inside the state_root/workspace/reproducers/ directory (never in the target_root directory). You must ensure the parent directory state_root/workspace/reproducers/ exists (e.g. using mkdir -p) before writing any files. Analyze the code path and constraints carefully. If your initial reproduction attempt fails, evaluate if the finding details (such as input paths, parameters, or assumptions) are slightly incorrect based on your observations, and adjust the finding details dynamically to attempt a fix. If you cannot find a triggerable path after trying multiple approaches and adjustments, abandon the attempt. Do NOT directly mark it as failed_to_reproduce — route the abandon decision through the Step-5 Block F (Reached-Sink Evidence) gate: if the harness provably reached the vulnerable entrypoint but the bug did not fire, classify as failed_to_reproduce; if evidence is absent (setup/build failure, exit 127, "No such file", or the sink was never reached), classify as not_attempted (retry-eligible). A raw negative from a setup/build failure burns the retry cap and silently drops a real bug.

   To run your script or payload, use the execution or containerization tools available in your environment to execute the code safely. Select the most appropriate runtime image and flags for the target. All compilation and test execution commands MUST be run in a PRIVATE BUILD SHADOW, never with Cwd=CODE_ROOT (the snapshot is read-only — Block A step 4). Before compiling, create BUILD_ROOT=$(mktemp -d) and copy CODE_ROOT into it (e.g. cp -a CODE_ROOT/. BUILD_ROOT/); run all compilation/test commands with Cwd=BUILD_ROOT; delete BUILD_ROOT on teardown. Keep the generated PoC file itself under state_root/workspace/reproducers/ (STATE-RELATIVE) and store its ABSOLUTE path in "run_command"/"reattack_run_command".

   Sanitizer compilation (C/C++ targets): When the bug class is memory-safety or undefined-behavior, compile w

...