Terminal
Terminal/Skill
Interactive guide for designing your own deterministic harness that runs the security review skills reliably.
By Google
Works with
npx skills add google/mantis --skill mantis-pipeline-adapterInteractive Pipeline Design Consultant. Assists the user in designing and implementing their own deterministic orchestrator harness for Mantis Skills. Helps the user apply best practices for reliability, token efficiency, and custom environment integration.
/mantis-pipeline-adapterworkspace/.mantis_state.json (to track current loop pass).workspace/.mantis_state.json fields active_snapshot, snapshot_history,
and vcs_info.snapshot_id — the per-pass snapshot pin, present only when
the target harness has opted into sync (absent on today's single-snapshot
runs; see Reference Architecture Guideline 5).schema.json (as the canonical pipeline specification reference).workspace/findings/*.json (as the State Store).workspace/learnings.jsonl (to understand memory rotation).Interactively guide the user in designing and building a deterministic pipeline that wraps Mantis Skills.
Follow these guidelines during the consultation:
snapshot_pinned unset, which
preserves today's single-snapshot behavior byte-for-byte. When --sync is
requested, the harness PINs in the PIN step and passes
--snapshot_root/--snapshot_id normally; Block A (Locator Resolution) is
universal across all code-reading stages.Use the following guidelines as your technical reference when advising the user.
workspace/findings/*.json) or a database as the single source of truth.
Skills should read from and write to this store. For horizontal scaling,
recommend a centralized database.workspace/learnings.jsonl) must be rotated. Upon
successful completion and verification of the Knowledge Base synthesis stage,
the orchestrator should ensure the archive directory exists (e.g.,
mkdir -p workspace/archive/learnings/) and move
workspace/learnings.jsonl to a numbered archive (e.g.,
workspace/archive/learnings/learnings_pass_${N}_${X}.jsonl where ${N} is
the loop pass and ${X} is a sub-index). If the synthesis fails, the active
queue must be left intact to prevent data loss.graph TD
Harness[Programmatic Harness / Orchestrator] <--> DB[(State Store: Disk/DB)]
subgraph Stages [Decomposed Stages]
KB[KB Architect]
TM[Threat Modeler]
P[Plan]
R[Researcher]
D[Deduplicator]
V[Validator/Review]
C[Critic]
Rep[Reproducer]
Ch[Chainer]
Pat[Patcher]
Cal[Calibrator]
Ref[Reflector]
end
Harness --> KB
Harness --> TM
Harness --> P
Harness --> R
Harness --> D
Harness --> V
Harness --> C
Harness --> Rep
Harness --> Ch
Harness --> Pat
Pat -.->|Re-attack Bypass Loop| Rep
Harness --> Cal
Harness --> Ref
subgraph LLM Pool [Tailored LLMs]
ModelA[Frontier Model: Deep Reasoning]
ModelB[Flash/Lite Model: Fast & Cheap]
ModelC[Alternative Provider: Diversified Logic]
end
KB -.-> ModelA
TM -.-> ModelB
P -.-> ModelB
R -.-> ModelA
R -.-> ModelC
D -.-> ModelB
V -.-> ModelB
C -.-> ModelA
Rep -.-> ModelA
Ch -.-> ModelA
Pat -.-> ModelA
Cal -.-> ModelB
Ref -.-> ModelB
To prevent the LLM from repeating large blocks of text (which increases latency, cost, and the risk of mangling data), use UUIDs as the primary key for all findings.
workspace/findings/<UUID>.json containing the full details (matching the
standard schema in Mantis Researcher).Instead of asking the LLM to read all findings, merge them in context, and write them back, use the following pattern:
Harness Action: Reads all workspace/findings/*.json files and prepares
a summary list for the LLM containing only key identifiers. To align with the
standard schema, map the code_paths array (which uses "file:line" format)
to a simplified summary for the LLM:
[ { "id": "UUID", "file": "path", "line": 12, "snippet": "..." } ].
LLM Action: Analyzes the summary and outputs a mapping of duplicates:
{
"primary_uuid_1": ["duplicate_uuid_a", "duplicate_uuid_b"],
"primary_uuid_2": []
}
Harness Action (Deterministic):
code_paths, taking highest severity, concatenating history).workspace/findings/primary_uuid_1.json on disk.mkdir -p workspace/findings/.trash/).workspace/findings/duplicate_uuid_a.json and
workspace/findings/duplicate_uuid_b.json to the trash staging directory
(workspace/findings/.trash/).workspace/findings/<UUID>.json, pass
only the relevant code context and finding description to the LLM.{"valid": true, "reason": "..."}).workspace/findings/<UUID>.json file with the validation status and reason.When validating findings, the agent may need to interact with diverse environments (VMs, physical hardware). Use the Model Context Protocol (MCP) to expose a clean, restricted API.
[Reproducer Agent] <--- MCP ---> [Custom MCP Server] <--- API ---> [Target Env]reboot_vm(), execute_payload().power_cycle_device() (via smart
plug), send_usb_packet().The pipeline can be split into independent services. When scaling horizontally
(e.g., multiple workers running the Reproducer stage in parallel):
Reproducer,
Patcher), spawn multiple parallel agents attempting to solve the exact same
finding using diverse logic paths. For the Reproducer stage, prune all other
trajectories as soon as one worker succeeds to save compute costs while
escaping LLM "give up" loops. For the Patcher stage, wait for all patches to
be generated and tested, then evaluate the successful ones to select the most
minimal, idiomatic, and correct fix.Match task complexity with the appropriate model tier:
Emphasize that using cheaper models for utility stages (like deduplication or calibration) must be validated with empirical evaluations against a benchmark dataset to ensure quality is not degraded.
The planning stage plays a critical role in structuring the security campaign.
The strategist (/mantis-plan) generates workspace/plan.json to define
targeted investigations, context pointers, and specific questions for the
auditor. The researcher (/mantis-researcher) reads workspace/plan.json at
startup to guide its sweep. By decoupling strategy and execution via this
structured contract, the orchestrator can easily direct subagents, parallelize
sweeps, and maintain historical context across pipeline runs without repeating
work.
A custom orchestrator (a bespoke CLI, an ADK agent, an MCP-native pipeline, or
any deterministic harness) does not inherit the living-project lifecycle
that mantis-meta-agent implements. To support continue-after-edits and
opt-in boundary sync without producing silent wrong results (false
VERIFIED_SECURE, false failed_to_reproduce, dropped regressions), the
harness must implement the following harness-agnostic contract. This is the same
contract recorded in schema.json under Non-JSON Contracts;
the Block A–Block G and SNAPSHOT_ID references below name mechanisms each
Mantis stage already carries in its own SKILL.md.
Mantis runs under multiple harnesses (various CLIs, ADK, custom deterministic
pipelines), so the lifecycle must not live only in mantis-meta-agent. Any
harness is conformant iff, per pass, it:
vcs_info + computes SNAPSHOT_ID (Block D steps 1-5) — only
after sync.snapshot_history (Block D step 5, not RECORD).vcs_info (incl. snapshot_id) + active_snapshot. Never
record an id or pin before syncing.--snapshot_root=<SNAPSHOT_ROOT> --snapshot_id=<SNAPSHOT_ID> --state_root=<workspace parent>.discovery_commit.A harness that does not implement the contract MUST leave snapshot_pinned
unset → today's behavior. When --sync is requested, the harness PINs in the
PIN step and passes --snapshot_root/ --snapshot_id normally; Block A
(Locator Resolution) is universal across all code-reading stages.
snapshot_pinned behaves exactly like today (one live
snapshot per run). Downstream stages treat an absent
active_snapshot/discovery_commit as the conservative branch, so an
un-upgraded harness is always safe — just not living-project-aware. Do not
advise treating these absent fields as an error.workspace/. The pinned copy (SNAPSHOT_ROOT)
must live under <state_root>/.mantis_snapshots/pass_<N> (or a clean-VCS
worktree/archive), and its path must not contain the segment /workspace/
— otherwise mantis-patch's state-vs-code path guard misfires. Keep the last
2 snapshots and garbage-collect older ones with the matching teardown
(rm -rf for copies, git worktree remove/prune for worktrees).git reset --hard, git checkout -- ., git clean, or hg update -C, or
any command that discards uncommitted/untracked/local-commit state — user
edits and in-progress work must survive every pass.SNAPSHOT_IDs, including dirty / no-VCS. Compute the id
over the whole pinned copy: clean git/hg → commit_hash; dirty git/hg →
commit_hash + ":" + content_hash; multi-vcs →
revision + ":" + content_hash; no-VCS / unknown copyable tree →
"content:" + content_hash. The embedded content hash is exactly what lets an
unchanged dirty or no-VCS tree MATCH across passes and still receive
verification + dedup — and what makes a repo sync that advances commits
under an unchanged manifest revision compare unequal. Never trust a bare
branch name or manifest revision string as an identity.active_snapshot for provenance/annotation. When the harness archives
and increments, retried findings must keep their original
discovery_commit.The scenarios below expose nearly every issue in the snapshot model. They are
reference checks, not features: the harness is responsible for preventing or
handling each one in its own environment. The table is a quick-reference; prose
detail follows for each scenario. The State column uses the 3-STATE RULE
(MODE-OFF / HALT / PINNED, branched on active_snapshot presence — see the
global backward-compat rule in schema.json and the advisory
notes above); SNAPSHOT_ID formats follow the ladder in the advisory notes
above (e.g. live:<ts> signals an unpinned/HALT pass).
Invariant legend (the labels below name safety properties enforced by the blocks and the global backward-compat rule in schema.json):
| Label | Property | Enforced by |
|---|---|---|
| INV-1 | No false VERIFIED_SECURE | Block G + HALT ceiling |
| INV-2 | No false failed_to_reproduce | Block F + HALT ceiling |
| INV-3 | No dropped regression | Block B NOT_MATCHED + POSSIBLE REGRESSION |
| INV-4 | Within-pass consistency | Block A sentinel + single pinned snapshot |
| INV-5 | No user data loss | Block C non-destructive sync + Block A step 4 |
| INV-6 | Fail-safe on missing data | Global backward-compat rule |
Quick-reference table:
| # | Scenario | State | Harness behavior | Stage behavior | Block / INV | Key fields |
|---|---|---|---|---|---|---|
| 1 | Colocated state | PINNED | HALT-and-yield (safe default), or relocate state_root outside CODE_ROOT when explicitly authorized (e.g. --auto_relocate_state); SNAPSHOT_ROOT path must not contain /workspace/ | mantis-patch state-vs-code guard misfires; Block A step 3 confuses SNAPSHOT- vs STATE-relative paths | A:3, D:3; INV-5 | active_snapshot.root, snapshot_root, state_root |
| 2 | Stale active_snapshot (active_snapshot.pass != state.pass_number) | PINNED → STOP or HALT-degrade | Block D step 0: handles same-pass re-entry only; if dir missing → STOP, yield to user | Block A step 2 sentinel may still MATCH (dir retained); CURRENT-PASS CHECK (active_snapshot.pass == state.pass_number) required: mismatch → STOP or HALT-degrade (Block B NOT_MATCHED, no authoritative verdicts) | A:2, D:0, B; INV-1, INV-3, INV-4, INV-6 | active_snapshot.{root, snapshot_id, snapshot_pinned, pass}, state.pass_number, discovery_commit |
| 3 | Pin failure | HALT | Block D step 2/4: skip copy on ENOSPC/error → step 5b; still write active_snapshot + pass roots | Authoritative verdicts forbidden; Block B always NOT_MATCHED; reproduce not_attempted; patch VERIFICATION_INCOMPLETE | D:2, D:4, D:5b; INV-1, INV-2, INV-6 | active_snapshot.{snapshot_id, snapshot_pinned} |
| 4 | Patched shadows | PINNED (pass); --snapshot_pinned=false arg | Pass --target_root=<PATCHED_SHADOW_ROOT> + --snapshot_pinned=false to reattack sub-agent | Block A step 1a: CODE_ROOT=--target_root (authoritative); step 2 sentinel SKIPPED (sentinel-EXEMPT) | A:1a, A:2; INV-4 | target_root, snapshot_pinned (arg), snapshot_root, discovery_commit |
| 5 | Different-snapshot duplicate candidates | PINNED | No special action — both passes pinned correctly; dedupe handles it | Block B pairwise: discovery_commit differs → NOT_MATCHED → keep ACTIVE + possible_duplicate_of; POSSIBLE REGRESSION if archived was RESOLVED | B; INV-3, INV-6 | discovery_commit, possible_duplicate_of, status, patch_status |
| 6 | Absent sink evidence | Any | No special action — Block F is a stage-level mechanical gate | Block F: evidence absent (build error, exit 127, sink unreached) → not_attempted (retry-eligible), NEVER failed_to_reproduce; HALT ceiling additionally forces not_attempted | F; INV-2, INV-6 | repro_status, reattack_status, repro_hints |
Per-scenario detail:
1. Colocated state (state_root nested inside CODE_ROOT / snapshot root)
— The pinned SNAPSHOT_ROOT must live under
<state_root>/.mantis_snapshots/pass_<N> (or a clean-VCS worktree/archive), and
its path must not contain the segment /workspace/ — otherwise
mantis-patch's state-vs-code path guard misfires (state files appear to be
"under CODE_ROOT"). If state_root itself is inside CODE_ROOT, the harness
must HALT-and-yield (safe default) or, when explicitly authorized (e.g.
--auto_relocate_state), relocate it outside the snapshot before pinning. Block
A step 3 distinguishes SNAPSHOT-RELATIVE path fields (read under CODE_ROOT)
from STATE-RELATIVE fields (read under state_root/workspace, never prefixed
with CODE_ROOT); colocation breaks this separation.
2. Stale active_snapshot (active_snapshot.pass != state.pass_number —
active_snapshot was preserved across the Stage 15 pass increment) — Block D
step 0 (crash-resume) handles only the SAME-pass re-entry case
(active_snapshot.pass == N → reuse). It does NOT catch a stale snapshot
carried across the Stage 15 pass increment, because Stage 15 deliberately
preserves active_snapshot while bumping pass_number (see Stage 15). Two
sub-cases:
(a) The prior snapshot dir is now MISSING: Block D step 0 STOPs and yields to
the user (never re-pin to a possibly-drifted live tree). (b) The prior snapshot
dir still EXISTS (default keep-2 retention) and its sentinel matches the
preserved active_snapshot.snapshot_id: Block A step 2 sentinel check SUCCEEDS
(it only compares the sentinel file to SNAPSHOT_ID, not to the current pass).
Block B's pairwise discovery_commit check would MATCH a carried-forward
finding against a new finding stamped with the same stale SNAPSHOT_ID,
silently dropping it as DUPLICATE — a false authoritative verdict.
To prevent (b), the HARNESS MUST guarantee that
active_snapshot.pass == state.pass_number before any consumer stage reads it.
The reference harness (mantis-meta-agent) satisfies this by re-pinning every
pass (Block D step 0 sees active_snapshot.pass != N → re-pins → refreshes
active_snapshot.pass before any stage runs), so sub-case (b) never fires
there. A custom harness that preserves active_snapshot across the Stage 15
pass increment WITHOUT re-pinning MUST either (a) re-pin every pass (the
reference behavior), or (b) inject an equivalent pre-stage gate that refreshes
active_snapshot.pass or clears active_snapshot entirely before invoking
stages. Stages CANNOT self-detect this staleness via Block B (which is
snapshot_id-only, not pass-aware): a carried-forward finding and a new
finding stamped with the same stale SNAPSHOT_ID will MATCH in Block B despite
the snapshot being stale. The active_snapshot.pass field is defined in
schema.json #/$defs/state/active_snapshot/pass for exactly this check. The
harness's Block D step 0 reuse check is NOT a substitute: it only fires on
same-pass re-entry. (Stages that read active_snapshot MAY additionally
self-check defensively — see each stage's Step 0 sentinel check — but the
binding guarantee is on the harness.)
3. Pin failure (snapshot copy fails — disk full, permissions, too-large
tree) — Block D step 2 (free-space precheck): compare du -s of the live tree
to df free space at state_root; if it won't fit → skip copy → step 5b. Block
D step 4 (failure-tolerant verify): check copy exit status + sanity check (file
count/size within ~90%); on failure → step 5b (unpinned/HALT). Step 5b:
SNAPSHOT_ROOT=<live root>, snapshot_pinned=false,
SNAPSHOT_ID="live:"+ISO8601. The harness still writes active_snapshot and
still passes --snapshot_root/--snapshot_id to stages so they see the HALT
signal. Every stage then degrades conservatively: authoritative verdicts
forbidden (VERIFIED_SECURE, failed_to_reproduce, DUPLICATE,
FALSE_POSITIVE, NON_VIABLE); Block B always returns NOT_MATCHED; reproduce
records not_attempted; patch's best attainable is VERIFICATION_INCOMPLETE.
4. Patched shadows (--target_root pointing at a pre-mutated tree;
sentinel-exempt path 1a in Block A) — mantis-patch passes
--target_root=<PATCHED_SHADOW_ROOT> and --snapshot_pinned=false to the
reproduce sub-agent for re-attack verification. Block A step 1a:
CODE_ROOT = --target_root (authoritative override, overrides --snapshot_root
and state fallback). Block A step 2: sentinel check SKIPPED (a --target_root
tree is deliberately mutated and is sentinel-EXEMPT). The
--snapshot_pinned=false argument is the sentinel-exemption, NOT a HALT signal
— detect HALT by reading STATE (active_snapshot.snapshot_id starts with
live:, equivalently active_snapshot.snapshot_pinned is false in state),
never from the argument passed on this invocation. The finding's
discovery_commit is unaffected — it retains the pass-level SNAPSHOT_ID from
when it was discovered; only the --snapshot_pinned=false argument is local to
the reattack invocation.
5. Different-snapshot duplicate candidates (cross-pass dedupe where
discovery_commit differs — the pairwise Block B NOT_MATCHED path) — Both
passes pinned correctly; the findings simply come from different snapshots.
mantis-dedupe Block B pairwise check compares the CURRENT finding's
discovery_commit against the ARCHIVED finding's discovery_commit (NOT
against the global SNAPSHOT_ID). If they differ → NOT_MATCHED. NOT_MATCHED
keeps the current finding ACTIVE and sets possible_duplicate_of (a soft,
non-terminal hint — the finding is NOT filtered or trashed). If the archived
finding was RESOLVED (patch_status in {VERIFIED_SECURE,
MITIGATION_PROPOSED} OR status==FALSE_POSITIVE OR
production_viability==NON_VIABLE) AND the pair is NOT_MATCHED → POSSIBLE
REGRESSION: keep ACTIVE, add a history note, never filter (a reverted fix
re-discovered on new code must never be trashed).
6. Absent sink evidence (Block F — PoC compiles but produces no reached-sink
evidence; not_attempted vs failed_to_reproduce) — mantis-reproduce Block
F: if EVIDENCE is ABSENT (any compiler/build nonzero exit, exit 127
command-not-found, exit 2 "No such file", or the sink was never reached) →
repro_status = not_attempted (retry-eligible), STOP. NEVER
failed_to_reproduce. In --reattack mode: leave reattack_status UNSET with
a history note "setup_failed" — NEVER failed_to_bypass. failed_to_reproduce
is reserved for when the harness PROVABLY reached the vulnerable entrypoint —
i.e. reached-sink evidence, not setup evidence — but the bug did not fire.
Reached-sink evidence must originate INSIDE the invoked path or from
target-produced tracing/backtraces: (a) a PoC script/source harness writes
MANTIS_REACHED_ENTRYPOINT to a sidecar file at the point just before the sink
call, within its own execution flow (the marker write is part of the invoked
path, not a pre-launch step); OR (b) for binary/firmware/raw-payload targets,
the captured crash backtrace or sanitizer trace (ASan/UBSan/MSan/TSan)
explicitly names the target sink function (target-produced tracing). A marker
written by an external wrapper BEFORE invoking the target is SETUP EVIDENCE ONLY
(proves "launch attempted," not "sink reached") and does NOT by itself justify
failed_to_reproduce — treat it as EVIDENCE ABSENT for the decision gate.
Evidence is recorded in repro_hints. In HALT mode, the HALT ceiling
additionally forces not_attempted (no failed_to_reproduce), since a negative
result on an unpinned tree cannot be trusted as authoritative.
For small repositories, the planner can manually scan workspace/kb/index.md
and the researcher can grep for call-sites. At scale (thousands of files, deep
directory trees, multi-pass campaigns), these approaches miss relevant context
and waste tokens reading irrelevant files. A semantic retrieval layer lets the
planner and researcher query for relevant KB entries and code locations without
reading everything.
Two implementations are supported, sharing the same data contract:
chunks.jsonl. Zero external dependencies —
works air-gapped, no vector embeddings or vector store required. Optional
vector embedding support if available.semantic_search_kb /
semantic_search_code MCP tools. Better for very large codebases where
per-invocation BM25 is too slow.Both are opt-in. The existing skills are not modified; the planner and researcher receive runtime instructions to use whichever retrieval mechanism is available, falling back to today's manual behavior if neither is present. Retrieval results are coverage HINTs only — they decide ordering and prioritization, never the membership of the audit set. A miss must never cause a file, call-site, or investigation to be skipped or dropped.
chunks.jsonlAfter Stage 2 (/mantis-architecture) completes, chunks are extracted into
workspace/kb/chunks.jsonl (one JSON object per line). The harness can do this
post-hoc by reading workspace/kb/*.md, or the architecture skill can be
instructed to write it during synthesis as a text-only side effect. Two chunk
types are produced:
KB chunks from the existing workspace/kb/*.md files:
{"id": "auth_module:0", "source_file": "workspace/kb/entities/auth_module.md", "entity_type": "entity", "chunk_text": "The auth module handles..."}
Code chunks from CODE_ROOT (the pinned snapshot). Each chunk includes
the file path and line range so the researcher can request specific files
from the snapshot:
{"id": "src/parser.c:0", "source_file": "src/parser.c", "start_line": 1, "end_line": 80, "chunk_text": "int parse_input(..."}
The first line of chunks.jsonl is a provenance header recording the
SNAPSHOT_ID the chunks were built against:
{"_provenance": true, "snapshot_id": "abc123", "kb_snapshot_id": "abc123"}
Before serving queries, check snapshot_id in the provenance header against the
current SNAPSHOT_ID; rebuild if they differ. In MODE-OFF (no
active_snapshot), kb_snapshot_id is never stamped — skip the index entirely
and let skills fall back to manual scanning. Never build code chunks from the
live tree — they must reflect the pinned copy the skills are reading.
A dedicated skill reads chunks.jsonl and writes+runs a helper script (e.g.
workspace/helpers/search_chunks.py) that performs BM25/TF-IDF similarity
search. The script is generated by the agent at runtime — no code is shipped
with the skill (same pattern as mantis-dedupe's merge_findings.py). This
requires zero external dependencies — no embedding model, no vector store, no
MCP server. It works in air-gapped and VPC-SC environments.
A complete reference blueprint for this skill is available at
references/mantis-kb-query.md. Builders can
adapt it to their environment. The blueprint includes Block A (Locator
Resolution), chunk provenance checking, the versioned helper script contract
(MANTIS_HELPER_VERSION = 1), and the JSON output schema.
active_snapshot from state via Block A
(same as every other skill) and checks chunk provenance before serving.For very large codebases where per-invocation BM25 is too slow, the harness can own a persistent vector index using vector embeddings, serving two MCP tools (following the same pattern as Guideline 2's Custom MCP for VMs/hardware):
semantic_search_kb(query: string) → [{id, source_file, entity_type, chunk_text, score}]
— Searches KB chunks. Returns relevant entity/vulnerability markdown context.
semantic_search_code(query: string) → [{file, start_line, end_line, snippet, score}]
— Searches code chunks from the pinned snapshot. Returns relevant code
locations.
The harness manages the vector index lifecycle: build from chunks.jsonl (or
directly from CODE_ROOT), rebuild when SNAPSHOT_ID changes, and handle
freshness checks. In HALT mode, serve with a STALE flag or refuse. In
MODE-OFF, skip entirely.
When a retrieval mechanism (skill or MCP) is available, instruct the following skills to use it. These are runtime instructions passed by the harness or meta-agent when invoking the skill — the skill files themselves are not modified:
mantis-architecture: No changes needed. The harness chunks the existing
workspace/kb/*.md files after the architect completes Stage 2. If the
builder prefers, they may instruct the architect to also write
workspace/kb/chunks.jsonl during synthesis (Step 3) as a text-only side
effect — but this is optional, since the harness can extract chunks post-hoc.
mantis-plan: If a retrieval mechanism is available, instruct the planner
to use it to discover kb_references for each investigation instead of only
manually scanning workspace/kb/index.md. For each investigation, query with
the investigation title and target file names, then add the top-K matching KB
entity/vulnerability files to the kb_references array. Manual scanning of
index.md remains the fallback when no mechanism is available.
mantis-researcher: If a retrieval mechanism is available, instruct Wave 1
sub-agents to use it to PRIORITIZE relevant call-sites and cross-module data
flows into sinks (e.g., "where does untrusted input reach memcpy in the
parser module"). Semantic search SUPPLEMENTS grep as a ranking HINT ONLY — it
decides ORDER, never MEMBERSHIP of the audit set. It MUST NEVER replace the
exhaustive Step-3 call-site sweep; every call-site or data-flow that a full
grep would reach must still be audited whether or not it ranks in top-K. Audit
the union of grep results and semantic search results. The researcher's
existing Wave 1/Wave 2 structure is unchanged.
The retrieval index — whether served by the skill or the harness — is a cache of the pinned snapshot, never a live view:
CODE_ROOT (the pinned snapshot), not the live tree.SNAPSHOT_ID changes (new pass, new pin).snapshot_pinned=false), serve results with a STALE flag or
refuse to serve — same conservative degradation as every other stage.When the pipeline runs many passes over a large codebase, the deduplicator
(/mantis-dedupe) must compare each current finding against every archived
finding — an O(n×m) comparison performed by an LLM reading summaries. At scale
(hundreds of findings across many passes), this is token-expensive and slow.
The harness can use embeddings as a fast pre-filter to reduce the candidate
space before invoking /mantis-dedupe. The skill's existing deterministic
matching (code_paths + title + discovery_commit) remains the sole
authority for hard dedup decisions.
This is entirely harness-side and opt-in. /mantis-dedupe is not modified.
Harness Action: Reads all workspace/findings/*.json (current) and
workspace/archive/findings_pass_*/*.json (archived). For each finding,
computes an embedding from a normalized text representation (e.g.,
title + description + first code_paths entry with line stripped).
Harness Action: Computes pairwise cosine similarity between current and archived findings. Surfaces candidate pairs above a configurable threshold (e.g., 0.85).
Harness Action: Writes a candidate-pairs manifest (e.g.,
workspace/helpers/dedup_candidates.json) containing the UUID pairs and
similarity scores.
mantis-dedupe invocation: The harness invokes /mantis-dedupe as usual.
If the candidate manifest exists, instruct the skill to read it and
prioritize those pairs for the LLM's pairwise comparison, instead of
comparing every finding against every archived finding. All existing
deterministic matching rules apply unchanged — the manifest only narrows
the search space.
Pre-filter only, never the decision. The embedding similarity score can
never cause a DUPLICATE verdict, a trash move, or a possible_duplicate_of
assignment. Only the skill's existing code_paths, title, and
discovery_commit checks can do that. A miss in the pre-filter only
over-retains a duplicate (safe — the LLM sees it and skips it); it never
under-retains (never drops a real duplicate).
No false negatives. The threshold should be set low enough (e.g., 0.75) to avoid missing true duplicates. Better to surface too many candidates than to miss a real one — the LLM and deterministic matching will filter false positives.
Fallback on failure. If the embedding computation is unavailable, the
candidate manifest is absent, or any error occurs, /mantis-dedupe falls back
to its existing O(n×m) comparison. The skill must not stop or error if the
manifest is missing.
Snapshot awareness. The harness should not compute embeddings across
different discovery_commit values without flagging them as cross-snapshot
candidates — the skill's Block B pairwise check will handle the final
MATCHED/NOT_MATCHED decision.
If the builder also implements Guideline 6 (Semantic Retrieval), reuse the same vector embedding infrastructure for finding embeddings. The finding embedding is a different payload (finding JSON, not KB chunks) but the same embedding capability can serve both.
For enterprise deployments tracking hundreds of thousands of vulnerabilities across distributed codebases and multi-tenant audit pipelines, SQLite vector storage can be swapped for managed cloud vector engines:
lineage_vectors in Spanner with
ARRAY<FLOAT32> vector columns. Utilize COSINE_DISTANCE with KNN search
indexes for real-time finding deduplication during parallel scan passes.pgvector):
vector extension. Store finding embeddings in a
vector(768) or vector(256) column with HNSW (vector_cosine_ops) or
IVFFlat indexes for sub-millisecond similarity queries.VECTOR_SEARCH(TABLE findings, 'embedding', ...) with COSINE distance for
serverless batch deduplication and historical regression analytics.Mantis's discovery engine is 100% LLM-generative (grep swarm + reasoning). A
weak LLM can structurally under-detect whole-program taint classes (injection,
path traversal, deserialization, UAF, format-string) that mature SAST tools
(CodeQL, Semgrep-taint) encode as interprocedural queries. A SAST seeding
adapter ingests external tool findings as PROVISIONALLY_VALID /
NEEDS_RESEARCH candidates that must earn their verdict through the unchanged
downstream gates. This is purely additive (INV-2-strengthening) — it expands
detection breadth without weakening any verification gate.
This follows exactly the RAG pattern from Guideline 6: opt-in, default off, provenance-tracked, snapshot-aware, fallback on failure.
Platform-agnostic IR (not SARIF): Rather than tying the adapter to SARIF (a complex, tool-specific format), the adapter consumes a minimal JSONL intermediate representation (IR). Any SAST tool's output (SARIF, Semgrep JSON, Bandit JSON, etc.) is converted to this IR by a thin wrapper. This maximizes platform agnosticism — the adapter works with any tool that can produce the simple JSONL format.
Two implementations are supported, sharing the same data contract:
/mantis-sast-seed)
reads the IR and uses LLM reasoning to normalize findings into mantis finding
JSONs. The LLM reads actual source code at each reported location under
CODE_ROOT to verify the finding and enrich the description with root-cause
analysis. Zero external dependencies — works air-gapped.workspace/findings/ before
invoking /mantis-dedupe.Both are opt-in. The existing skills are not modified. Seeded findings enter
workspace/findings/ alongside researcher findings and flow through the
unchanged downstream gates (dedupe -> review -> critic -> reproduce -> patch ->
calibrate).
A complete reference blueprint is available at references/mantis-sast-seed.md.
sast_findings.jsonlThe IR is a JSONL file at workspace/sast_findings.jsonl (STATE-RELATIVE). It
follows the same provenance-header pattern as chunks.jsonl (Guideline 6A).
Line 1 — Provenance header:
{"_provenance": true, "scan_snapshot_id": "abc123def456", "tool": "codeql", "tool_version": "2.15.0", "scan_timestamp": "2026-07-22T10:00:00Z"}
scan_snapshot_id: The SNAPSHOT_ID the scan was run against. This is the
primary provenance anchor — compared byte-for-byte to the current pass
SNAPSHOT_ID (same comparison as Block B). If the harness ran the SAST tool
against the pinned CODE_ROOT, it sets this to SNAPSHOT_ID.tool: Tool name (e.g., codeql, semgrep, bandit). Informational.tool_version: Tool version. Informational.scan_timestamp: ISO 8601. Informational.Lines 2+ — One finding per line:
{"rule_id": "cpp/sql-injection", "rule_name": "SQL injection", "cwe": "CWE-89", "severity": "HIGH", "code_paths": ["src/db/query.c:42"], "message": "User input flows into SQL query without sanitization"}
| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | Yes | Tool-specific rule identifier |
severity | string | Yes | CRITICAL, HIGH, MEDIUM, LOW (Mantis scale) |
code_paths | array | Yes | Array of "file:line" strings (SNAPSHOT-RELATIVE) |
message | string | Yes | Original SAST finding message |
rule_name | string | No | Human-readable rule name |
cwe | string | No | CWE identifier (e.g., CWE-89) |
IR conversion (harness responsibility): The harness converts SAST tool output to this IR before invoking the adapter. Conversion examples:
ruleId, map level to severity (error->HIGH,
warning->MEDIUM, note->LOW), extract locations to code_paths, copy
message.text.check_id as rule_id, map extra.severity to Mantis
severity, extract path:start.line as code_paths, copy extra.message.A dedicated skill reads sast_findings.jsonl, applies allow-listing, verifies
provenance, computes signature/lineage_id/discovery_commit, and writes
finding JSONs. The LLM reads actual source code at each reported location under
CODE_ROOT to verify the finding and enrich the description.
/mantis-sast-seed with
--snapshot_root/--snapshot_id/--state_root after Stage 6 (Research) and
before Stage 7 (Dedupe). The seeded findings land in workspace/findings/
before /mantis-dedupe runs.sast_findings.jsonl is absent, the skill outputs
nothing and notifies the caller. It never fails — it simply returns empty.sast_provenance.line_verified field records
whether verification succeeded.active_snapshot from state via Block A
and stamps discovery_commit only when the snapshot is pinned and the
finding's location is verified under CODE_ROOT.For maximum determinism, the harness can normalize SAST output into finding JSONs using deterministic code. This bypasses the LLM for the normalization step:
workspace/findings/.discovery_commit only if the scan provably ran
against the pinned CODE_ROOT.The adapter stamps discovery_commit ONLY if the scan provably ran against a
line-identical pinned CODE_ROOT. Verification ladder:
active_snapshot from workspace/.mantis_state.json (via Block A). If
absent, this is MODE-OFF — skip to step 5.snapshot_pinned is false, this is HALT — skip to step 6.scan_snapshot_id.scan_snapshot_id present AND exactly equals SNAPSHOT_ID.
Stamp discovery_commit = SNAPSHOT_ID. Status = PROVISIONALLY_VALID.active_snapshot absent. OMIT discovery_commit. Status =
PROVISIONALLY_VALID (MODE-OFF permits all verdicts).snapshot_pinned is false. OMIT discovery_commit. Status =
NEEDS_RESEARCH.scan_snapshot_id present but differs. OMIT discovery_commit
entirely. Status = NEEDS_RESEARCH.scan_snapshot_id absent. OMIT discovery_commit. Status =
NEEDS_RESEARCH.Line-existence verification (additional check when VERIFIED or DRIFT and
CODE_ROOT is resolved): For each finding, verify each code_paths entry: strip
trailing :line, check file exists under CODE_ROOT, check line number is within
file's line count. If file missing or line out of range -> downgrade to DRIFT
(omit discovery_commit, status = NEEDS_RESEARCH).
This is the exact same "UNTRUSTED-IF-ABSENT" pattern as discovery_commit
(schema.json) and signature/lineage_id.
workspace/sast_allowlist.json (optional config file, STATE-RELATIVE):
{
"enabled": true,
"severity_filter": ["CRITICAL", "HIGH"],
"cwe_allowlist": {
"enabled": true,
"cwes": ["CWE-89", "CWE-78", "CWE-79", "CWE-22", "CWE-787", "CWE-416", "CWE-502"]
},
"rule_allowlist": {
"enabled": false,
"rules": []
},
"per_rule_cap": 5,
"total_cap": 50
}
If the config file is absent, defaults apply: CRITICAL+HIGH only,
per_rule_cap=5, total_cap=50.
How allow-listing protects the retry cap: The reproduce stage
(/mantis-reproduce) has a hard ceiling of 6 attempts per finding (absolute,
never reset). If 1000 SAST findings are seeded without filtering, the reproduce
stage would need up to 6000 attempts — starving the retry budget. The
allow-listing chain (severity filter -> CWE/rule filters -> per-rule cap ->
total cap) ensures only a bounded, high-signal set of candidates enters the
pipeline. The review (13-rule negative filter) and critic (production viability)
stages further filter before reproduce runs.
When the SAST seed skill is available, instruct the harness to invoke it between Stage 6 (Research) and Stage 7 (Dedupe). These are runtime instructions passed by the harness — the skill files themselves are not modified:
/mantis-sast-seed with
--snapshot_root/--snapshot_id/--state_root after /mantis-researcher
completes and before /mantis-dedupe.workspace/findings/ alongside researcher findings. Dedupe processes them
identically (signature-based matching, Block B pairwise check).sast_provenance field is
informational and can be displayed in reports.The SAST seed adapter follows Block A (Locator Resolution) exactly like every other code-reading skill:
--snapshot_root / state active_snapshot.state_root/workspace/findings/ (STATE-RELATIVE).discovery_commit. All verdicts permitted.discovery_commit. Seeded findings get NEEDS_RESEARCH.discovery_commit = SNAPSHOT_ID if verified.The SAST tool output itself is NOT snapshot-aware — it may have been produced
against a different tree. The adapter's provenance verification is what bridges
the gap: it re-grounds each finding against the pinned CODE_ROOT before stamping
discovery_commit.
PROVISIONALLY_VALID /
NEEDS_RESEARCH candidates. They must pass through the unchanged downstream
gates: dedupe (Block B), review (13-rule filter), critic (viability),
reproduce (Block F reached-sink evidence + HALT ceiling), patch (Block G
re-attack), calibrate (sanity caps). No gate is weakened.VERIFIED_SECURE. Seeded findings start at PROVISIONALLY_VALID
— they can never reach VERIFIED_SECURE without passing through the full
patch + re-attack pipeline.failed_to_reproduce. Seeded findings that reach reproduce are
subject to the same Block F evidence gate and HALT ceiling.discovery_commit, Block B returns NOT_MATCHED ->
possible_duplicate_of -> finding stays active.sast_findings.jsonl is absent, no findings
written. If a finding can't be verified, NEEDS_RESEARCH.workspace/findings/ before /mantis-dedupe runs.sast_provenance is informational only. It does not affect any safety-
critical invariant, gate, or verdict. The finding's discovery_commit is the
field that governs Block B snapshot matching.For small repositories, the researcher can grep for call-sites and the planner can infer dependencies. At scale, grep-based call-site discovery is unreliable (misses indirect calls, cannot distinguish calls from comments/strings, no function boundary awareness). A structural code index provides AST-level context (function boundaries, call graphs, symbol tables) to improve LLM reasoning quality during discovery.
This follows the RAG pattern from Guideline 6: optional, provenance-tracked, snapshot-aware, fallback on failure. The structural index is a coverage HINT only — it decides ordering and prioritization, never the membership of the audit set. A miss must never cause a file, call-site, or investigation to be skipped or dropped.
The full specification — including the manifest schema, SQLite serving store, capability-based per-partition backend selection, canonical symbol IDs, query interface, baseline-plus-delta overlay, deterministic partial coverage, and safety guardrails — lives in a single source of truth:
→ ../mantis-structural-index/SKILL.md
A thin reference blueprint is at references/mantis-structural-index.md.
Two implementations are supported, sharing the same query contract:
mantis-structural-index skill
generates and runs helper scripts (build_structural_index.py and
query_structural_index.py, both # MANTIS_HELPER_VERSION = 5) using
capability-based per-partition backend selection, degrading to grep.find_callers(symbol), find_callees(function),
get_function_boundary(file, line) MCP tools, backed by the same SQLite
serving store.Both are optional. A non-conformant harness simply skips the structural index stage. The structural index supplements grep as a ranking HINT ONLY — it decides ORDER, never MEMBERSHIP of the audit set.
Consumers MUST use the query interface (query_structural_index.py) rather than
filtering JSONL directly. The query interface provides bounded results,
pagination, explicit name resolution, precision/backend metadata, and coverage
on empty results.
When a structural index is available, instruct the following skills to use it. These are the consumption contract — runtime instructions passed by the harness. The structural index is a HINT-only enhancement; skills that do not use it behave exactly as they do today:
mantis-structural-index at Stage 0.5) during KB synthesis,
cross-referencing it with dependencies.json.dependencies.json).find_callers() to SUPPLEMENT
grep as a ranking HINT for call-site discovery — it decides ORDER, never
MEMBERSHIP. It MUST NEVER replace the exhaustive Step-3 call-site sweep; every
call-site that a full grep would reach must still be audited whether or not it
ranks in the structural index. Audit the union of grep results and structural
index results. Wave 2 deep auditors use get_function_boundary() to start
with the enclosing function, expanding to callers/callees/file as needed for
cross-function context. The researcher's existing Wave 1/Wave 2 structure is
unchanged.chunks.jsonl as
entity_type: "structural" chunks.For complex services, attempting a single-shot reproduction directly against a full sandboxed service often suffers from high search entropy, brittle configuration, and hard-to-debug failures. A tiered strategy breaks reproduction into incremental milestones, while an inter-conversation retry architecture prevents reasoning deadlocks and context bloat.
Intra-Conversation Retries (Local Agent Trajectory):
Inter-Conversation Retries (Fresh Context + Accumulated Artifacts):
reproduced), the orchestrator terminates the stalled conversation and
launches a new subagent conversation (a fresh context window).state_root/workspace/archive/.repro_attempts.json and trajectory
learnings from workspace/learnings.jsonl (e.g., "Attempt 1 failed due to
missing auth header X; Attempt 2 proved parser strips unescaped quotes").Attempt Cap Accounting & Arithmetic:
state_root/workspace/archive/.repro_attempts.json.To prevent un-gated exploit execution on live infrastructure, Tier 4 (Staging / Pre-Production verification) is strictly owned and enforced by the programmatic orchestrator harness, never by LLM discretion:
mantis-reproduce executes strictly within isolated
local sandboxes (Tiers 1–3) ending at Tier 3 (reproduced /
failed_to_reproduce).reproduced verdict.
If live/staging validation (Tier 4) is configured, the harness MUST NOT
automatically invoke remote execution. It must enforce a programmatic
Human-in-the-Loop gate:
To eliminate false-positive findings caused by default edge filters ("Works on localhost:8080, but dies at the WAF/proxy"), the orchestrator can optionally execute a Tier 3 PoC through a local reverse proxy or API gateway (e.g. NGINX, Envoy, ModSecurity) running inside the local sandbox:
reproduced verdict to failed_to_reproduce.ingress_blocked: true (or edge
filter details) in the finding's repro_hints or history. This provides
empirical evidence for /mantis-critic to classify production_viability as
"CONDITIONAL_VIABLE" (mitigated by default edge proxy configuration).