企业官网建设流程全解析

PentAGI 自定义渗透测试镜像集成 OpenVAS/GVM 实战指南

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi

PentAGI 本身并未内置 OpenVAS/GVM 的安装、配置、Feed 同步或编排能力，但通过"自定义渗透测试镜像 + 环境变量 + 提示词引导"的组合，你可以在 PentAGI 的渗透测试容器内完整接入 OpenVAS/GVM 进行实验。本指南以 examples/guides/openvas-custom-image.md 为骨架，结合仓库源码与实际配置逐层讲解镜像构建、入口点改造、镜像接入、提示词引导与故障排查的完整闭环，读完后你将能够独立部署一套可被 PentAGI Agent 识别和调用的 OpenVAS 扫描环境。

背景与定位：PentAGI 与 OpenVAS 的边界

PentAGI 是一个能够自主执行复杂渗透测试任务的 AI Agent 系统，其 Agent 在 Docker 容器内执行各类安全测试工具。社区通过 Issue #69 提出了对 OpenVAS 的支持需求，但官方维护者的推荐方案并非在 PentAGI 内部增加原生支持，而是构建一个预装 OpenVAS/GVM 的自定义渗透测试镜像，然后通过配置与提示词让 Agent 学会使用它。

这一点在源码中有明确的证据链：

• backend/pkg/config/config.go 中定义了环境变量DOCKER_DEFAULT_IMAGE_FOR_PENTEST，默认值为vxcontrol/kali-linux，即 PentAGI 默认的渗透测试镜像；
• backend/cmd/installer/checker/checker.go 中同样以DefaultImageForPentest = "vxcontrol/kali-linux"作为安装检查器的默认值；
• README.md 的环境变量表中明确说明该变量默认值为vxcontrol/kali-linux。

因此，本工作流的前提认知是：这是"自定义镜像工作流"，而不是 PentAGI 的 OpenVAS 内建支持。PentAGI 不会替你安装 OpenVAS/GVM、初始化漏洞库 Feed、管理服务就绪状态，也不提供专门的 OpenVAS API 集成层。镜像的构建、服务的自启动、以及告诉 Agent "何时、如何使用 OpenVAS"，全部需要你自己完成。

何时使用该工作流

如果满足以下条件，适合采用本方案：

• 你希望在 PentAGI 的渗透测试容器内部实验 OpenVAS/GVM，同时保持改动只局限于你自己的部署环境；
• 你的基础设施允许构建并维护一个自定义 Docker 镜像（需要能够拉取基础镜像并执行docker build）；
• 你愿意通过提示词（Prompt）来引导 Agent 使用新工具，并接受"Agent 可能自行选择其他工具"的行为偏差。

同时需要明确：本指南不能作为"PentAGI 具备原生 OpenVAS 编排、内置安装器或维护完善的 OpenVAS API 集成"的证据。如果镜像内包安装失败，应优先走源码编译路线排查，而不是推断 PentAGI 缺少功能。

构建自定义渗透测试镜像

OpenVAS/GVM 默认期望 systemd 环境来管理其服务，因此维护者的建议是：从vxcontrol/kali-linux:systemd出发，而不是 PentAGI 默认的vxcontrol/kali-linux镜像。基础镜像仓库为 vxcontrol 的 kali-linux-image 项目，其上游入口点脚本为container-entrypoint.sh，位于/usr/local/bin/container-entrypoint。

方案一：基于软件包安装自定义镜像（最短路径）

当所需软件包在你的基础镜像状态下可用时，这是最直接的构建方式。文档给出的 Dockerfile 如下：

FROM vxcontrol/kali-linux:systemd RUN apt update && apt install -y openvas gvm \ && rm -rf /var/lib/apt/lists/* # Provide your own modified copy of the upstream entrypoint that starts both # systemd and the GVM/OpenVAS services you need. COPY container-entrypoint.sh /usr/local/bin/container-entrypoint RUN chmod +x /usr/local/bin/container-entrypoint

几点实操注意：

• apt install -y openvas gvm是示例包名。包名、软件源与服务的启动细节会随发行版状态变化，如果安装失败，请先核对软件源，再退回源码编译路线（见方案二），不要把它当作 PentAGI 的功能缺失；
• rm -rf /var/lib/apt/lists/*用于清理 APT 缓存，缩小镜像体积；
• Dockerfile 末尾覆盖了入口点脚本：因为上游基础镜像已经在/usr/local/bin/container-entrypoint放置了自定义入口点，你需要维护一份自己的修改版，让它同时启动 systemd 与所需的 GVM/OpenVAS 服务。PentAGI 仓库并不附带现成的container-entrypoint.sh。

方案二：源码编译构建

如果软件包安装路径在你的镜像状态下不可行，可以参考 Greenbone 官方 openvas-scanner 仓库中针对 Debian 稳定版的示例 Dockerfile（该示例位于 Greenbone 官方仓库的.docker目录下）。要点是：以 Greenbone 的构建步骤为参考编译 scanner，但仍要从vxcontrol/kali-linux:systemd作为基础镜像，并且提供一个能够同时启动 systemd 与你所依赖的 GVM/OpenVAS 服务的可用入口点。

也就是说，源码编译只解决"软件包装不上"的问题，入口点的职责与方案一完全一致，不能省略。

入口点（Entrypoint）注意事项

上游基础镜像已经使用了自定义入口点/usr/local/bin/container-entrypoint（上游脚本位于 vxcontrol/kali-linux-image 仓库根目录的container-entrypoint.sh）。在你的镜像构建过程中，必须创建并维护该入口点的修改副本，使其按以下顺序完成启动：

1. 启动 systemd（基础镜像的运行基础）；
2. 启动 GVM/OpenVAS 相关的守护进程与服务（如gvmd、openvas扫描器、必要时的gsadWeb 服务等）；
3. 让容器保持在运行状态，以便 PentAGI Agent 在容器内执行命令。

镜像构建完成前的本地验证建议：直接以该镜像启动一个容器，确认 systemd 正常运行、/usr/local/bin/container-entrypoint可执行、GVM 相关服务进程存活，再进入下一步接入 PentAGI。

将自定义镜像接入 PentAGI

镜像构建完成后，按以下四步接入 PentAGI：

1. 构建并打标签

docker build -t myorg/kali-linux:openvas .

2. 在.env中设置 PentAGI 渗透测试镜像

DOCKER_DEFAULT_IMAGE_FOR_PENTEST=myorg/kali-linux:openvas

该变量在仓库中的传递链路是完整且可追溯的：

• .env.example 中声明了DOCKER_DEFAULT_IMAGE_FOR_PENTEST=（默认留空，由应用侧默认值兜底）；
• docker-compose.yml 将${DOCKER_DEFAULT_IMAGE_FOR_PENTEST:-}透传进pentagi服务容器的环境变量；
• backend/pkg/config/config.go 以envDefault:"vxcontrol/kali-linux"读取，未设置时回退到官方默认镜像。

3. 重启 PentAGI，使新的默认镜像对后续新建的渗透测试任务生效。

4. 重启后新建一个渗透测试任务（Task）或流程（Flow），让自动镜像选择逻辑使用新镜像。

[!NOTE] 如果用户在任务中显式指定了其他 Docker 镜像，PentAGI 可能会优先使用该镜像。DOCKER_DEFAULT_IMAGE_FOR_PENTEST只影响自动镜像选择，不影响用户在任务中的显式覆盖。

这一点在源码中有直接实现证据。镜像选择由 backend/pkg/templates/prompts/image_chooser.tmpl 驱动的 LLM 提示词完成，其中明确写着：

• 如果用户任务中指定了特定镜像，必须使用该确切镜像（If the user specifies a particular Docker image in their task, you must use that exact image.）；
• 对于安全/渗透测试任务，默认使用{{.DefaultImageForPentest}}；
• 对不明确的情况，回退到{{.DefaultImage}}。

DefaultImageForPentest的值由 backend/pkg/providers/providers.go 从配置中的DockerDefaultImageForPentest注入模板，即你在.env中设置的值。

分布式（Worker Node）部署下的使用

如果你运行的是分布式部署（PentAGI 主节点 + 独立的 Worker 节点），需要在 Worker 节点一侧同样使用自定义镜像作为渗透测试镜像。Worker 节点的部署方式决定了 Agent 容器的实际运行位置：PentAGI 通过 TLS 连接到 Worker 节点的主 Docker 守护进程创建pentagi-terminal-N工作容器，Agent 再通过 dind 的 TLS 端点管理自己的嵌套容器（详见 Worker Node Setup 中的连接模式说明）。因此，只有自定义镜像同时存在于 Worker 节点可拉取的镜像仓库中，任务容器才会基于它启动。

两种部署形态下的配置要点：

• 单机部署：在.env中设置DOCKER_DEFAULT_IMAGE_FOR_PENTEST即可；
• 分布式部署：除.env外，还需保证 Worker 节点上运行 Agent 工作容器的 daemon 能够拉取/访问该自定义镜像。如果通过交互式安装器（./installer）配置，可在 "Tools → Docker Environment" 的Pentesting Image字段中填写镜像名，其底层同样写入DOCKER_DEFAULT_IMAGE_FOR_PENTEST环境变量（对应 backend/cmd/installer/wizard/controller/controller.go 中的DockerDefaultImageForPentest配置项）。

提示词引导（Prompt Guidance）

镜像就绪后，还需要让 Agent 知道"环境中存在 OpenVAS/GVM"以及"何时应该使用它"，否则 Agent 可能根本不会调用扫描器。操作入口有两处：

• 在Settings -> Prompts中添加可复用的引导提示词（对所有任务生效）；
• 如果你已经使用自定义的 Flow 提示词，请在 Flow 级别加入同样的预期说明，保持流程内行为一致。

文档给出的小型示例提示词文本如下：

OpenVAS/GVM is available in this deployment's pentest image. Before using it, verify the required services and scanner are ready inside the container. Use OpenVAS when broad vulnerability scanning is appropriate, and save scan outputs and exported artifacts under /work. If OpenVAS is unavailable or not ready, continue with other tools and report the limitation clearly.

对提示词文本的逐句解读与建议：

• "验证服务就绪再使用"：GVM 组件（数据库、扫描器、守护进程）启动需要时间，Agent 应先检查服务状态，避免在未就绪时误报扫描失败；
• "输出与导出产物保存到 /work"：/work是 PentAGI 工作容器的持久化工作目录。仓库实现中，backend/cmd/installer/wizard/locale/locale.go 对数据目录的说明明确写道：PentAGI 将 Agent 生成的文件放在flow-N子目录下，这些子目录在 Worker 容器内映射为/work。提示词中要求 Agent 把扫描报告、导出文件放到/work，才能保证产物在任务结束后仍可被 PentAGI 检索与展示；
• "不可用则继续其他工具并明确报告限制"：这是重要的兜底条款。OpenVAS 镜像构建或服务启动失败时，Agent 应降级使用 nmap 等既有工具，而不是卡死在 OpenVAS 上。

提示词应放在**镜像变更生效（重启后）**再添加或更新，因为 Agent 只有在新任务中才会重新读取提示词与镜像选择逻辑。

局限与预期

请在使用前完整理解本工作流的边界：

• 这是自管理的自定义镜像工作流，不是 PentAGI 内置的 OpenVAS 支持；
• PentAGI 不会替你安装 OpenVAS、初始化漏洞库 Feed、管理服务就绪状态，也不暴露专门的 OpenVAS API 层；
• 提示词改动是必需的，否则 Agent 不知道 OpenVAS 何时可用、何时适合使用；
• 重启后新建的任务会可靠地使用更新后的默认镜像，而已运行中的任务可能继续使用旧镜像创建的容器，需要主动新建任务来验证。

故障排查

apt install openvas gvm失败或软件包缺失

包名与软件源可用性会随发行版状态变化。排查步骤：

1. 确认基础镜像内的软件源配置是否正常（如 Kali 的sources.list是否指向可用镜像）；
2. 执行apt update确认索引刷新成功；
3. 如果软件包路径确实不可用，退回方案二的源码编译路线。

该问题与 PentAGI 本身无关，不要将其误判为 PentAGI 功能缺失。

PentAGI 仍在使用旧渗透测试镜像

逐步核对：

1. 确认.env中的DOCKER_DEFAULT_IMAGE_FOR_PENTEST已正确设置且无拼写错误（可对照 .env.example 的键名）；
2. 重启 PentAGI（docker compose环境变量在服务启动时读取，见 docker-compose.yml 的透传逻辑）；
3. 新建一个渗透测试任务或 Flow 再验证——已运行中的工作可能继续使用旧镜像创建的容器；
4. 检查用户任务文本中是否显式指定了其他镜像——如前面所述，显式指定优先于自动选择（见 image_chooser.tmpl 的规则）。

Agent 忽略 OpenVAS

Agent 可能在阅读提示词后仍选择了其他工具，这是自主 Agent 的正常行为。建议：

1. 优化提示词措辞，明确写出"OpenVAS/GVM 已可用"及其适用场景；
2. 将 OpenVAS 可用性的表述放在提示词更靠前的位置；
3. 查看任务执行轨迹（execution traces），确认 Agent 是"识别到了工具但选择了其他路径"，还是"根本没有识别到"。如果是后者，优先检查提示词是否实际生效、是否只配置在了 Settings 而 Flow 级提示词未同步。

GVM 或系统服务未启动

重新检查你的自定义/usr/local/bin/container-entrypoint逻辑。该工作流的成败高度依赖镜像能否在 Agent 尝试使用工具之前完成 systemd 与 OpenVAS/GVM 服务的启动。常见检查项：

• 入口点脚本是否可执行（chmod +x）且以正确用户运行；
• systemd 是否真正接管（而非仅启动了第一个进程）；
• GVM 相关服务（gvmd、扫描器进程等）是否在容器启动后存活，必要时查看服务日志；
• 本地先行验证：docker run --rm myorg/kali-linux:openvas启动后手动ps aux | grep -E 'gvmd|openvas'确认进程存在，再交给 PentAGI。

小结

围绕"自定义镜像 + 环境变量 + 提示词"三要素，本工作流在不改动 PentAGI 核心代码的前提下，将 OpenVAS/GVM 完整接入自主渗透测试流程：以vxcontrol/kali-linux:systemd为基础构建镜像（软件包安装或源码编译两条路线），用修改版container-entrypoint.sh保证 systemd 与服务自启，通过DOCKER_DEFAULT_IMAGE_FOR_PENTEST让自动镜像选择器（image_chooser.tmpl）优先选用该镜像，再用 Settings/Flow 级提示词告诉 Agent 何时调用 OpenVAS、产物保存到/work。需要始终牢记的是：这是一条自维护的进阶路线，PentAGI 不提供任何 OpenVAS 的安装、编排或 API 集成能力，镜像的可用性与服务的就绪完全由部署者负责。

【免费下载链接】pentagiFully autonomous AI Agents system capable of performing complex penetration testing tasks项目地址: https://gitcode.com/GitHub_Trending/pe/pentagi