Mantis ChainSAFE

A modular, stack-agnostic toolkit for AI coding agents to autonomously find, reproduce, and patch vulnerabilities.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: mantis-chain
description: >-
  Analyzes individual security findings to identify and construct complex exploit chains.
  Use after validation stages to see if multiple low-severity bugs can be combined into a higher impact vulnerability.
  Don't use for initial codebase auditing or writing patch code.
---

# 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_file

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Mantis Chain](https://modelsatlas.com/skills/google/mantis-chain/badge.svg)](https://modelsatlas.com/skills/google/mantis-chain/)

Not your listing, or something out of date? Claim or update your listing.