Skip to content
Back to search

mantis

SkillOfficial: GoogleGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/google/mantis with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/google/mantis'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/google-mantis/badge.svg)](/listings/google-mantis)

HTML

<a href="/listings/google-mantis"><img src="/api/listings/google-mantis/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

First, install python3-venv such as with `sudo apt install python3-venv`, then run the install script. Mantis comes with automated configuration and launcher tools (`mantis-configure` and `mantis-launch`):

cd reference && ./install.sh

# 0. Authenticate Google Cloud Application Default Credentials (ADC) if using Vertex AI
gcloud auth application-default login

# 1. Fast Configuration & Capability Auto-Detection (or --interactive wizard)
python3 scripts/configure.py --auto

# 2. Fast Preflight Validation (~1s) & Live Reachability Probe
python3 scripts/configure.py --test --probe

# 3. Launch Vulnerability Review Campaign (file or repository)
./run.sh path/to/code            # a file or a directory

# 4. (Optional) Tell the planner what to hunt for, in plain language (standard pipeline)
./run.sh path/to/code --focus "look for IDOR"

# 5. (Optional) Remove spend limits for long unattended runs
./run.sh path/to/code --no-budget --parallel 32

# 6. (Optional) Research Graph Synthesis: designs a new agent-graph topology for your objective
./run.sh path/to/code --objective "Audit for Server-Side Request Forgery and SSRF in webhook handlers"

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 242 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Mantis: Portable Toolkit for Building Secure Software
  2. > [!CAUTION] **USE AT YOUR OWN RISK. BE EXTREMELY CAREFUL.** This suite is
  3. > designed to generate and execute autonomously generated code that may be
  4. > unstable or perform unexpected actions. **USE THIS ONLY IN ISOLATED,
  5. > RESTRICTED ENVIRONMENTS.** Never run this suite on a machine with access to
  6. > production systems, sensitive data, or internal networks.
  7. > [!IMPORTANT] **RESPONSIBLE USE** AI models are non-deterministic and can
  8. > hallucinate findings or generate incorrect patches. **All findings must be
  9. > manually verified by a security expert before being reported.** Do not
  10. > mass-file unverified, AI-generated reports to open-source maintainers. A
  11. > failure to automatically reproduce a vulnerability does not definitively mean
  12. > it is a false positive, nor does a successful reproducer guarantee the bug is
  13. > exploitable in all contexts. Use Mantis responsibly.
  14. > [!WARNING] **The pull request scan is untested.** The GitHub Action in
  15. > `action/`, the `mantis-pr-scan` and `mantis-knowledge-refresh` workflows under
  16. > `.github/workflows/`, and `reference/scripts/setup_github_action.sh` have been
  17. > reviewed and exercised against stubs, but have not yet been run end-to-end
  18. > against a live project. Do not use the action to gate merges. The status note
  19. > at the top of
  20. > [reference/docs/github-action.md](reference/docs/github-action.md) lists what
  21. > execution has not verified and will be removed when it has.
  22. Mantis is a set of skills along with an ADK reference harness for building
  23. secure software in the new AI era of software development.
  24. - [`skills/`](skills/) -- the method: the skills an agent loads on demand, from
  25. threat modelling through research, review, patching and reporting.
  26. - [`reference/`](reference/) -- an ADK harness that runs the method as a
  27. pipeline, with its own two skills to configure and launch it. Meant to be
  28. adapted; works as is.
  29. - [`action/`](action/) -- a GitHub Action that runs the harness over a pull
  30. request (see the warning above).
  31. ## Getting Started
  32. ### Prerequisites
  33. - **OS**: Linux, WSL2, or macOS (Apple Silicon supports local microVM sandboxes;
  34. Intel macOS works in `static-only` mode; native Windows is unsupported).
  35. - **Python**: **3.12 – 3.14** with `venv` (on Debian/Ubuntu:
  36. `sudo apt install python3-venv`).
  37. - **LLM credentials** (pick one):
  38. - **Vertex AI**: `gcloud auth application-default login` (with an active GCP
  39. project or `export GOOGLE_CLOUD_PROJECT=<project-id>`)
  40. - **Gemini API**: `export GEMINI_API_KEY=...`
  41. - **Anthropic / OpenAI / custom OpenAI-compatible endpoints**: export the
  42. provider API key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc. per
  43. [LiteLLM Providers](https://docs.litellm.ai/docs/providers)) **and** select
  44. a matching `--model` in Step 2 below
  45. ### 1. Install
  46. ```bash
  47. cd reference && ./install.sh
  48. ```
  49. `install.sh` creates `reference/.venv` and, if `docker`/`podman`/`buildah` is
  50. available, builds the optional local sandbox image for dynamic reproduction. If
  51. no container/VM tooling is available, Mantis falls back cleanly to
  52. `static-only`.
  53. ### 2. Configure & verify
  54. ```bash
  55. # Auto-detect sandbox capabilities and Vertex AI / GEMINI_API_KEY defaults
  56. # (or pass --interactive for a guided wizard). Writes gitignored workflow.local.json.
  57. .venv/bin/python3 scripts/configure.py --auto
  58. # Non-Vertex providers: set --model explicitly (required for Anthropic, OpenAI, and --api-base)
  59. # Gemini API: .venv/bin/python3 scripts/configure.py --model gemini-3.8-flash
  60. # Anthropic: .venv/bin/python3 scripts/configure.py --model anthropic/claude-sonnet-4-5
  61. # OpenAI/custom: .venv/bin/python3 scripts/configure.py --model openai/gpt-4o --api-base https://api.openai.com/v1
  62. # Optional: force static-only mode (zero VM/container requirements)
  63. .venv/bin/python3 scripts/configure.py --sandbox static-only
  64. # Fast preflight check (~1s) + live LLM reachability probe
  65. .venv/bin/python3 scripts/configure.py --test --probe
  66. ```
  67. ### 3. Run your first scan
  68. `./run.sh` activates `reference/.venv` automatically and accepts either a single
  69. file or a repository directory:
  70. ```bash
  71. # Balanced full-stack + firmware/RTL scan (defaults to --depth 30)
  72. ./run.sh /path/to/repo
  73. # Fast triage (Critical/High focus, single campaign on typical repos)
  74. ./run.sh /path/to/repo --depth 10
  75. # Exhaustive multi-pass deep audit across the repository
  76. ./run.sh /path/to/repo --depth 100
  77. # Scan a single file
  78. ./run.sh /path/to/file.py
  79. ```
  80. `--depth` takes any integer from **1** (fast shallow triage) to **100**
  81. (exhaustive full-coverage multi-pass audit) and defaults to **30**. It smoothly
  82. scales risk-ranked file coverage, batch granularity, reasoning effort,
  83. deterministic sink checklists, and pass count while always respecting existing
  84. budget guardrails (`--token-budget`, `--max-time`) and explicit CLI overrides
  85. (`--scan-mode`, `--passes`, `--reasoning-effort`, `--model`, `--sandbox`). See
  86. [reference/README.md](reference/README.md#audit-depth) for the full breakdown.
  87. ### 4. Inspect results & use Mantis during development
  88. Every run prints a summary to the terminal and saves verified findings, threat
  89. models, risk scores, coverage, and learnings in `reference/knowledge.db` (custom
  90. path via `--db`):
  91. ```bash
  92. # Query accumulated threat models, findings, and prior fixes for a file
  93. .venv/bin/python3 scripts/advise.py --file /path/to/repo/src/auth.py
  94. ```
  95. - **SARIF 2.1.0 export**: set `"sarif_output": "workspace/mantis.sarif"` in
  96. `workflow.local.json` (see
  97. [reference/README.md](reference/README.md#output-sarif)).
  98. - **IDE / coding-agent sidecar (MCP)**: connect MCP-capable coding agents (such
  99. as Gemini CLI) via [reference/docs/mcp.md](reference/docs/mcp.md) for live
  100. `mantis_check_change` diff gating and background scans.
  101. ### Common Options
  102. ```bash
  103. # One-shot model or sandbox override without changing workflow.local.json
  104. ./run.sh /path/to/repo --sandbox static-only --model vertex_ai/gemini-3.8-flash
  105. # Steer the planner in plain language, or exclude vendored/generated paths
  106. ./run.sh /path/to/repo --focus "look for IDOR"
  107. ./run.sh /path/to/repo --exclude vendor,testdata --exclude 'third_party/*'
  108. # Choose an explicit scan mode, or verify fixes incrementally after editing code
  109. ./run.sh /path/to/repo --scan-mode file-by-file # or whole, uncovered, cross-functional, auto
  110. ./run.sh /path/to/repo --scan-mode changed # new run after edits (omit --resume)
  111. # Resume an interrupted or budget-paused run on the same snapshot
  112. ./run.sh /path/to/repo --resume # inherits recorded scan mode
  113. # Export/import learned knowledge alongside a repository (.mantis/knowledge/)
  114. .venv/bin/python3 scripts/knowledge.py export --db knowledge.db --repo /path/to/repo
  115. ./run.sh /path/to/repo --import-knowledge /path/to/repo/.mantis/knowledge
  116. # Control spend ceilings and parallelism (SQLite lock wait defaults to max(60s, 15s x --parallel))
  117. ./run.sh /path/to/repo --max-tokens 2M --cache-discount 1
  118. ./run.sh /path/to/repo --no-budget --parallel 32 --db-timeout 600 # or MANTIS_DB_TIMEOUT=600
  119. # Synthesize a custom multi-agent research graph for a specific objective
  120. ./run.sh /path/to/repo --objective "Audit for SSRF in webhook handlers"
  121. ```
  122. See [reference/README.md](reference/README.md) for the complete CLI reference,
  123. scan modes, sandboxes, and Harness² evolution loop.
  124. ## Overview of Mantis
  125. Mantis is roughly designed to:
  126. - Review history of a codebase to look for historical vulnerabilities we do not
  127. wish to repeat
  128. - Build a semantic tree-sitter index (20+ native grammars across backend,
  129. frontend, mobile, smart contracts, shell/IaC/policy, and firmware/RTL) and
  130. discover repository docs (`README.md`, `SECURITY.md`, `THREAT_MODEL.md`,
  131. architecture specs) as untrusted intent context to verify against real code
  132. - Automatically generate a threat model
  133. - Build up a set of hypotheses for individual agents to research (or simply
  134. "scan every file")
  135. - Execute on those research plans
  136. - Deduplicate existing findings
  137. - Triage/critique findings to combat hallucination and statically verify
  138. production viability
  139. - Reproduce the vulnerability to varying degrees, depending on available
  140. environments, anywhere from a static guess at what an exploit might look like
  141. up to a unit test or even spinning up a mock server to attempt to exploit
  142. - Look across known vulnerabilities to attempt to build more impactful chains
  143. - Patch discovered vulnerabilities, using an adversarial loop to verify the
  144. vulnerability is really fixed
  145. - Calibrate all findings based on an established rubric to combat LLM inflation
  146. of severity (surfacing the most critical risks to humans instead of spewing
  147. thousands of "criticals")
  148. - Reflect on each iteration of the loop to look for things we've learned in the
  149. now completed round of research
  150. - Based on all of the collected learnings, threat model, and knowledge base, use
  151. the `/mantis-advise` skill (or the [MCP server](reference/docs/mcp.md)) to
  152. develop code more securely and ensure that during development you do not
  153. repeat prior mistakes or trigger edge cases in code that were previously
  154. protected by some guard that was removed
  155. Additionally, the ADK reference harness shows some of the neat ways in which we
  156. can build agentic workflows. Specifically, `reference/workflow.json` shows how a
  157. deep review is done, and research graph synthesis
  158. (`./run.sh target --objective "..."`) allows generating custom graph topologies
  159. on the fly. This is a very powerful construct because you can use this to build
  160. any kind of agentic deep dive security review you might imagine.
  161. Mantis works out of the box across full-stack web apps, backend/systems code,
  162. firmware/RTL (Verilog, SystemVerilog, VHDL, embedded/eBPF), Smart Contracts/ZK,
  163. CI/CD supply chains, mobile (Swift, Objective-C, Dart, Android), AI/ML/agentic
  164. pipelines, desktop/browser extensions, and Cloud/IaC/policy repos — with
  165. blocklist-default file selection so novel languages and DSLs are never silently
  166. dropped. It is also intended to be a starting point rather than a rigid set of
  167. instructions: you can further adapt, tune, and extend the
  168. [skills and specialized domain guides](README_AGENTS.md#adaptability--specialized-domains)
  169. to fit your organization's specific stack. We provide an ADK-based reference
  170. harness which works out of the box, but any competent coding agent should be
  171. able to convert this to use your framework of choice.
  172. We strongly recommend using AI to iterate on Mantis or integrate it with your
  173. existing harness. Use your internal documentation, coding standards, and build
  174. systems to augment the threat models you use for scanning. We also strongly
  175. recommend adapting risk calibration to your environment and risk tolerance.
  176. Above all, while orchestrated vulnerability discovery is incredibly powerful and
  177. useful, it is even more important to use this in a suitably isolated environment
  178. to prevent impacting production systems. The ADK reference harness provides some
  179. example sandboxes for testing, but if you use the most advanced frontier models
  180. you should go beyond this and additionally set up an additional sandboxing layer
  181. that itself contains very strong monitoring to look for escape attempts.
  182. ## License
  183. Mantis is licensed under the [Apache License, Version 2.0](LICENSE). Every
  184. Python and shell file carries the license header;
  185. `reference/scripts/check_license_headers.py` (run by `pre-commit` and the test
  186. suite) keeps it that way.
  187. ## Disclaimers
  188. This is not an officially supported Google product. If you are looking for a
  189. managed and hosted code security agent rather than building your own, we
  190. recommend [CodeMender](https://cloud.google.com/security/codemender). This
  191. project is not eligible for the
  192. [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).
  193. This project is intended for demonstration purposes only. It is not intended for
  194. use in a production environment.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.