cain-agent（Cain）是一个面向真实授权安全评估的实战型 AI 渗透测试工程师，内置覆盖 AWS / Azure / GCP 及阿里云 / 腾讯云 / 华为云的云安全检测模块，基于 Claude Agent SDK 构建，支持确定性攻击流水线、Scope 硬约束与只读安全工具链。本文带你完成安装并在 10 分钟内跑完第一次授权渗透测试。

一、cain-agent 是什么？适合谁用？

Cain 和常见的 CTF 靶场型 AI Agent 不同，它面向的是真实企业资产、漏洞赏金与授权渗透项目：

它的核心安全设计是「确定性工程约束 Agent 自由度」：阶段流转、范围强制、危险操作熔断都是硬约束，路径选择与证据分析才交给 AI。

⚠️法律红线：Cain 严格仅限自有资产或已获书面授权的目标，未授权目标一律默认拒绝。

核心源码位于 src/cain_agent/，安全钩子实现见 src/cain_agent/scope.py。

二、安装前的环境准备：最快配置方法

三、一键安装步骤

打开终端，依次执行：

git clone https://gitcode.com/gh_mirrors/ca/cain-agent cd cain-agent pip install -e . # 或使用: uv pip install -e . cain-agent --version # 验证安装，输出形如 cain-agent 0.2.0

如需云检测能力（AWS S3 / 华为 OBS / Kubernetes 检查），加装可选组件：

pip install -e ".[cloud]"

更推荐的是Docker 一键运行，免去本地环境依赖，详见 docs/docker.md：

docker build -t cain-agent:latest . docker run --rm cain-agent:latest --version

四、第一次运行：先 dry-run 看执行计划

首次运行前，先用--dry-run初始化工作区、写入 scope 白名单并打印执行计划，不启动任何 Agent：

cain-agent run --target https://app.example.com --dry-run

确认计划无误后，正式跑测试（--total-budget为墙钟总预算秒数，新手建议从 1800 起步）：

cain-agent run \ --target https://app.example.com \ --workspace ./workspace \ --total-budget 1800

常用参数速查：

• --target（必填）：目标 host/URL，归一化后作为唯一in_scope条目
• --workspace：状态目录（默认./workspace），全部产物落在这里
• --total-budget/--idle-timeout：总预算与单步空闲超时
• --backend pi：切换到 pi 执行后端（多 provider 支持）

Scope 是工程强制的：每次工具调用前由 PreToolUse 钩子校验，目标落在白名单外一律拒绝——不依赖模型自觉。想调整范围，直接编辑workspace/scope.yaml（支持域名、通配子域、IP、CIDR；示例见 templates/scope.example.yaml）。

五、读懂输出产物：一次 run 落三件报告

运行结束后，workspace/report/目录会生成：

其中「发现 ≠ 校验」是最大亮点：每条漏洞由独立会话复核，谁也不能既当运动员又当裁判，校验语义见 src/cain_agent/validator.py 与 docs/articles/02-validation-loop-deep-dive.md。

六、进阶：按阶段混搭模型，省成本

侦察是重复性枚举，测试才需要高能力判断——两个阶段可以各走各的引擎：

cain-agent run --target https://app.example.com \ --recon-backend pi --recon-provider anthropic --recon-model cheap-model-id \ --test-backend claude

不传任何阶段参数时，行为与只配置--backend完全一致，安全语义不变。完整参数说明运行cain-agent run --help，用户指南全文见 docs/usage.md。

七、常见问题

Q: 提示pi bridge not found？pi 后端需先执行npm ci --prefix toolchain/pi（Node ≥ 20），指南见 toolchain/pi/README.md。

Q: 测试阶段 0 findings？先看validation-summary.json与 recon 的endpoints.json——可能是攻击面确实被前置防护（如 nginx 405）拦住。

Q: 想中断？Ctrl-C 会优雅收敛：已完成阶段产物保留，重跑同命令从断点续走（状态全部以文件形式存在 workspace，详见 src/cain_agent/workspace.py）。

至此你已完成了从安装到跑完第一次 AI 渗透测试的全流程。下一步建议：阅读 docs/community.md 了解社区与问题反馈渠道，或查看 bench/README.md 了解 cain-agent 自建的 vulnerable-terraform 评测基准。