Autonomous Pentest Agent 本地部署教程：从安装配置到自主探索与复测

先了解项目与使用边界

Autonomous Pentest Agent 是一个由 LLM 多 Agent 驱动的自主渗透测试系统，采用 Go 后端、Next.js 前端和 PostgreSQL。项目可以管理任务、资产、探索链路、发现结果、流量记录、工具审批和人在环路对话。

重要安全与合规提示：README 明确要求本项目仅用于个人学习、源码研究和本地隔离环境中的技术验证，不得用于任何网站、线上服务、联网系统、生产环境或实际渗透测试。请仅在你拥有控制权的本地靶场中使用，并遵守所在地区的网络安全、数据保护和计算机犯罪相关法律法规。

项目提供了在线 Demo用于了解交互界面，但实际部署和验证应严格限制在本地隔离环境内。

核心功能与界面

系统的前端提供仪表盘、任务列表、执行会话、探索链路、发现、资产、资产覆盖图、流量录制、Agent 管理、LLM 配置、拦截审批和后端日志等页面。

仪表盘用于查看整体状态、Token 消耗和活动流。任务与会话页面则展示任务执行过程，包括 Agent 会话和工具调用。

探索链路用于观察目标、意图、事实和发现之间的血缘关系；发现页面用于查看漏洞及其证据，资产页面用于浏览系统收集和归并的目标资产。

系统架构概览

系统由内嵌 Next.js 静态前端的 Go 单体后端、PostgreSQL、Agent 引擎和若干支撑子系统组成。后端通过 REST API、JWT 鉴权和 SSE 向前端提供服务，任务引擎负责调度 planner 与多个 worker。

项目采用双图架构：

• 资产图：跨任务共享资产真值库，包含根域名、子域名、IP、服务、应用和端点等节点。
• 探索图：按任务记录目标、意图、事实、提示和发现，并通过血缘关系描述探索过程。
• 锚点关系：将探索节点关联到具体资产，用于查看资产测试覆盖度和探索范围。

Planner 负责读取探索态势并派发意图，Worker 领取意图、使用工具执行并写回事实、资产和发现。图发生变化后会再次唤醒 Planner，形成事件驱动闭环。多个 Worker 还可以检索其他 Worker 的执行过程，而共享 todolist 则帮助多轮规划按依赖推进连续步骤。

安装前准备

运行项目至少需要 PostgreSQL。要执行探索，还需要配置 LLM，可使用 ANTHROPIC_API_KEY 或 OPENAI_API_KEY，也可以稍后在 Web 界面的「LLM 配置」页填写。

推荐准备 Docker，以便快速启动数据库和应用。无论选择哪种部署方式，都建议先创建隔离的本地测试网络、备份重要数据，并确认测试目标属于本地实验环境。

方式一：使用一键安装脚本

这是 README 推荐的安装方式。脚本会检测或安装 Docker，并让你选择完整 Docker 部署或本地编译运行。

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
./install.sh

选择完整 Docker 部署时，脚本会要求填写 PostgreSQL 密码，也可以直接回车生成随机密码，然后写入 .env 并执行 docker compose up -d。选择本地运行时，可以连接已有数据库，或使用 Docker 启动数据库；脚本会生成 config.json，编译内嵌前端的 Go 单二进制并启动服务。

安装完成后访问 http://localhost:8787。首次进入时打开 /setup 设置管理员密码。

方式二：使用 Docker Compose

如果你希望手动控制环境，可以直接使用 Compose：

git clone https://github.com/kutukam/autonomous-pentest-agent.git
cd autonomous-pentest-agent
cp .env.example .env
docker compose up -d

请编辑 .env 填写 POSTGRES_PASSWORD，并按需配置 ANTHROPIC_API_KEY。启动后访问 http://localhost:8787。

Docker 镜像包含常用工具，./skills 和 ./data 使用绑定挂载保存数据。远程 MCP 可以在系统设置中选择 Streamable HTTP 或旧版 SSE；使用旧版 SSE 时，URL 通常填写 /sse，并按照服务要求设置 Authorization=Bearer <token> 请求头。

方式三：使用预编译二进制

也可以从Releases下载对应平台的压缩包。解压后通常包含 apagent、start.sh 或 Windows 下的 start.bat、skills/ 和 config.example.json。

cp config.example.json config.json
./start.sh

请使用 start.sh 或 start.bat 启动，而不要直接运行 ./apagent。启动脚本负责在程序退出后按退出码决定是否重新拉起，页面中的一键更新功能也依赖该机制。后台运行可以使用：

nohup ./start.sh >apagent.log 2>&1 &

方式四：从源码编译

从源码编译时，需要先构建前端静态文件，再将其复制到后端的内嵌目录，最后使用 embedui 标签编译 Go 程序。

cd web && npm ci && npm run build:static && cd ..
cp -r web/out server/webui/dist
CGO_ENABLED=0 go build -tags embedui -o apagent ./cmd/apagent
./start.sh

如果需要构建跨平台发布包，可以运行：

./build.sh --release

默认会生成 Linux、macOS 和 Windows 的多个目标包。也可以通过 APAGENT_TARGETS 自定义目标。UPX 默认不启用，因为压缩后的自解压二进制可能与部分 Linux 内核、虚拟化环境或安全策略不兼容。

配置数据库与 LLM

本地编译或二进制运行时，可以在 config.json 中配置 PostgreSQL：

{
  "database": {
    "host": "127.0.0.1",
    "port": 5432,
    "user": "apagent",
    "password": "yourpass",
    "dbname": "apagent",
    "sslmode": "disable"
  }
}

也可以使用 APAGENT_PG_DSN 覆盖数据库连接配置。LLM 可以通过环境变量配置：

export ANTHROPIC_API_KEY=sk-...
# 或者
export OPENAI_API_KEY=...

可选参数包括 APAGENT_LLM_PROVIDER、APAGENT_LLM_MODEL、APAGENT_LLM_BASE_URL 和 APAGENT_LLM_PROXY。如果不想使用环境变量，可以在 UI 的「LLM 配置」页填写。每个任务的 Worker 数量可以在「系统设置」中调整，默认值为 3。

基本使用流程

1. 完成初始化：访问本地服务，在 /setup 设置管理员密码，并检查数据库连接。
2. 配置 LLM：在系统环境变量或「LLM 配置」页面中设置可用模型及必要参数。
3. 准备本地目标：仅添加隔离实验环境中由你控制的资产，确认不会访问线上系统或生产服务。
4. 创建并观察任务：使用任务页面管理任务，在仪表盘和活动流中查看运行状态。
5. 查看探索结果：通过探索链路了解意图、事实和发现之间的关系，通过资产图查看已归并的资产。
6. 检查执行证据：在会话、工具调用和流量页面查看过程记录；遇到需要人工确认的操作时，在拦截审批页面处理。

资产覆盖图以力导向布局展示范围内资产和已测试节点，支持节点折叠与展开。它适合用于快速判断本地实验范围中哪些资产已经被探索。

从 ScopeSentry 同步资产

项目支持从ScopeSentry同步资产，减少重复收集。打开「资产同步」页，填写 ScopeSentry 地址和 API Key，然后按项目或任务选择需要同步的目标与资产类型。

• 支持按范围选择域名、子域、IP、端口、站点和端点等资产类型。
• 导入后会按公司资产范围归并。
• 同步结果会进入 Autonomous Pentest Agent 的资产图，供后续本地实验任务使用。

流量记录与审批

系统提供流量录制代理，可以通过类似 ./start.sh -addr :8787 -proxy :8788 的方式指定前端与 API 地址和流量代理地址。Worker 的工具执行过程会留下活动记录，拦截审批机制则用于在需要时让人在环路确认工具操作。

审批记录支持在全局审批记录、任务内拦截审批以及对话中的审批卡片中展开查看详情。使用时应仔细核对操作对象和参数，并始终将目标限制在隔离实验环境。

漏洞复测

任务详情的「复测」页签可以分页选择漏洞、查看历史结论和证据，并发起独立的复测 Agent 会话。漏洞列表、漏洞详情和资产视图都提供复测入口。

复测结论包括「仍可复现」「已修复」和「无法确认」。每次复测的结论、证据和会话链接都会保存在漏洞详情中。复测成功且结论为「已修复」时，系统会自动更新漏洞处置状态；执行中、失败、停止或其他结论不会自动改变原状态。

后端首次启动会预置可编辑的「漏洞复测」Agent，也就是 retester。它可以在 Agent 管理中配置提示词、LLM、运行预算和工具。如果同一漏洞正在复测，系统会复用已有会话；停止、失败或服务重启后可以重新发起。README 同时说明，历史复测记录暂未纳入漏洞报告导出或任务归档包，也未自动关联流量包。

反向代理部署

前端、API 和 SSE 默认由同一个后端端口提供，因此通常不需要设置 NEXT_PUBLIC_SSE_BASE。如果通过 Nginx 暴露 HTTPS，需要关闭 SSE 缓冲并设置较长的读取超时：

server {
    listen 443 ssl;
    server_name your.domain.com;

    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_cache off;
        proxy_read_timeout 3600s;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }
}

如果 SSE 使用与页面不同的来源，才需要在构建期设置 NEXT_PUBLIC_SSE_BASE。该变量会在 next build 时固化到静态包，容器运行时再设置不会生效。

升级与数据保护

项目升级时只替换程序，不会主动删除 PostgreSQL 数据卷、./data 或 ./skills。应用启动时会幂等执行数据库结构初始化和迁移，因此通常不需要手动执行迁移脚本。不过升级前仍应备份 ./data 和数据库。

推荐在系统配置页的「版本与更新」卡片中执行更新。程序会下载当前平台发布包、校验 SHA256、进行冒烟测试，再由启动脚本完成替换。校验失败时会丢弃暂存文件；新版连续启动失败时会自动回滚。更新会重启服务并中断正在运行的任务，应在空闲时进行。

Docker 部署时，页面更新只替换程序，不会更新镜像中的 Playwright、nmap 等工具链。需要更新镜像时运行：

docker compose pull apagent
docker compose up -d apagent

也可以使用仓库中的更新脚本：

./update.sh

本地开发与测试

开发模式可以同时启动后端、流量代理和 Next.js 开发服务器：

./dev.sh

默认访问地址为 http://localhost:5173。也可以分别运行：

go run ./cmd/apagent
cd web && npm run dev
go test ./...

不带 -tags embedui 时，后端不会内嵌前端。若只想预览前端而不启动后端，可以使用：

cd web && NEXT_PUBLIC_MOCK=1 npm run dev

常见注意事项

• 确认 PostgreSQL 已启动，并检查用户名、密码、数据库名和端口。
• 如果活动流连接成功但没有事件，检查反向代理是否关闭了缓冲，并确认长连接超时足够长。
• 使用预编译版本时，不要绕过 start.sh 或 start.bat，否则页面更新后的自动换装和重启机制可能无法正常工作。
• 修改前端静态资源后，必须重新执行 npm run build:static，再复制到 server/webui/dist 并重新编译。
• 升级前备份数据库、./data 和 ./skills；数据库结构可以自动迁移，但不会自动回退。
• 不要把真实线上资产、生产凭据或敏感数据导入本地实验系统。

总结

Autonomous Pentest Agent 将 Go 服务、Next.js 界面、PostgreSQL 双图数据模型和 LLM 多 Agent 调度结合起来，提供任务管理、探索链路、资产覆盖、流量留痕、审批和漏洞复测能力。你可以先用 Docker 或安装脚本在本地隔离环境启动，再配置数据库与 LLM，最后通过任务、资产图和执行会话逐步理解系统行为。使用过程中务必遵守项目声明的本地学习用途和全部法律合规要求。

项目采用 AGPL-3.0 许可证；如修改并通过网络向用户提供服务，需要按照许可证要求公开相应完整源码。更多实现细节可参考仓库中的源码、norma SDK以及项目的 LICENSE 文件。