Mantis Chain

Vulnerability Chainer (/mantis-chain)

System Goal

Exploit Chain Architect. Analyzes isolated, individually-validated security findings and historical knowledge base primitives to identify and construct complex, multi-step exploit chains.

Command Definition

• Command: /mantis-chain
• Description: Analyzes individual security findings to identify and construct complex exploit chains.
• Arguments (all optional; supplied by the orchestrator per the harness lifecycle contract — see `schema.json` "Non-JSON Contracts"):
• --snapshot_root / SNAPSHOT_ROOT — the pinned, immutable code snapshot root for this pass. Consumed by Block A.
• --snapshot_id / SNAPSHOT_ID — the snapshot identity string for this pass. Consumed by Block A (sentinel) and Block B (match check).
• --state_root — parent directory of workspace/. When absent, defaults to the current directory (Block A step 1c/1d).
• --target_root — an already-prepared tree that OVERRIDES the snapshot root (rarely used by this stage; honored by Block A step 1a). When NONE of these are passed, Block A falls back to active_snapshot in workspace/.mantis_state.json; if that is absent too, the stage runs MODE-OFF (snapshot_pinned = false) and behaves exactly as today (see Backward-compat).

Input/Output Contract

• Reads:
• workspace/findings/ (validated finding JSON files where status is "VALID", and viability is "VIABLE", "CONDITIONAL_VIABLE", or "SAMPLE_OR_TEST").
• workspace/kb/entities/*.md and workspace/kb/vulnerabilities/*.md (knowledge base primitives).
• workspace/.mantis_state.json (to track current loop pass).
• Writes:
• Net-new exploit chain finding JSON files to workspace/findings/<new_uuid>.json. Original findings are left unmodified.
• Preconditions:
• Validated or viable findings must exist in workspace/findings/.
• Idempotency Guarantee:
• Before writing a new exploit chain finding, the skill must check existing exploit chain findings by comparing the constituent finding sequence. Scan BOTH the current workspace/findings/ directory AND every archived pass under workspace/archive/findings_pass_*/ AND legacy workspace/archive/loop*_findings/ (all STATE-RELATIVE — never prefix CODE_ROOT). A chain JSON is any finding whose constituent_findings array is present and non-empty. If a chain with the EXACT same ordered constituent sequence already exists in EITHER location, skip creating a duplicate.
• Signature-keyed idempotency (preferred) — with a code_paths tiebreak: If ALL constituent findings have a signature field, compare the ordered constituent signature sequence (not UUIDs). Treat two chains as the SAME (and skip creating the new one) ONLY IF their ordered signature sequences are equal AND, for each corresponding constituent pair, at least one code_paths entry (line-inclusive, i.e. compared WITH its trailing :line) is identical. If the signature sequences match but any corresponding constituent's code_paths differ, the chains are DISTINCT — create the new chain. (Over-reporting is safe; a signature collision must never suppress a genuinely new exploit chain, because signature strips line numbers and can collide between distinct same-file bugs.)
• UUID fallback (today's behavior): If ANY constituent finding lacks a signature field, fall back to comparing the ordered constituent UUID sequence exactly as before. This preserves today's behavior for legacy / un-upgraded findings.
• This archive scan is now fully effective with stable finding signatures: two chains whose constituents share the same signatures are correctly deduplicated across passes. When signatures are absent (legacy findings), the scan remains HARMLESS — it cannot falsely suppress a legitimate new chain (no silent dropped result) and simply prevents exact-UUID re-duplication within a resumed / rerun pass. If the workspace/archive/ directory does not exist, treat the archived set as empty and proceed.

Instructions

Locator Resolution (run first — all stages)

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).

Stage-specific notes for Block A:

• mantis-chain is NOT a findings-only stage (it is not report/calibrate/reflect), so Block A runs steps 1–6 and resolves CODE_ROOT, SNAPSHOT_ID, and snapshot_pinned from --snapshot_root / --snapshot_id / state active_snapshot.