Pentest Harness AI 渗透测试工作台详细部署教程

Pentest Harness 是一个专为授权渗透测试、漏洞赏金、安全实验室和 CTF 挑战设计的开源 AI 智能体工作台。它采用插件化架构，支持接入任何 AI 模型 API，并提供完整的工具集（Shell、文件系统、Web 研究等），帮助安全专家更高效地完成测试任务。本教程将指导您完成从安装到首次运行的完整部署流程。

📋 目录

  1. Pentest Harness 是什么
  2. 核心功能
  3. 系统要求与准备
  4. 安装步骤
  5. 首次运行与配置
  6. 核心使用指南
  7. 更新与卸载
  8. 常见问题排查
  9. 安全与法律声明

Pentest Harness 是什么

Pentest Harness 是一个自托管的 AI 驱动工作台，专为网络安全专业人士设计。它不是一个自动化渗透工具，而是一个能极大提升测试效率的智能助手。

核心特性：

  • AI 模型无关：支持 OpenAI、Anthropic、DeepSeek、Google、Groq、OpenRouter 以及任何 OpenAI 兼容的 API 网关，自带模型自动发现功能。
  • 完整的智能体工具集：提供 Shell 命令执行、文件系统操作、Web 研究、子任务、技能调用等，覆盖渗透测试常见需求。
  • 持久化会话：基于 JSONL/SQLite 的会话持久化，支持中断后精准恢复，测试进度不丢失。
  • 安全凭据存储：API 密钥存储在仅所有者可读的凭据库中，不会写入设置文件或日志。
  • 专注的深色主题：专为长时间测试设计的低眩光界面。
  • 完全插件化：基于 Cordis 架构，每个层级（模型适配器、工具、会话、设置）都可替换。

核心功能

功能模块 描述
多提供商 LLM 引擎 支持 OpenAI、Anthropic、DeepSeek 等，一键自动发现模型
智能体工具集 Shell、文件系统、Web 研究、技能、子智能体、后台任务
渗透测试模式 为授权测试提供的专业操作标准
提供商卡片 实时连接测试、启用/禁用切换、上下文长度显示
持久化会话 JSONL/SQLite 持久化，支持会话回放和恢复
上下文管理 Token 计量、自动压缩、工具结果修剪，防止上下文溢出
安全凭据存储 API 密钥存储在仅所有者可读的凭据存储中，绝不在设置文件或日志中暴露

系统要求与准备

软件要求

  • Node.js：版本 20 或更高（推荐 Node.js 22 LTS）。
  • pnpm：包管理器。如果未安装，可通过 npm i -g pnpm 全局安装。
  • Git：用于克隆仓库。

硬件要求

  • 内存：建议 ≥ 4GB，运行大型 AI 模型推理时需要更多。
  • 网络：需要访问互联网以下载依赖和接入 AI 模型 API。

安装步骤

1. 克隆仓库

1
2
git clone https://github.com/S1N6H/pentest-harness.git
cd pentest-harness

2. 安装依赖

1
pnpm install

此命令会安装工作区所有依赖。

3. 构建项目

1
pnpm build

构建所有包和应用程序。

4. 启动 Web 界面

1
pnpm dsh web

Web UI 默认在 http://127.0.0.1:2323 打开。

如果 pnpm dsh 命令未找到，可以尝试：

1
2
3
pnpm exec dsh web
# 或直接调用
node apps/cli/lib/index.js web

指定其他端口：

1
pnpm dsh web --port 3000

首次运行与配置

1. 访问 Web UI

在浏览器中打开 http://127.0.0.1:2323。

2. 配置 AI 模型提供商

这是使用前必须完成的步骤。

  1. 在 Web UI 中，导航至 Settings (设置) → Models (模型)。
  2. 点击 Add a custom provider (添加自定义提供商) 或编辑现有的提供商卡片。
  3. 填入 API 信息：
    • API Base URL：粘贴您的 API 端点地址（如 OpenAI 的 https://api.openai.com/v1，或 OpenRouter 的 https://openrouter.ai/api/v1）。提供商的 ID 和显示名称通常会自动填充。
    • API Key：输入您的 API 密钥。密钥会安全地存储在本地凭据存储中，不会写入设置文件。
  4. 保存并发现模型：保存后，系统会尝试从该端点自动发现可用模型。您可以从列表中添加所需的模型。
  5. 选择模型：在对话编辑器 (composer) 中选择您刚添加的模型，即可开始使用。

核心使用指南

创建与管理会话

  • 新会话：在 Web UI 中点击“新建会话”，选择要使用的 AI 模型和渗透测试模式。
  • 持久会话：所有会话会自动保存。您可以在任何时间关闭并重新打开会话，进度不会丢失。

使用智能体工具

在对话中，您可以通过自然语言指示 AI 智能体执行任务，例如：

  • 文件系统操作："列出当前目录下的所有文件"。
  • Shell 命令执行："运行 nmap -sV 192.168.1.1"。
  • Web 研究："搜索最新的 CVE-2024-XXXX 漏洞详情"。
  • 子任务委托："创建一个子智能体来扫描目标网站的 /admin 目录"。

渗透测试模式

启用“渗透测试模式”后，系统会遵循一套更严格的操作标准，适用于授权的渗透测试。此模式可能包含更详细的审计日志和操作审批流程。

更新与卸载

更新 Pentest Harness

  1. 进入项目目录：cd pentest-harness
  2. 拉取最新代码：git pull
  3. 更新依赖：pnpm install
  4. 重新构建：pnpm build
  5. 重启 Web 服务：pnpm dsh web

卸载

由于是源码部署，卸载只需删除 pentest-harness 整个目录即可。

常见问题排查

问题：pnpm install 失败或非常慢。

  • 解决：确认网络连接稳定。可尝试切换 npm 镜像源（如淘宝镜像），或设置代理。也可尝试删除 node_modules 和 pnpm-lock.yaml 后重新运行 pnpm install。

问题：运行 pnpm dsh web 后无法访问 http://127.0.0.1:2323。

  • 解决：
    1. 确认终端没有报错，服务已成功启动。
    2. 检查防火墙是否阻止了本地端口 2323。
    3. 确保没有其他程序占用该端口。

问题：配置 AI 提供商后无法发现模型。

  • 解决：
    1. 确认 API Base URL 和 API Key 填写正确。
    2. 检查网络能否正常访问该 API 端点。
    3. 部分网关可能需要特定的 API 路径，可参考提供商的文档调整 Base URL。

问题：会话中工具执行报错。

  • 解决：检查当前工作目录是否有足够权限。某些敏感操作（如文件写入、系统命令）可能需要在运行工作台的用户权限下才能执行。

安全与法律声明

重要声明：

  • 仅限授权使用：此工具必须在获得明确授权的情况下，用于合法的安全测试、漏洞赏金计划或自有的实验环境。严禁用于任何未经授权的网络攻击或入侵行为。
  • 使用者责任：您有责任确保您的所有操作符合相关法律法规和目标系统的服务条款。项目作者和贡献者对因不当使用本工具产生的任何后果概不负责。
  • 数据安全：虽然项目采用本地存储凭据，但您仍需对本地工作台的安全负责，防止未授权访问。

通过以上步骤，您应该能够成功部署并开始使用 Pentest Harness。这是一个功能强大的安全测试辅助平台，能够有效提升渗透测试和漏洞研究的效率。请始终以合法合规的方式使用它。