PentestCode 是一个多智能体 AI 渗透测试系统，可在终端中自主运行。它采用“战略师-协调员”架构，通过 13 个协同工作的专业智能体，对目标进行系统化的信息收集、漏洞识别、利用和报告生成，整个过程的状态和发现都会被持久化记录。

本教程将指导您完成 PentestCode 的安装、配置和基本使用。

1. 项目概览与核心价值

核心设计理念

  • 多智能体协作 (Multi-Agent)：由一个总控智能体 (pentest) 负责任务分解和调度，并分发任务给 13 个专业子智能体（如侦察、扫描、利用、身份认证、Web应用等）并行执行，效率远高于单智能体。
  • 持久化状态 (Persistent State)：所有扫描结果、发现的漏洞、凭据、访问权限和攻击路径都存储在一个结构化的“交战状态”中。会话关闭后，下次启动可从中断处继续。
  • 结构化工具 (Structured Tools)：提供了 18 个专门的解析和操作工具（如 nmap_parse, nuclei_parse），确保工具输出被正确解析并录入状态，而非依赖智能体猜测。

适用场景

  • 渗透测试：遵循完整方法论，从侦察到报告。
  • CTF 竞赛：管理多目标、跟踪 Flag。
  • 漏洞赏金：自动化 Web 应用测试、API 安全审查。
  • 基础设施安全审计：网络服务扫描、默认凭据检查。

2. 环境准备

PentestCode 设计为单一自包含二进制文件，无需 Node.js、Bun 等运行时环境，极大简化了部署。

2.1 基础要求

  • 操作系统：Linux 或 macOS (支持 x64 和 ARM64 架构)。Windows 目前不在官方支持列表中。
  • 权限：运行渗透测试工具（如 nmap）通常需要管理员/root 权限。
  • 网络：能够访问目标系统和 LLM API 端点。

2.2 安装 PentestCode

您可以通过以下两种方式安装：

方式一：使用官方安装脚本 (推荐)

1
curl -fsSL https://raw.githubusercontent.com/s0ld13rr/pentestcode/main/install.sh | bash

该脚本会自动下载适合您系统架构的二进制文件并安装。

方式二：使用 npm (如果已安装 Node.js 环境)

1
npm install -g pentestcode-ai

其他安装选项：

  • 指定版本：PENTESTCODE_VERSION=0.1.7 curl -fsSL ... | bash
  • 自定义安装目录：PENTESTCODE_INSTALL=/usr/local/bin curl -fsSL ... | bash

2.3 验证安装

安装完成后，在终端中运行以下命令，确认安装成功并查看版本信息：

1
pentestcode --version

3. 配置与初始设置

3.1 配置 LLM 提供商

PentestCode 本身不包含 AI 模型，需要连接外部 LLM API。支持 20 多种提供商，包括 Anthropic、OpenAI、Google、Azure、Ollama 等。

  1. 登录/认证：使用命令连接您的 LLM 提供商。例如，使用 Anthropic 的 Claude：

    1
    pentestcode auth login

    该命令会引导您设置 API 密钥。您也可以通过配置文件手动设置。

  2. 配置文件：配置文件位于 ~/.pentestcode/pentestcode.jsonc。您可以在此指定默认模型等设置。示例：

    1
    2
    3
    4
    5
    6
    7
    {
      "provider": {
        "anthropic": {
          "model": "claude-sonnet-4-20250514"
        }
      }
    }

    支持的提供商包括：Anthropic, OpenAI, Google, Azure, AWS Bedrock, Ollama, Together, Groq, Fireworks, DeepSeek, Mistral 等。

4. 使用 PentestCode

4.1 启动交互式会话

在终端中直接输入 pentestcode 并回车，即可启动一个交互式会话。您会看到一个类似 Shell 的提示符，可以输入自然语言指令或斜杠命令。

1
pentestcode

4.2 核心操作模式

您可以通过 /mode 命令在三种操作模式间切换：

模式 描述
auto (自动) 智能体自主运行，按渗透测试阶段推进，自动生成并执行任务。这是最核心的模式。
guided (引导) 智能体每执行一步都会提出建议，并等待您批准后再执行。适合学习和谨慎操作。
free (自由) 无阶段结构，智能体直接响应您的具体请求（如“扫描 80 端口”），并绕过范围检查。

暂停行为：结合 /pause 命令，您可以设置在特定条件下暂停执行：

  • never：从不暂停。
  • always：每一步都暂停，等待确认。
  • checkpoint：仅在关键发现（如漏洞）时暂停。

例如，auto 模式 + pause always 可实现“自动执行，但每个重要发现都需人工审核”的流程。

4.3 关键斜杠命令 (Slash Commands)

在交互式会话中，使用以下命令查看和管理渗透测试进程：

命令 功能
/status 显示交战状态仪表盘：主机、漏洞、凭据、当前阶段总览。
/targets 列出发现的主机和服务详细信息。
/vulns 按严重程度列出所有发现的漏洞。
/creds 显示所有已获取的凭据（用户名/密码/哈希）。
/scope 查看或修改测试目标范围（CIDR、IP、域名）。
/phase 管理当前所处的渗透测试阶段（侦察、扫描、利用等）。
/report 根据当前状态生成一份 Markdown 格式的渗透测试报告。
/pause / /resume 手动暂停或恢复智能体的活动。
/exit 退出当前会话（状态会自动保存）。

4.4 单次任务模式

您也可以不进入交互式会话，直接执行一条指令：

1
pentestcode --prompt "对 10.10.10.0/24 网段进行扫描并枚举所有服务"

5. 理解工作流与状态

PentestCode 的核心优势在于其结构化的流程和共享状态。一个典型的攻击链如下：

  1. 您发出指令：例如 pentest 10.10.10.5。
  2. 总控智能体规划：将目标拆解为侦察任务。
  3. 侦察智能体执行：调用 nmap 扫描端口，并将结果传给 nmap_parse 工具。
  4. 状态自动更新：nmap_parse 解析输出，将发现的主机、端口、服务版本写入“交战状态”数据库。所有智能体都能立即查询到这些信息。
  5. 专业化推进：其他智能体（如 Web 应用智能体、AD 智能体）根据新数据，并行启动更深入的服务枚举或漏洞检查。
  6. 利用与后渗透：一旦发现有效凭据或漏洞，利用智能体会尝试获得访问权限，并更新状态中的“访问”和“凭据”部分。
  7. 路径规划：系统会基于实体关系图（如 ADMIN_OF, PIVOT_TO），使用 Dijkstra 算法计算最短攻击路径。

您可以通过 /status 或直接查看项目目录下的 findings.md 文件（tail -f findings.md）来实时跟踪整个过程的进展和发现。

6. 高级功能：技能 (Skills) 与自定义

PentestCode 内置了 19 个技能包，它们是按需加载的 Markdown 知识文档，不会占用常规上下文。这些技能包括阶段检查清单、具体服务知识、操作手册等。

  • 自定义技能：您可以通过添加自己的 SKILL.md 文件到技能目录（~/.pentestcode/skills/）来扩展其知识库，无需修改代码。这非常适合添加内部流程、特定应用知识或自定义检查列表。

7. 常见问题与排查

问题 可能原因与解决方案
pentestcode 命令未找到 安装目录未加入 PATH 环境变量。找到安装位置（如 /usr/local/bin）并添加到您的 ~/.bashrc 或 ~/.zshrc 中。
API 认证失败 API 密钥未正确设置或已过期。请重新运行 pentestcode auth login 设置正确的 API 密钥，并检查您的网络能否正常访问 API 端点。
工具（如 nmap）执行失败 系统未安装目标工具。PentestCode 会调用系统工具（如 nmap, nuclei），请确保它们已安装且在 PATH 中。建议在运行前用 which nmap 等命令确认。
智能体行为循环或低效 这是 beta 版本的可能缺陷。请收集相关的 findings.md 和终端输出，并在 GitHub 仓库中提交 Issue，这能帮助项目变得更好。
如何完全重置测试状态？ 删除项目目录下的 .pentestcode 文件夹（这是一个隐藏文件夹）。注意，此操作将清除所有进度和数据。

通过以上步骤，您已经成功部署了 PentestCode。请务必注意：该工具应仅用于您拥有合法授权测试的目标。未经授权的扫描和利用活动是违法的。现在，您可以开始体验 AI 驱动的自动化渗透测试了。