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 with `-fsanitize=address,undefined` (ASan + UBSan) at a minimum. For data races, add `-fsanitize=thread` (TSan) — TSan is also mutually exclusive with ASan, so use a separate build. Use `-fno-omit-frame-pointer` for usable stack traces. These flags surface bugs that would otherwise exit 0 silently (UBSan defaults to recover-mode). **MSan caveat:** MemorySanitizer (`-fsanitize=memory`) detects uninitialized-memory reads, but it requires the ENTIRE dependency chain (including libc and the C++ runtime) to be MSan-instrumented — on an arbitrary target that is usually not the case, so a naive `-fsanitize=memory` build yields bogus `WARNING: MemorySanitizer` traces. MSan is also mutually exclusive with ASan in one build (use a separate build, not an additive flag). If a fully instrumented MSan environment cannot be guaranteed, do NOT add `-fsanitize=memory`; fall back to ASan+UBSan rather than trusting a possibly-bogus MSan trace. Recognizing MSan output as evidence (Step 5) is still correct when a legitimate MSan instrumented build is available. **Sanitizer consistency guardrail:** the SAME sanitizer flags MUST be used for the baseline, attack, and re-attack runs — a different sanitizer can mask the bug and produce a false negative (INV-2) or false `VERIFIED_SECURE` (INV-1). See Block G. **{TARGET_ROOT} token substitution (numbered step):** 1. When writing `run_command` or `reattack_run_command`, use the literal token `{TARGET_ROOT}` for any path that references the target tree. 2. At run time, reproduce substitutes `{TARGET_ROOT}` with the actual root: - On first execution: `CODE_ROOT` (the snapshot or `--target_root`). - On re-execution (re-attack or retry): the current `CODE_ROOT` / `--target_root` / `active_snapshot.root`. 3. This ensures the stored command resolves correctly after snapshot GC — never bake an absolute `.mantis_snapshots/pass_<N>` path into the stored command. **Execute your reproduction using the appropriate environment:** If the target is firmware, you may write a script to boot it via `qemu`, `unicorn`, or Firmadyne. If it's a binary, you may use dynamic instrumentation or standard execution. Use your best judgment to construct a working harness for the artifact. - *Parallel Trajectory Search vs. Tiered Iterative Reproduction:*