TyrusRC/mantis
GitHub: TyrusRC/mantis
mantis 是一款结合 SAST 与 LLM 的本地代码安全审计工具包，通过传统静态扫描与 AI 深度推理的分阶段流水线，帮助开发者和安全工程师高效发现并确认代码漏洞。
Stars: 0 | Forks: 2
# mantis
用于本地代码安全审计的混合 SAST + LLM 工具包。
OpenGrep（或 Semgrep）负责查找候选项；LLM 则对扫描器标记的切片进行推理分析。可作为 Claude Code 的斜杠命令运行，或作为独立的 CLI 针对任何 litellm 支持的提供商运行。仅限本地运行。
## 要求
- Python 3.10+
- [OpenGrep](https://www.opengrep.dev/) 或 [Semgrep](https://semgrep.dev/)
- MCP 模式：[Claude Code](https://docs.claude.com/claude-code)
- 独立模式：任意 LLM 提供商（Anthropic, Google, OpenAI, OpenRouter, Ollama, ...）
## 安装
从 PyPI 安装（推荐）：
```
pipx install mantis-sast # the CLI binary is `mantis`
pipx install opengrep # or: pipx install semgrep
mantis --version
```
从源码安装（用于修改规则/代理）：
```
git clone https://github.com/TyrusRC/automated-code-examination-mcp.git mantis
cd mantis
./setup.sh # installs opengrep + mantis via pipx
./doctor.sh # verifies the install
```
对于 MCP 模式（Claude Code），将代理和斜杠命令复制到目标项目中：
```
./install.sh /path/to/target/project
```
## 更新
`mantis` 会在启动时每 24 小时检查一次 PyPI，如果存在新版本，将打印一行提示。若要显式检查或就地升级：
```
mantis update --check # query PyPI, bypass the 24h cache
mantis update # upgrade via the same installer used (pipx or pip)
```
设置 `MANTIS_NO_UPDATE_CHECK=1` 可禁用被动检查。可编辑安装会被跳过（您通过 git 维护它们）。
## 使用方法
### MCP（在 Claude Code 内部）
```
/audit [path] [mode] [--fix] [--lite] [focus:]
```
| 调用方式 | 行为 |
|---|---|
| `/audit` | 自动检测技术栈，全量 pipeline |
| `/audit quick` | 仅限 ERROR 严重级别、HIGH 置信度，仅分诊 |
| `/audit deep` | 每条规则，全量 pipeline |
| `/audit bugbounty` | 漏洞利用优先，以入口点可达性作为门槛 |
| `/audit cve` | 仅限 SCA / lockfile 依赖扫描 |
| `/audit mobile` \| `web` \| `desktop` \| `llm` | 限定在单一规则包范围 |
| `/audit secrets` \| `iac` \| `cloud` | 硬编码凭据 / Terraform+Dockerfile+K8s / AWS-GCP-Azure SDK 误用 |
| `/audit deep focus:auth` | 全量 pipeline，仅对带 auth 标签的发现进行深度审查 |
| `/audit --fix` | 在 worktree 中应用补丁，并重新验证 |
| `/audit --lite` | 跳过切片和深度审查 |
`focus:` 可接受：`auth`, `crypto`, `injection`, `storage`, `network`, `webview`, `secrets`, `privacy`, `ipc`, `business-logic`, `prompt-injection`。
### 独立 CLI
```
mantis init [path] # scaffold .mantis.yaml + .env.example
mantis doctor [path] # probe install, scanner, agents, keys, config
mantis audit [path] [mode] [focus:] [options]
mantis history [path] # list past runs
mantis show [ref] [--path .] # print a past report (ref: id, prefix, latest, -N)
mantis diff [a] [b] [--path .] # unified diff between two runs
mantis update [--check] # query PyPI, upgrade in place
```
值得了解的 `audit` 选项：
| 参数 | 效果 |
|---|---|
| `--since ` | 仅扫描相较于某个 git ref（`main`, `HEAD~1`, `uncommitted`, `staged`）发生变化的文件 |
| `--format md\|json\|sarif\|all` | 在 markdown 报告之外写入结构化输出 |
| `--no-cache` | 绕过基于单个文件的 SAST 结果缓存 |
| `--skip-llm` | 仅 SAST + 清单；无需提供商 |
| `--lite` | 跳过切片 + 深度审查 |
| `--fix` | 在 worktree 中应用补丁，并重新验证 |
| `--fail-on low\|medium\|high\|critical` | 如果存在任何未忽略的发现达到或超过此严重级别，则以非零状态退出（用于 pre-commit / 本地拦截） |
`audit` 模式是位置参数，并与 MCP 斜杠形式相匹配：
`mantis audit quick`, `mantis audit deep focus:auth`, `mantis audit . web --since main`。
报告会存放在 `/.mantis/runs/-.md`，并在 `/.mantis/latest.md` 和 `/security-audit-report.md` 处提供稳定的指针。使用 `--fix` 时，补丁会应用在 `../.audit-fix-/` 中；工作树永远不会被修改。
### 忽略与抑制
在目标根目录下放置一个 `.mantisignore` 文件，以屏蔽已知且被接受的发现。被抑制的发现永远不会传送到 LLM。只需提供简短的规则 ID 即可；匹配器也接受完全限定的扫描器 ID 或 fnmatch glob。
```
- rule_id: iac-k8s-host-network
path: "k8s/cni/**"
reason: hostNetwork required for our CNI in this cluster
- rule_id: iac-*
path: "tests/fixtures/**"
reason: deliberately vulnerable test fixtures
- rule_id: secret-generic-password-assignment
path: "docs/examples/**"
```
同一函数中的发现（例如一个辅助函数中的 12 个 SQLi 调用）会在分诊前被合并为一个代表性项，这样深度审查器就不必处理 12 个几乎相同的调用；报告会在代表性项上显示 `(+N similar in same function)`。
## 配置（独立模式）
目标项目中的 `.mantis.yaml`（参见 `.mantis.example.yaml`）：
```
provider: google # anthropic | google | openai | openrouter | ollama
models:
fast: gemini-2.5-flash-lite
mid: gemini-2.5-flash
deep: gemini-2.5-pro
budget:
max_findings: 200
max_deep_calls: 50
sast_bin: opengrep # opengrep | semgrep | auto
triage:
mode: single # single | dual
```
环境变量覆盖：`MANTIS_PROVIDER`, `MANTIS_MODEL_FAST`, `MANTIS_MODEL_MID`, `MANTIS_MODEL_DEEP`, `MANTIS_API_BASE`, `MANTIS_SAST_BIN`, `MANTIS_CONFIG`, `MANTIS_TRIAGE_MODE`。
API 密钥来自提供商的标准环境变量：
`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENAI_API_KEY`, `OPENROUTER_API_KEY`。Ollama 不需要密钥；只需设置 `api_base: http://localhost:11434`。
模型名称会从该文件中原样读取。工具包中没有任何硬编码的名称。
## Pipeline
```
0 inventory detect stack, lockfiles, entrypoints
1 static wide opengrep/semgrep with the selected pack
2 SCA lockfile dependency-CVE rules
3 secrets high-confidence secrets pack
4 deobf gate route minified/packed files to the deobfuscator
5 triage fast tier per finding (single or dual chain)
6 slice depth-limited callgraph, entrypoint reachability
7 deep review deep tier on reachable TRUE / NEEDS-DEEP slices
8 fix patch in worktree, re-run scanner (only with --fix)
9 report write /.mantis/runs/-.md (+ latest.md symlink)
```
根据模式和参数，阶段 6–8 会被有条件地跳过。分诊和切片在隔离的上下文中运行，以保持编排器的窗口较小。
## 仓库结构
```
mantis/ standalone CLI Python package
mantis/resources/agents/ subagent definitions (model: + tier: frontmatter)
mantis/resources/commands/ slash command for MCP mode
mantis/resources/rules/ opengrep/semgrep YAML rules + pack specs + manifest
mantis/resources/scripts/ build_manifest.py, pack_compose.py
mantis/resources/checklists/ OWASP Testing Guide chapters for the deep-reviewer
install.sh install agents/commands into a target (MCP mode)
setup.sh install opengrep + mantis CLI
doctor.sh verify install
CLAUDE.md conventions for future contributors / Claude sessions
```
资源文件位于 `mantis/` 目录下，因此它们会被打包并发布到 PyPI 的 wheel 中。CLI 会通过 `Path(__file__).parent/'resources'` 解析它们，并针对旧版安装回退到顶级目录结构。
### 子代理
| 名称 | 角色 | 层级 |
|---|---|---|
| sast-orchestrator | 规划、分发、编写报告 | mid |
| triage-analyst | 分类发现、剔除误报 (FP) | fast |
| slice-extractor | 带有入口点可达性的过程间切片 | mid |
| deep-reviewer | 确认漏洞、映射 CWE/CVSS、提供 PoC | deep |
| fix-author | 在 worktree 中进行最小化补丁修复，并重新验证 | mid |
| deobfuscator | 压缩 / 打包 / 编码文件（仅限静态） | mid |
### 规则包
| 包 | 选择范围 |
|---|---|
| `fast` | 严重级别 ERROR，置信度 HIGH |
| `deep` | 全部 |
| `bugbounty` | 严重级别 ERROR，置信度 HIGH 或 MEDIUM |
| `cve` | 设置了 `metadata.cve` 的规则 |
| `sca` | 依赖项 / lockfile 规则 |
| `mobile`, `mobile-ios`, `mobile-android` | 按语言和路径 |
| `web`, `llm`, `taint` | 按路径 |
组合一个规则包：
```
python3 mantis/resources/scripts/pack_compose.py mantis/resources/rules/packs/fast.yaml --as-args
opengrep $(python3 mantis/resources/scripts/pack_compose.py mantis/resources/rules/packs/fast.yaml --as-args) --json
```
## 仅限本地
无 CI 集成，无 forge API 调用，无发现的遥测数据。`--fix` 会写入到同级的 git worktree，绝对不会改动工作树。审计报告存放在 `/.mantis/runs/` 下；唯一的对外网络调用是每天一次的 PyPI 版本检查（设置 `MANTIS_NO_UPDATE_CHECK=1` 可禁用）。
### 发布到 PyPI
```
# 1. 在 pyproject.toml 中 bump version
# 2. clean + build
rm -rf dist build mantis_sast.egg-info
pipx run build
# 3. 检查 wheel 和 metadata
pipx run twine check dist/*
unzip -l dist/mantis_sast-*.whl | tail -5 # confirm resources/ shipped
# 4. 先上传至 TestPyPI
pipx run twine upload --repository testpypi dist/*
pipx install --index-url https://test.pypi.org/simple/ \
--pip-args "--extra-index-url https://pypi.org/simple" \
mantis-sast
mantis --version
# 5. 打 tag 并上传至 PyPI
git tag v0.1.0 && git push origin v0.1.0
pipx run twine upload dist/*
```
使用存储在 `~/.pypirc` 或 `TWINE_PASSWORD` 中的 API token（用户名为 `__token__`，密码为该 token）—— 切勿将其提交到代码库中。
## 许可证
[MIT](LICENSE)
## 致谢
- **架构**：[AGHAST](https://www.bouncesecurity.com/blog/2026/04/14/introducing-aghast), [Slice](https://noperator.dev/posts/slice/), [Vulnhuntr](https://github.com/protectai/vulnhuntr), [Tree-of-AST (Black Hat USA 2025)](https://ruik.ai/)
- **工具**：[OpenGrep](https://github.com/opengrep/opengrep), [Semgrep](https://github.com/semgrep/semgrep), [litellm](https://github.com/BerriAI/litellm)
- **标准**：[OWASP MASVS](https://mas.owasp.org/MASVS/), [MASTG](https://mas.owasp.org/MASTG/), [OWASP Top 10:2025](https://owasp.org/Top10/), [LLM Top 10:2025](https://genai.owasp.org/resource/owasp-top-10-for-llm-applications-2025/)
标签：DLL 劫持, MCP, Python, 大语言模型, 无后门, 逆向工具, 静态应用安全测试