Docker 一键启动：快速搭建 cain-agent AI 渗透 Agent 运行环境

cain-agent 是一个面向真实授权场景的 AI 渗透测试 Agent，内置覆盖 AWS / Azure / GCP 与阿里云 / 腾讯云 / 华为云的云安全检测模块。本文介绍如何用Docker 一键启动的方式，跳过繁琐的 Python 依赖配置，快速搭建 cain-agent 的 AI 渗透 Agent 运行环境——只需 3 条命令即可跑起这个安全测试 Agent。

为什么用 Docker 一键启动？

手动安装 cain-agent 需要 Python ≥ 3.11、pip 依赖、可选的 cloud 扩展包，环境不一致时常踩坑。而 Docker 方式把运行时依赖全部封装进一个精简镜像，零环境配置：

镜像构建逻辑见 Dockerfile，完整说明见 docs/docker.md。

第一步：克隆仓库并构建 Docker 镜像

在终端依次执行：

git clone https://gitcode.com/gh_mirrors/ca/cain-agent cd cain-agent docker build -t cain-agent:latest .

首次构建会拉取python:3.11-slim基础镜像并安装项目依赖，之后构建会命中层缓存，速度很快。.dockerignore已排除tests/、docs/、skills/、.git等目录，保证镜像只包含运行时所需内容。

第二步：一条命令验证镜像可用

docker run --rm cain-agent:latest --version

输出形如cain-agent 0.2.0，说明镜像构建成功。镜像的关键特征如下：

最快上手：挂载 workspace 卷

cain-agent 的所有状态文件（scope.yaml/assets.json/findings.json等）都保存在 workspace 目录中。通过-v参数把宿主机的目录挂载进容器，运行结束后产物不会丢失：

docker run --rm \ -v "$(pwd)/workspace:/workspaces/cain" \ cain-agent:latest --help

容器内/workspaces/cain对应宿主机./workspace目录，Orchestrator 读写的文件都会落在宿主机卷上。

运行第一次授权测试

准备一个已获授权的测试目标（自建靶场、自有环境或书面授权项目），执行：

docker run --rm \ -v "$(pwd)/workspace:/workspaces/cain" \ cain-agent:latest run \ --target http://127.0.0.1:3000 \ --total-budget 1800

• --target（必填）：目标地址，会写入scope.yaml成为唯一的授权范围；
• --total-budget：总时间预算（秒），推荐 1800 起步；
• 目标必须已在授权范围内，超出scope.yaml的工具调用会被 Scope Guard 直接拦截——安全由工程强制，而非 AI 自觉。

运行结束后，workspace/report/目录会生成三份产物：人类可读的report.md、机器可读的aggregated-report.json、校验汇总validation-summary.json。详细参数说明见 docs/usage.md。

云凭证安全注入（以阿里云为例）

红线：严禁把 AccessKey 写进 Dockerfile 或 build-arg。凭证只在运行时通过-e环境变量注入：

docker run --rm \ -e ALIBABA_CLOUD_ACCESS_KEY_ID="your-key-id" \ -e ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-secret" \ -v "$(pwd)/workspace:/workspaces/cain" \ cain-agent:latest <command>

凭证读取顺序为：代码层构造参数 →ALIBABA_CLOUD_ACCESS_KEY_ID/ALIBABA_CLOUD_ACCESS_KEY_SECRET→OSS_ACCESS_KEY_ID/OSS_ACCESS_KEY_SECRET，任一来源缺失会抛出OssCredentialError，绝不静默继续。凭证不落盘、不写日志，evidence 字段只记录 ACL 与 Policy 元数据。

进阶：docker-compose 一键拉起本地回归靶场

如果你还没有测试目标，项目内置了本地回归靶场——OWASP Juice Shop 和 DVWA，用一条命令即可拉起（bench/docker-compose.yml）：

cd bench docker-compose up -d

• Juice Shop：浏览器访问http://127.0.0.1:3000，开箱即用，覆盖 SQLi / XSS / 访问控制等漏洞面；
• DVWA：访问http://127.0.0.1:8080，首次需先访问/setup.php完成初始化。

⚠️ 两个靶场的端口仅绑定 127.0.0.1，严禁对外网或局域网暴露；测试完成后用docker-compose down -v彻底销毁，不留任何数据。

注意：pi 执行后端需要 Node.js ≥ 20 与一次性桥接安装（npm ci --prefix toolchain/pi），该步骤需在宿主机完成，详见 toolchain/pi/README.md。

常见问题

Q：docker build很慢？首次构建需要下载基础镜像和 pip 依赖，属正常现象；第二次起会利用层缓存，秒级完成。

Q：中断了测试怎么办？Ctrl-C 会优雅收敛：已完成阶段产物保留，重跑同一条run命令会从断点续走（CLI 入口逻辑见 src/cain_agent/cli.py）。

Q：scope 白名单怎么维护？直接编辑workspace/scope.yaml，支持裸域名、通配子域、IP 与 CIDR；格式参考 templates/scope.example.yaml。判定顺序为：先查out_of_scope（拒绝优先），再查in_scope，两者都不中则默认拒绝。

写在最后

至此，你已完成 cain-agent 的 Docker 一键启动：构建镜像 → 验证版本 → 挂载 workspace → 挂载靶场 → 跑起第一次授权测试。Docker 方式让 AI 渗透 Agent 的部署成本降到最低，而 Scope 硬约束、只读工具链与凭证脱敏这些安全设计，在容器内同样完整生效。

• 完整 Docker 指南：docs/docker.md
• 用户手册（后端选型 / 模型路由）：docs/usage.md
• 本地靶场配置：bench/docker-compose.yml

⚠️ 法律提醒：cain-agent 仅限用于已获书面授权的安全测试。你须对所列目标的合法性独自承担责任，请遵守所在地法律法规。