google/mantis instruction manual

1. Purpose, scope, and Claude Code classification

Mantis is a portable, stack-agnostic collection of security-review skills plus an optional Python/Google ADK reference harness. Its goal is to help coding agents plan a review, find candidate vulnerabilities, consolidate and validate them, test production viability, reproduce them in isolation, connect findings into exploit chains, develop patches, calibrate risk, retain lessons, and produce a stakeholder report. It can be adapted to source code, hardware/RTL, infrastructure as code, ML pipelines, firmware, binaries, or staging endpoints.

**Claude Code classification: unclassified.** The supplied first-party files describe Mantis as platform-agnostic and report use with Gemini CLI, Antigravity CLI, Google ADK, and Antigravity SDK. They do not document a Claude Code plugin manifest, Claude-specific installation directory, hook, MCP server, or tested Claude Code setup. Mechanistically, Mantis is clearly a **portable skill/context-injection library** and a **sequential orchestration design**, but the evidence does not establish how it integrates specifically with Claude Code. If your agent recognizes installed Agent Skills, the documented skill commands may be available; do not assume native Claude Code integration from the supplied evidence.

This is a starting point, not a rigid scanner. Adapt threat models, risk calibration, negative filters, build knowledge, and domain assumptions to the target. The project is for demonstration, is not an officially supported Google product, is not eligible for Google’s Open Source Software Vulnerability Rewards Program, and is explicitly not intended for production use.

2. Safety model and responsible operation

Treat all generated findings, reproducers, and patches as untrusted. Mantis can generate and execute unstable code, so use a dedicated, restricted VM or equivalent isolated environment with no production access, sensitive data, credentials, or internal-network reachability. Agent instructions are not a security boundary: a non-deterministic model may skip isolation or attempt unsafe actions.

Begin in interactive, human-in-the-loop mode. Invoke one stage at a time and inspect every proposed sensitive action, especially reproduction and patching. The documentation specifically says not to use automatic-approval modes such as `--yolo` or `--dangerously-skip-permissions` unless strong containment has been implemented. Generated scripts should run only in sandboxes when you have not personally reviewed them.

Reproduction and patch verification are designed for network-disabled isolation, but successful reproduction does not prove universal exploitability, and failed reproduction does not prove a false positive. Every finding and patch must be manually verified by a security or subject-matter expert before deployment, disclosure, or reporting. Do not mass-file unverified AI reports against open-source projects.

For gVisor-backed container isolation, the documented host setup is:

sudo runsc install -- --network=none && sudo systemctl restart docker

Alternatively, register `runsc` in `/etc/docker/daemon.json` as shown in the repository. Even with gVisor, prefer a dedicated VM. Start with narrow review scopes, expect false positives, and tune `/mantis-review` negative filters before attempting repository-wide sweeps.

3. Skill installation and interactive quick start

The portable skill collection can be installed through the documented skills CLI:

npx skills add google/mantis

The repository also says you may clone it and ask your coding agent to use its skills, but it supplies no clone command or Claude-specific destination, so none is prescribed here. After installation, start your coding agent in the target software or hardware workspace using its normal launch procedure.

Run the review manually by entering slash commands inside the agent’s interactive prompt. A minimal complete pass begins with architecture and threat context, then planning, research, validation, reproduction, remediation, and reporting. Optional preparatory stages can improve context:

/mantis-history
/mantis-structural-index
/mantis-summarize
/mantis-architecture
/mantis-threat-model
/mantis-plan
/mantis-researcher
/mantis-dedupe
/mantis-review
/mantis-critic
/mantis-reproduce
/mantis-chain
/mantis-patch
/mantis-calibrate
/mantis-reflect
/mantis-report

Manual mode defaults to **MODE-OFF**: a point-in-time review of the current directory without an orchestrator-pinned immutable snapshot. It does not deadlock waiting for a snapshot, but edits made during a pass are not frozen. The opt-in snapshot-per-pass model is available through `/mantis-meta-agent` with `--sync` or a compatible harness. If synchronized state would sit inside the target, pass `--state_root=<path outside the target>` to avoid colocating mutable state with reviewed code.

At the end, manually inspect the report and approved patch diffs. The workflow does not leave source patched by default: patch testing is transactional. Apply and commit only human-approved changes. Before another pass, archive or clear `workspace/findings/` as documented, and refresh `/mantis-architecture` after any upstream synchronization.

4. Complete pipeline stage reference

The canonical flow contains sixteen review stages, with reporting as the final user-facing action:

1. **`mantis-history`** extracts commit history, churn hotspots, developer activity, and past vulnerability signals.
2. **`mantis-structural-index`** builds a content-addressed structural index: manifest, catalog, AST/symbol/function boundaries, and query helper.
3. **`mantis-summarize`** creates `mantis-summary.md` directory maps and high-level functionality summaries.
4. **`mantis-architecture`** synthesizes structure and history into the Markdown knowledge base under `workspace/kb/`.
5. **`mantis-threat-model`** records actors, assets, entry points, and trust boundaries in `workspace/kb/THREAT_MODEL.md`.
6. **`mantis-plan`** writes prioritized investigations to `workspace/plan.json`, using the KB, changed files, archived outcomes, dependency fan-out, and optional structural-index hints.
7. **`mantis-researcher`** performs deep static-analysis sweeps and writes candidate finding JSON.
8. **`mantis-dedupe`** merges same-location duplicates, preserves provenance, stages redundant files in `.trash/`, and logs transactions.
9. **`mantis-review`** checks code validity, reachability, and negative rules to filter false positives.
10. **`mantis-critic`** independently determines whether validated issues are viable in production, conditional, test-only, or non-viable.
11. **`mantis-reproduce`** creates and executes proof-of-concept reproducers in isolation.
12. **`mantis-chain`** tests whether validated findings’ postconditions satisfy other findings’ preconditions, creating separate multi-step chain findings.
13. **`mantis-patch`** designs minimal fixes in transactional shadows, replays attacks and benign controls, and stores clean unified diffs.
14. **`mantis-calibrate`** assigns a justified final 0–100 risk score.
15. **`mantis-reflect`** writes execution lessons to `workspace/learnings.jsonl` and rotates knowledge into future passes.
16. **`mantis-report`** produces the campaign-wide Markdown review packet and executive summary.

`mantis-advise` is a separate proactive developer aid: it queries accumulated security knowledge before or during future edits.

5. Planning, deduplication, viability, and exploit chaining

`/mantis-plan` has two behaviors. Mode A applies when `workspace/kb/index.md` is absent: it crawls production code, ignores tests/build/vendor directories, uses available `mantis-summary.md` files, and writes exhaustive baseline investigations. Mode B uses the KB, threat model, archived findings, reproduction-attempt cache, VCS changes, dependencies, and historical outcomes for targeted reviews. Structural-index results only prioritize work; they never remove files from scope. Ambiguous symbols must be narrowed or all matches scheduled. Unknown change state fails open to broader review in pinned/synchronized operation.

`/mantis-dedupe` compares current findings with current and archived findings. Hard deduplication requires same-location, line-inclusive evidence and similar titles; signatures may tighten candidate matching but cannot alone trash a finding. Snapshot mismatches stay active as possible regressions. Current-batch duplicates are merged deterministically, moved—not deleted—to `workspace/findings/.trash/`, and recorded in `workspace/.tx_log.jsonl`. Exact-UUID copies remain available for intentional retries.

`/mantis-critic` reads at least 15 lines around a finding and independently evaluates release-build reachability. Outcomes are `VIABLE`, `CONDITIONAL_VIABLE`, `SAMPLE_OR_TEST`, or `NON_VIABLE`. Snapshot drift, missing files, or invalid line locations conservatively become `CONDITIONAL_VIABLE`, never `NON_VIABLE`. It considers padding, disabled assertions, debug-only routes, test code, deployment controls, and reproduction telemetry.

`/mantis-chain` requires at least two validated findings whose viability is `VIABLE`, `CONDITIONAL_VIABLE`, or `SAMPLE_OR_TEST`. In pinned mode, all constituents must match the same snapshot; HALT mode creates no chains. It writes a new finding without modifying constituents, records ordered constituent UUIDs, inherits entry-point privilege and attacker position, requires interaction if any step does, and never labels a chain end-to-end `reproduced`. Existing equivalent chains in active or archived state are skipped.

6. Reproduction, patching, and verification guarantees

Dynamic work must remain isolated. `mantis-reproduce` creates PoCs and records commands, output, snapshot provenance, and reached-sink evidence. A valid evidence channel is either an in-path sidecar marker written immediately before the sink or a target-produced crash/sanitizer trace naming the sink. A wrapper’s pre-launch marker is setup evidence only. Build failures, missing commands, and missing files are evidence absence, not successful non-reproduction.

`/mantis-patch` processes reproduced findings and exploit chains. For source, it designs a minimal fix; for a binary or firmware blob without source, it does not modify the artifact and instead records `MITIGATION_PROPOSED`. Chain status is derived from constituent validity and patch status rather than patching the chain itself.

Pinned operation mandates a private temporary shadow copied from the immutable code root. All edits, compilation, reproduction, and re-attacks occur there. Legacy first attempts may use locked file backups or another rollback-safe mechanism, but must leave no pollution, prevent concurrent edits, and guarantee restoration. Mantis stores a VCS-agnostic unified diff and rolls the source back; users apply approved patches manually.

`VERIFIED_SECURE` has a strict gate: the bug must trigger on a fresh unpatched copy with reached-sink evidence; the patched build must compile; a benign input must still reach the sink without crashing; the attack must stop triggering; and an independent re-attack must try at least three valid variants, all unsuccessful. Sanitizer flags must remain identical across baseline, benign, attack, and re-attack runs. Missing evidence, no benign control, infrastructure limits, or unset re-attack status yields `VERIFICATION_INCOMPLETE`; a still-triggering attack yields `VERIFICATION_FAILED`; invalid current baselines or missing files yield `ERROR`. HALT/degraded mode can never emit `VERIFIED_SECURE`.

7. Snapshot lifecycle, state layout, and reporting

Mantis distinguishes three states. **MODE-OFF** has no `active_snapshot` and preserves legacy point-in-time behavior. **PINNED** has an immutable snapshot plus exact snapshot ID; source reads use that code root while mutable artifacts remain under `state_root/workspace/`. **HALT** records an attempted but unpinned live snapshot and forbids authoritative verdicts. A stale pass binding or sentinel mismatch must stop or degrade safely.

Snapshot-relative paths include source `code_paths` and planned target files. State-relative paths include findings, KB references, reproducers, reports, helpers, archives, and `.mantis_state.json`; never prefix these with the code root. Pinned code is read-only. VCS history, diff, and blame operate on the live repository because snapshot copies omit VCS metadata. Snapshot comparisons are exact strings, never fuzzy matches.

`/mantis-report` reads active findings and newest archived open findings, conservatively folding only exact UUIDs or records sharing lineage, signature, and a line-inclusive code path. It includes chains, reproduced findings, and statically confirmed findings only when empirical crash/sanitizer evidence exists. Low-priority items move to an appendix. It redacts credentials, PII, internal hostnames, and overly weaponized payloads.

The report groups standard findings into independently verified patches, proposed/incomplete mitigations, and unpatched/failed verification. Chains appear only under **Exploit Chains (Not End-to-End Reproduced)**. Reports are written as `workspace/report/review_packet_pass_<N>_<snapshot_tag>.md`, or the legacy unsuffixed name when no snapshot exists. `workspace/report/review_packet-latest.md` always points to or copies the current campaign-wide report. HALT, dirty-tree, and mixed-snapshot warnings are added when applicable.

8. ADK reference harness: install, configure, and launch

The `reference/` directory is a Google ADK implementation of the complete campaign graph. Native Windows is unsupported; use WSL2. Linux, including WSL2, follows the standard path. macOS can install, but KVM microVMs are unavailable, so dynamic execution needs a container runtime or static-only analysis.

From the repository root, the documented setup is:

cd reference && ./install.sh

gcloud auth application-default login

python3 scripts/configure.py --auto
python3 scripts/configure.py --test
./run.sh path/to/code

The installer creates `.venv`, installs hash-pinned requirements, and attempts to build/load `mantis-sandbox:latest` using Buildah, Podman, or Docker. Failure to build the image does not prevent static analysis, but dynamic reproduction then needs another supported backend.

Configuration is layered. Tracked `workflow.json` defines the graph and defaults; ignored `workflow.local.json` contains machine-specific project, model, and sandbox values. `configure.py --auto` and `run.sh` auto-heal placeholders into the local overlay so the tracked file stays clean. `--no-auto-configure` disables healing; `--save-tracked` or `--global` writes base configuration.

Select static-only mode with:

python3 scripts/configure.py --sandbox static-only

Or override sandbox and model for one campaign:

./run.sh path/to/code --sandbox static-only --model gemini-3.7-flash

`mantis-configure` detects virtualization/cloud capabilities, configures sandboxes and providers, and runs preflight checks. `mantis-launch` validates readiness, accepts file or repository targets and CLI overrides, then executes the sixteen-node review graph. A workflow node may load a canonical skill through ADK `SkillToolset`, or use a custom Markdown `system_prompt` with directly attached tools.

9. Sandbox backends, typed tools, and schema generation

The reference harness implements four ADK environments. **StaticOnlyEnvironment** has no virtualization dependency and skips exploit execution and patch testing. **GvisorEnvironment** uses Docker/Podman plus `runsc`, a networkless container, and `/workspace` isolation. **MicrosandboxEnvironment** uses libkrun/KVM microVM isolation with `Network.none()`. **GceEnvironment** creates a hardened ephemeral single VM with a private non-internet VPC, DNS blackholing, no service account or external IP, and IAP SSH tunneling. GCE requires a project, isolated VPC/subnet, and custom image; microVMs require `/dev/kvm`.

The supplied automated GCE setup entry point is:

PROJECT_ID=your-gcp-project SOURCE_INSTANCE=your-dev-vm ./reference/scripts/setup_gce_sandbox.sh

Review the first-party GCE guide before unattended deployment; the root documentation requires hardening against prompt injection and network exfiltration.

The harness exposes typed, SQLite-backed domain tools. `report_findings(report)` validates and stores a `VulnerabilityReport`; `get_findings()` returns findings for the current target; `dedupe_findings(...)` merges duplicates; `record_plan(plan)` writes the validated plan; `record_threat_model(...)` writes `THREAT_MODEL.md`; `record_summary(...)` writes `mantis-summary.md`; `record_exploit_chain(...)` stores a chain; `score_risk(score, reasoning)` enforces a 0–100 score; `record_learning(...)` rotates a learning into SQLite; and `generate_report(...)` writes the latest review packet.

The canonical root `schema.json` generates the Pydantic state contracts in `core/schemas.py`. Regenerate them with the documented command:

python3 reference/scripts/generate_schemas.py

This is intended to keep skills, external orchestrators, and the ADK harness aligned on one schema rather than maintaining duplicate models.

10. Security Advisor, troubleshooting, limits, and contribution policy

After a campaign populates `knowledge.db`, `mantis-advise` supplies pre-implementation guidance from threat models, historical lineages, verified patches, triaged false positives, learnings, and risk scores. Query a file, a lineage, or JSON output:

python3 reference/scripts/advise.py --file src/auth.py
python3 reference/scripts/advise.py --lineage c3a5e982-1234-5678-9abc-def012345678
python3 reference/scripts/advise.py --file src/auth.py --json

The database defaults to auto-discovered `knowledge.db` or `workspace/knowledge.db`; `--db` selects another path, and `--signature` queries a content signature. Programmatic use is also documented:

from core.database import query_security_guidance

guidance = query_security_guidance(db_path="knowledge.db", filepath="src/auth.py")
print(guidance["guidance_summary"])

Use the advisor before endpoints, parsers, path handling, subprocess calls, or vulnerable-component refactors. Review trust boundaries, recurring lineage, verified safe idioms, and intentional false positives. It advises but does not replace review or run the multi-pass offensive pipeline.

If later passes repeatedly scan the same code, verify that `/mantis-architecture` completed, that `workspace/kb/` is writable, and that its synthesized KB exists; `/mantis-plan` relies on it to avoid duplication. For other failures, inspect the agent conversations and execution trajectories with a coding tool, as the repository suggests.

Mantis remains non-deterministic and demonstration-only. Static-only mode cannot dynamically reproduce or verify patches. External tools, cloud access, virtualization, build dependencies, and model providers vary by target. The repository accepts no external pull requests or code contributions at this time; users are encouraged to fork and remix skills for specialized workflows. Any automated changes to security-critical skill prompts should remain human-gated to resist prompt-injection-driven weakening of global review rules.