NullAILab/PENNULL
GitHub: NullAILab/PENNULL
基于多 Agent AI 系统的自主渗透测试平台，结合大语言模型推理能力与专业安全工具，实现从侦察到报告的端到端自动化安全测试。
Stars: 1 | Forks: 0
# PENNULL
React + TypeScript] API[Backend API
Go + GraphQL] DB[(Vector Store
PostgreSQL + pgvector)] MQ[Task Queue
Async Processing] Agent[AI Agents
Multi-Agent System] end subgraph Knowledge Graph Graphiti[Graphiti
Knowledge Graph API] Neo4j[(Neo4j
Graph Database)] end subgraph Monitoring Grafana[Grafana
Dashboards] VictoriaMetrics[VictoriaMetrics
Time-series DB] Jaeger[Jaeger
Distributed Tracing] Loki[Loki
Log Aggregation] OTEL[OpenTelemetry
Data Collection] end subgraph Analytics Langfuse[Langfuse
LLM Analytics] ClickHouse[ClickHouse
Analytics DB] Redis[Redis
Cache + Rate Limiter] MinIO[MinIO
S3 Storage] end subgraph Security Tools Scraper[Web Scraper
Isolated Browser] PenTest[Security Tools
20+ Pro Tools
Sandboxed Execution] end UI --> |HTTP/WS| API API --> |SQL| DB API --> |Events| MQ MQ --> |Tasks| Agent Agent --> |Commands| PenTest Agent --> |Queries| DB Agent --> |Knowledge| Graphiti Graphiti --> |Graph| Neo4j API --> |Telemetry| OTEL OTEL --> |Metrics| VictoriaMetrics OTEL --> |Traces| Jaeger OTEL --> |Logs| Loki Grafana --> |Query| VictoriaMetrics Grafana --> |Query| Jaeger Grafana --> |Query| Loki API --> |Analytics| Langfuse Langfuse --> |Store| ClickHouse Langfuse --> |Cache| Redis Langfuse --> |Files| MinIO classDef core fill:#f9f,stroke:#333,stroke-width:2px,color:#000 classDef knowledge fill:#ffa,stroke:#333,stroke-width:2px,color:#000 classDef monitoring fill:#bbf,stroke:#333,stroke-width:2px,color:#000 classDef analytics fill:#bfb,stroke:#333,stroke-width:2px,color:#000 classDef tools fill:#fbb,stroke:#333,stroke-width:2px,color:#000 class UI,API,DB,MQ,Agent core class Graphiti,Neo4j knowledge class Grafana,VictoriaMetrics,Jaeger,Loki,OTEL monitoring class Langfuse,ClickHouse,Redis,MinIO analytics class Scraper,PenTest tools ```
Embeddings DB)] KB[Knowledge Base
Domain Expertise] Tools[Tools Knowledge
Usage Patterns] end subgraph "Working Memory" Context[Current Context
Task State] Goals[Active Goals
Objectives] State[System State
Resources] end subgraph "Episodic Memory" Actions[Past Actions
Commands History] Results[Action Results
Outcomes] Patterns[Success Patterns
Best Practices] end Context --> |Query| VS VS --> |Retrieve| Context Goals --> |Consult| KB KB --> |Guide| Goals State --> |Record| Actions Actions --> |Learn| Patterns Patterns --> |Store| VS Tools --> |Inform| State Results --> |Update| Tools VS --> |Enhance| KB KB --> |Index| VS classDef ltm fill:#f9f,stroke:#333,stroke-width:2px,color:#000 classDef wm fill:#bbf,stroke:#333,stroke-width:2px,color:#000 classDef em fill:#bfb,stroke:#333,stroke-width:2px,color:#000 class VS,KB,Tools ltm class Context,Goals,State wm class Actions,Results,Patterns em ```
` 和 `` 部分
- **可配置**：通过 `EXECUTION_MONITOR_ENABLED` 启用（默认：false），使用 `EXECUTION_MONITOR_SAME_TOOL_LIMIT` 和 `EXECUTION_MONITOR_TOTAL_TOOL_LIMIT` 自定义阈值
**最适用于**：较小的模型（< 32B 参数），需要持续指导的复杂攻击场景，防止 Agent 困在单一方法上
**性能影响**：执行时间和 token 使用量增加 2-3 倍，但根据 Qwen3.5-27B-FP8 的测试，结果质量可**提升 2 倍**
### 智能任务规划 (Beta)
- **自动分解**：规划器（处于规划模式的顾问）在专业 Agent 开始工作之前生成 3-7 个具体的、可操作的步骤
- **上下文感知计划**：通过丰富器 Agent 分析完整的执行上下文以创建明智的计划
-结构化分配**：原始请求包装在带有执行计划和指令的 `` 结构中
- **范围管理**：通过让 Agent 仅专注于当前子任务来防止范围蔓延
- **丰富的指令**：计划突出关键操作、潜在陷阱和验证点
- **可配置**：通过 `AGENT_PLANNING_STEP_ENABLED` 启用（默认：false）
**最适用于**：< 32B 参数的模型，复杂的渗透测试工作流，提高复杂任务的成功率
**增强的顾问配置**：当顾问 Agent 使用更强的模型或增强的设置时，效果尤为出色。例如：对顾问使用相同的基础模型并开启最大推理模式（参见 [`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml))，可以在相同的模型架构下实现全面的任务分析和战略规划。
**性能影响**：增加规划开销，但显著提高完成率并减少冗余工作
### 工具调用限制 (始终激活)
- **硬性限制**：无论监督模式状态如何，都防止失控执行
- **按 Agent 类型区分**：
- 通用 Agent (Assistant, Primary Agent, Pentester, Coder, Installer)：`MAX_GENERAL_AGENT_TOOL_CALLS`（默认：100）
- 有限 Agent (Searcher, Enricher, Memorist, Generator, Reporter, Adviser, Reflector, Planner)：`MAX_LIMITED_AGENT_TOOL_CALLS`（默认：20）
- **优雅终止**：Reflector 在接近限制时引导 Agent 正确完成
- **资源保护**：确保系统稳定性并防止资源耗尽
### Reflector 集成 (始终激活)
- **自动纠正**：当 LLM 在 3 次尝试后未能生成工具调用时被调用
- **战略指导**：分析失败并引导 Agent 正确使用工具或障碍工具（`done`，`ask`）
- **恢复机制**：根据特定的失败模式提供上下文指导
- **限制执行**：当达到工具调用限制时协调优雅终止
### 开源模型建议
**小于 32B 参数的模型必备**：
使用 Qwen3.5-27B-FP8 进行的测试表明，启用执行监控和任务规划对于较小的开源模型是**必不可少**的：
- **质量提升**：与没有监督的基线执行相比，结果好 2 倍
- **防止循环**：显著减少无限循环和冗余工作
- **攻击多样性**：鼓励探索多种攻击向量，而不是固守单一方法
- **气隙部署**：能够在具有本地 LLM 推理的封闭网络环境中进行生产级自主渗透测试
**权衡**：
- token 消耗：由于导师/规划器的调用增加 2-3 倍
- 执行时间：由于分析和规划步骤长 2-3 倍
- 结果质量：在完整性、准确性和攻击覆盖率方面提高 2 倍
- 模型要求：当顾问使用增强配置（更高的推理参数、更强的模型变体或不同的模型）时效果最佳
**配置策略**：
为了在使用较小模型时获得最佳性能，请使用增强设置为顾问 Agent 进行配置：
- 使用具有最大推理模式的相同模型（例如：[`vllm-qwen3.5-27b-fp8.provider.yml`](examples/configs/vllm-qwen3.5-27b-fp8.provider.yml))
- 或者对顾问使用更强的模型，同时其他 Agent 保留基础模型
- 根据任务复杂性和模型能力调整监控阈值
penNULL 的架构设计为模块化、可扩展且安全。以下是关键组件：
1. **核心服务**
- 前端 UI：基于 React 的 Web 界面，使用 TypeScript 确保类型安全
- 后端 API：基于 Go 的 REST 和 GraphQL API，具有用于编程访问的 Bearer token 身份验证
- 向量存储：带有 pgvector 的 PostgreSQL，用于语义搜索和记忆存储
- 任务队列：用于可靠操作的异步任务处理系统
- AI Agent：具有专门角色的多 Agent 系统，用于高效测试
2. **知识图谱**
- Graphiti：用于语义关系跟踪和上下文理解的知识图谱 API
- Neo4j：用于存储和查询实体、行动和结果之间关系的图数据库
- 自动捕获 Agent 响应和工具执行，以构建全面的知识库
3. **监控堆栈**
- OpenTelemetry：统一的可观测性数据收集和关联
- Grafana：实时可视化和警报仪表板
- VictoriaMetrics：高性能时间序列指标存储
- Jaeger：端到端分布式跟踪以进行调试
- Loki：可扩展的日志聚合和分析
4. **分析平台**
- Langfuse：高级 LLM 可观测性和性能分析
- ClickHouse：列式分析数据仓库
- Redis：高速缓存和速率限制
- MinIO：与 S3 兼容的对象存储，用于工件
5. **安全工具**
- Web Scraper：隔离的浏览器环境，用于安全的网络交互
- 渗透测试工具：包含 20 多种专业安全工具的综合套件
- 沙箱执行：所有操作都在隔离的容器中运行
6. **记忆系统**
- 长期记忆：持久化存储知识和经验
- 工作记忆：当前操作的主动上下文和目标
- 情景记忆：历史行动和成功模式
- 知识库：结构化的领域专业知识和工具能力
- 上下文管理：使用链式摘要智能管理不断增长的 LLM 上下文窗口
系统使用 Docker 容器进行隔离和轻松部署，为核心服务、监控和分析设置独立的网络以确保适当的安全边界。每个组件都设计为可水平扩展的，并且可以在生产环境中配置为高可用性。
## 快速开始
### 第 1 步 — 系统要求
在开始之前，请确保您的机器满足以下要求：
| 要求 | 最低配置 |
|---|---|
| CPU | 2 vCPU |
| RAM | 4 GB |
| 磁盘 | 20 GB 可用空间 |
| 软件 | Docker + Docker Compose (或 Podman) |
| 网络 | 互联网访问 (用于拉取镜像) |
| LLM 提供商 | 至少一个 API 密钥 — OpenAI, Anthropic, Gemini, AWS Bedrock, 或 Ollama |
### 第 2 步 — 安装 Docker
如果您的系统上已经安装了 Docker，请跳过此步。
### 第 3 步 — 下载并配置
**1. 创建工作目录**
```
# Linux / macOS
mkdir pennull && cd pennull
```
```
# Windows (PowerShell)
mkdir pennull; cd pennull
```
**2. 下载配置文件**
```
# Linux / macOS
curl -O https://raw.githubusercontent.com/nullailab/pennull/master/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/nullailab/pennull/master/.env.example
curl -o example.custom.provider.yml https://raw.githubusercontent.com/nullailab/pennull/master/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/nullailab/pennull/master/examples/configs/ollama-llama318b.provider.yml
```
```
# Windows (PowerShell)
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nullailab/pennull/master/docker-compose.yml" -OutFile "docker-compose.yml"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nullailab/pennull/master/.env.example" -OutFile ".env"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nullailab/pennull/master/examples/configs/custom-openai.provider.yml" -OutFile "example.custom.provider.yml"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/nullailab/pennull/master/examples/configs/ollama-llama318b.provider.yml" -OutFile "example.ollama.provider.yml"
```
**3. 添加您的 LLM API 密钥**
使用任何文本编辑器打开 `.env` 并设置以下**至少一项**：
```
# 选择一个或多个 — 至少需要一个
OPEN_AI_KEY=sk-... # OpenAI (GPT-4, o3, o4-mini, …)
ANTHROPIC_API_KEY=sk-ant-... # Anthropic (Claude 3.5, Claude 4, …)
GEMINI_API_KEY=AIza... # Google AI (Gemini 2.0, Gemini 2.5, …)
```
对于**使用 Ollama 的本地推理**（无需云密钥）：
```
OLLAMA_SERVER_URL=http://host.docker.internal:11434 # Windows / macOS
# OLLAMA_SERVER_URL=http://172.17.0.1:11434 # Linux (Docker bridge)
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
```
**4. 强化安全凭证** *(在任何网络暴露之前强烈建议)*
打开 `.env` 并将这些值更改为随机字符串：
```
COOKIE_SIGNING_SALT=change-this-to-a-random-value
PENNULL_POSTGRES_USER=pennull
PENNULL_POSTGRES_PASSWORD=change-this-password
PUBLIC_URL=https://localhost:8443 # Set to your actual domain/IP for remote access
```
**5. 启动 penNULL**
```
# Linux / macOS / Windows (Docker Desktop 的 PowerShell)
docker compose up -d
```
观察容器启动：
```
docker compose logs -f pennull
```
在打开浏览器之前，请等待直到看到类似 `server started on :8443` 的行。
### 第 4 步 — 访问 penNULL
打开浏览器并访问：
```
https://localhost:8443
```
### 第 5 步 — 登录并保护您的账户
使用**默认凭证**登录：
| 字段 | 值 |
|---|---|
| **邮箱** | `admin@pennull.com` |
| **密码** | `admin` |
### 接下来做什么？
| 目标 | 去哪里 |
|---|---|
| 运行你的第一次渗透测试 | → [运行你的第一次渗透测试](#running-your-first-pentest) |
| 从另一台机器访问 penNULL | → [外部网络访问](#accessing-pennull-from-external-networks) |
| 添加更多 LLM 提供商 | → [LLM 提供商配置](#custom-llm-provider-configuration) |
| 启用 Langfuse / Grafana | → [高级设置](#advanced-setup) |
| 使用 REST / GraphQL API | → [API 访问](#api-access) |
### 从外部网络访问 penNULL
默认情况下，penNULL 绑定到 `127.0.0.1`（仅本地主机）。要允许从网络上的其他机器进行访问：
**1. 更新 `.env`：**
```
PENNULL_LISTEN_IP=0.0.0.0
PENNULL_LISTEN_PORT=8443
PUBLIC_URL=https://192.168.1.100:8443 # ← replace with your actual IP
CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443
```
**2. 重新创建容器：**
```
docker compose down
docker compose up -d --force-recreate
```
**3. 验证端口绑定：**
```
docker ps | grep pennull
# 预期：0.0.0.0:8443->8443/tcp 或 :::8443->8443/tcp
```
**4. 打开防火墙端口 (仅限 Linux)：**
```
# Ubuntu / Debian
sudo ufw allow 8443/tcp && sudo ufw reload
# CentOS / RHEL
sudo firewall-cmd --permanent --add-port=8443/tcp && sudo firewall-cmd --reload
```
**5. 访问：**
- 本地：`https://localhost:8443`
- 远程：`https://your-server-ip:8443`
### 助手配置
| 变量 | 默认值 | 描述 |
|---|---|---|
| `ASSISTANT_USE_AGENTS` | `false` | 创建新助手时的默认 Agent 委派状态 |
将 `ASSISTANT_USE_AGENTS=true` 设置为默认为所有新助手启用 **Use Agents**。用户始终可以在 UI 中针对每个助手切换此选项。
## 环境配置 (.env)
所有 penNULL 设置都通过 `.env` 文件进行控制。复制参考文件并进行编辑：
```
cp .env.example .env
```
`.env.example` 文件包含**每个可用的变量及其内联注释**，解释了它的作用、接受的值以及在首次运行前必须更改哪些值。以下是最重要部分的摘要。
### ⚠️ 运行前必须更改的变量
这些变量附带了较弱的占位符值。在首次启动 penNULL 之前请更改它们：
| 变量 | 设置内容 |
|---|---|
| `COOKIE_SIGNING_SALT` | 随机字符串 — `openssl rand -hex 16` |
| `PENNULL_POSTGRES_PASSWORD` | 强密码 — `openssl rand -hex 16` |
| `LOCAL_SCRAPER_USERNAME` | 任何用户名（用于 scraper 认证） |
| `LOCAL_SCRAPER_PASSWORD` | scraper 的强密码 |
| `SCRAPER_PRIVATE_URL` | 使用上面的用户名/密码进行更新 |
| `NEO4J_PASSWORD` | 强密码（如果使用 Graphiti） |
| `LANGFUSE_POSTGRES_PASSWORD` | 强密码（如果使用 Langfuse） |
| `LANGUSE_CLICKHOUSE_PASSWORD` | 强密码（如果使用 Langfuse） |
| `LANGFUSE_REDIS_AUTH` | 强密码 — `openssl rand -hex 24` |
| `LANGFUSE_SALT` | 随机十六进制 — `openssl rand -hex 14` |
| `LANGFUSE_ENCRYPTION_KEY` | 64 字符十六进制 — `openssl rand -hex 32` |
| `LANGFUSE_NEXTAUTH_SECRET` | 随机字符串 — `openssl rand -hex 16` |
| `LANGFUSE_S3_ACCESS_KEY_ID` | 任何字符串，最少 3 个字符 |
| `LANGFUSE_S3_SECRET_ACCESS_KEY` | 任何字符串，最少 8 个字符 |
| `LANGFUSE_INIT_USER_PASSWORD` | Langfuse 管理员密码 |
### LLM 提供商
设置**至少一个**。可以同时激活多个提供商。
| 提供商 | 关键变量 | 备注 |
|---|---|---|
| OpenAI | `OPEN_AI_KEY` | 支持 GPT-4.1, o3, o4-mini 等 |
| Anthropic | `ANTHROPIC_API_KEY` | 支持 Claude 3.5, Claude 4 等 |
| Google AI | `GEMINI_API_KEY` | 支持 Gemini 2.0, 2.5 等 |
| AWS Bedrock | `BEDROCK_REGION` + auth | 多种认证方式 — 详见 `.env.example` |
| DeepSeek | `DEEPSEEK_API_KEY` | 强推理模型 |
| GLM (智谱) | `GLM_API_KEY` | |
| Kimi (月之暗面) | `KIMI_API_KEY` | 超长上下文 |
| Qwen (阿里巴巴) | `QWEN_API_KEY` | 多模态支持 |
| 自定义 / OpenRouter | `LLM_SERVER_URL` + `LLM_SERVER_KEY` | 任何兼容 OpenAI 的端点 |
| Ollama (本地) | `OLLAMA_SERVER_URL` + `OLLAMA_SERVER_MODEL` | 零成本，无需互联网 |
### Embeddings
```
EMBEDDING_PROVIDER=ollama # openai | ollama | mistral | jina | huggingface | googleai | voyageai
EMBEDDING_MODEL=nomic-embed-text # Model name for your chosen provider
EMBEDDING_URL=http://host.docker.internal:11434 # Leave empty to inherit from LLM provider
```
### Agent 行为
| 变量 | 默认值 | 描述 |
|---|---|---|
| `ASSISTANT_USE_AGENTS` | `true` | 为新助手默认启用多 Agent 模式 |
| `ASK_USER` | `true` | 允许 Agent 暂停并请求输入 |
| `AGENT_PLANNING_STEP_ENABLED` | `true` | 在每个子任务之前生成执行计划（推荐用于较小的模型） |
| `EXECUTION_MONITOR_ENABLED` | `false` | 为卡死检测启用导师 Agent（2-3 倍 token 成本，2 倍质量提升） |
| `MAX_GENERAL_AGENT_TOOL_CALLS` | `100` | 主要/渗透测试/编码器 Agent 的硬性限制 |
| `MAX_LIMITED_AGENT_TOOL_CALLS` | `20` | 搜索器/记忆器/报告器 Agent 的硬性限制 |
### 搜索引擎
DuckDuckGo 和 Sploitus 是免费的（无需密钥）。所有其他都需要 API 密钥。
```
DUCKDUCKGO_ENABLED=true # Free web search
SPLOITUS_ENABLED=true # Free exploit/CVE search
TAVILY_API_KEY= # Best for research tasks
GOOGLE_API_KEY= # Google Custom Search
PERPLEXITY_API_KEY= # AI-powered search
SEARXNG_URL= # Self-hosted meta search
```
### 可选堆栈
| 堆栈 | Compose 文件 | 用于启用的关键变量 |
|---|---|---|
| Langfuse (LLM 跟踪) | `docker-compose-langfuse.yml` | `LANGFUSE_BASE_URL=http://langfuse-web:3000` |
| Graphiti (知识图谱) | `docker-compose-graphiti.yml` | `GRAPHITI_ENABLED=true` + `GRAPHITI_URL=http://graphiti:8000` |
| 可观测性 (Grafana) | `docker-compose-observability.yml` | `OTEL_HOST=otelcol:8148` |
一起启动所有堆栈：
```
docker compose -f docker-compose.yml \
-f docker-compose-langfuse.yml \
-f docker-compose-graphiti.yml \
-f docker-compose-observability.yml up -d
```
## 运行你的第一次渗透测试
完成快速开始安装后，请按照以下步骤运行你的第一次自主渗透测试。
### 1. 访问 Web UI
打开浏览器并导航到：
```
https://localhost:8443
```
### 2. 登录
使用默认凭证登录：
| 字段 | 默认值 |
| -------- | --------------------- |
| 邮箱 | `admin@pennull.com` |
| 密码 | `admin` |
### 3. 验证 LLM 提供商
在运行测试之前，请确认已配置至少一个 LLM 提供商：
1. 转到 **Settings → Providers**
2. 验证您的 API 密钥是否存在并且连接测试通过（绿色对勾）
3. 如果未设置提供商，请在 `.env` 中添加您的 API 密钥并重新启动堆栈：
```
docker compose down && docker compose up -d
```
### 4. 创建一个助手
助手定义了 penNULL 将使用的 AI 模型和 Agent 设置。
1. 点击左侧边栏中的 **Assistants**
2. 点击 **New Assistant**
3. 选择一个名称（例如 `Web App Tester`）
4. 选择您的 LLM 提供商和模型
5. 切换 **Use Agents** 以启用完整的多 Agent 模式
6. 点击 **Save**
### 5. 启动渗透测试流程
1. 点击左侧边栏中的 **New Flow**（或 **+** 按钮）
2. 选择您在第 4 步中创建的助手
3. 在消息输入框中，描述您的目标和范围，例如：
对 http://192.168.1.100 执行一次全面的渗透测试。
重点关注 Web 应用程序漏洞（SQLi、XSS、IDOR、身份验证绕过）。
该目标是我拥有并拥有完全测试授权的实验机器。
4. 按 **Enter**（或点击 **Send**）以启动流程
### 6. 监控 Agent 进度
一旦流程开始，您可以实时观察 Agent 的工作：
- **Flow 视图** — 显示当前任务、活跃的 Agent 和实时的工具输出
- **Tasks 面板** — 列出已完成和正在进行中的任务及其状态指示器
- **Logs 面板** — 显示来自 Docker 沙箱的原始工具输出
Agent 将自动在侦察、漏洞发现、利用尝试和报告生成之间推进，无需任何手动步骤。
### 7. 查看和导出报告
当流程到达 **Reporter** Agent 时，将自动生成结构化的漏洞报告：
1. 在侧边栏中点击显示为 **Completed** 的流程
2. 打开 **Report** 选项卡以阅读格式化的漏洞摘要
3. 使用 **Export** 按钮将报告下载为 Markdown 或 PDF
报告包括：
- 执行摘要
- 发现的漏洞列表及其 CVSS 评分
- 漏洞利用证据和概念验证详情
- 修复建议
## API 访问
penNULL 通过 REST 和 GraphQL API 提供全面的编程访问，允许您将渗透测试工作流集成到您的自动化流水线、CI/CD 流程和自定义应用程序中。
### 生成 API Token
API Token 通过 penNULL Web 界面进行管理：
1. 在 Web UI 中导航至 **Settings** → **API Tokens**
2. 点击 **Create Token** 以生成新的 API Token
3. 配置 Token 属性：
- **名称**（可选）：Token 的描述性名称
- **过期日期**：Token 过期时间（最短 1 分钟，最长 3 年）
4. 点击 **Create** 并**立即复制 Token** - 出于安全原因，它只会显示一次
5. 在您的 API 请求中将此 Token 作为 Bearer Token 使用
每个 Token 都与您的用户账户关联，并继承您角色的权限。
### 使用 API Token
在您的 HTTP 请求的 `Authorization` 头中包含 API Token：
```
# GraphQL API 示例
curl -X POST https://your-pennull-instance:8443/api/v1/graphql \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"query": "{ flows { id title status } }"}'
# REST API 示例
curl https://your-pennull-instance:8443/api/v1/flows \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
### API 探索和测试
penNULL 提供了交互式文档，用于探索和测试 API 端点：
#### GraphQL Playground
访问 `https://your-pennull-instance:8443/api/v1/graphql/playground` 处的 GraphQL Playground
1. 点击底部的 **HTTP Headers** 选项卡
2. 添加您的授权头：
{
"Authorization": "Bearer YOUR_API_TOKEN"
}
3. 交互式地探索 schema、运行查询并测试修改
#### Swagger UI
访问 `https://your-pennull-instance:8443/api/v1/swagger/index.html` 处的 REST API 文档
1. 点击 **Authorize** 按钮
2. 以以下格式输入您的 Token：`Bearer YOUR_API_TOKEN`
3. 点击 **Authorize** 以应用
4. 直接从 Swagger UI 测试端点
### 生成 API 客户端
您可以使用 penNULL 附带的 schema 文件为您喜欢的编程语言生成类型安全的 API 客户端：
#### GraphQL 客户端
GraphQL schema 可在以下位置获取：
- **Web UI**：导航到设置以下载 `schema.graphqls`
- **直接文件**：代码库中的 `backend/pkg/graph/schema.graphqls`
使用以下工具生成客户端：
- **GraphQL Code Generator** (JavaScript/TypeScript)：[https://the-guild.dev/graphql/codegen](https://the-guild.dev/graphql/codegen)
- **genqlient** (Go)：[https://github.com/Khan/genqlient](https://github.com/Khan/genqlient)
- **Apollo iOS** (Swift)：[https://www.apollographql.com/docs/ios](https://www.apollographql.com/docs/ios)
#### REST API 客户端
OpenAPI 规范可在以下位置获取：
- **Swagger JSON**：`https://your-pennull-instance:8443/api/v1/swagger/doc.json`
- **Swagger YAML**：位于 `backend/pkg/server/docs/swagger.yaml`
使用以下工具生成客户端：
- **OpenAPI Generator**：[https://openapi-generator.tech](https://openapi-generator.tech)
openapi-generator-cli generate \
-i https://your-pennull-instance:8443/api/v1/swagger/doc.json \
-g python \
-o ./pennull-client
- **Swagger Codegen**：[https://github.com/swagger-api/swagger-codegen](https://github.com/swagger-api/swagger-codegen)
swagger-codegen generate \
-i https://your-pennull-instance:8443/api/v1/swagger/doc.json \
-l typescript-axios \
-o ./pennull-client
- **swagger-typescript-api** (TypeScript)：[https://github.com/acacode/swagger-typescript-api](https://github.com/acacode/swagger-typescript-api)
npx swagger-typescript-api \
-p https://your-pennull-instance:8443/api/v1/swagger/doc.json \
-o ./src/api \
-n pennull-api.ts
### API 使用示例
{
const query = `
mutation CreateFlow($provider: String!, $input: String!) {
createFlow(modelProvider: $provider, input: $input) {
id
title
status
createdAt
}
}
`;
const response = await this.client.post('/graphql', {
query,
variables: { provider, input },
});
return response.data.data.createFlow;
}
async getFlows(): Promise {
const response = await this.client.get('/flows');
return response.data.flows;
}
async getFlow(flowId: string): Promise {
const response = await this.client.get(`/flows/${flowId}`);
return response.data;
}
}
// Usage
const client = new penNULLClient(
'https://your-pennull-instance:8443',
'your_api_token_here'
);
// Create a new flow
const flow = await client.createFlow(
'openai',
'Perform penetration test on https://example.com'
);
console.log('Created flow:', flow);
// List all flows
const flows = await client.getFlows();
console.log(`Total flows: ${flows.length}`);
```
### 安全最佳实践
使用 API Token 时：
- **永远不要将 Token 提交到版本控制** - 使用环境变量或密钥管理
- **定期轮换 Token** - 设置适当的过期日期并定期创建新 Token
- **为不同的应用程序使用单独的 Token** - 在需要时更容易撤销访问权限
- **监控 Token 使用情况** - 在设置页面中查看 API Token 活动
- **撤销未使用的 Token** - 禁用或删除不再需要的 Token
- **仅使用 HTTPS** - 切勿通过未加密的连接发送 API Token
### Token 管理
- **查看 Token**：在 Settings → API Tokens 中查看所有活跃的 Token
- **编辑 Token**：更新 Token 名称或撤销 Token
- **删除 Token**：永久删除 Token（此操作无法撤销）
- **Token ID**：每个 Token 都有一个唯一的 ID，可以复制以供参考
Token 列表显示：
- Token 名称（如果提供）
- Token ID（唯一标识符）
- 状态（活跃/已撤销/已过期）
- 创建日期
- 过期日期
### 自定义 LLM 提供商配置
当使用带有 `LLM_SERVER_*` 变量的自定义 LLM 提供商时，您可以微调请求中使用的推理格式。
| 变量 | 默认值 | 描述 |
| ------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `LLM_SERVER_URL` | | 自定义 LLM API 端点的基本 URL |
| `LLM_SERVER_KEY` | | 自定义 LLM 提供商的 API 密钥 |
| `LLM_SERVER_MODEL` | | 要使用的默认模型（可以在提供商配置中覆盖） |
| `LLM_SERVER_CONFIG_PATH` | | 用于特定 Agent 模型的 YAML 配置文件路径 |
| `LLM_SERVER_PROVIDER` | | 模型名称的提供商前缀（例如用于 LiteLLM proxy 的 `openrouter`、`deepseek`) |
| `LLM_SERVER_LEGACY_REASONING` | `false` | 控制 API 请求中的推理格式 |
| `LLM_SERVER_PRESERVE_REASONING` | `false` | 在多轮对话中保留推理内容（某些提供商需要 |
当使用 **LiteLLM proxy**（它为模型名称添加提供商前缀）时，`LLM_SERVER_PROVIDER` 设置特别有用。例如，当通过 LiteLLM 连接到 Moonshot API 时，像 `kimi-2.5` 这样的模型会变成 `moonshot/kimi-2.5`。通过设置 `LLM_SERVER_PROVIDER=moonshot`，您可以对直接 API 访问和 LiteLLM proxy 访问使用相同的提供商配置文件，而无需修改。
`LLM_SERVER_LEGACY_REASONING` 设置会影响推理参数发送给 LLM 的方式：
- `false`（默认）：使用现代格式，其中推理作为带有 `max_tokens` 参数的结构化对象发送
- `true`：使用带有基于字符串的 `reasoning_effort` 参数的旧版格式
此设置在使用不同的 LLM 提供商时很重要，因为它们可能在其 API 请求中期望不同的推理格式。如果您在使用自定义提供商时遇到与推理相关的错误，请尝试更改此设置。
`LLM_SERVER_PRESERVE_REASONING` 设置控制是否在多轮对话中保留推理内容：
- `false`（默认）：在对话历史记录中不保留推理内容
- `true`：保留推理内容并在后续 API 调用中发送
某些 LLM 提供商（例如 Moonshot）需要此设置，当多轮对话中不包含推理内容时，它们会返回类似“thinking is enabled but reasoning_content is missing in assistant tool call message”的错误。如果您的提供商要求保留推理内容，请启用此设置。
### Ollama 提供商配置
penNULL 支持 Ollama 进行本地 LLM 推理（零成本，增强隐私）和 Ollama Cloud（具有免费套餐的托管服务）。
#### 配置变量
| 变量 | 默认值 | 描述 |
| ----------------------------------- | ----------- | ----------------------------------------- |
| `OLLAMA_SERVER_URL` | | 您的 Ollama 服务器或 Ollama Cloud 的 URL |
| `OLLAMA_SERVER_API_KEY` | | 用于 Ollama Cloud 认证的 API 密钥 |
| `OLLAMA_SERVER_MODEL` | | 用于推理的默认模型 |
| `OLLAMA_SERVER_CONFIG_PATH` | | 自定义 Agent 配置文件的路径 |
| `OLLAMA_SERVER_PULL_MODELS_TIMEOUT` | `600` | 模型下载超时时间（秒） |
| `OLLAMA_SERVER_PULL_MODELS_ENABLED` | `false` | 启动时自动下载模型 |
| `OLLAMA_SERVER_LOAD_MODELS_ENABLED` | `false` | 查询服务器以获取可用模型 |
#### Ollama Cloud 配置
Ollama Cloud 提供具有慷慨免费套餐和可扩展付费计划的托管推理。
**免费套餐设置（单模型）**
```
# 免费套餐一次仅允许使用一个模型
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_MODEL=gpt-oss:120b # Example: OpenAI OSS 120B model
```
**付费套餐设置（多模型与预构建配置）**
对于支持多个并发模型的付费套餐，请使用预构建的 Ollama Cloud 配置：
```
# 使用预构建的 Ollama Cloud 配置（包含在 Docker 镜像中）
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_CONFIG_PATH=/opt/pennull/conf/ollama-cloud.provider.yml
```
预构建的 `ollama-cloud.provider.yml` 配置包含了针对所有 Agent 类型的优化模型分配：
- **Simple/Assistant**：`nemotron-3-super:cloud` - 快速的通用模型
- **Primary Agent**：`qwen3-coder-next:cloud` - 具有高工作量的高级推理模式
- **Coder/Pentester**：`qwen3-coder-next:cloud` - 专门的编码模型
- **Searcher**：`qwen3.5:397b-cloud` - 用于信息收集的大上下文
- **Refiner/Refactor**：`glm-5:cloud` - 高质量的文本精炼
- **Adviser/Enricher**：`minimax-m2.7:cloud` - 高效的顾问任务
- **Installer**：`devstral-2:123b-cloud` - 安装和设置任务
**自定义配置（高级）**
要创建您自己的 Agent 配置，请从主机文件系统挂载自定义文件：
```
# 使用自定义 provider 配置
OLLAMA_SERVER_URL=https://ollama.com
OLLAMA_SERVER_API_KEY=your_ollama_cloud_api_key
OLLAMA_SERVER_CONFIG_PATH=/opt/pennull/conf/ollama.provider.yml
# 从主机文件系统挂载自定义配置（在 .env 或 docker-compose override 中）
PENNULL_OLLAMA_SERVER_CONFIG_PATH=/path/on/host/my-ollama-config.yml
```
`PENNULL_OLLAMA_SERVER_CONFIG_PATH` 环境变量将您的主机配置文件映射到容器内的 `/opt/pennull/conf/ollama.provider.yml`。
**自定义配置示例** (`my-ollama-config.yml`)：
```
primary_agent:
model: "qwen3-coder-next:cloud"
temperature: 1.0
top_p: 0.9
max_tokens: 32768
reasoning:
effort: high
coder:
model: "qwen3-coder:32b"
temperature: 1.0
max_tokens: 20480
```
#### 本地 Ollama 配置
对于自托管的 Ollama 实例：
```
# 基本本地 Ollama 设置
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
# 带有自动拉取和模型发现的生产设置
OLLAMA_SERVER_URL=http://ollama-server:11434
OLLAMA_SERVER_PULL_MODELS_ENABLED=true
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900
OLLAMA_SERVER_LOAD_MODELS_ENABLED=true
# 使用 Docker 镜像中的预构建配置
OLLAMA_SERVER_CONFIG_PATH=/opt/pennull/conf/ollama-llama318b.provider.yml
# 或
OLLAMA_SERVER_CONFIG_PATH=/opt/pennull/conf/ollama-qwen332b-fp16-tc.provider.yml
# 或
OLLAMA_SERVER_CONFIG_PATH=/opt/pennull/conf/ollama-qwq32b-fp16-tc.provider.yml
```
**性能注意事项：**
- **模型发现**（`OLLAMA_SERVER_LOAD_MODELS_ENABLED=true`）：增加 1-2 秒的启动延迟以查询 Ollama API
- **自动拉取**（`OLLAMA_SERVER_PULL_MODELS_ENABLED=true`）：首次启动可能需要几分钟来下载模型
- **拉取超时**（`OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900`）：以秒为单位的 15 分钟
- **静态配置**：禁用这两个标志并在配置文件中指定模型以实现最快启动
#### 使用扩展上下文创建自定义 Ollama 模型
penNULL 需要比默认 Ollama 配置具有更大上下文窗口的模型。您需要通过 Modelfile 创建具有增加的 `num_ctx` 参数的自定义模型。虽然典型的 Agent 工作流消耗大约 64K token，但 penNULL 使用 110K 的上下文大小作为安全余量，以处理复杂的渗透测试场景。
**重要提示**：`num_ctx` 参数只能在通过 Modelfile 创建模型期间设置——它不能在模型创建后更改，也不能在运行时覆盖。
##### 示例：具有扩展上下文的 Qwen3 32B FP16
创建一个名为 `Modelfile_qwen3_32b_fp16_tc` 的 Modelfile：
```
FROM qwen3:32b-fp16
PARAMETER num_ctx 110000
PARAMETER temperature 0.3
PARAMETER top_p 0.8
PARAMETER min_p 0.0
PARAMETER top_k 20
PARAMETER repeat_penalty 1.1
```
构建自定义模型：
```
ollama create qwen3:32b-fp16-tc -f Modelfile_qwen3_32b_fp16_tc
```
##### 示例：具有扩展上下文的 QwQ 32B FP16
创建一个名为 `Modelfile_qwq_32b_fp16_tc` 的 Modelfile：
```
FROM qwq:32b-fp16
PARAMETER num_ctx 110000
PARAMETER temperature 0.2
PARAMETER top_p 0.7
PARAMETER min_p 0.0
PARAMETER top_k 40
PARAMETER repeat_penalty 1.2
```
构建自定义模型：
```
ollama create qwq:32b-fp16-tc -f Modelfile_qwq_32b_fp16_tc
```
这些自定义模型在 Docker 镜像的 `/opt/pennull/conf/` 目录中包含的预构建提供商配置文件（`ollama-qwen332b-fp16-tc.provider.yml` 和 `ollama-qwq32b-fp16-tc.provider.yml`）中被引用。
### OpenAI 提供商配置
penNULL 集成了 OpenAI 全面的模型阵容，具有带有扩展思维链的高级推理能力、具有增强工具集成的代理模型，以及用于安全工程的专门代码模型。
#### 配置变量
| 变量 | 默认值 | 描述 |
| -------------------- | --------------------------- | --------------------------- |
| `OPEN_AI_KEY` | | OpenAI 服务的 API 密钥 |
| `OPEN_AI_SERVER_URL` | `https://api.openai.com/v1` | OpenAI API 端点 |
#### 配置示例
```
# 基本 OpenAI 设置
OPEN_AI_KEY=your_openai_api_key
OPEN_AI_SERVER_URL=https://api.openai.com/v1
# 配合代理使用以增强安全性
OPEN_AI_KEY=your_openai_api_key
PROXY_URL=http://your-proxy:8080
```
#### 支持的模型
penNULL 支持 31 个具有工具调用、流式传输、推理模式和提示缓存的 OpenAI 模型。标有 `*` 的模型在默认配置中使用。
**GPT-5.2 系列 - 最新旗舰代理模型（2025 年 12 月）**
| 模型 ID | 思考 | 价格 (输入/输出/缓存) | 用例 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-5.2`* | ✅ | $1.75/$14.00/$0.18 | 具有增强推理和工具集成的最新旗舰模型，自主安全研究 |
| `gpt-5.2-pro` | ✅ | $21.00/$168.00/$0.00 | 具有卓越代理编码的高级版本，关键任务安全研究，零日漏洞发现 |
| `gpt-5.2-codex` | ✅ | $1.75/$14.00/$0.18 | 最先进的代码专用模型，上下文压缩，强大的网络安全能力 |
**GPT-5/5.1 系列 - 高级代理模型**
| 模型 ID | 思考 | 价格 (输入/输出/缓存) | 用例 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-5` | ✅ | $1.25/$10.00/$0.13 | 具有高级推理的高级代理模型，自主安全研究，漏洞利用链开发 |
| `gpt-5.1` | ✅ | $1.25/$10.00/$0.13 | 具有自适应推理的增强代理模型，平衡的渗透测试与强大的工具协调 |
| `gpt-5-pro` | ✅ | $15.00/$120.00/$0.00 | 具有重大推理改进的高级版本，减少幻觉，关键安全操作 |
| `gpt-5-mini` | ✅ | $0.25/$2.00/$0.03 | 平衡速度与智能的高效模型，自动化漏洞分析，漏洞利用生成 |
| `gpt-5-nano` | ✅ | $0.05/$0.40/$0.01 | 适用于高吞吐量扫描的最快模型，侦察，批量漏洞检测 |
**GPT-5/5.1 Codex 系列 - 代码专用**
| 模型 ID | 思考 | 价格 (输入/输出/缓存) | 用例 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-5.1-codex-max` | ✅ | $1.25/$10.00/$0.13 | 用于复杂编码的增强推理，已证实的 CVE 发现，系统化的漏洞利用开发 |
| `gpt-5.1-codex` | ✅ | $1.25/$10.00/$0.13 | 具有强推理的标准代码优化模型，漏洞利用生成，漏洞分析 |
| `gpt-5-codex` | ✅ | $1.25/$10.00/$0.13 | 基础代码专用模型，漏洞扫描，基本漏洞利用生成 |
| `gpt-5.1-codex-mini` | ✅ | $0.25/$2.00/$0.03 | 紧凑型高性能模型，容量提高 4 倍，快速漏洞检测 |
| `codex-mini-latest` | ✅ | $1.50/$6.00/$0.38 | 最新的紧凑型代码模型，自动化代码审查，基本漏洞分析 |
**GPT-4.1 系列 - 增强智能**
| 模型 ID | 思考 | 价格 (输入/输出/缓存) | 用例 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-4.1` | ❌ | $2.00/$8.00/$0.50 | 具有卓越函数调用的增强旗舰模型，复杂威胁分析，复杂的漏洞利用开发 |
| `gpt-4.1-mini`* | ❌ | $0.40/$1.60/$0.10 | 具有更高效率的平衡性能，常规安全评估，自动化代码分析 |
| `gpt-4.1-nano` | ❌ | $0.10/$0.40/$0.03 | 超快轻量级模型，批量安全扫描，快速侦察，持续监控 |
**GPT-4o 系列 - 多模态旗舰**
| 模型 ID | 思考 | 价格 (输入/输出/缓存) | 用例 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `gpt-4o` | ❌ | $2.50/$10.00/$1.25 | 具有视觉的多模态旗舰模型，图像分析，Web UI 评估，多工具编排 |
| `gpt-4o-mini` | ❌ | $0.15/$0.60/$0.08 | 具有强大函数调用的紧凑型多模态模型，高频扫描，经济高效的批量操作 |
**o 系列 - 高级推理模型**
| 模型 ID | 思考 | 价格 (输入/输出/缓存) | 用例 |
| --------------------- | -------- | -------------------------- | ----------------------------------------------- |
| `o4-mini`* | ✅ | $1.10/$4.40/$0.28 | 具有增强速度的下一代推理模型，有条理的安全评估，系统化的漏洞利用开发 |
| `o3`* | ✅ | $2.00/$8.00/$0.50 | 高级推理引擎，多阶段攻击链，深度漏洞分析 |
| `o3-mini` | ✅ | $1.10/$4.40/$0.55 | 具有扩展思考的紧凑型推理模型，循序渐进的攻击规划，逻辑漏洞链 |
| `o1` | ✅ | $15.00/$60.00/$7.50 | 具有最大深度的首要推理模型高级渗透测试，新颖的漏洞利用研究 |
| `o3-pro` | ✅ | $20.00/$80.00/$0.00 | 最先进的推理，比 o1-pro 便宜 80%，零日研究，关键安全调查 |
| `o1-pro` | ✅ | $150.00/$600.00/$0.00 | 上一代高级推理模型，详尽的安全分析，关键任务挑战 |
**价格**：每 1M Token。推理模型在输出定价中包含思考 Token。
**推理工作量级别**：
- **高**：最大推理深度（精炼器 - 具有高工作量的 o3）
- **中**：平衡推理（primary_agent, assistant, reflector - 具有中等工作量的 o4-mini/o3）
- **低**：高效的定向推理（coder, installer, pentester - 具有低工作量的 o3/o4-mini；adviser - 具有低工作量的 gpt-5.2）
**主要特性**：
- **扩展推理**：带有思维链的 o 系列模型，用于复杂的安全分析
- **代理智能**：具有增强工具集成和自主能力的 GPT-5/5.1/5.2 系列
- **提示缓存**：在重复上下文上降低成本（占输入价格的 10-50%）
- **代码专业化**：专门的 Codex 模型，用于漏洞发现和漏洞利用开发
- **多模态支持**：用于基于视觉的安全评估的 GPT-4o 系列
- **工具调用**：所有模型都具有强大的函数调用功能，用于渗透测试工具编排
- **流式传输**：用于交互式工作流的实时响应流
- **经过验证的记录**：业界领先的模型，具有 CVE 发现和现实世界安全应用
### Anthropic 提供商配置
penNULL 集成了 Anthropic 的 Claude 模型，具有高级扩展思考能力、卓越的安全机制，以及对复杂安全上下文和提示缓存的复杂理解。
#### 配置变量
| 变量 | 默认值 | 描述 |
| ---------------------- | ------------------------------ | ------------------------------ |
| `ANTHROPIC_API_KEY` | | Anthropic 服务的 API 密钥 |
| `ANTHROPIC_SERVER_URL` | `https://api.anthropic.com/v1` | Anthropic API 端点 |
#### 配置示例
```
# 基本 Anthropic 设置
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1
# 配合代理在安全环境中使用
ANTHROPIC_API_KEY=your_anthropic_api_key
PROXY_URL=http://your-proxy:8080
```
#### 支持的模型
penNULL 支持 10 个具有工具调用、流式传输、扩展思考、自适应思考和提示缓存的 Claude 模型。标有 `*` 的模型在默认配置中使用。
**Claude 4 系列 - 最新模型 (2025-2026)**
| 模型 ID | 思考 | 发布日期 | 价格 (输入/输出/缓存 读/写) | 用例 |
| ------------------------ | -------- | ------------ | ------------------------------ | ----------------------------------------------- |
| `claude-opus-4-6`* | ✅ | 2025 年 5 月 | $5.00/$25.00/$0.50/$6.25 | 用于自主 Agent 和编码的最智能模型。扩展 + 自适应思考，用于复杂的漏洞利用开发，多阶段攻击模拟 |
| `claude-sonnet-4-6`* | ✅ | 2025 年 8 月 | $3.00/$15.00/$0.30/$3.75 | 具有自适应思考的最佳速度/智能平衡。多阶段安全评估，智能漏洞分析，实时威胁追踪 |
| `claude-haiku-4-5`* | ✅ | 2025 年 10 月 | $1.00/$5.00/$0.10/$1.25 | 具有接近前沿智能的最快模型。高频扫描，实时监控，批量自动化测试 |
**传统模型 - 仍受支持**
| 模型 ID | 思考 | 发布日期 | 价格 (输入/输出/缓存 读/写) | 用例 |
| ------------------------ | -------- | ------------ | ------------------------------ | ----------------------------------------------- |
| `claude-sonnet-4-5` | ✅ | 2025 年 9 月 | $3.00/$15.00/$0.30/$3.75 | 最先进的推理（已被 4-6 取代）。复杂的渗透测试，高级威胁分析 |
| `claude-opus-4-5` | ✅ | 2025 年 11 月 | $5.00/$25.00/$0.50/$6.25 | 终极推理（已被 opus-4-6 取代）。关键安全研究，零日发现，红队行动 |
| `claude-opus-4-1` | ✅ | 2025 年 8 月 | $15.00/$75.00/$1.50/$18.75 | 高级推理（已取代）。复杂的渗透测试，复杂的威胁建模 |
| `claude-sonnet-4-0` | ✅ | 2025 年 5 月 | $3.00/$15.00/$0.30/$3.75 | 高性能推理（已取代）。复杂的威胁建模，多工具协调 |
| `claude-opus-4-0` | ✅ | 2025 年 5 月 | $15.00/$75.00/$1.50/$18.75 | 第一代 Opus（已取代）。多步骤漏洞利用开发，自主渗透测试工作流 |
**已弃用模型 - 请迁移到当前模型**
| 模型 ID | 思考 | 发布日期 | 价格 (输入/输出/缓存 读/写) | 备注 |
| ---------------------------- | -------- | ------------ | ------------------------------ | -------------------------------------------- |
| `claude-3-haiku-20240307` | ❌ | 2024 年 3 月 | $0.25/$1.25/$0.03/$0.30 | 将于 2026 年 4 月 19 日停用。请迁移到 claude-haiku-4-5 |
**价格**：每 1M Token。缓存定价包括读取和写入成本。
**扩展思考配置**：
- **最大 Token 4096**：生成器 (claude-opus-4-6) 用于在复杂的漏洞利用开发上进行最大推理深度
- **最大 Token 2048**：编码器 (claude-sonnet-4-6) 用于平衡的代码分析和漏洞研究
- **最大 Token 1024**：主要 Agent、助手、精炼器、顾问、反射器、搜索器、安装器、渗透测试员，用于特定任务的集中推理
- **扩展思考**：所有 Claude 4.5+ 和 4.6 模型都支持可配置的扩展思考，用于深度推理任务
**主要特性**：
- **扩展思考**：所有 Claude 4.5+ 和 4.6 模型都具有可配置的思维链推理深度，用于复杂的安全分析
- **自适应思考**：Claude 4.6 系列（Opus/Sonnet）根据任务复杂度动态调整推理深度以获得最佳性能
- **提示缓存**：具有单独读/写定价的显著成本降低（读取为 10%，写入为输入的 125%）
- **扩展上下文窗口**：标准 200K Token，Claude Opus/Sonnet 4.6 最多可达 1M Token（Beta），用于全面的代码库分析
- **工具调用**：具有卓越准确性的强大函数调用，用于安全工具编排
- **流式传输**：用于交互式渗透测试工作流的实时响应流
- **安全第一设计**：内置安全机制，确保负责任的安全测试实践
- **多模态支持**：最新模型中的视觉功能，用于屏幕截图分析和 UI 安全评估
- **宪法 AI**：高级安全培训，提供可靠和符合道德的安全指导
### Google AI (Gemini) 提供商配置
penNULL 通过 Google AI API 集成了 Google 的 Gemini 模型，提供具有扩展思考和上下文缓存的最新多模态推理能力。
#### 配置变量
| 变量 | 默认值 | 描述 |
| ------------------- | ------------------------------------------- | ------------------------------ |
| `GEMINI_API_KEY` | | Google AI 服务的 API 密钥 |
| `GEMINI_SERVER_URL` | `https://generativelanguage.googleapis.com` | Google AI API 端点 |
#### 配置示例
```
# 基本 Gemini 设置
GEMINI_API_KEY=your_gemini_api_key
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com
# 配合代理使用
GEMINI_API_KEY=your_gemini_api_key
PROXY_URL=http://your-proxy:8080
```
#### 支持的模型
penNULL 支持 13 个具有工具调用、流式传输、思考模式和上下文缓存的 Gemini 模型。标有 `*` 的模型在默认配置中使用。
**Gemini 3.1 系列 - 最新旗舰（2026 年 2 月）**
| 模型 ID | 思考 | 上下文 | 价格 (输入/输出/缓存) | 用例 |
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemini-3.1-pro-preview`* | ✅ | 1M | $2.00/$12.00/$0.20 | 具有优化思考、改进 token 效率的最新旗舰模型，为软件工程和代理工作流进行了优化 |
| `gemini-3.1-pro-preview-customtools` | ✅ | 1M | $2.00/$12.00/$0.20 | 为 bash 和自定义工具（view_file, search_code）优先级优化的自定义工具端点 |
| `gemini-3.1-flash-lite-preview`* | ✅ | 1M | $0.25/$1.50/$0.03 | 对于大批量代理任务和低延迟应用，具有最快性能的最具成本效益的模型 |
**Gemini 3 系列 (⚠️ gemini-3-pro-preview 已弃用 - 将于 2026 年 3 月 9 日关闭)**
| 模型 ID | 思考 | 上下文 | 价格 (输入/输出/缓存) | 用例 |
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemini-3-pro-preview` | ✅ | 1M | $2.00/$12.00/$0.20 | ⚠️ 已弃用 - 请在 2026 年 3 月 9 日之前迁移到 gemini-3.1-pro-preview |
| `gemini-3-flash-preview`* | ✅ | 1M | $0.50/$3.00/$0.05 | 具有卓越搜索聚合的前沿智能，高吞吐量安全扫描 |
**Gemini 2.5 系列 - 高级思考模型**
| 模型 ID | 思考 | 上下文 | 价格 (输入/输出/缓存) | 用例 |
| ---------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemini-2.5-pro` | ✅ | 1M | $1.25/$10.00/$0.13 | 用于复杂编码和推理的最先进技术，复杂的威胁建模 |
| `gemini-2.5-flash` | ✅ | 1M | $0.30/$2.50/$0.03 | 具有思考预算的首个混合推理模型，对于大规模评估具有最佳性价比 |
| `gemini-2.5-flash-lite` | ✅ | 1M | $0.10/$0.40/$0.01 | 适用于规模化使用的最小且最具成本效益的模型，高吞吐量扫描 |
| `gemini-2.5-flash-lite-preview-09-2025` | ✅ | 1M | $0.10/$0.40/$0.01 | 针对成本效益、高吞吐量和质量进行了优化的最新预览版 |
**Gemini 2.0 系列 - 面向 Agent 的平衡多模态**
| 模型 ID | 思考 | 上下文 | 价格 (输入/输出/缓存) | 用例 |
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemini-2.0-flash` | ❌ | 1M | $0.10/$0.40/$0.03 | 为 Agent 时代构建的平衡多模态模型，多样化的安全任务和实时监控 |
| `gemini-2.0-flash-lite` | ❌ | 1M | $0.08/$0.30/$0.00 | 用于持续监控、基本扫描、自动化警报处理的轻量级模型 |
**专门的开源模型（免费）**
| 模型 ID | 思考 | 上下文 | 价格 (输入/输出/缓存) | 用例 |
| ------------------------------------- | -------- | ------- | -------------------------- | ----------------------------------------------- |
| `gemma-3-27b-it` | ❌ | 128K | 免费/免费/免费 | 源自 Gemini 技术的开源，本地安全操作，隐私敏感测试 |
| `gemma-3n-4b-it` | ❌ | 128K | 免费/免费/免费 | 适用于边缘设备（手机/笔记本电脑/平板电脑），离线漏洞扫描 |
**价格**：每 1M Token（标准付费层级）。上下文窗口为输入 Token 限制。
**主要特性**：
- **扩展思考**：用于复杂安全分析的逐步推理（所有 Gemini 3.x 和 2.5 系列）
- **上下文缓存**：在重复上下文上显著降低成本（占输入价格的 10-90%）
- **超长上下文**：1M Token，用于全面的代码库分析和文档审查
- **多模态支持**：文本、图像、视频、音频和 PDF 处理，用于全面的评估
- **工具调用**：通过函数调用无缝集成 20 多种渗透测试工具
- **流式传输**：用于交互式安全工作流的实时响应流
- **代码执行**：内置代码执行，用于攻击性工具测试和漏洞利用验证
- **搜索聚合**：集成 Google 搜索，用于威胁情报和 CVE 研究
- **文件搜索**：文档检索和 RAG 功能，用于基于知识的评估
- **批量 API**：对于非实时批处理可降低 50% 的成本
**推理工作量级别**：
- **高**：用于复杂多步分析的最大思考深度（生成器）
- **中**：用于常规代理任务的平衡推理（primary_agent, assistant, refiner, adviser）
- **低**：用于集中任务的高效思考（coder, installer, pentester）
### AWS Bedrock 提供商配置
penNULL 集成了 Amazon Bedrock，提供对来自领先 AI 公司（包括 Anthropic、Amazon、Cohere、DeepSeek、OpenAI、Qwen、Mistral 和 Moonshot）的 20 多个基础模型的访问。
#### 配置变量
| 变量 | 默认值 | 描述 |
| --------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `BEDROCK_REGION` | `us-east-1` | Bedrock 服务的 AWS 区域 |
| `BEDROCK_DEFAULT_AUTH` | `false` | 使用 AWS SDK 默认凭证链（环境、EC2 角色、~/.aws/credentials） - 最高优先级 |
| `BEDROCK_BEARER_TOKEN` | | Bearer Token 认证 - 优先于静态凭证 |
| `BEDROCK_ACCESS_KEY_ID` | | 用于静态凭证的 AWS 访问密钥 ID |
| `BEDROCK_SECRET_ACCESS_KEY` | | 用于静态凭证的 AWS 秘密访问密钥 |
| `BEDROCK_SESSION_TOKEN` | | 用于临时凭证的 AWS 会话 Token（可选，与静态凭证一起使用） |
| `BEDROCK_SERVER_URL` | | 自定义 Bedrock 端点（VPC 端点，本地测试） |
**认证优先级**：`BEDROCK_DEFAULT_AUTH` → `BEDROCK_BEARER_TOKEN` → `BEDROCK_ACCESS_KEY_ID`+`BEDROCK_SECRET_ACCESS_KEY`
#### 配置示例
```
# 推荐：默认 AWS SDK 身份验证（EC2/ECS/Lambda 角色）
BEDROCK_REGION=us-east-1
BEDROCK_DEFAULT_AUTH=true
# Bearer token 身份验证（AWS STS，自定义认证）
BEDROCK_REGION=us-east-1
BEDROCK_BEARER_TOKEN=your_bearer_token
# 静态凭证（开发，测试）
BEDROCK_REGION=us-east-1
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
# 配合代理和自定义 endpoint
BEDROCK_REGION=us-east-1
BEDROCK_DEFAULT_AUTH=true
BEDROCK_SERVER_URL=https://bedrock-runtime.us-east-1.vpce-xxx.amazonaws.com
PROXY_URL=http://your-proxy:8080
```
#### 支持的模型
penNULL 支持 21 个具有工具调用、流式传输和多模态功能的 AWS Bedrock 模型。标有 `*` 的模型在默认配置中使用。
| 模型 ID | 提供商 | 思考 | 多模态 | 价格 (输入/输出) | 用例 |
| ------------------------------------------------ | --------------- | -------- | ---------- | -------------------- | --------------------------------------- |
| `us.amazon.nova-2-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.33/$2.75 | 自适应推理，高效思考 |
| `us.amazon.nova-premier-v1:0` | Amazon Nova | ❌ | ✅ | $2.50/$12.50 | 复杂推理，高级分析 |
| `us.amazon.nova-pro-v1:0` | Amazon Nova | ❌ | ✅ | $0.80/$3.20 | 准确性、速度、成本的平衡 |
| `us.amazon.nova-lite-v1:0` | Amazon Nova | ❌ | ✅ | $0.06/$0.24 | 快速处理，大批量操作 |
| `us.amazon.nova-micro-v1:0` | Amazon Nova | ❌ | ❌ | $0.035/$0.14 | 超低延迟，实时监控 |
| `us.anthropic.claude-opus-4-6-v1`* | Anthropic | ✅ | ✅ | $5.00/$25.00 | 世界级编码，企业级 Agent |
| `us.anthropic.claude-sonnet-4-6` | Anthropic | ✅ | ✅ | $3.00/$15.00 | 前沿智能，企业规模 |
| `us.anthropic.claude-opus-4-5-20251101-v1:0` | Anthropic | ✅ | ✅ | $5.00/$25.00 | 多日软件开发 |
| `us.anthropic.claude-haiku-4-5-20251001-v1:0`* | Anthropic | ✅ | ✅ | $1.00/$5.00 | 接近前沿的性能，高速度 |
| `us.anthropic.claude-sonnet-4-5-20250929-v1:0`* | Anthropic | ✅ | ✅ | $3.00/$15.00 | 真实世界 Agent，卓越的编码能力 |
| `us.anthropic.claude-sonnet-4-20250514-v1:0` | Anthropic | ✅ | ✅ | $3.00/$15.00 | 平衡的性能，生产就绪 |
| `us.anthropic.claude-3-5-haiku-20241022-v1:0` | Anthropic | ❌ | ❌ | $0.80/$4.00 | 最快的模型，高性价比扫描 |
| `cohere.command-r-plus-v1:0` | Cohere | ❌ | ❌ | $3.00/$15.00 | 大规模操作，卓越的 RAG |
| `deepseek.v3.2` | DeepSeek | ❌ | ❌ | $0.58/$1.68 | 长上下文推理，高效率 |
| `openai.gpt-oss-120b-1:0`* | OpenAI (OSS) | ✅ | ❌ | $0.15/$0.60 | 强推理，科学分析 |
| `openai.gpt-oss-20b-1:0` | OpenAI (OSS) | ✅ | ❌ | $0.07/$0.30 | 高效编码，软件开发 |
| `qwen.qwen3-next-80b-a3b` | Qwen | ❌ | ❌ | $0.15/$1.20 | 超长上下文，旗舰级推理 |
| `qwen.qwen3-32b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | 均衡推理，研究用例 |
| `qwen.qwen3-coder-30b-a3b-v1:0` | Qwen | ❌ | ❌ | $0.15/$0.60 | Vibe 编程，自然语言优先 |
| `qwen.qwen3-coder-next` | Qwen | ❌ | ❌ | $0.45/$1.80 | 工具调用，针对函数调用优化 |
| `mistral.mistral-large-3-675b-instruct` | Mistral | ❌ | ✅ | $4.00/$12.00 | 高级多模态，长上下文 |
| `moonshotai.kimi-k2.5` | Moonshot | ❌ | ✅ | $0.60/$3.00 | 集视觉、语言、代码于一体的模型 |
**价格**：按每 1M token 计费。支持思考/推理的模型在推理阶段会产生额外的计算成本。
#### 已测试但兼容的模型
部分 AWS Bedrock 模型已经过测试，但由于技术限制**不支持**：
| 模型系列 | 不兼容原因 |
| ------------------------- | ----------------------------------------------------------------------------------------- |
| **GLM (Z.AI)** | 工具调用格式与 Converse API 不兼容（期望字符串而非 JSON） |
| **AI21 Jamba** | 严格的速率限制（1-2 请求/分钟）导致无法进行可靠测试和生产使用 |
| **Meta Llama 3.3/3.1** | 工具调用结果处理不稳定，在多轮工作流中会导致意外故障 |
| **Mistral Magistral** | 模型不支持工具调用 |
| **Moonshot K2-Thinking** | 使用工具调用时流式传输行为不稳定，在生产环境中不可靠 |
| **Qwen3-VL** | 使用工具调用时流式传输不稳定，多模态+工具组合间歇性失败 |
**核心功能**：
- **自动提示缓存**：在重复上下文中可降低 40-70% 的成本（Claude 4.x 模型）
- **扩展思考**：针对复杂安全分析的逐步推理（Claude, DeepSeek R1, OpenAI GPT）
- **多模态分析**：处理屏幕截图、图表、视频以进行全面测试（Nova, Claude, Mistral, Kimi）
- **工具调用**：通过函数调用无缝集成 20 多种渗透测试工具
- **流式传输**：实时响应流，用于交互式安全评估工作流
### DeepSeek 提供商配置
penNULL 集成了 DeepSeek，可访问具有强大推理、编码能力和上下文缓存的高级 AI 模型，且价格具有竞争力。
#### 配置变量
| 变量 | 默认值 | 描述 |
| --------------------- | -------------------------- | --------------------------------------------------- |
| `DEEPSEEK_API_KEY` | | 用于身份验证的 DeepSeek API 密钥 |
| `DEEPSEEK_SERVER_URL` | `https://api.deepseek.com` | DeepSeek API 端点 URL |
| `DEEPSEEK_PROVIDER` | | 用于 LiteLLM 集成的提供商前缀（可选） |
#### 配置示例
```
# 直接 API 使用
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com
# 配合 LiteLLM 代理使用
DEEPSEEK_API_KEY=your_litellm_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek # Adds prefix to model names (deepseek/deepseek-chat) for LiteLLM
```
#### 支持的模型
penNULL 支持 2 个具备工具调用、流式传输、思考模式和上下文缓存功能的 DeepSeek-V3.2 模型。这两个模型均在默认配置中使用。
| 模型 ID | 思考 | 上下文 | 最大输出 | 价格 (输入/输出/缓存) | 用例 |
| --------------------- | -------- | ------- | ---------- | -------------------------- | ----------------------------------------------- |
| `deepseek-chat`* | ❌ | 128K | 8K | $0.28/$0.42/$0.03 | 通用对话，代码生成，工具调用 |
| `deepseek-reasoner`* | ✅ | 128K | 64K | $0.28/$0.42/$0.03 | 高级推理，复杂逻辑，安全分析 |
**价格**：按每 1M token 计费。缓存价格适用于提示缓存（输入成本的 10%）。支持思考的模型包含强化学习思维链推理。
**核心功能**：
- **自动提示缓存**：在重复上下文中可降低 40-60% 的成本（输入价格的 10%）
- **扩展思考**：用于复杂安全分析的强化学习 CoT (deepseek-reasoner)
- **强大的编码能力**：针对代码生成和漏洞利用开发进行了优化
- **工具调用**：通过函数调用无缝集成 20 多种渗透测试工具
- **流式传输**：用于交互式工作流的实时响应流
- **多语言**：强大的中英文支持
- **附加功能**：JSON 输出、聊天前缀补全、FIM (Fill-in-the-Middle) 补全
**LiteLLM 集成**：将 `DEEPSEEK_PROVIDER` 设置为 `deepseek`，以便在使用带有 LiteLLM 代理的默认 penNULL 配置时启用模型名称前缀。直接使用 API 时请留空。
### GLM 提供商配置
penNULL 集成了由智谱 AI (Z.AI) 开发的 GLM，提供了基于 MoE 架构的高级语言模型，具备强大的推理和代理能力，由清华大学开发。
#### 配置变量
| 变量 | 默认值 | 描述 |
| ----------------- | ------------------------------- | ---------------------------------------------------------- |
| `GLM_API_KEY` | | 用于身份验证的 GLM API 密钥 |
| `GLM_SERVER_URL` | `https://api.z.ai/api/paas/v4` | GLM API 端点 URL（国际版） |
| `GLM_PROVIDER` | | 用于 LiteLLM 集成的提供商前缀（可选） |
#### 配置示例
```
# 直接 API 使用（国际 endpoint）
GLM_API_KEY=your_glm_api_key
GLM_SERVER_URL=https://api.z.ai/api/paas/v4
# 替代 endpoints
GLM_SERVER_URL=https://open.bigmodel.cn/api/paas/v4 # China
GLM_SERVER_URL=https://api.z.ai/api/coding/paas/v4 # Coding-specific
# 配合 LiteLLM 代理使用
GLM_API_KEY=your_litellm_key
GLM_SERVER_URL=http://litellm-proxy:4000
GLM_PROVIDER=zai # Adds prefix to model names (zai/glm-4) for LiteLLM
```
#### 支持的模型
penNULL 支持 12 个具备工具调用、流式传输、思考模式和提示缓存功能的 GLM 模型。标有 `*` 的模型在默认配置中使用。
**GLM-5 系列 - 旗舰级 MoE (744B/40B 激活)**
| 模型 ID | 思考 | 上下文 | 最大输出 | 价格 (输入/输出/缓存) | 用例 |
| ----------------------- | ------------- | ------- | ---------- | -------------------------- | ----------------------------------------------- |
| `glm-5`* | ✅ 强制 | 200K | 128K | $1.00/$3.20/$0.20 | 旗舰级代理工程，复杂的多阶段任务 |
| `glm-5-code`† | ✅ 强制 | 200K | 128K | $1.20/$5.00/$0.30 | 代码专用，漏洞利用开发（需要 Coding Plan） |
**GLM-4.7 系列 - 具备交错思考的高级版本**
| 模型 ID | 思考 | 上下文 | 最大输出 | 价格 (输入/输出/缓存) | 用例 |
| ----------------------- | ------------- | ------- | ---------- | -------------------------- | ----------------------------------------------- |
| `glm-4.7`* | ✅ 强制 | 200K | 128K | $0.60/$2.20/$0.11 | 在每次响应/工具调用前进行思考的高级版本 |
| `glm-4.7-flashx`* | ✅ 混合 | 200K | 128K | $0.07/$0.40/$0.01 | 具有优先 GPU 的高速版本，最佳性价比 |
| `glm-4.7-flash` | ✅ 混合 | 200K | 128K | 免费/免费/免费 | 免费的约 30B SOTA 模型，1 个并发请求 |
**GLM-4.6 系列 - 具备自动思考的均衡版本**
| 模型 ID | 思考 | 上下文 | 最大输出 | 价格 (输入/输出/缓存) | 用例 |
| ----------------------- | ------------- | ------- | ---------- | -------------------------- | ----------------------------------------------- |
| `glm-4.6` | ✅ 自动 | 200K | 128K | $0.60/$2.20/$0.11 | 均衡，流式工具调用，token 效率提升 30% |
**GLM-4.5 系列 - 统一的推理/编码/代理**
| 模型 ID | 思考 | 上下文 | 最大输出 | 价格 (输入/输出/缓存) | 用例 |
| ----------------------- | ------------- | ------- | ---------- | -------------------------- | ----------------------------------------------- |
| `glm-4.5` | ✅ 自动 | 128K | 96K | $0.60/$2.20/$0.11 | 统一模型，MoE 355B/32B 激活 |
| `glm-4.5-x` | ✅ 自动 | 128K | 96K | $2.20/$8.90/$0.45 | 超快速高级版，最低延迟 |
| `glm-4.5-air`* | ✅ 自动 | 128K | 96K | $0.20/$1.10/$0.03 | 高性价比，MoE 106B/12B，最佳价格/质量比 |
| `glm-4.5-airx` | ✅ 自动 | 128K | 96K | $1.10/$4.50/$0.22 | 具有优先 GPU 的加速版 Air |
| `glm-4.5-flash` | ✅ 自动 | 128K | 96K | 免费/免费/免费 | 支持推理/编码/代理的免费版本 |
**GLM-4 遗留版本 - 密集架构**
| 模型 ID | 思考 | 上下文 | 最大输出 | 价格 (输入/输出/缓存) | 用例 |
| ----------------------- | ------------- | ------- | ---------- | -------------------------- | ----------------------------------------------- |
| `glm-4-32b-0414-128k` | ❌ | 128K | 16K | $0.10/$0.10/$0.00 | 超低成本密集 32B，大批量解析 |
**价格**：按每 1M token 计费。缓存价格适用于提示缓存。† 模型需要 **Coding Plan 订阅**。
**思考模式**：
- **强制**：模型在响应前总是使用思考模式（GLM-5, GLM-4.7）
- **混合**：模型智能决定何时使用思考（GLM-4.7-FlashX, GLM-4.7-Flash）
- **自动**：模型自动确定何时需要推理（GLM-4.6, GLM-4.5 系列）
**核心功能**：
- **提示缓存**：在重复上下文中显著降低成本（显示了缓存的输入定价）
- **交错思考**：GLM-4.7 在每次响应和工具调用前进行思考，并在多轮对话中保留推理过程
- **超长上下文**：GLM-5 和 GLM-4.7/4.6 系列支持 200K token，用于海量代码库分析
- **MoE 架构**：拥有 744B 参数、40B 激活的高效模型 (GLM-5)，355B/32B (GLM-4.5)，106B/12B (GLM-4.5-Air)
- **工具调用**：通过函数调用无缝集成 20 多种渗透测试工具
- **流式传输**：支持流式工具调用的实时响应流（GLM-4.6+）
- **多语言**：卓越的中英文 NLP 能力
- **免费选项**：GLM-4.7-Flash 和 GLM-4.5-Flash 适用于原型设计和实验
**LiteLLM 集成**：将 `GLM_PROVIDER` 设置为 `zai`，以便在使用带有 LiteLLM 代理的默认 penNULL 配置时启用模型名称前缀。直接使用 API 时请留空。
### Kimi 提供商配置
penNULL 集成了来自 Moonshot AI 的 Kim，提供具有多模态能力的超长上下文模型，非常适合分析庞大的代码库和文档。
#### 配置变量
| 变量 | 默认值 | 描述 |
| ------------------ | -----------------------------| --------------------------------------------------- |
| `KIMI_API_KEY` | | 用于身份验证的 Kimi API 密钥 |
| `KIMI_SERVER_URL` | `https://api.moonshot.ai/v1` | Kimi API 端点 URL（国际版） |
| `KIMI_PROVIDER` | | 用于 LiteLLM 集成的提供商前缀（可选） |
#### 配置示例
```
# 直接 API 使用（国际 endpoint）
KIMI_API_KEY=your_kimi_api_key
KIMI_SERVER_URL=https://api.moonshot.ai/v1
# 替代 endpoint
KIMI_SERVER_URL=https://api.moonshot.cn/v1 # China
# 配合 LiteLLM 代理使用
KIMI_API_KEY=your_litellm_key
KIMI_SERVER_URL=http://litellm-proxy:4000
KIMI_PROVIDER=moonshot # Adds prefix to model names (moonshot/kimi-k2.5) for LiteLLM
```
#### 支持的模型
penNULL 支持 11 个具备工具调用、流式传输、思考模式和多模态能力的 Kimi/Moonshot 模型。标有 `*` 的模型在默认配置中使用。
**Kimi K2.5 系列 - 高级多模态**
| 模型 ID | 思考 | 多模态 | 上下文 | 速度 | 价格 (输入/输出) | 用例 |
| -------------------------- | -------- | ---------- | ------- | ---------- | -------------------- | ----------------------------------------------- |
| `kimi-k2.5`* | ✅ | ✅ | 256K | 标准 | $0.60/$3.00 | 最智能、最全能，视觉+文本+代码 |
**Kimi K2 系列 - MoE 基础版 (1T 参数，32B 激活)**
| 模型 ID | 思考 | 多模态 | 上下文 | 速度 | 价格 (输入/输出) | 用例 |
| -------------------------- | -------- | ---------- | ------- | ---------- | -------------------- | ----------------------------------------------- |
| `kimi-k2-0905-preview`* | ❌ | ❌ | 256K | 标准 | $0.60/$2.50 | 增强的代理编码，改进的前端 |
| `kimi-k2-0711-preview` | ❌ | ❌ | 128K | 标准 | $0.60/$2.50 | 强大的代码和代理能力 |
| `kimi-k2-turbo-preview`* | ❌ | ❌ | 256K | Turbo | $1.15/$8.00 | 高速版本，60-100 token/秒 |
| `kimi-k2-thinking` | ✅ | ❌ | 256K | 标准 | $0.60/$2.50 | 长期思考，多步骤工具使用 |
| `kimi-k2-thinking-turbo` | ✅ | ❌ | 256K | Turbo | $1.15/$8.00 | 高速思考，深度推理 |
**Moonshot V1 系列 - 通用文本生成**
| 模型 ID | 思考 | 多模态 | 上下文 | 速度 | 价格 (输入/输出) | 用例 |
| -------------------------- | -------- | ---------- | ------- | ---------- | -------------------- | ----------------------------------------------- |
| `moonshot-v1-8k` | ❌ | ❌ | 8K | 标准 | $0.20/$2.00 | 短文本生成，高性价比 |
| `moonshot-v1-32k` | ❌ | ❌ | 32K | 标准 | $1.00/$3.00 | 长文本生成，均衡 |
| `moonshot-v1-128k` | ❌ | ❌ | 128K | 标准 | $2.00/$5.00 | 超长文本生成，广泛的上下文 |
**Moonshot V1 视觉系列 - 多模态**
| 模型 ID | 思考 | 多模态 | 上下文 | 速度 | 价格 (输入/输出) | 用例 |
| ----------------------------- | -------- | ---------- | ------- | ---------- | -------------------- | ----------------------------------------------- |
| `moonshot-v1-8k-vision-preview` | ❌ | ✅ | 8K | 标准 | $0.20/$2.00 | 视觉理解，短上下文 |
| `moonshot-v1-32k-vision-preview` | ❌ | ✅ | 32K | 标准 | $1.00/$3.00 | 视觉理解，中等上下文 |
| `moonshot-v1-128k-vision-preview` | ❌ | ✅ | 128K | 标准 | $2.00/$5.00 | 视觉理解，长上下文 |
**价格**：按每 1M token 计费。Turbo 模型提供 60-100 token/秒的输出速度，价格更高。
**核心功能**：
- **超长上下文**：高达 256K token，用于全面的代码库分析
- **多模态能力**：视觉模型支持用于屏幕截图分析的图像理解（Kimi K2.5, V1 视觉系列）
- **扩展思考**：通过多步骤工具使用进行深度推理（kimi-k2.5, kimi-k2-thinking 模型）
- **高速 Turbo**：60-100 token/秒输出，用于实时工作流（Turbo 变体）
- **工具调用**：通过函数调用无缝集成 20 多种渗透测试工具
- **流式传输**：用于交互式安全评估的实时响应流
- **多语言**：强大的中英文语言支持
- **MoE 架构**：K2 系列拥有 1T 总参数，32B 激活的高效模型
**LiteLLM 集成**：将 `KIMI_PROVIDER` 设置为 `moonshot`，以便在使用带有 LiteLLM 代理的默认 penNULL 配置时启用模型名称前缀。直接使用 API 时请留空。
### Qwen 提供商配置
penNULL 集成了来自阿里云模型工作室 (DashScope) 的 Qwen，提供强大的多语言模型，具备推理能力和上下文缓存支持。
#### 配置变量
| 变量 | 默认值 | 描述 |
| ------------------ | ------------------------------------------------------ | --------------------------------------------------- |
| `QWEN_API_KEY` | | 用于身份验证的 Qwen API 密钥 |
| `QWEN_SERVER_URL` | `https://dashscope-us.aliyuncs.com/compatible-mode/v1` | Qwen API 端点 URL（国际版） |
| `QWEN_PROVIDER` | | 用于 LiteLLM 集成的提供商前缀（可选） |
#### 配置示例
```
# 直接 API 使用（全球/美国 endpoint）
QWEN_API_KEY=your_qwen_api_key
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1
# 替代 endpoints
QWEN_SERVER_URL=https://dashscope-intl.aliyuncs.com/compatible-mode/v1 # International (Singapore)
QWEN_SERVER_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 # Chinese Mainland (Beijing)
# 配合 LiteLLM 代理使用
QWEN_API_KEY=your_litellm_key
QWEN_SERVER_URL=http://litellm-proxy:4000
QWEN_PROVIDER=dashscope # Adds prefix to model names (dashscope/qwen-plus) for LiteLLM
```
#### 支持的模型
penNULL 支持 32 个具备工具调用、流式传输、思考模式和上下文缓存功能的 Qwen 模型。标有 `*` 的模型在默认配置中使用。
**广泛可用模型（所有区域）**
| 模型 ID | 思考 | 国际 | 全球/美国 | 中国 | 价格 (输入/输出/缓存) | 用例 |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ----------------------------------------------- |
| `qwen3-max`* | ✅ | ✅ | ✅ | ✅ | $2.40/$12.00/$0.48 | 旗舰级推理，复杂的安全分析 |
| `qwen3-max-preview` | ✅ | ✅ | ✅ | ✅ | $2.40/$12.00/$0.48 | 具有扩展思考的预览版本 |
| `qwen-max` | ❌ | ✅ | ❌ | ✅ | $1.60/$6.40/$0.32 | 强大的指令遵循，遗留的旗舰模型 |
| `qwen3.5-plus`* | ✅ | ✅ | ✅ | ✅ | $0.40/$2.40/$0.08 | 均衡推理，通用对话，编码 |
| `qwen-plus` | ✅ | ✅ | ✅ | ✅ | $0.40/$4.00/$0.08 | 高性价比的均衡性能 |
| `qwen3.5-flash`* | ✅ | ✅ | ✅ | ✅ | $0.10/$0.40/$0.02 | 超快轻量级，高吞吐量 |
| `qwen-flash` | ❌ | ✅ | ✅ | ✅ | $0.05/$0.40/$0.01 | 具有上下文缓存的快速模型，成本优化 |
| `qwen-turbo` | ✅ | ✅ | ❌ | ✅ | $0.05/$0.50/$0.01 | 已弃用，请改用 qwen-flash |
| `qwq-plus` | ✅ | ✅ | ❌ | ✅ | $0.80/$2.40/$0.16 | 深度推理，思维链分析 |
**特定区域模型**
| 模型 ID | 思考 | 国际 | 全球/美国 | 中国 | 价格 (输入/输出/缓存) | 用例 |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ----------------------------------------------- |
| `qwen-plus-us` | ✅ | ❌ | ✅ | ❌ | $0.40/$4.00/$0.08 | 针对美国区域优化的均衡模型 |
| `qwen-long-latest` | ❌ | ❌ | ❌ | ✅ | $0.07/$0.29/$0.01 | 超长上下文（10M token） |
**开源 - Qwen3.5 系列**
| 模型 ID | 思考 | 国际 | 全球/美国 | 中国 | 价格 (输入/输出/缓存) | 用例 |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ----------------------------------------------- |
| `qwen3.5-397b-a17b` | ✅ | ✅ | ✅ | ✅ | $0.60/$3.60/$0.12 | 最大的 397B 参数，卓越的推理能力 |
| `qwen3.5-122b-a10b` | ✅ | ✅ | ✅ | ✅ | $0.40/$3.20/$0.08 | 大型 122B 参数，强大的性能 |
| `qwen3.5-27b` | ✅ | ✅ | ✅ | ✅ | $0.30/$2.40/$0.06 | 中等 27B 参数，均衡 |
| `qwen3.5-35b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.25/$2.00/$0.05 | 高效的 35B 参数，3B 激活的 MoE |
**开源 - Qwen3 系列**
| 模型 ID | 思考 | 国际 | 全球/美国 | 中国 | 价格 (输入/输出/缓存) | 用例 |
| ------------------------------ | -------- | ---- | --------- | ----- | -------------------------- | ----------------------------------------------- |
| `qwen3-next-80b-a3b-thinking` | ✅ | ✅ | ✅ | ✅ | $0.15/$1.43/$0.03 | 下一代 80B 纯思考模式 |
| `qwen3-next-80b-a3b-instruct` | ❌ | ✅ | ✅ | ✅ | $0.15/$1.20/$0.03 | 下一代 80B 指令遵循 |
| `qwen3-235b-a22b` | ✅ | ✅ | ✅ | ✅ | $0.70/$8.40/$0.14 | 双模式 235B，22B 激活 |
| `qwen3-32b` | ✅ | ✅ | ✅ | ✅ | $0.29/$2.87/$0.06 | 多功能 32B 双模式 |
| `qwen3-30b-a3b` | ✅ | ✅ | ✅ | ✅ | $0.20/$2.40/$0.04 | 高效的 30B MoE 架构 |
| `qwen3-14b` | ✅ | ✅ | ✅ | ✅ | $0.35/$4.200.07 | 中等 14B 性能与成本平衡 |
| `qwen3-8b` | ✅ | ✅ | ✅ | ✅ | $0.18/$2.10/$0.04 | 紧凑的 8B 效率优化 |
| `qwen3-4b` | ✅ | ✅ | ❌ | ✅ | $0.11/$1.26/$0.02 | 适用于简单任务的轻量级 4B |
| `qwen3-1.7b` | ✅ | ✅ | ❌ | ✅ | $0.11/$1.26/$0.02 | 超紧凑的 1.7B 基础任务 |
| `qwen3-0.6b` | ✅ | ✅ | ❌ | ✅ | $0.11/$1.26/$0.02 | 最小的 0.6B 最小资源消耗 |
**开源 - QwQ 和 Qwen2.5 系列**
| 模型 ID | 思考 | 国际 | 全球/美国 | 中国 | 价格 (输入/输出/缓存) | 用例 |
| ---------------------------- | -------- | ---- | --------- | ----- | -------------------------- | ----------------------------------------------- |
| `qwq-32b` | ✅ | ✅ | ✅ | ✅ | $0.29/$0.86/$0.06 | 开源 32B 推理，深度研究 |
| `qwen2.5-14b-instruct-1m` | ❌ | ✅ | ❌ | ✅ | $0.81/$3.22/$0.16 | 扩展的 1M 上下文，14B 参数 |
| `qwen2.5-7b-instruct-1m` | ❌ | ✅ | ❌ | ✅ | $0.37/$1.47/$0.07 | 扩展的 1M 上下文，7B 参数 |
| `qwen2.5-72b-instruct` | ❌ | ✅ | ❌ | ✅ | $1.40/$5.60/$0.28 | 大型 72B 指令遵循 |
| `qwen2.5-32b-instruct` | ❌ | ✅ | ❌ | ✅ | $0.70/$2.80/$0.14 | 中等 32B 指令遵循 |
| `qwen2.5-14b-instruct` | ❌ | ✅ | ❌ | ✅ | $0.35/$1.40/$0.07 | 紧凑的 14B 指令遵循 |
| `qwen2.5-7b-instruct` | ❌ | ✅ | ❌ | ✅ | $0.18/$0.70/$0.04 | 小型 7B 指令遵循 |
| `qwen2.5-3b-instruct` | ❌ | ❌ | ❌ | ✅ | $0.04/$0.13/$0.01 | 仅限中国大陆的轻量级 3B |
**价格**：按每 1M token 计费。缓存价格适用于隐式上下文缓存（输入成本的 20%）。支持思考的模型在 CoT 阶段包含额外的推理计算。
**区域可用性**：
- **国际**：新加坡区域 (`dashscope-intl.aliyuncs.com`)
- **全球/美国**：美国弗吉尼亚区域 (`dashscope-us.aliyuncs.com`)
- **中国**：中国大陆北京区域 (`dashscope.aliyuncs.com`)
**核心功能**：
- **自动上下文缓存**：通过隐式缓存在重复上下文中降低 30-50% 的成本（输入价格的 20%）
- **扩展思考**：用于复杂安全分析的思维链推理（Qwen3-Max, QwQ, Qwen3.5-Plus）
- **工具调用**：通过函数调用无缝集成 20 多种渗透测试工具
- **流式传输**：用于交互式工作流的实时响应流
- **多语言**：强大的中文、英文及多语言支持
- **超长上下文**：qwen-long-latest 支持高达 10M token，用于海量代码库分析
**LiteLLM 集成**：将 `QWEN_PROVIDER` 设置为 `dashscope`，以便在使用带有 LiteLLM 代理的默认 penNULL 配置时启用模型名称前缀。直接使用 API 时请留空。
## 高级设置
### Langfuse 集成
Langfuse 提供了高级功能，用于监控和分析 AI 代理操作。
1. 在现有的 `.env` 文件中配置 Langfuse 环境变量。
2. 在 `.env` 文件中启用 penNULL 服务的 Langfuse 集成。
```
LANGFUSE_BASE_URL=http://langfuse-web:3000
LANGFUSE_PROJECT_ID= # default: value from ${LANGFUSE_INIT_PROJECT_ID}
LANGFUSE_PUBLIC_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_PUBLIC_KEY}
LANGFUSE_SECRET_KEY= # default: value from ${LANGFUSE_INIT_PROJECT_SECRET_KEY}
```
3. 运行 Langfuse 技术栈：
```
curl -O https://raw.githubusercontent.com/nullailab/pennull/master/docker-compose-langfuse.yml
docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d
```
访问 [localhost:4000](http://localhost:4000) 以使用 `.env` 文件中的凭据登录 Langfuse Web UI：
- `LANGFUSE_INIT_USER_EMAIL` - 管理员邮箱
- `LANGFUSE_INIT_USER_PASSWORD` - 管理员密码
### 监控和可观测性
为了进行详细的系统操作跟踪，我们提供了与监控工具的集成。
1. 在 `.env` 文件中启用 penNULL 的 OpenTelemetry 及所有可观测性服务的集成。
```
OTEL_HOST=otelcol:8148
```
2. 运行可观测性技术栈：
```
curl -O https://raw.githubusercontent.com/nullailab/pennull/master/docker-compose-observability.yml
docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d
```
访问 [localhost:3000](http://localhost:3000) 以打开 Grafana Web UI。
### 知识图谱集成
penNULL 集成了 [Graphiti](https://github.com/nullailab/pennull-graphiti)，这是一个基于 Neo4j 的时间知识图谱系统，可为 AI 代理操作提供高级的语义理解和关系跟踪。nullailab 的分叉版本提供了专门用于渗透测试的自定义实体和边缘类型。
#### 什么是 Graphiti？
Graphiti 自动从代理交互中提取并存储结构化知识，构建包含实体、关系和时间上下文的图谱。这可实现：
- **语义记忆**：存储和召回工具、目标、漏洞和技术之间的关系
- **上下文理解**：跟踪不同的渗透测试操作随时间推移的相互关联
- **知识复用**：从过去的渗透测试中学习，并将见解应用于新的评估
- **高级查询**：搜索复杂模式，例如“哪些工具对类似目标有效？”
#### 启用 Graphiti
Graphiti 知识图谱是**可选的**，默认禁用。要启用它：
1. 在 `.env` 文件中配置 Graphiti 环境变量：
```
## Graphiti 知识图谱设置
GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
GRAPHITI_MODEL_NAME=gpt-5-mini
# Neo4j 设置（由 Graphiti 技术栈使用）
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687
# OpenAI API 密钥（Graphiti 进行实体提取时需要）
OPEN_AI_KEY=your_openai_api_key
```
2. 将 Graphiti 技术栈与主要的 penNULL 服务一起运行：
```
# 如果需要，下载 Graphiti compose 文件
curl -O https://raw.githubusercontent.com/nullailab/pennull/master/docker-compose-graphiti.yml
# 启动带有 Graphiti 的 penNULL
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d
```
3. 验证 Graphiti 是否正在运行：
```
# 检查服务健康状况
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml ps graphiti neo4j
# 查看 Graphiti 日志
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml logs -f graphiti
# 访问 Neo4j Browser（可选）
# 访问 http://localhost:7474 并使用 NEO4J_USER/NEO4J_PASSWORD 登录
# 访问 Graphiti API（可选，用于调试）
# 访问 http://localhost:8000/docs 获取 Swagger API 文档
```
#### 存储内容
启用后，penNULL 会自动捕获：
- **代理响应**：所有代理的推理、分析和决策
- **工具执行**：执行的命令、使用的工具及其结果
- **上下文信息**：流、任务和子任务的层次结构
### GitHub 和 Google OAuth 集成
与 GitHub 和 Google 的 OAuth 集成允许用户使用其现有账户在这些平台上进行身份验证。这提供了以下好处：
- 简化的登录过程，无需创建单独的凭据
- 通过受信任的身份提供商增强安全性
- 访问 GitHub/Google 账户中的用户个人资料信息
- 与现有开发工作流的无缝集成
要使用 GitHub OAuth，您需要在 GitHub 账户中创建一个新的 OAuth 应用，并在 `.env` 文件中设置 `OAUTH_GITHUB_CLIENT_ID` 和 `OAUTH_GITHUB_CLIENT_SECRET`。
要使用 Google OAuth，您需要在 Google 账户中创建一个新的 OAuth 应用，并在 `.env` 文件中设置 `OAUTH_GOOGLE_CLIENT_ID` 和 `OAUTH_GOOGLE_CLIENT_SECRET`。
### Docker 镜像配置
penNULL 允许您配置用于执行各种任务的 Docker 镜像选择。系统会根据任务类型自动选择最合适的镜像，但您可以通过指定首选镜像来限制此选择：
| 变量 | 默认值 | 描述 |
| ---------------------------------- | ---------------------- | ----------------------------------------------------------- |
| `DOCKER_DEFAULT_IMAGE` | `debian:latest` | 用于常规任务和模糊情况的默认 Docker 镜像 |
| `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` | `nullailab/kali-linux` | 用于安全/渗透测试任务的默认 Docker 镜像 |
设置这些环境变量后，AI 代理将被限制为您指定的镜像选择。这对于以下情况特别有用：
- **安全强制执行**：将使用限制为仅经过验证和受信任的镜像
- **环境标准化**：在所有操作中使用企业或自定义镜像
- **性能优化**：利用预装了必要工具的预构建镜像
配置示例：
```
# 使用自定义镜像执行常规任务
DOCKER_DEFAULT_IMAGE=mycompany/custom-debian:latest
# 使用专门用于渗透测试的镜像
DOCKER_DEFAULT_IMAGE_FOR_PENTEST=mycompany/pentest-tools:v2.0
```
## 开发
### 开发要求
- golang
- nodejs
- docker
- postgres
- commitlint
### 环境设置
#### 后端设置
运行一次 `cd backend && go mod download` 来安装所需的包。
要生成 swagger 文件，必须运行
```
swag init -g ../../pkg/server/router.go -o pkg/server/docs/ --parseDependency --parseInternal --parseDepth 2 -d cmd/pennull
```
在通过以下方式安装 `swag` 包之前
```
go install github.com/swaggo/swag/cmd/swag@v1.8.7
```
要生成 graphql 解析器文件，必须运行
```
go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml
```
之后您可以在 `pkg/graph` 文件夹中看到生成的文件。
要从 sqlc 配置生成 ORM 方法（数据库包）
```
docker run --rm -v $(pwd):/src -w /src --network pennull-network -e DATABASE_URL="{URL}" sqlc/sqlc:1.27.0 generate -f sqlc/sqlc.yml
```
从 OpenAPI 规范生成 Langfuse SDK
```
fern generate --local
```
并安装 fern-cli
```
npm install -g fern-api
```
#### 测试
要运行测试，请使用 `cd backend && go test -v ./...`
#### 前端设置
运行一次 `cd frontend && npm install` 来安装所需的包。
要生成 graphql 文件，必须运行 `npm run graphql:generate`，该命令使用 `graphql-codegen.ts` 文件。
请确保您已全局安装 `graphql-codegen`：
```
npm install -g graphql-codegen
```
之后您可以运行：
* `npm run prettier` 检查代码格式是否正确
* `npm run prettier:fix` 进行修复
* `npm run lint` 检查代码 lint 是否正确
* `npm run lint:fix` 进行修复
要生成 SSL 证书，您需要运行 `npm run ssl:generate`，该命令使用 `generate-ssl.ts` 文件，或者在您运行 `npm run dev` 时会自动生成。
#### 后端配置
在 `.vscode/launch.json` 文件中编辑 `backend` 的配置：
- `DATABASE_URL` - PostgreSQL 数据库 URL（例如 `postgres://postgres:postgres@localhost:5432/pennulldb?sslmode=disable`）
- `DOCKER_HOST` - Docker SDK API（例如对于 macOS，`DOCKER_HOST=unix:///Users//Library/Containers/com.docker.docker/Data/docker.raw.sock`）[更多信息](https://stackoverflow.com/a/62757128/5922857)
可选：
- `SERVER_PORT` - 运行服务器的端口（默认：`8443`）
- `SERVER_USE_SSL` - 为服务器启用 SSL（默认：`false`）
#### 前端配置
在 `.vscode/launch.json` 文件中编辑 `frontend` 的配置：
- `VITE_API_URL` - 后端 API URL。*省略* URL 方案（例如 `localhost:8080`，*而不是* `http://localhost:8080`）
- `V_USE_HTTPS` - 为服务器启用 SSL（默认：`false`）
- `VITE_PORT` - 运行服务器的端口（默认：`8000`）
- `VITE_HOST` - 运行服务器的主机（默认：`0.0.0.0`）
### 运行应用程序
#### 后端
在 `backend` 文件夹中运行命令：
- 使用 `.env` 文件设置环境变量，如 `source .env`
- 运行 `go run cmd/pennull/main.go` 启动服务器
#### 前端
在 `frontend` 文件夹中运行命令：
- 运行 `npm install` 安装依赖项
- 运行 `npm run dev` 运行 Web 应用程序
- 运行 `npm run build` 构建 Web 应用程序
打开浏览器并访问 Web 应用程序的 URL。
## 测试 LLM 代理
penNULL 包含一个名为 `ctester` 的强大实用程序，用于测试和验证 LLM 代理能力。此工具有助于确保您的 LLM 提供商配置在不同代理类型中正常工作，让您能够针对每个特定代理角色优化模型选择。
该实用程序具有并行测试多个代理、详细报告和灵活配置选项的特点。
### 核心功能
- **并行测试**：同时测试多个代理以获得更快的结果
- **全面的测试套件**：评估基础补全、JSON 响应、函数调用和渗透测试知识
- **详细报告**：生成带有成功率和性能指标的 Markdown 报告
- **灵活配置**：根据需要测试特定代理或测试组
- **专用测试组**：包含针对网络安全和渗透测试场景的领域特定测试
### 使用场景
#### 面向开发者（带有本地 Go 环境）
如果您克隆了存储库并安装了 Go：
```
# 使用 .env 文件的默认配置
cd backend
go run cmd/ctester/*.go -verbose
# 自定义 provider 配置
go run cmd/ctester/*.go -config ../examples/configs/openrouter.provider.yml -verbose
# 生成报告文件
go run cmd/ctester/*.go -config ../examples/configs/deepinfra.provider.yml -report ../test-report.md
# 仅测试特定的 agent 类型
go run cmd/ctester/*.go -agents simple,simple_json,primary_agent -verbose
# 仅测试特定的测试组
go run cmd/ctester/*.go -groups basic,advanced -verbose
```
#### 面向用户（使用 Docker 镜像）
如果您喜欢使用预构建的 Docker 镜像而不设置开发环境：
```
# 使用 Docker 在默认环境下进行测试
docker run --rm -v $(pwd)/.env:/opt/pennull/.env nullailab/pennull /opt/pennull/bin/ctester -verbose
# 使用你的自定义 provider 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pennull/.env \
-v $(pwd)/my-config.yml:/opt/pennull/config.yml \
nullailab/pennull /opt/pennull/bin/ctester -config /opt/pennull/config.yml -agents simple,primary_agent,coder -verbose
# 生成详细报告
docker run --rm \
-v $(pwd)/.env:/opt/pennull/.env \
-v $(pwd):/opt/pennull/output \
nullailab/pennull /opt/pennull/bin/ctester -report /opt/pennull/output/report.md
```
#### 使用预配置的提供商
Docker 镜像内置了对主要提供商（OpenAI, Anthropic, Gemini, Ollama）的支持，并为其他服务（OpenRouter, DeepInfra, DeepSeek, Moonshot, Novita）提供了预配置的提供商文件：
```
# 使用 OpenRouter 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/openrouter.provider.yml
# 使用 DeepInfra 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/deepinfra.provider.yml
# 使用 DeepSeek 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -provider deepseek
# 使用 GLM 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -provider glm
# 使用 Kimi 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -provider kimi
# 使用 Qwen 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -provider qwen
# 使用自定义 provider 的 DeepSeek 配置文件进行测试
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/deepseek.provider.yml
# 使用自定义 provider 的 Moonshot 配置文件进行测试
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/moonshot.provider.yml
# 使用 Novita 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/novita.provider.yml
# 使用 OpenAI 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -type openai
# 使用 Anthropic 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -type anthropic
# 使用 Gemini 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -type gemini
# 使用 AWS Bedrock 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -type bedrock
# 使用自定义 OpenAI 配置进行测试
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/custom-openai.provider.yml
# 使用 Ollama 配置进行测试（本地推理）
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/ollama-llama318b.provider.yml
# 使用 Ollama Qwen3 32B 配置进行测试（需要创建自定义模型）
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/ollama-qwen332b-fp16-tc.provider.yml
# 使用 Ollama QwQ 32B 配置进行测试（需要创建自定义模型以及 71.3GB VRAM）
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/ollama-qwq32b-fp16-tc.provider.yml
```
要使用这些配置，您的 `.env` 文件只需包含：
```
LLM_SERVER_URL=https://openrouter.ai/api/v1 # or https://api.deepinfra.com/v1/openai or https://api.openai.com/v1 or https://api.novita.ai/openai
LLM_SERVER_KEY=your_api_key
LLM_SERVER_MODEL= # Leave empty, as models are specified in the config
LLM_SERVER_CONFIG_PATH=/opt/pennull/conf/openrouter.provider.yml # or deepinfra.provider.ymll or custom-openai.provider.yml or novita.provider.yml
LLM_SERVER_PROVIDER= # Provider name for LiteLLM proxy (e.g., openrouter, deepseek, moonshot, novita)
LLM_SERVER_LEGACY_REASONING=false # Controls reasoning format, for OpenAI must be true (default: false)
LLM_SERVER_PRESERVE_REASONING=false # Preserve reasoning content in multi-turn conversations (required by Moonshot, default: false)
# 对于 OpenAI（官方 API）
OPEN_AI_KEY=your_openai_api_key # Your OpenAI API key
OPEN_AI_SERVER_URL=https://api.openai.com/v1 # OpenAI API endpoint
# 对于 Anthropic (Claude 模型)
ANTHROPIC_API_KEY=your_anthropic_api_key # Your Anthropic API key
ANTHROPIC_SERVER_URL=https://api.anthropic.com/v1 # Anthropic API endpoint
# 对于 Gemini（Google AI）
GEMINI_API_KEY=your_gemini_api_key # Your Google AI API key
GEMINI_SERVER_URL=https://generativelanguage.googleapis.com # Google AI API endpoint
# 对于 AWS Bedrock（企业基础模型）
BEDROCK_REGION=us-east-1 # AWS region for Bedrock service
# 身份验证（选择一种方法，优先级：DefaultAuth > BearerToken > AccessKey）：
BEDROCK_DEFAULT_AUTH=false # Use AWS SDK credential chain (env vars, EC2 role, ~/.aws/credentials)
BEDROCK_BEARER_TOKEN= # Bearer token authentication (takes priority over static credentials)
BEDROCK_ACCESS_KEY_ID=your_aws_access_key # AWS access key ID (static credentials)
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key # AWS secret access key (static credentials)
BEDROCK_SESSION_TOKEN= # AWS session token (optional, for temporary credentials with static auth)
BEDROCK_SERVER_URL= # Optional custom Bedrock endpoint (VPC endpoints, local testing)
# 对于 Ollama（本地服务器或云端）
OLLAMA_SERVER_URL= # Local: http://ollama-server:11434, Cloud: https://ollama.com
OLLAMA_SERVER_API_KEY= # Required for Ollama Cloud (https://ollama.com/settings/keys), leave empty for local
OLLAMA_SERVER_MODEL=
OLLAMA_SERVER_CONFIG_PATH=
OLLAMA_SERVER_PULL_MODELS_TIMEOUT=
OLLAMA_SERVER_PULL_MODELS_ENABLED=
OLLAMA_SERVER_LOAD_MODELS_ENABLED=
# 对于 DeepSeek（具有强大推理能力的中国 AI）
DEEPSEEK_API_KEY= # DeepSeek API key
DEEPSEEK_SERVER_URL=https://api.deepseek.com # DeepSeek API endpoint
DEEPSEEK_PROVIDER= # Optional: LiteLLM prefix (e.g., 'deepseek')
# 对于 GLM（Zhipu AI）
GLM_API_KEY= # GLM API key
GLM_SERVER_URL=https://api.z.ai/api/paas/v4 # GLM API endpoint (international)
GLM_PROVIDER= # Optional: LiteLLM prefix (e.g., 'zai')
# 对于 Kimi（Moonshot AI）
KIMI_API_KEY= # Kimi API key
KIMI_SERVER_URL=https://api.moonshot.ai/v1 # Kimi API endpoint (international)
KIMI_PROVIDER= # Optional: LiteLLM prefix (e.g., 'moonshot')
# 对于 Qwen（阿里云 DashScope）
QWEN_API_KEY= # Qwen API key
QWEN_SERVER_URL=https://dashscope-us.aliyuncs.com/compatible-mode/v1 # Qwen API endpoint (US)
QWEN_PROVIDER= # Optional: LiteLLM prefix (e.g., 'dashscope')
# 对于 Ollama（本地推理）使用上面的变量
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
OLLAMA_SERVER_CONFIG_PATH=/opt/pennull/conf/ollama-llama318b.provider.yml
OLLAMA_SERVER_PULL_MODELS_ENABLED=false
OLLAMA_SERVER_LOAD_MODELS_ENABLED=false
```
#### 使用未验证组织的 OpenAI
对于未验证组织的 OpenAI 账户，这些账户无法访问最新的推理模型（o1, o3, o4-mini），您需要使用自定义配置。
要将 OpenAI 与未验证的组织账户一起使用，请按如下方式配置您的 `.env` 文件：
```
LLM_SERVER_URL=https://api.openai.com/v1
LLM_SERVER_KEY=your_openai_api_key
LLM_SERVER_MODEL= # Leave empty, models are specified in config
LLM_SERVER_CONFIG_PATH=/opt/pennull/conf/custom-openai.provider.yml
LLM_SERVER_LEGACY_REASONING=true # Required for OpenAI reasoning format
```
此配置使用预构建的 `custom-openai.provider.yml` 文件，将所有代理类型映射到未验证组织可用的模型，使用 `o3-mini` 代替 `o1`、`o3` 和 `o4-mini` 等模型。
您可以使用以下命令测试此配置：
```
# 使用自定义 OpenAI 配置测试未经核实的账户
docker exec -it pennull /opt/pennull/bin/ctester -config /opt/pennull/conf/custom-openai.provider.yml
```
#### 使用 LiteLLM 代理
当使用 LiteLLM 代理访问各种 LLM 提供商时，模型名称会以提供商名称为前缀（例如 `moonshot/kimi-2.5` 而不是 `kimi-2.5`）。要在直接 API 访问和 LiteLLM 代理中使用相同的提供商配置文件，请设置 `LLM_SERVER_PROVIDER` 变量：
```
# 直接访问 Moonshot API
LLM_SERVER_URL=https://api.moonshot.ai/v1
LLM_SERVER_KEY=your_moonshot_api_key
LLM_SERVER_CONFIG_PATH=/opt/pennull/conf/moonshot.provider.yml
LLM_SERVER_PROVIDER= # Empty for direct access
# 通过 LiteLLM 代理访问
LLM_SERVER_URL=http://litellm-proxy:4000
LLM_SERVER_KEY=your_litellm_api_key
LLM_SERVER_CONFIG_PATH=/opt/pennull/conf/moonshot.provider.yml
LLM_SERVER_PROVIDER=moonshot # Provider prefix for LiteLLM
```
设置 `LLM_SERVER_PROVIDER=moonshot` 后，系统会自动为配置文件中的所有模型名称添加 `moonshot/` 前缀，使其与 LiteLLM 的模型命名约定兼容。
**LiteLLM 提供商名称映射：**
使用 LiteLLM 代理时，设置相应的 `*_PROVIDER` 变量以启用模型前缀：
- `deepseek` - 用于 DeepSeek 模型（`DEEPSEEK_PROVIDER=deepseek` → `deepseek/deepseek-chat`）
- `zai` - 用于 GLM 模型（`GLM_PROVIDER=zai` → `zai/glm-4`）
- `moonshot` - 用于 Kimi 模型（`KIMI_PROVIDER=moonshot` → `moonshot/kimi-k2.5`）
- `dashscope` - 用于 Qwen 模型（`QWEN_PROVIDER=dashscope` → `dashscope/qwen-plus`）
- `openai`, `anthropic`, `gemini` - 用于主要的云提供商
- `openrouter` - 用于 OpenRouter 聚合器
- `deepinfra` - 用于 DeepInfra 托管
- `novita` - 用于 Novita AI
- 您的 LiteLLM 实例中配置的任何其他提供商名称
**使用 LiteLLM 的示例：**
```
# 通过带有模型前缀的 LiteLLM 代理使用 DeepSeek 模型
DEEPSEEK_API_KEY=your_litellm_proxy_key
DEEPSEEK_SERVER_URL=http://litellm-proxy:4000
DEEPSEEK_PROVIDER=deepseek # Models become deepseek/deepseek-chat, deepseek/deepseek-reasoner for LiteLLM
# 直接使用 DeepSeek API（无需前缀）
DEEPSEEK_API_KEY=your_deepseek_api_key
DEEPSEEK_SERVER_URL=https://api.deepseek.com
# 将 DEEPSEEK_PROVIDER 留空
```
此方法允许您：
- 对直接访问和代理访问使用相同的配置文件
- 无需修改配置文件即可在提供商之间切换
- 轻松测试 LiteLLM 的不同路由策略
#### 在生产环境中运行测试
如果您已经有一个正在运行的 penNULL 容器，并且想要测试当前配置：
```
# 使用当前环境变量在现有容器中运行 ctester
docker exec -it pennull /opt/pennull/bin/ctester -verbose
# 以确定性顺序测试特定的 agent 类型
docker exec -it pennull /opt/pennull/bin/ctester -agents simple,primary_agent,pentester -groups basic,knowledge -verbose
# 在容器内生成报告文件
docker exec -it pennull /opt/pennull/bin/ctester -report /opt/pennull/data/agent-test-report.md
# 从主机访问报告
docker cp pennull:/opt/pennull/data/agent-test-report.md ./
```
### 命令行选项
该实用程序接受多个选项：
- `-env ` - 环境文件的路径（默认：`.env`）
- `-type ` - 提供商类型：`custom`、`openai`、`anthropic`、`ollama`、`bedrock`、`gemini`（默认：`custom`）
- `-config ` - 自定义提供商配置的路径（默认：来自 `LLM_SERVER_CONFIG_PATH` 环境变量）
- `-tests ` - 自定义测试 YAML 文件的路径（可选）
- `-report ` - 写入报告文件的路径（可选）
- `-agents
```
██████╗ ███████╗███╗ ██╗███╗ ██╗██╗ ██╗██╗ ██╗
██╔══██╗██╔════╝████╗ ██║████╗ ██║██║ ██║██║ ██║
██████╔╝█████╗ ██╔██╗ ██║██╔██╗ ██║██║ ██║██║ ██║
██╔═══╝ ██╔══╝ ██║╚██╗██║██║╚██╗██║██║ ██║██║ ██║
██║ ███████╗██║ ╚████║██║ ╚████║╚██████╔╝███████╗███████╗
╚═╝ ╚══════╝╚═╝ ╚═══╝╚═╝ ╚═══╝ ╚═════╝ ╚══════╝╚══════╝
```
**渗透测试 NULL Intelligence** — 自主 AI 驱动的安全测试平台
作者：[NullAI Lab](https://github.com/NullAILab)
[](https://go.dev/)
[](https://www.typescriptlang.org/)
[](https://react.dev/)
[](https://www.postgresql.org/)
[](https://docs.docker.com/compose/)
[](https://graphql.org/)
[](LICENSE)
## 目录
- [概述](#overview)
- [功能特性](#features)
- [系统架构](#architecture)
- [Agent 监督](#advanced-agent-supervision)
- [快速开始](#quick-start)
- [第 1 步 — 系统要求](#step-1--system-requirements)
- [第 2 步 — 安装 Docker](#step-2--install-docker)
- [第 3 步 — 下载并配置](#step-3--download--configure)
- [第 4 步 — 访问 penNULL](#step-4--access-pennull)
- [第 5 步 — 登录并保护您的账户](#step-5--log-in--secure-your-account)
- [外部网络访问](#accessing-pennull-from-external-networks)
- [环境配置 (.env)](#environment-configuration-env)
- [运行你的第一次渗透测试](#running-your-first-pentest)
- [API 访问](#api-access)
- [LLM 提供商配置](#custom-llm-provider-configuration)
- [Ollama](#ollama-provider-configuration)
- [OpenAI](#openai-provider-configuration)
- [Anthropic](#anthropic-provider-configuration)
- [Google AI (Gemini)](#google-ai-gemini-provider-configuration)
- [AWS Bedrock](#aws-bedrock-provider-configuration)
- [DeepSeek](#deepseek-provider-configuration)
- [GLM](#glm-provider-configuration)
- [Kimi](#kimi-provider-configuration)
- [Qwen](#qwen-provider-configuration)
- [高级设置](#advanced-setup)
- [Langfuse 集成](#langfuse-integration)
- [监控与可观测性](#monitoring-and-observability)
- [知识图谱 (Graphiti)](#knowledge-graph-integration-graphiti)
- [OAuth 集成](#github-and-google-oauth-integration)
- [Docker 镜像配置](#docker-image-configuration)
- [开发](#development)
- [测试 LLM Agent](#testing-llm-agents)
- [Embedding 配置与测试](#embedding-configuration-and-testing)
- [使用 ftester 进行功能测试](#function-testing-with-ftester)
- [构建](#building)
- [致谢](#credits)
- [许可证](#license)
## 概述
**penNULL** 是一个由多 Agent AI 系统驱动的完全自主的渗透测试平台。它将大语言模型的推理能力与一套专业的安全工具相结合——完全在隔离的 Docker 容器中运行——以最少的人工干预进行端到端的渗透测试。
与传统运行预定义检查的安全扫描器不同，penNULL 能够*思考*：它读取目标，形成假设，执行工具，解释结果，调整策略，并交付完整的漏洞报告——所有这些都不需要手把手的逐步指导。
```
┌─────────────────────────────────────────────────────────────┐
│ You: "Test the security of 192.168.1.100" │
│ │
│ penNULL: │
│ [1] Researcher agent → recon & OSINT gathering │
│ [2] Developer agent → attack strategy & payload design │
│ [3] Executor agent → tool execution in Docker sandbox │
│ [4] Memorist agent → save findings to vector memory │
│ [5] Reporter agent → generate full vuln report │
│ │
│ Result: Professional penetration test report in minutes │
└─────────────────────────────────────────────────────────────┘
```
### 是什么让 penNULL 与众不同？
| 能力 | 传统工具 | penNULL |
|------------|-------------------|---------|
| 执行模式 | 手动、逐步 | 完全自主的 AI Agent |
| 适应性 | 固定的扫描配置文件 | 基于发现的动态策略 |
| 记忆 | 无 | 持久化向量数据库 + 知识图谱 |
| 报告 | 原始输出转储 | 结构化的漏洞报告 |
| LLM 支持 | 无 | 10 多家提供商 (OpenAI, Claude, Gemini, Ollama, …) |
| 隔离性 | 主机级别 | 每个任务使用 Docker 沙箱容器 |
| 可观测性 | 基础日志 | Grafana + OpenTelemetry + Langfuse |
## 功能特性
- 安全与隔离。所有操作都在具有完全隔离的沙箱 Docker 环境中执行。
- 完全自主。AI 驱动的 Agent 可自动确定并执行渗透测试步骤，并带有可选的执行监控和智能任务规划功能，以增强可靠性。
- 专业渗透测试工具。内置 20 多种专业安全工具套件，包括 nmap、metasploit、sqlmap 等。
- 智能记忆系统。长期存储研究结果和成功的方法，以备将来使用。
- 知识图谱集成。基于 Graphiti 并使用 Neo4j 的知识图谱，用于语义关系跟踪和高级上下文理解。
- 网络情报。通过 [scraper](https://hub.docker.com/r/nullailab/scraper) 内置浏览器，用于从网络来源收集最新信息。
- 外部搜索系统。集成高级搜索 API，包括 [Tavily](https://tavily.com)、[Traversaal](https://traversaal.ai)、[Perplexity](https://www.perplexity.ai)、[DuckDuckGo](https://duckduckgo.com/)、[Google Custom Search](https://programmablesearchengine.google.com/)、[Sploitus Search](https://sploitus.com) 和 [Searxng](https://searxng.org)，用于全面的信息收集。
- 专家团队。委派系统配备了专门的 AI Agent，用于研究、开发和基础设施任务，并通过可选的执行监控和智能任务规划功能得到增强，以便在较小模型下实现最佳性能。
- 全面监控。详细的日志记录并与 Grafana/Prometheus 集成，用于实时系统观察。
- 详细的报告。生成包含漏洞利用指南的详尽漏洞报告。
- 智能容器管理。根据特定任务要求自动选择 Docker 镜像。
- 现代化界面。干净直观的 Web UI，用于系统管理和监控。
- 全面的 API。具有 Bearer token 身份验证的全功能 REST 和 GraphQL API，用于自动化和集成。
- 持久化存储。所有命令和输出都存储在带有 [pgvector](https://hub.docker.com/r/nullailab/pgvector) 扩展的 PostgreSQL 中。
- 可扩展的架构。基于微服务的架构设计，支持水平扩展。
- 自托管解决方案。完全控制您的部署和数据。
- 灵活的身份验证。支持 10 多家 LLM 提供商（[OpenAI](https://platform.openai.com/)、[Anthropic](https://www.anthropic.com/)、[Google AI/Gemini](https://ai.google.dev/)、[AWS Bedrock](https://aws.amazon.com/bedrock/)、[Ollama](https://ollama.com/)、[DeepSeek](https://www.deepseek.com/en/)、[GLM](https://z.ai/)、[Kimi](https://platform.moonshot.ai/)、[Qwen](https://www.alibabacloud.com/en/)、自定义）以及聚合器（[OpenRouter](https://openrouter.ai/)、[DeepInfra](https://deepinfra.com/)）。有关生产环境本地部署，请参阅我们的 [vLLM + Qwen3.5-27B-FP8 指南](examples/guides/vllm-qwen35-27b-fp8.md)。
- API Token 身份验证。安全的 Bearer token 系统，用于对 REST 和 GraphQL API 的编程访问。
- 快速部署。通过 [Docker Compose](https://docs.docker.com/compose/) 轻松设置，并提供全面的环境配置。
## 系统架构
### 系统上下文
```
flowchart TB
classDef person fill:#08427B,stroke:#073B6F,color:#fff
classDef system fill:#1168BD,stroke:#0B4884,color:#fff
classDef external fill:#666666,stroke:#0B4884,color:#fff
pentester["👤 Security Engineer
(User of the system)"]
pennull["✨ penNULL
(Autonomous penetration testing system)"]
target["🎯 target-system
(System under test)"]
llm["🧠 llm-provider
(OpenAI/Anthropic/Ollama/Bedrock/Gemini/Custom)"]
search["🔍 search-systems
(Google/DuckDuckGo/Tavily/Traversaal/Perplexity/Sploitus/Searxng)"]
langfuse["📊 langfuse-ui
(LLM Observability Dashboard)"]
grafana["📈 grafana
(System Monitoring Dashboard)"]
pentester --> |Uses HTTPS| pennull
pentester --> |Monitors AI HTTPS| langfuse
pentester --> |Monitors System HTTPS| grafana
pennull --> |Tests Various protocols| target
pennull --> |Queries HTTPS| llm
pennull --> |Searches HTTPS| search
pennull --> |Reports HTTPS| langfuse
pennull --> |Reports HTTPS| grafana
class pentester person
class pennull system
class target,llm,search,langfuse,grafana external
linkStyle default stroke:#ffffff,color:#ffffff
```
容器架构 (点击展开)
``` graph TB subgraph Core Services UI[Frontend UIReact + TypeScript] API[Backend API
Go + GraphQL] DB[(Vector Store
PostgreSQL + pgvector)] MQ[Task Queue
Async Processing] Agent[AI Agents
Multi-Agent System] end subgraph Knowledge Graph Graphiti[Graphiti
Knowledge Graph API] Neo4j[(Neo4j
Graph Database)] end subgraph Monitoring Grafana[Grafana
Dashboards] VictoriaMetrics[VictoriaMetrics
Time-series DB] Jaeger[Jaeger
Distributed Tracing] Loki[Loki
Log Aggregation] OTEL[OpenTelemetry
Data Collection] end subgraph Analytics Langfuse[Langfuse
LLM Analytics] ClickHouse[ClickHouse
Analytics DB] Redis[Redis
Cache + Rate Limiter] MinIO[MinIO
S3 Storage] end subgraph Security Tools Scraper[Web Scraper
Isolated Browser] PenTest[Security Tools
20+ Pro Tools
Sandboxed Execution] end UI --> |HTTP/WS| API API --> |SQL| DB API --> |Events| MQ MQ --> |Tasks| Agent Agent --> |Commands| PenTest Agent --> |Queries| DB Agent --> |Knowledge| Graphiti Graphiti --> |Graph| Neo4j API --> |Telemetry| OTEL OTEL --> |Metrics| VictoriaMetrics OTEL --> |Traces| Jaeger OTEL --> |Logs| Loki Grafana --> |Query| VictoriaMetrics Grafana --> |Query| Jaeger Grafana --> |Query| Loki API --> |Analytics| Langfuse Langfuse --> |Store| ClickHouse Langfuse --> |Cache| Redis Langfuse --> |Files| MinIO classDef core fill:#f9f,stroke:#333,stroke-width:2px,color:#000 classDef knowledge fill:#ffa,stroke:#333,stroke-width:2px,color:#000 classDef monitoring fill:#bbf,stroke:#333,stroke-width:2px,color:#000 classDef analytics fill:#bfb,stroke:#333,stroke-width:2px,color:#000 classDef tools fill:#fbb,stroke:#333,stroke-width:2px,color:#000 class UI,API,DB,MQ,Agent core class Graphiti,Neo4j knowledge class Grafana,VictoriaMetrics,Jaeger,Loki,OTEL monitoring class Langfuse,ClickHouse,Redis,MinIO analytics class Scraper,PenTest tools ```
实体关系 (点击展开)
``` erDiagram Flow ||--o{ Task : contains Task ||--o{ SubTask : contains SubTask ||--o{ Action : contains Action ||--o{ Artifact : produces Action ||--o{ Memory : stores Flow { string id PK string name "Flow name" string description "Flow description" string status "active/completed/failed" json parameters "Flow parameters" timestamp created_at timestamp updated_at } Task { string id PK string flow_id FK string name "Task name" string description "Task description" string status "pending/running/done/failed" json result "Task results" timestamp created_at timestamp updated_at } SubTask { string id PK string task_id FK string name "Subtask name" string description "Subtask description" string status "queued/running/completed/failed" string agent_type "researcher/developer/executor" json context "Agent context" timestamp created_at timestamp updated_at } Action { string id PK string subtask_id FK string type "command/search/analyze/etc" string status "success/failure" json parameters "Action parameters" json result "Action results" timestamp created_at } Artifact { string id PK string action_id FK string type "file/report/log" string path "Storage path" json metadata "Additional info" timestamp created_at } Memory { string id PK string action_id FK string type "observation/conclusion" vector embedding "Vector representation" text content "Memory content" timestamp created_at } ```Agent 交互 (点击展开)
``` sequenceDiagram participant O as Orchestrator participant R as Researcher participant D as Developer participant E as Executor participant VS as Vector Store participant KB as Knowledge Base Note over O,KB: Flow Initialization O->>VS: Query similar tasks VS-->>O: Return experiences O->>KB: Load relevant knowledge KB-->>O: Return context Note over O,R: Research Phase O->>R: Analyze target R->>VS: Search similar cases VS-->>R: Return patterns R->>KB: Query vulnerabilities KB-->>R: Return known issues R->>VS: Store findings R-->>O: Research results Note over O,D: Planning Phase O->>D: Plan attack D->>VS: Query exploits VS-->>D: Return techniques D->>KB: Load tools info KB-->>D: Return capabilities D-->>O: Attack plan Note over O,E: Execution Phase O->>E: Execute plan E->>KB: Load tool guides KB-->>E: Return procedures E->>VS: Store results E-->>O: Execution status ```记忆系统 (点击展开)
``` graph TB subgraph "Long-term Memory" VS[(Vector StoreEmbeddings DB)] KB[Knowledge Base
Domain Expertise] Tools[Tools Knowledge
Usage Patterns] end subgraph "Working Memory" Context[Current Context
Task State] Goals[Active Goals
Objectives] State[System State
Resources] end subgraph "Episodic Memory" Actions[Past Actions
Commands History] Results[Action Results
Outcomes] Patterns[Success Patterns
Best Practices] end Context --> |Query| VS VS --> |Retrieve| Context Goals --> |Consult| KB KB --> |Guide| Goals State --> |Record| Actions Actions --> |Learn| Patterns Patterns --> |Store| VS Tools --> |Inform| State Results --> |Update| Tools VS --> |Enhance| KB KB --> |Index| VS classDef ltm fill:#f9f,stroke:#333,stroke-width:2px,color:#000 classDef wm fill:#bbf,stroke:#333,stroke-width:2px,color:#000 classDef em fill:#bfb,stroke:#333,stroke-width:2px,color:#000 class VS,KB,Tools ltm class Context,Goals,State wm class Actions,Results,Patterns em ```
链式摘要 (点击展开)
链式摘要系统通过选择性地摘要较早的消息来管理对话上下文的增长。这对于防止超出 token 限制，同时保持对话连贯性至关重要。 ``` flowchart TD A[Input Chain] --> B{Needs Summarization?} B -->|No| C[Return Original Chain] B -->|Yes| D[Convert to ChainAST] D --> E[Apply Section Summarization] E --> F[Process Oversized Pairs] F --> G[Manage Last Section Size] G --> H[Apply QA Summarization] H --> I[Rebuild Chain with Summaries] I --> J{Is New Chain Smaller?} J -->|Yes| K[Return Optimized Chain] J -->|No| C classDef process fill:#bbf,stroke:#333,stroke-width:2px,color:#000 classDef decision fill:#bfb,stroke:#333,stroke-width:2px,color:#000 classDef output fill:#fbb,stroke:#333,stroke-width:2px,color:#000 class A,D,E,F,G,H,I process class B,J decision class C,K output ``` 该算法在对话链的结构化表示（ChainAST）上运行，该表示保留了消息类型，包括工具调用及其响应。所有摘要操作在减小上下文大小的同时，都会保留关键的对话流。 ### 全局摘要器配置选项 | 参数 | 环境变量 | 默认值 | 描述 | | --------------------- | -------------------------------- | ------- | ---------------------------------------------------------- | | 保留最后部分 | `SUMMARIZER_PRESERVE_LAST` | `true` | 是否将最后部分中的所有消息保持不变 | | 使用问答对 | `SUMMARIZER_USE_QA` | `true` | 是否使用问答对摘要策略 | | 在问答对中摘要人类消息 | `SUMMARIZER_SUM_MSG_HUMAN_IN_QA` | `false` | 是否在问答对中摘要人类消息 | | 最后部分大小 | `SUMMARIZER_LAST_SEC_BYTES` | `51200` | 最后部分的最大字节大小 (50KB) | | 最大主体对大小 | `SUMMARIZER_MAX_BP_BYTES` | `16384` | 单个主体对的最大字节大小 (16KB) | | 最大问答节数 | `SUMMARIZER_MAX_QA_SECTIONS` | `10` | 要保留的最大问答对节数 | | 最大问答大小 | `SUMMARIZER_MAX_QA_BYTES` | `65536` | 问答对部分的最大字节大小 (64KB) | | 保留问答节数 | `SUMMARIZER_KEEP_QA_SECTIONS` | `1` | 不进行摘要的最近问答节数 | ### 助手摘要器配置选项 助手实例可以使用自定义的摘要设置来微调上下文管理行为： | 参数 | 环境变量 | 默认值 | 描述 | | ------------------ | --------------------------------------- | ------- | -------------------------------------------------------------------- | | 保留最后部分 | `ASSISTANT_SUMMARIZER_PRESERVE_LAST` | `true` | 是否保留助手最后部分中的所有消息 | | 最后部分大小 | `ASSISTANT_SUMMARIZER_LAST_SEC_BYTES` | `76800` | 助手最后部分的最大字节大小 (75KB) | | 最大主体对大小 | `ASSISTANT_SUMMARIZER_MAX_BP_BYTES` | `16384` | 助手上下文中单个主体对的最大字节大小 (16KB) | | 最大问答节数 | `ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS` | `7` | 在助手上下文中要保留的最大问答节数 | | 最大问答大小 | `ASSISTANT_SUMMARIZER_MAX_QA_BYTES` | `76800` | 助手问答部分的最大字节大小 (75KB) | | 保留问答节数 | `ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS` | `3` | 不进行摘要的最近问答节数 | 助手摘要器配置相比全局设置提供了更多的内存用于上下文保留，保留了更多最近的对话历史，同时仍能确保高效的 token 使用。 ### 摘要器环境配置 ``` # 全局摘要器逻辑的默认值 SUMMARIZER_PRESERVE_LAST=true SUMMARIZER_USE_QA=true SUMMARIZER_SUM_MSG_HUMAN_IN_QA=false SUMMARIZER_LAST_SEC_BYTES=51200 SUMMARIZER_MAX_BP_BYTES=16384 SUMMARIZER_MAX_QA_SECTIONS=10 SUMMARIZER_MAX_QA_BYTES=65536 SUMMARIZER_KEEP_QA_SECTIONS=1 # 助手摘要器逻辑的默认值 ASSISTANT_SUMMARIZER_PRESERVE_LAST=true ASSISTANT_SUMMARIZER_LAST_SEC_BYTES=76800 ASSISTANT_SUMMARIZER_MAX_BP_BYTES=16384 ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS=7 ASSISTANT_SUMMARIZER_MAX_QA_BYTES=76800 ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS=3 ```高级 Agent 监督 (点击展开)
penNULL 包含复杂的多层 Agent 监督机制，以确保高效的任务执行，防止无限循环，并提供从卡死状态的智能恢复： ### 执行监控 (Beta) - **自动导师干预**：当执行模式表明存在潜在问题时，会自动调用顾问 Agent（导师） - **模式检测**：监控相同的工具调用（阈值：5，可配置）和总工具调用（阈值：10，可配置） - **进度分析**：评估 Agent 是否向子任务目标推进，检测循环和低效情况 - **替代策略**：当当前策略失败时推荐不同的方法 - **信息检索指导**：建议搜索已有的解决方案而不是重新发明 - **增强的响应格式**：工具响应包括 `🪟 Windows
1. 下载并安装 **[Docker Desktop for Windows](https://www.docker.com/products/docker-desktop/)** 2. 在安装过程中，确保选中 **“Use WSL 2”**（推荐） 3. 启动 Docker Desktop 并等待任务栏中的鲸鱼图标变为绿色（正在运行） 4. 打开 **PowerShell** 或 **命令提示符** 并验证： ``` docker --version docker compose version ``` 您应该会看到这两个命令的版本号。🐧 Linux (Ubuntu / Debian)
``` # 安装 Docker Engine sudo apt-get update sudo apt-get install -y ca-certificates curl sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \ https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \ | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 将你的用户添加到 docker 组（避免每个命令都需要 sudo） sudo usermod -aG docker $USER newgrp docker # 验证 docker --version docker compose version ```🍎 macOS
1. 下载并安装 **[Docker Desktop for Mac](https://www.docker.com/products/docker-desktop/)** - **Apple Silicon (M1/M2/M3):** 选择 **Apple Silicon** 版本 - **Intel:** 选择 **Intel Chip** 版本 2. 从应用程序中打开 Docker Desktop 并等待状态栏图标显示 “Docker Desktop is running” 3. 打开 **终端** 并验证： ``` docker --version docker compose version ```🦭 Podman (Docker 的替代方案)
penNULL 支持 Podman 作为 Docker 的直接替代品。当在 **无根 (rootless) 模式** 下使用 **Podman** 时，scraper 服务需要进行一项小的配置更改，因为无根容器无法绑定低于 1024 的端口。 **编辑 `docker-compose.yml`** — 将 `scraper` 服务的端口从 `443` 更改为 `3000`： ``` scraper: expose: - 3000/tcp ports: - "${SCRAPER_LISTEN_IP:-127.0.0.1}:${SCRAPER_LISTEN_PORT:-9443}:3000" ``` **更新 `.env`** — 对 scraper 使用 HTTP 和端口 3000： ``` SCRAPER_PRIVATE_URL=http://someuser:somepass@scraper:3000/ LOCAL_SCRAPER_USERNAME=someuser LOCAL_SCRAPER_PASSWORD=somepass ``` 然后使用 `podman-compose up -d --force-recreate` 启动。 如果在 **有根 (rootful) 模式** 下运行 Podman（使用 sudo），则无需更改 — 默认配置即可按原样工作。可选：附加提供商和搜索引擎
``` # AWS Bedrock BEDROCK_REGION=us-east-1 BEDROCK_DEFAULT_AUTH=true # Use AWS SDK credential chain (EC2/ECS) # BEDROCK_ACCESS_KEY_ID=... # 或：静态凭证 # BEDROCK_SECRET_ACCESS_KEY=... # DeepSeek / GLM / Kimi / Qwen # DEEPSEEK_API_KEY=... # GLM_API_KEY=... # KIMI_API_KEY=... # QWEN_API_KEY=... # 搜索引擎（可选但推荐） DUCKDUCKGO_ENABLED=true SPLOITUS_ENABLED=true # TAVILY_API_KEY=... # TRAVERSAAL_API_KEY=... # PERPLEXITY_API_KEY=... # GOOGLE_API_KEY=... # GOOGLE_CX_KEY=... ```安全相关变量的完整列表
| 变量 | 描述 | |---|---| | `COOKIE_SIGNING_SALT` | 用于会话 cookie 签名的 Salt | | `PUBLIC_URL` | 服务器的公共 URL（例如 `https://pennull.example.com`） | | `SERVER_SSL_CRT` / `SERVER_SSL_KEY` | 您自己的 SSL 证书和密钥的路径 | | `PENNULL_POSTGRES_USER` | PostgreSQL 用户名 | | `PENNULL_POSTGRES_PASSWORD` | PostgreSQL 密码 | | `NEO4J_USER` / `NEO4J_PASSWORD` | Neo4j 凭证（用于 Graphiti 知识图谱） | | `SCRAPER_PUBLIC_URL` | scraper 服务的公共 URL | | `SCRAPER_PRIVATE_URL` | scraper 服务的内部 URL |创建新流程 (GraphQL)
``` mutation CreateFlow { createFlow( modelProvider: "openai" input: "Test the security of https://example.com" ) { id title status createdAt } } ```列出流程 (REST API)
``` curl https://your-pennull-instance:8443/api/v1/flows \ -H "Authorization: Bearer YOUR_API_TOKEN" \ | jq '.flows[] | {id, title, status}' ```Python 客户端示例
``` import requests class penNULLClient: def __init__(self, base_url, api_token): self.base_url = base_url self.headers = { "Authorization": f"Bearer {api_token}", "Content-Type": "application/json" } def create_flow(self, provider, target): query = """ mutation CreateFlow($provider: String!, $input: String!) { createFlow(modelProvider: $provider, input: $input) { id title status } } """ response = requests.post( f"{self.base_url}/api/v1/graphql", json={ "query": query, "variables": { "provider": provider, "input": target } }, headers=self.headers ) return response.json() def get_flows(self): response = requests.get( f"{self.base_url}/api/v1/flows", headers=self.headers ) return response.json() # 用法 client = penNULLClient( "https://your-pennull-instance:8443", "your_api_token_here" ) # 创建新 flow flow = client.create_flow("openai", "Scan https://example.com for vulnerabilities") print(f"Created flow: {flow}") # 列出所有 flows flows = client.get_flows() print(f"Total flows: {len(flows['flows'])}") ```TypeScript 客户端示例
``` import axios, { AxiosInstance } from 'axios'; interface Flow { id: string; title: string; status: string; createdAt: string; } class penNULLClient { private client: AxiosInstance; constructor(baseURL: string, apiToken: string) { this.client = axios.create({ baseURL: `${baseURL}/api/v1`, headers: { 'Authorization': `Bearer ${apiToken}`, 'Content-Type': 'application/json', }, }); } async createFlow(provider: string, input: string): PromiseLangfuse 常用环境变量
### 数据库凭据 - `LANGFUSE_POSTGRES_USER` 和 `LANGFUSE_POSTGRES_PASSWORD` - Langfuse PostgreSQL 凭据 - `LANGFUSE_CLICKHOUSE_USER` 和 `LANGFUSE_CLICKHOUSE_PASSWORD` - ClickHouse 凭据 - `LANGFUSE_REDIS_AUTH` - Redis 密码 ### 加密和安全密钥 - `LANGFUSE_SALT` - Langfuse Web UI 中用于哈希的盐值 - `LANGFUSE_ENCRYPTION_KEY` - 加密密钥（32 字节十六进制） - `LANGFUSE_NEXTAUTH_SECRET` - NextAuth 的密钥 ### 管理员凭据 - `LANGFUSE_INIT_USER_EMAIL` - 管理员邮箱 - `LANGFUSE_INIT_USER_PASSWORD` - 管理员密码 - `LANGFUSE_INIT_USER_NAME` - 管理员用户名 ### API 密钥和令牌 - `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` - 项目公钥（penNULL 端也会使用） - `LANGFUSE_INIT_PROJECT_SECRET_KEY` - 项目密钥（penNULL 端也会使用） ### S3 存储 - `LANGFUSE_S3_ACCESS_KEY_ID` - S3 访问密钥 ID - `LANGFUSE_S3_SECRET_ACCESS_KEY` - S3 秘密访问密钥- ` - 要测试的代理类型的逗号分隔列表（默认：`all`）
- `-groups
- ` - 要运行的测试组的逗号分隔列表（默认：`all`）
- `-verbose` - 启用详细输出，显示每个代理的详细测试结果
### 可用的代理类型
代理按以下确定性顺序进行测试：
1. **simple** - 基础补全任务
2. **simple_json** - JSON 结构化响应
3. **primary_agent** - 主推理代理
4. **assistant** - 交互式助手模式
5. **generator** - 内容生成
6. **refiner** - 内容提炼和改进
7. **adviser** - 专家建议和咨询
8. **reflector** - 自我反思和分析
9. **searcher** - 信息收集和搜索
10. **enricher** - 数据丰富和扩展
11. **coder** - 代码生成和分析
12. **installer** - 安装和设置任务
13. **pentester** - 渗透测试和安全评估
### 可用的测试组
- **basic** - 基础补全和提示响应测试
- **advanced** - 复杂推理和函数调用测试
- **json** - JSON 格式验证和结构测试（专为 `simple_json` 代理设计）
- **knowledge** - 针对网络安全和渗透测试的领域特定知识测试
### 提供商配置示例
提供商配置定义了用于不同代理类型的模型：
```
simple:
model: "provider/model-name"
temperature: 0.7
top_p: 0.95
n: 1
max_tokens: 4000
simple_json:
model: "provider/model-name"
temperature: 0.7
top_p: 1.0
n: 1
max_tokens: 4000
json: true
# ... 其他 agent 类型 ...
```
### 优化工作流
1. **创建基线**：使用默认配置运行测试以建立基准性能
2. **分析特定代理的性能**：查看确定性的代理排序以识别表现不佳的代理
3. **测试专门的配置**：使用特定于提供商的配置为每种代理类型尝试不同的模型
4. **关注领域知识**：特别关注网络安全专业知识的知识组测试
5. **验证函数调用**：确保关键代理类型的基于工具的测试能够持续通过
6. **比较结果**：寻找在所有测试组中的最佳成功率和性能
7. **部署最佳配置**：使用您优化后的设置在生产环境中部署
此工具有助于确保您的 AI 代理为其特定任务使用最有效的模型，在优化成本的同时提高可靠性。
## 嵌入配置与测试
penNULL 使用向量嵌入进行语义搜索、知识存储和内存管理。系统支持多种嵌入提供商，可根据您的需求和偏好进行配置。
### 支持的嵌入提供商
penNULL 支持以下嵌入提供商：
- **OpenAI**（默认）：使用 OpenAI 的文本嵌入模型
- **Ollama**：通过 Ollama 提供本地嵌入模型
- **Mistral**：Mistral AI 的嵌入模型
- **Jina**：Jina AI 的嵌入服务
- **HuggingFace**：来自 HuggingFace 的模型
- **GoogleAI**：Google 的嵌入模型
- **VoyageAI**：VoyageAI 的嵌入模型
嵌入提供商配置（点击展开）
### 环境变量 要配置嵌入提供商，请在您的 `.env` 文件中设置以下环境变量： ``` # 主要 embedding 配置 EMBEDDING_PROVIDER=openai # Provider type (openai, ollama, mistral, jina, huggingface, googleai, voyageai) EMBEDDING_MODEL=text-embedding-3-small # Model name to use EMBEDDING_URL= # Optional custom API endpoint EMBEDDING_KEY= # API key for the provider (if required) EMBEDDING_BATCH_SIZE=100 # Number of documents to process in a batch EMBEDDING_STRIP_NEW_LINES=true # Whether to remove new lines from text before embedding # 高级设置 PROXY_URL= # Optional proxy for all API calls HTTP_CLIENT_TIMEOUT=600 # Timeout in seconds for external API calls (default: 600, 0 = no timeout) # SSL/TLS 证书配置（用于与 LLM 后端和工具服务器的外部通信） EXTERNAL_SSL_CA_PATH= # Path to custom CA certificate file (PEM format) inside the container # Must point to /opt/pennull/ssl/ directory (e.g., /opt/pennull/ssl/ca-bundle.pem) EXTERNAL_SSL_INSECURE=false # Skip certificate verification (use only for testing) ```如何添加自定义 CA 证书（点击展开）
如果您看到此错误：`tls: failed to verify certificate: x509: certificate signed by unknown authority` **步骤 1：** 获取 PEM 格式的 CA 证书包（可包含多个证书） **步骤 2：** 将文件放在主机上的 SSL 目录中： ``` # 默认位置（如果未设置 PENNULL_SSL_DIR） cp ca-bundle.pem ./pennull-ssl/ # 或自定义位置（如果在 docker-compose.yml 中使用 PENNULL_SSL_DIR） cp ca-bundle.pem /path/to/your/ssl/dir/ ``` **步骤 3：** 在 `.env` 文件中设置路径（路径必须在容器内部）： ``` # 卷 pennull-ssl 挂载到容器内的 /opt/pennull/ssl EXTERNAL_SSL_CA_PATH=/opt/pennull/ssl/ca-bundle.pem EXTERNAL_SSL_INSECURE=false ``` **步骤 4：** 重启 penNULL： ``` docker compose restart pennull ``` **注意：** - `pennull-ssl` 卷挂载到容器内的 `/opt/pennull/ssl` - 您可以在 docker-compose.yml 中使用 `PENNULL_SSL_DIR` 变量更改主机目录 - 该文件支持在一个 PEM 文件中包含多个证书和中间 CA - 仅在测试时使用 `EXTERNAL_SSL_INSECURE=true`（不建议在生产环境中使用）etester 命令（点击展开）
``` # 测试 embedding provider 和数据库连接 cd backend go run cmd/etester/main.go test -verbose # 显示有关 embedding 数据库的统计信息 go run cmd/etester/main.go info # 删除 embedding 数据库中的所有文档（谨慎使用！） go run cmd/etester/main.go flush # 重新计算所有文档的 embeddings（在更改 provider 之后） go run cmd/etester/main.go reindex # 在 embedding 数据库中搜索文档 go run cmd/etester/main.go search -query "How to install PostgreSQL" -limit 5 ``` ### 使用 Docker 如果您在 Docker 中运行 penNULL，可以在容器内使用 etester： ``` # 测试 embedding provider docker exec -it pennull /opt/pennull/bin/etester test # 显示详细的数据库信息 docker exec -it pennull /opt/pennull/bin/etester info -verbose ``` ### 高级搜索选项 `search` 命令支持各种过滤器以缩小结果范围： ``` # 按文档类型筛选 docker exec -it pennull /opt/pennull/bin/etester search -query "Security vulnerability" -doc_type guide -threshold 0.8 # 按 flow ID 筛选 docker exec -it pennull /opt/pennull/bin/etester search -query "Code examples" -doc_type code -flow_id 42 # 所有可用的搜索选项 docker exec -it pennull /opt/pennull/bin/etester search -help ``` 可用的搜索参数： - `-query STRING`：搜索查询文本（必需） - `-doc_type STRING`：按文档类型过滤 (answer, memory, guide, code) - `-flow_id NUMBER`：按流 ID 过滤（正数） - `-answer_type STRING`：按答案类型过滤 (guide, vulnerability, code, tool, other) - `-guide_type STRING`：按指南类型过滤 (install, configure, use, pentest, development, other) - `-limit NUMBER`：最大结果数（默认：3） - `-threshold NUMBER`：相似度阈值（0.0-1.0，默认：0.7） ### 常见故障排除场景 1. **更改嵌入提供商后**：始终运行 `flush` 或 `reindex` 以确保一致性 2. **搜索结果不佳**：尝试调整相似度阈值或检查嵌入是否正确生成 3. **数据库连接问题**：验证 PostgreSQL 是否正在运行并已安装 pgvector 扩展 4. **缺少 API 密钥**：检查所选嵌入提供商的环境变量可用函数（点击展开）
### 环境函数 - **terminal**：在容器中执行命令并返回输出 - **file**：在容器中执行文件操作（读取、写入、列出） ### 搜索函数 - **browser**：访问网站并截取屏幕截图 - **google**：使用 Google 自定义搜索搜索网络 - **duckduckgo**：使用 DuckDuckGo 搜索网络 - **tavily**：使用 Tavily AI 搜索引擎进行搜索 - **traversaal**：使用 Traversaal AI 搜索引擎进行搜索 - **perplexity**：使用 Perplexity AI 进行搜索 - **sploitus**：搜索安全漏洞利用、漏洞 (CVE) 和渗透测试工具 - **searxng**：使用 Searxng 元搜索引擎进行搜索（聚合来自多个引擎的结果） ### 向量数据库函数 - **search_in_memory**：在向量数据库中搜索信息 - **search_guide**：在向量数据库中查找指导文档 - **search_answer**：在向量数据库中寻找问题的答案 - **search_code**：在向量数据库中查找代码示例 ### AI 代理函数 - **advice**：从 AI 代理获取专家建议 - **coder**：请求代码生成或修改 - **maintenance**：运行系统维护任务 - **memorist**：在向量数据库中存储和组织信息 - **pentester**：执行安全测试和漏洞分析 - **search**：跨多个来源的复杂搜索 ### 实用程序函数 - **describe**：显示有关流、任务和子任务的信息调试流上下文（点击展开）
`describe` 函数提供了有关流中任务和子任务的详细信息。当 penNULL 遇到问题或卡住时，这对于诊断问题特别有用。 ``` # 列出系统中的所有 flows go run cmd/ftester/main.go describe # 显示特定 flow 的所有 tasks 和 subtasks go run cmd/ftester/main.go -flow 123 describe # 显示特定 task 的详细信息 go run cmd/ftester/main.go -flow 123 -task 456 describe # 显示特定 subtask 的详细信息 go run cmd/ftester/main.go -flow 123 -task 456 -subtask 789 describe # 显示带有完整描述和结果的详细输出 go run cmd/ftester/main.go -flow 123 describe -verbose ``` 此函数允许您识别流可能卡住的确切位置，并通过直接调用相应的代理函数来恢复处理。函数帮助和发现（点击展开）
每个函数都有一个帮助模式，显示可用参数： ``` # 获取特定功能的帮助 go run cmd/ftester/main.go [function_name] -help # 示例： go run cmd/ftester/main.go terminal -help go run cmd/ftester/main.go browser -help go run cmd/ftester/main.go describe -help ``` 您也可以不带参数运行 ftester 以查看所有可用函数的列表： ``` go run cmd/ftester/main.go ```输出格式（点击展开）
`ftester` 实用程序使用彩色输出使解释更容易： - **蓝色标题**：章节标题和键名 - **青色 [INFO]**：一般信息消息 - **绿色 [SUCCESS]**：成功操作 - **红色 [ERROR]**：错误消息 - **黄色 [WARNING]**：警告消息 - **黄色 [MOCK]**：指示模拟模式操作 - **洋红色值**：函数参数和结果 JSON 和 Markdown 响应会自动格式化以提高可读性。高级使用场景（点击展开）
### 调试卡住的 AI 流 当 penNULL 在流中卡住时： 1. 通过 UI 暂停流 2. 使用 `describe` 识别当前任务和子任务 3. 使用相同的任务/子任务 ID 直接调用代理函数 4. 检查详细输出以识别问题 5. 根据需要恢复流或手动干预 ### 测试环境变量 验证 API 密钥和外部服务是否配置正确： ``` # 测试 Google 搜索 API 配置 go run cmd/ftester/main.go google -query "pentesting tools" # 测试对外部网站的浏览器访问 go run cmd/ftester/main.go browser -url "https://example.com" ``` ### 开发新的 AI 代理行为 在开发新的提示模板或代理行为时： 1. 在 UI 中创建测试流 2. 使用 ftester 使用不同的提示直接调用代理 3. 观察响应并相应地调整提示 4. 检查 Langfuse 以获取所有函数调用的详细跟踪 ### 验证 Docker 容器设置 确保容器配置正确： ``` go run cmd/ftester/main.go -flow 123 terminal -command "env | grep -i proxy" -message "Check proxy settings" ```Docker 容器使用（点击展开）
如果您在 Docker 中运行 penNULL，可以在容器内使用 ftester： ``` # 在运行中的 penNULL 容器内运行 ftester docker exec -it pennull /opt/pennull/bin/ftester [arguments] # 示例： docker exec -it pennull /opt/pennull/bin/ftester -flow 123 describe docker exec -it pennull /opt/pennull/bin/ftester -flow 123 terminal -command "ps aux" -message "List processes" ``` 这对于没有本地开发环境的生产部署特别有用。与可观测性工具集成（点击展开）
通过 ftester 进行的所有函数调用都会记录到： 1. **Langfuse**：捕获整个 AI 代理交互链，包括提示、响应和函数调用 2. **OpenTelemetry**：记录用于系统性能分析的指标、跟踪和日志 3. **终端输出**：提供有关函数执行的即时反馈 要访问详细日志： - 查看 Langfuse UI 以获取 AI 代理跟踪（通常位于 `http://localhost:4000`） - 使用 Grafana 仪表板查看系统指标（通常位于 `http://localhost:3000`） - 检查终端输出以获取即时的函数结果和错误标签：AI安全, Chat Copilot, CISA项目, DLL 劫持, Docker, EVTX分析, Go, GraphQL, LLM, NIDS, NullAI, PENNULL, PE 加载器, PostgreSQL, PyRIT, React, Red Teaming, Ruby工具, Syscalls, TGT, TypeScript, Unmanaged PE, 人工智能, 多智能体系统, 大语言模型, 安全大模型, 安全插件, 安全防御评估, 容器化, 密码管理, 恶意样本开发, 插件系统, 搜索引擎查询, 攻击模拟, 攻防演练, 日志审计, 沙箱, 测试用例, 用户代理, 用户模式Hook绕过, 网络安全, 网络安全审计, 自动化漏洞挖掘, 请求拦截, 隐私保护, 驱动签名利用