PentesterFlow/agent

``` $ pentesterflow ╭────────────────────────────────────────────────╮ │ PentesterFlow │ │ local agent · tools ready · analyst approved │ ╰────────────────────────────────────────────────╯ › /target https://app.example.com target set to https://app.example.com › test the orders API for broken access control ⏺ Skill webvuln ⎿ loaded skill: webvuln ⏺ http GET https://app.example.com/api/v1/orders/1043 ⎿ 200 OK ⏺ BashTool(curl -s -H "Authorization: Bearer $USER_B" ...) ⎿ cross-account response confirmed ⏺ Confirmed Finding (high) IDOR on /api/v1/orders/{id} ⎿ written to ./findings/idor-orders.md ``` ## 概述 PentesterFlow 是一个开源的终端助手，专为授权的攻击安全工作而设计。它连接到本地或托管的 LLM，针对范围内的目标进行规划，使用真实的渗透测试工具，在执行敏感操作前请求批准，跨会话记住有用的经验教训，并撰写有证据支持的发现。 它围绕三个理念构建： - **分析人员控制**：由人批准敏感操作并决定范围。 - **透明的执行**：curl 优先、可复现的命令、可见的工具调用、保存的证据，以及易于审计的日志。 - **操作学习**：本地项目和个人知识库可改善未来的会话，无需重新训练模型或增加面向用户的复杂性。 ## 为什么选择 PentesterFlow 当前的 AI 代理系统通常难以处理安全相关的特定工作流，容易出现幻觉发现、上下文保留能力弱、工具集成差以及可审计性有限等问题。PentesterFlow 通过以下方式解决了这些痛点： | 挑战 | PentesterFlow 的方法 | |---|---| | 通用的 AI 工作流 | 内置针对侦察、Web 漏洞、SSRF、SSTI、JWT、GraphQL、竞态条件、接管、Supabase 和反序列化的渗透测试技能。 | | 幻觉发现 | `confirm_finding` 仅应在使用请求/响应证据复现后使用。 | | 长期测试 | 保存的会话、压缩、上下文快照、恢复摘要和持续的本地学习。 | | 真实工具 | Shell/Bash、HTTP、Burp 桥接、浏览器捕获、MCP、文件工具、grep/glob 和自定义插件。 | | 人工监督 | 权限提示、允许一次/会话决策，以及用于实验室的显式 YOLO 模式。 | | 可重现性 | 可直接复制粘贴的命令、Markdown 发现、JSON-lines 日志和稳定的会话文件。 | | 大型攻击面 | 覆盖率跟踪、`/next`、技能、捕获的流量查询以及学习到的覆盖率缺口。 | ## 核心能力 | 领域 | 提供的功能 | |---|---| | Agent 循环 | 针对范围内的任务进行规划、行动、观察、验证、报告和学习。 | | 模型后端 | Ollama、LM Studio、Kimi、Groq、Gemini 和兼容 OpenAI 的 API。 | | 工具 | Shell/Bash、HTTP、文件工具、搜索、浏览器捕获、Burp 摄取、MCP 和发现确认。 | | 技能 | 包含方法论、Payload、约束和允许工具的 Markdown Playbook。 | | 记忆 | 会话记忆、上下文快照、恢复摘要和持续的本地智能。 | | 报告 | 确认的发现将连同证据、影响、PoC 和修复建议保存到 `./findings/.md`。 | | 用户体验 | 全屏终端 UI、斜杠命令、紧凑的记录、权限弹窗以及交互式的提供商/模型设置。 | ## 安装说明 安装程序会为您的操作系统下载最新的独立二进制文件，并在可用时验证已发布的 SHA-256 校验和。 ``` # macOS / Linux curl -fsSL https://raw.githubusercontent.com/PentesterFlow/agent/main/install.sh | sh ``` ``` # Windows PowerShell irm https://raw.githubusercontent.com/PentesterFlow/agent/main/install.ps1 | iex ``` 固定版本或选择安装目录： ``` PENTESTERFLOW_VERSION=v0.1.6 PENTESTERFLOW_INSTALL_DIR="$HOME/.local/bin" \ sh -c "$(curl -fsSL https://raw.githubusercontent.com/PentesterFlow/agent/main/install.sh)" ``` 直接从 [GitHub Releases](https://github.com/PentesterFlow/agent/releases) 下载二进制文件： | 操作系统 | 文件 | |---|---| | macOS | `pentesterflow-darwin-arm64`, `pentesterflow-darwin-x64` | | Linux | `pentesterflow-linux-arm64`, `pentesterflow-linux-x64` | | Windows | `pentesterflow-windows-x64.exe` | x64 独立二进制文件是使用 Bun 的基线 runtime 为较旧的 x86_64 CPU 构建的。它们不需要 AVX2。 ## 快速开始 ``` # 本地模型示例 ollama pull qwen2.5-coder:32b pentesterflow ``` 在 CLI 中： ``` /provider /target https://app.example.com map the authenticated API surface and test for IDOR ``` 恢复之前的评估： ``` pentesterflow --resume ``` 恢复时，PentesterFlow 会自动显示上一个会话的持久记忆摘要，因此您无需手动重建上下文即可继续。 ## 提供商 交互式设置： ``` /provider /model list /model ``` CLI 示例： ``` # Ollama pentesterflow --backend ollama --model qwen2.5-coder:32b # LM Studio pentesterflow --backend lmstudio --model zai-org/glm-4.7-flash # OpenAI-compatible endpoint pentesterflow --backend openai-compat \ --base-url https://api.example.com/v1 \ --api-key sk-... # Kimi MOONSHOT_API_KEY=sk-... pentesterflow --backend kimi --model kimi-k2.6 # Groq GROQ_API_KEY=gsk_... pentesterflow --backend groq --model openai/gpt-oss-20b # OpenRouter OPENROUTER_API_KEY=sk-or-... pentesterflow --backend openrouter --model openrouter/auto # DeepSeek DEEPSEEK_API_KEY=sk-... pentesterflow --backend deepseek --model deepseek-v4-flash # Gemini GEMINI_API_KEY=AIza... pentesterflow --backend gemini --model models/gemini-3.5-flash ``` 注意事项： - Groq 会话使用紧凑的提示和较低的压缩阈值，以避免在长时间评估期间出现按需 TPM 错误。 - LM Studio 响应受到 stop token 和模板标记修剪的保护，以避免重复的 `<|user|>` / `<|observation|>` 泄漏。 - Gemini 选择器会突出显示推荐和低成本的模型。 ## 渗透测试生命周期 PentesterFlow 旨在协助整个测试过程： 1. **范围**：设置目标 URL、约束、凭证和授权说明。 2. **侦察**：发现主机、endpoint、技术、文件、API 和暴露的元数据。 3. **枚举**：映射参数、角色、认证状态、捕获的浏览器/Burp 流量以及攻击面。 4. **验证**：使用确定性请求重现候选问题，并比较证据。 5. **覆盖率**：跟踪已测试的 endpoint/参数/漏洞类别元组，并使用 `/next` 获取未测试的工作。 6. **报告**：将确认的发现与 PoC、证据、影响和补救措施一起持久化保存。 7. **学习**：静默保存可重用的经验教训，以改善未来的会话。 ## 持续学习 PentesterFlow 包含一个本地持续学习系统。它可以改善未来的会话，而无需重新训练模型权重，也无需用户手动管理记忆。 它存储的内容： - 用户偏好和工作风格。 - 重要的决策和项目上下文。 - 成功的工作流和经过验证的命令。 - 错误、失败的假设以及吸取的教训。 - 覆盖率缺口、遗漏的检查和后续场景。 - 发现模式和证据要求。 - 运行良好的工具/配置模式。 它存储记忆的位置： | 路径 | 用途 | |---|---| | `./.pentesterflow/intelligence/scenarios.jsonl` | 针对当前工作区/工作空间的项目特定智能。 | | `~/.pentesterflow/intelligence/scenarios.jsonl` | 跨未来项目的个人可重用智能。 | 它的行为方式： - 学习在完成的回合和压缩后在后台运行。 - 检索是静默的，仅在相关时作为隐藏上下文注入。 - 重复的项目/个人记忆在到达模型之前会进行去重。 - 敏感数据在存储前会被脱敏处理。 - 学习失败会被记录下来，而不是显示为面向用户的任务错误。 这使得用户体验保持简单，同时随着时间的推移使 Agent 更加有效。 ## 会话记忆与恢复 PentesterFlow 将会话保存在 `~/.pentesterflow/sessions/*.json` 下。 ``` ls -lt ~/.pentesterflow/sessions/*.json | head pentesterflow --resume ``` 会话连续性包括： - 保存的对话历史。 - 持久化的压缩记忆。 - 目标状态。 - 启动时的恢复摘要。 - 位于 `~/.pentesterflow/context/` 下的上下文快照。 - 活动会话期间每五分钟进行一次自动快照。 有用的命令： | 命令 | 用途 | |---|---| | `/compact` | 将当前会话总结为持久记忆。 | | `/memory` | 显示保存的事实 + 会话检查点。 | | `/memory add ` | 保存一个持久事实（等同于 `#`）。 | | `/memory list` | 列出保存的事实。 | | `/memory forget ` | 丢弃与文本匹配的保存事实和检查点项目。 | | `/snapshot` | 立即写入已脱敏的上下文快照。 | | `/next [objective]` | 请求基于覆盖率的下一步操作。 | ### 保存的记忆（`#` 快速添加） 输入 `#` 并在后面加上您希望 Agent 在本次会话及以后记住的任何内容——例如 `#orders API 在 /api/orders/{id} 上容易受到 IDOR 攻击`。使用 `#!` 可将其保存到您的**个人**范围，而不是项目范围。 - 保存的事实是持久的、人类可读的 Markdown——每个事实一个文件，包含 frontmatter——位于 `./.pentesterflow/memory/`（项目）和 `~/.pentesterflow/memory/`（个人）下，并带有生成的 `MEMORY.md` 索引。 - 事实目录在**每个**回合都会被固定在系统提示词中，因此它能够在压缩后保留下来；与当前回合最相关的事实会被自动完整召回（您会看到一行 `recalled memory: …`）。 - 敏感信息在事实写入磁盘前会被脱敏。 - 使用 `#` / `/memory add`、`/memory list` 和 `/memory forget ` 管理它们。 ## Burp 集成 使用配套的 [PentesterFlow Burp 集成](https://github.com/PentesterFlow/Burp-Integration) 工具将选定的 Burp 流量发送到 CLI 中，并将确认的发现导回 Burp。 启动本地 PentesterFlow 监听器： ``` pentesterflow --burp pentesterflow --burp 9999 ``` 从源码运行： ``` npm run dev -- --burp 9999 ``` Burp/PentesterFlow 桥接支持： - 将选定的 Burp 请求发送到 PentesterFlow。 - 将请求排队作为扫描任务。 - 将确认的发现导回 Burp issues。 - 保留完整的原始请求，以便用于证据和重放。 - 通过 `browser_capture_*` 工具读取捕获的请求和 issues。 默认监听器为 `http://127.0.0.1:9999`。 ## 浏览器捕获与 MCP `pentesterflow --burp` 启动一个本地摄取服务器，用于捕获请求、endpoint 和浏览器快照。配套的 `pentesterflow-browser-mcp` 二进制文件将相同的捕获数据作为 MCP 服务器公开给兼容的客户端。 ``` { "mcpServers": { "pentesterflow-browser": { "command": "pentesterflow-browser-mcp", "args": [] } } } ``` ## 斜杠命令 | 命令 | 描述 | |---|---| | `/help` | 显示快捷键和命令参考。 | | `/provider` | 以交互方式选择后端、API key 和模型。 | | `/model ` / `/model list` | 切换或列出后端模型。 | | `/plan [objective]` | 仅规划回合，不执行工具。 | | `/next [objective]` | 基于覆盖率的下一步测试建议。 | | `/target ` | 设置或清除测试的根 URL。 | | `/compact` | 总结为持久会话记忆。 | | `/memory` | 显示当前的持久会话记忆。 | | `/snapshot` | 立即写入已脱敏的上下文快照。 | | `/burp [port]` | 启动本地 Burp/PentesterFlow 桥接并打印其 URL + token。 | | `/skills [enable\|disable\|new ]` | 管理或生成技能脚手架。 | | `/maxsteps ` | 设置每回合的工具调用上限。 | | `/thinking on\|off` | 切换可见的推理指导。 | | `/update [version]` | 安装最新或固定的版本。 | | `/yolo [on\|off]` | 为实验室环境切换自动批准模式。 | | `/reset` | 清除对话和已保存的会话状态。 | | `/clear` | 仅清除屏幕上的记录。 | | `/` | 将技能加载到下一个回合中。 | | `/exit` | 退出。 | ## 命令行标志 | 标志 | 描述 | |---|---| | `--backend ollama\|lmstudio\|kimi\|groq\|openrouter\|deepseek\|gemini\|openai-compat` | 选择 LLM 后端。 | | `--model ` | 设置模型 ID。 | | `--base-url ` / `--api-key ` | 配置远程或兼容 OpenAI 的后端。 | | `--skills ` | 加载额外的技能目录。 | | `--resume ` | 恢复已保存的会话并显示摘要。 | | `--browser` | 为当前会话启用浏览器 MCP 具。 | | `--burp [port]` | 启动本地 Burp/PentesterFlow 桥接。 | | `--browser-ingest [port]` | 已弃用的 `--burp` 别名。 | | `--no-stream` | 对有 SSE/工具调用问题的提供商禁用流式传输。 | | `--yolo` | YOLO 模式：自动批准非敏感工具调用（别名：`--dangerously-skip-permissions`）。 | | `--list-tools` / `--list-skills` | 打印已注册的工具或发现的技能。 | | `--log ` | 覆盖 JSON-lines 日志路径。 | | `--debug-session` | 写入完整的 JSON-lines 调试会话日志。 | | `--debug-session-path ` | 将调试会话日志写入自定义路径。 | | `--version` / `--help` | 打印版本或帮助信息。 | ## 工具 | 工具 | 用途 | |---|---| | `shell` / `BashTool` | 在批准和安全检查下运行 shell 命令。 | | `http` | 向完整 URL 或活动的 `/target` 发送 HTTP/HTTPS 请求。 | | `file_read` / `file_write` / `file_edit` | 读取、创建和修补文件。 | | `GlobTool` / `GrepTool` | 发现文件和搜索内容。 | | `web_fetch` / `web_search` | 抓取页面或执行网络搜索。 | | `ask_user` | 在范围或方向不明确时请求做出决策。 | | `confirm_finding` | 将验证过的发现保存到 `./findings/.md`。 | | `coverage` | 跟踪已测试的 endpoint/参数/漏洞类别元组。 | | `load_skill` | 将方法论 Playbook 加载到上下文中。 | | `browser_capture_*` | 查询捕获的浏览器/Burp 流量、endpoint、请求、issues 和快照。 | ## 技能 技能是打包了方法论、Payload 和工具约束的 Markdown Playbook。内置技能包括： | 技能 | 重点 | |---|---| | `recon` | 子域名、指纹识别、内容发现和攻击面映射。 | | `webvuln` | IDOR、访问控制失效、注入、认证和会话逻辑。 | | `ssrf` | 过滤器绕过、元数据访问、内部可达性和盲 SSRF。 | | `ssti` | 模板引擎指纹识别和提权路径。 | | `jwt` | 算法混淆、`kid` 滥用、弱密钥和 token 验证缺陷。 | | `graphql` | Introspection、授权缺口、批处理和深度滥用。 | | `race` | TOCTOU 问题、限制绕过和竞态条件验证。 | | `takeover` | 悬挂 DNS 和无人认领的云资源。 | | `supabase` | 行级安全和匿名访问错误。 | | `deserialize` | 不安全的反序列化接收器和利用链测试。 | 发现顺序： 1. 内置 `skills/` 2. 项目本地 `./.pentesterflow/skills/` 3. 个人 `~/.pentesterflow/skills/` 4. 通过 `--skills` 传递的目录 如果发生名称冲突，后加载的条目优先。 ## 报告 `confirm_finding` 工具将确认的问题写入： ``` ./findings/.md ``` 报告包括： - 标题和严重程度。 - 受影响的 URL、方法、参数和 Payload（如果有）。 - 证明该问题的响应摘录。 - 影响和修复建议。 - 可直接复制粘贴的 curl 复现命令。 - 用于 Burp issue 导入的原始请求材料（如果有）。 ## 安全模型 - **仅限授权使用**：为合法的安全工作而构建。 - **默认人在回路**：受权限控制的工具需要选择允许一次、允许本次会话或拒绝。 - **敏感路径保护**：高风险的本地路径保持受控状态。 - **Shell 安全保障**：灾难性的命令模式在执行前会被拦截。 - **凭证脱敏**：压缩、快照和学习路径会对常见的敏感格式进行脱敏。 - **透明的证据**：发现应有可复现的请求和观察到的响应作为支持。 - **可审计性**：会话、日志、发现、覆盖率和发布产物将写入确定的本地路径。 ## 配置与数据 | 路径 | 内容 | |---|---| | `~/.pentesterflow/config.json` | 后端、模型、endpoint 和已禁用技能的设置。 | | `~/.pentesterflow/sessions/*.json` | 用于 `--resume` 的已保存会话。 | | `~/.pentesterflow/context/*.md` | 已脱敏的上下文快照。 | | `./.pentesterflow/intelligence/scenarios.jsonl` | 从当前工作区学习到的项目智能。 | | `~/.pentesterflow/intelligence/scenarios.jsonl` | 跨项目的个人可重用智能。 | | `~/.pentesterflow/builtin-skills//SKILL.md` | 由安装程序管理的内置技能。 | | `~/.pentesterflow/skills//SKILL.md` | 个人技能。 | | `./.pentesterflow/skills//SKILL.md` | 项目本地技能。 | | `./findings/.md` | 当前测试的确认发现。 | | `./findings/coverage-.json` | 用于 endpoint/参数/漏洞类别测试的覆盖率状态。 | | `~/.pentesterflow/logs/pentesterflow.log` | 结构化的 JSON-lines 日志。 | | `~/.pentesterflow/debug/session-*.jsonl` | 自愿启用的完整会话调试日志。 | 在复现使用问题时启用完整的调试日志： ``` pentesterflow --debug-session PENTESTERFLOW_DEBUG_SESSION=1 pentesterflow PENTESTERFLOW_DEBUG_SESSION=1 PENTESTERFLOW_DEBUG_SESSION_PATH=/tmp/pf-debug.jsonl pentesterflow ``` 请将调试日志视为敏感信息，因为它们可能包含目标数据、命令输出和复制的请求材料。 ## 开发 ``` npm install npm run dev -- --version npm run dev -- --burp 9999 npm run typecheck npm run lint npm run test npm run build node dist/cli.js ``` `npm run ci` 会运行类型检查、Lint、测试和构建。 ## 贡献 欢迎提交 issue 和 pull request。请保持更改的聚焦，为行为更新包含测试，并在打开 pull request 之前运行 `npm run ci`。新技能应包含 `SKILL.md` 并通过技能一致性测试。 ## 许可证 [Apache-2.0](LICENSE)。请负责任地使用，并仅在获得授权的情况下使用。

**[报告问题](https://github.com/PentesterFlow/agent/issues)** · **[请求功能](https://github.com/PentesterFlow/agent/issues/new)** · **[发布版本](https://github.com/PentesterFlow/agent/releases)**

标签：AI智能体, GNU通用公共许可证, Maven, MITM代理, Node.js, 实时处理, 密码管理, 数据泄露, 文档结构分析, 漏洞验证, 自动化报告, 自动化攻击