0xSteph/pentest-ai · 上手攻略

• 仓库：0xSteph/pentest-ai
• 链接：https://github.com/0xSteph/pentest-ai
• 分类：安全工具 · AI 渗透测试 · MCP
• 作者：Tom
• 更新：2026-07-18

这是什么

pentest-ai（CLI 入口 ptai）是一个 AI 驱动的渗透测试框架。核心创新不是"发现更多漏洞"，而是每个漏洞都必须被机器 Oracle 重复验证才能进入最终报告。思路借鉴 TruffleHog：TruffleHog 发现泄露密钥后实际登录验证，ptai 发现 Web 漏洞后实际重新触发一遍。一个 finding 停留在"候选"状态，直到 Oracle 对目标重放成功 N 次，才标记为 VERIFIED——假阳性在 Oracle 层被直接过滤，不进报告，不浪费分析师的时间。

这与传统 AI 渗透工具的逻辑恰好相反：大多数工具追求高检出率，代价是假阳性爆炸；ptai 追求高精度，代价是验证覆盖率受探针库限制。官方认为这是一个正确的取舍——"假阳性训练团队忽略工具"比"漏报"更伤害安全团队。

官方基准数据（均可自行 replay 验证）： - OWASP Juice Shop（标准靶场）：单次扫描 12 个 VERIFIED，100% 精度，零假阳性 - 自建 Honeypot（含人工植入漏洞）：23 个 VERIFIED，跨越 14 个漏洞类，100% 精度 - 覆盖：205+ 工具封装，60+ SPA 感知探针，17 个专项 Agent，MIT 协议，本地运行，无遥测数据外发

解决什么问题

安全团队在实际渗透测试中面临三个常见痛点，ptai 分别对应解决：

痛点一：扫描器噪音导致警报疲劳。nuclei、nikto、ZAP 这些扫描器输出几十上百条 findings，分析师逐条判断真假，效率低下。ptai 把所有第三方扫描器输出按住，直到 Oracle 验证成功才放行，最终报告只呈现经过机器证明的高置信度发现。

痛点二：认证劫持和多步攻击链难以自动化。大多数扫描工具遇到登录页就卡住。ptai 内置会话维持机制，持有登录 Cookie 并在工具链中向下传递；同时维护 Findings 数据库，支持多步攻击链分析（IDOR → 提权 → RCE）。

痛点三：内网隔离和离线环境无法使用云端 LLM。ptai 支持 Ollama 完全离线运行，也支持接入任何 OpenAI 兼容端点（DeepSeek、Groq、Together AI、vLLM 等），不绑定任何云服务商的密钥体系。

快速安装

pip install ptai

Python ≥ 3.10。无需 API Key 即可运行（MCP 路径使用 Claude 订阅，Ollama 路径完全免费）。

核心用法

路径一：MCP 集成（Claude Code 用户，零额外配置）

MCP 是 ptai 最推荐的用法。Claude Code（Pro/Max/Team 订阅）用户不需要任何 API Key，ptai 通过 MCP 协议调用你的 Anthropic 订阅：

# 添加 MCP Server
claude mcp add pentest-ai -- ptai mcp

# 重启 Claude Code，然后直接对话：
# "Run an authenticated pentest against staging.acme.com.
#  Login page is at /login, credentials in $APP_PASS."

ptai 提供 47 个 MCP 工具对 LLM 可见： - list_tools / run_tool：列出并调用 200+ 封装安全工具 - list_probes / run_probe：运行 60+ SPA 感知探针，覆盖 OWASP Top 10 - http_request：原始 HTTP 请求，在严格 scope 保护下发送 - start_engagement / get_findings / get_attack_chains：Engagement 生命周期管理 - test_web_app / test_api_security / test_active_directory / test_cloud：专项测试入口

其他 MCP 客户端（Claude Desktop、Cursor、Codex）：

ptai setup --mcp
# 自动检测本机已安装的 MCP 客户端，写入对应配置文件

MCP 路径不消耗 PTAI_PRICE_LIMIT 费用上限，计费由 Claude Code 等客户端自行处理。

路径二：独立 CLI（自带 LLM 编排）

这个路径需要自备 LLM，支持四种方式，优先级从高到低：

A. Anthropic Claude（推荐，效果最好）

export ANTHROPIC_API_KEY=sk-ant-...
ptai start https://target.com
# 默认模型 claude-sonnet-4-20250514
# 指定模型：export PENTEST_AI_MODEL=claude-opus-4-5

B. OpenAI 或 OpenAI 兼容端点（DeepSeek / Groq / Together AI / vLLM / LM Studio）

# 真实 OpenAI
export OPENAI_API_KEY=sk-...

# 第三方 OpenAI 兼容端点（必须设置 BASE_URL + MODEL）
export OPENAI_API_KEY=<your-deepseek-key>
export OPENAI_BASE_URL=https://api.deepseek.com/v1
export PENTEST_AI_MODEL=deepseek-chat        # 必须指定，第三方默认 gpt-4o 会 404

# Groq 示例
export OPENAI_BASE_URL=https://api.groq.com/openai/v1
export PENTEST_AI_MODEL=llama-3.3-70b-versatile

# 本地 vLLM / LM Studio
export OPENAI_BASE_URL=http://localhost:8080/v1
export PENTEST_AI_MODEL=<your-server-model-name>

C. Ollama（完全本地，免费）

# 确保 Ollama 已运行（默认 localhost:11434）
ollama serve
ollama pull llama3   # 拉取模型

export PENTEST_AI_LLM_PROVIDER=ollama
export PENTEST_AI_MODEL=llama3
ptai start https://target.com

D. LiteLLM（300+ 模型任意选）

pip install litellm
export PENTEST_AI_LLM_PROVIDER=deepseek  # 或 groq / together / azure / openrouter
export OPENAI_API_KEY=<对应key>

费用上限（独立 CLI 路径）：默认 $10 USD / engagement，深度扫描 Opus 4.7 模型可能超出。

export PTAI_PRICE_LIMIT=25   # 调高上限
ptai start https://target.com
# 若上限触发，状态标记为 aborted_cost_limit，检查点保留
ptai resume <engagement_id>  # 调高后恢复

路径三：REST API

pip install "ptai[api]"
ptai serve --port 8888
# GET  /health, /version, /agents, /tools
# POST /engagements           → 启动新扫描
# GET  /engagements/{id}      → 扫描详情
# GET  /engagements/{id}/findings
# GET  /engagements/{id}/chains
# WS   /engagements/{id}/stream  # 实时事件流
# 写入端点（POST /engagements 等）需要 Authorization: Bearer $PENTEST_AI_API_TOKEN

零目标演示（2 分钟体验，无需任何目标）

ptai demo

演示流程：扫描内置靶场，报告 4 findings → 4 个全部 oracle-VERIFIED → replay 其中一个证明胶囊（3/3 重放成功）→ 扫描同一靶场的加固版本 → 0 findings。Findings 随漏洞存在/消失，证明验证机制真实有效，而非工具沉默。

工具封装与安装策略

ptai 封装了 205+ 安全工具，涵盖：nmap、sqlmap、nikto、nuclei、ZAP、dirb、ffuf、dalfox、wpscan、paramspider 等。

安装方式分三级：

# 按需安装（推荐）：LLM 预测需要哪些工具，一次性提示安装
ptai start https://target.com

# 批量安装
ptai setup --tier core        # ~6 核心工具，约 30 秒
ptai setup --tier recommended # + fuzzers、crawlers、密码工具，约 5 分钟
ptai setup --tier full        # 全部，约 30 分钟

# 指定工具
ptai setup --per-tool wpscan,dalfox,paramspider
ptai setup --wizard            # 交互式选择器

结果验证与 CI 集成

ptai findings <engagement_id>   # 列出所有 findings 及状态
ptai replay <finding_id>        # TUI 重放攻击步骤，VERIFIED 状态实时翻转

# CI 门禁：只在发现 VERIFIED findings 时失败构建
ptai start https://target.com --fail-on verified

# 导出格式
ptai export --format sarif <engagement_id>  # GitHub SAST 兼容
ptai export --format junit <engagement_id>  # JUnit XML

Oracle 验证覆盖的 14 个漏洞类

每个 Oracle 类均内置 safe-target 控制测试：如果目标无此漏洞，Oracle 主动放弃而非假阳性通过。

探针库还检测更多漏洞（SQLi UNION、Auth-Bypass 等），但仅通过 Oracle 验证的 finding 才进入最终报告。

典型使用场景

坑与注意

1. Oracle 验证会真实发包：ptai 在目标上实际触发漏洞做验证，不只是读扫描结果。必须在书面授权范围内使用，项目明确要求接受 AUP（可接受使用政策）。

2. Ollama 端口和环境变量：默认 localhost:11434，远程 Ollama 实例用 OLLAMA_HOST 环境变量覆盖，如 export OLLAMA_HOST=http://your-ollama-server:11434。

3. 本地模型质量影响 LLM 编排层：Oracle 验证是确定性算法，不依赖 LLM；但攻击链规划、多步推理、报告生成依赖 LLM 的能力。Llama3 70B vs Sonnet 4 在复杂多步场景有明显差距，有条件优先使用 Claude。

4. 费用上限仅对独立 CLI 生效：MCP 路径由 Claude Code 等客户端自行计费，PTAI_PRICE_LIMIT 在该路径下无效。

5. 默认 $10 上限可能不足：使用 Opus 4.7 等大模型进行深度扫描时，建议 export PTAI_PRICE_LIMIT=25 或更高。

6. --no-llm 纯探针模式：跳过 LLM 编排，只运行确定性探针，结果不进入 VERIFIED 报告流程。

7. Scope Safety 机制：sqlmap、dalfox 等主动工具被主机锁定在 engagement 范围内，不会对爬取到的第三方 URL 发包。内网测试时请注意 DNS 解析范围。

与同类工具对比

核心差异在于 Oracle 验证是 ptai 独有的机制。传统工具追求检出率，用人工判断过滤假阳性；ptai 用确定性机器重放替代人工判断，从根本上消除假阳性进入报告的可能性。

一句话推荐结论

授权渗透测试场景下，如果你最头疼假阳性噪音导致团队对工具失去信任、或者客户质疑报告可信度，pentest-ai 的 Oracle 验证机制是当前开源领域里把"每个发现都机器重跑一遍"做得最彻底的方案——报告里每一个 VERIFIED 都附带 proof capsule，可以当场 replay 给客户看。

数据来源：项目 README、docs/llm-providers.md（github.com/0xSteph/pentest-ai），2026-07-18 访问验证。所有用法仅限书面授权的渗透测试环境。