Agent-2 自托管安全测试工作流

这是什么？适合谁？

Agent-2（aaravshah1311/Agent-2）是一个自托管的自治 AI Agent，跑在你自己的机器上、用你自己的 Gemini API key、把全部状态存进代码旁边的一个 agent2.db SQLite 文件——无账号、无服务、无遥测、无构建步骤。它同时是编码助手、终端 Agent、安全测试器与持久记忆系统，提供 CLI / Web UI / 双模式三个界面，共享同一套系统提示、工具分发器、记忆与规则表、diff 引擎与模型路由。

本工作流聚焦其**安全测试（security testing）**能力：Agent-2 拥有 18 个内置工具（run_command、scan_project、grep_search、web_search 等），并可经 MCP 桥接动态挂载 burp_*、zap_* 等安全工具。仓库 2026-09-04 创建，8 天 97★/8 fork，MIT，Python 3.9+，带 2670 项测试。

适合谁：

• 想要”一个 Python 仓库 clone 下来就能跑”的自托管 Agent 的开发者
• 对目标项目做授权范围内安全扫描/渗透测试辅助的安全工程师
• 需要跨 CLI/Web 两个界面共享同一记忆与状态的个人用户

不适合：需要多用户/团队协作平台的团队（状态是单文件单机）；不愿把命令执行权交给 LLM 的严格环境；用非 Gemini 提供商的用户（模型栈绑定 Google Gemini）。

使用前提：Python 3.9+、Gemini API key（aistudio 免费申请）、被测目标的明确授权。

准备工作

1. 安装：git clone https://github.com/aaravshah1311/Agent-2.git && cd Agent-2 && python run.py——run.py 会建 .venv、装依赖并提示填 Gemini API key
2. 环境：Python 3.9+；可选 Docker（python run.py --docker）
3. 授权：安全测试仅限自有/授权目标；确认 Agent-2 的 exec 权限模式配置
4. 成本：软件 MIT 免费；Gemini API 按用量计费（flash 系列便宜，免费额度可覆盖小规模扫描）
5. 时间：安装约 5 分钟；一轮项目扫描+验证 1-3 小时

3 步核心流程

第一步：建立目标与权限边界

确定被测目标（本地代码目录或授权范围），启动 Agent-2：

python run.py --cli          # CLI 界面（默认）
python run.py --web          # 或 Web UI（localhost:1311）

首次启动填入 Gemini API key（python run.py --addapi 可管理多 key 轮换）。在配置中明确允许的命令域（exec capability gate 有两处实现：工具分发器与终端流式执行，CLI 的副本刻意放在重试循环外——拒绝不能因重试变成放行）。

预期产出：Agent-2 可对话、可执行受限命令，权限模式与目标范围已固化。

第二步：Agent 扫描项目与探测攻击面

让 Agent 枚举与探测，例如提示：

扫描 /path/to/project：列出全部入口点（路由/handler/CLI）、外部输入面、
依赖清单中的已知漏洞组件。对每个发现给出文件与行号证据。

Agent 会用 scan_project、grep_search、read_file、list_dir 组合完成枚举，需要执行命令时走 run_command（流式 + 双重能力门禁）。如已接 Burp/ZAP MCP 桥，burp_*/zap_* 工具自动加入工具表（所有权按”成员归属”判定，断连的桥不再占用工具名）。

预期产出：带文件/行号证据的攻击面清单。

第三步：验证漏洞并出报告

对候选发现逐一验证——要求 Agent “每条结论必须先复现再写报告”：

对上述每个候选漏洞：给出可复现的验证步骤（命令或请求），实际执行验证，
只保留验证通过的条目；save_memory 记录结论，最后输出结构化报告
（发现/证据/风险/修复建议）。

验证中工具能力门禁以 error 返回而非异常（模型能读错并自适应，turn 不中断）。结论用 save_memory 存入持久记忆，后续会话可复用。

预期产出：仅含已验证条目的结构化安全报告。

初级用法

单点代码审查

不开安全模式，直接让 Agent 读指定文件并指出输入校验缺陷——最小成本的安全辅助。

记忆驱动的复测

save_memory 沉淀的结论跨会话存活（SQLite 单文件），修复后让 Agent 对照记忆复测同一条目。

双界面切换

python run.py --dual：Web 在后台线程、CLI 在前台，同一 agent2.db——长扫描开 Web 看流式工具调用，终端继续干别的。

高级玩法

挂载 Burp/ZAP MCP 桥

把专业安全工具的 MCP server 接入，burp_*/zap_* 工具动态加入，Agent 可驱动代理扫描与主动验证。

模型路由分级

Gemini 6 模型（2.5-flash 默认至 3.7-flash）由 llm/router.rank_candidates() 路由：枚举用 lite 省钱，验证推理用高阶模型。

命令看门狗长任务

CLI 的 live command watchdog 监控长命令执行，避免安全扫描中的静默挂死。

小技巧

1. 安全测试先在隔离环境（容器/虚拟机）里授权命令域，再放行真实命令
2. 多 key 用 --addapi 轮换，长扫描不会因单 key 限速中断
3. 让 Agent 每条结论附文件与行号，报告才可审计
4. 升级用 python run.py --update，它会保留 agent2.db（记忆不丢）
5. 验证阶段明确要求”先复现再入报告”，可把幻觉发现率压到接近零

常见踩坑

踩坑 1：把 Agent-2 当团队服务部署

• 现象：多用户同时写状态
• 原因：架构是单机单文件 SQLite（agent2.db），无并发/多租户设计
• 解决：个人或单人使用；团队场景换服务端方案

踩坑 2：命令执行权限没收敛

• 现象：Agent 执行了范围外命令
• 原因：exec capability gate 配置过宽
• 解决：测试前在配置里固化允许的命令域；门禁设计上拒绝优先（重试不会变放行）

踩坑 3：未验证发现直接入报告

• 现象：报告里有”看起来存在”的漏洞
• 原因：模型推断 ≠ 事实
• 解决：流程强制”每条结论先复现”；工具门禁返回 error 让模型自纠

踩坑 4：MCP 桥断连后工具名残留

• 现象：调用 zap_* 报”工具不存在”但列表里还有
• 原因：早期版本前缀判断；现版本 registry.resolve() 按成员归属判定
• 解决：更新到最新版（python run.py --update）

踩坑 5：项目极新文档可能变

• 现象：命令/参数与本文不符
• 原因：仓库 2026-09-04 创建，8 天内仍在快速迭代
• 解决：以 README 与 USAGE.md 为准

常见问题 FAQ

Q1: 它只能用 Gemini 吗？

A: 是。模型栈绑定 Google Gemini（2.5 至 3.7 六个 flash 档位），run.py 启动时申请 key。key 在 aistudio 免费申请，flash 系列用量便宜。

Q2: 安全测试合法吗？

A: 仅限自有或获得明确授权的目标。工具本身中立；权限边界由使用者在第一步配置固化。

Q3: CLI 和 Web 是两个应用吗？

A: 不是。三个界面共享系统提示、工具分发器、记忆、diff 引擎与数据库——切界面只改”看什么”，不改”能做什么”。

Q4: 状态存哪？

A: 全部在代码目录旁的单个 agent2.db（SQLite）：记忆、规则、key、diff。更新保留该文件，卸载删除它。

Q5: 有测试吗？

A: 仓库 badge 显示 2670 项测试（pytest），run.py 生态内含 CI 资产（.github/、.gitleaks.toml）。

Q6: 和 OpenHands 等自托管 Agent 平台的区别？

A: Agent-2 走”零服务、单文件状态、三界面共享”路线，面向个人；OpenHands 类是服务化多用户平台。前者 5 分钟 clone 即跑，后者部署成本高但协作强。

参考链接

• 官方仓库
• USAGE.md
• FEATURES.md
• Gemini API key 申请

本文基于公开资料（GitHub 官方 README/USAGE/FEATURES）整理，AI 辅助生成，未做本地安装实测；采集日期 2026-09-12。功能与数据以官方仓库最新说明为准。