vxcontrol/pentagi
GitHub: vxcontrol/pentagi
PentAGI 是一款基于多智能体和知识图谱技术的全自主 AI 渗透测试系统，旨在通过自动化规划与执行复现复杂的攻击路径并生成报告。
Stars: 8842 | Forks: 991
# PentAGI
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 ```
PentAGI 的架构设计是模块化、可扩展且安全的。以下是关键组件：
1. **核心服务**
- Frontend UI：基于 React 的 Web 界面，使用 TypeScript 确保类型安全
- Backend API：基于 Go 的 REST 和 GraphQL API，具有 Bearer token 认证，用于程序化访问
- Vector Store：带有 pgvector 的 PostgreSQL，用于语义搜索和记忆存储
- Task Queue：异步任务处理系统，用于可靠操作
- AI Agent：具有专门角色的多智能体系统，用于高效测试
2. **知识图谱**
- Graphiti：知识图谱 API，用于语义关系跟踪和上下文理解
- Neo4j：图数据库，用于存储和查询实体、动作和结果之间的关系
- 自动捕获智能体响应和工具执行，以构建全面的知识库
3. **监控栈**
- OpenTelemetry：统一的可观测性数据收集和关联
- Grafana：实时可视化和告警仪表板
- VictoriaMetrics：高性能时间序列指标存储
- Jaeger：端到端分布式追踪，用于调试
- Loki：可扩展的日志聚合和分析
4. **分析平台**
- Langfuse：高级 LLM 可观测性和性能分析
- ClickHouse：列式分析数据仓库
- Redis：高速缓存和速率限制
- MinIO：兼容 S3 的对象存储，用于存储工件
5. **安全工具**
- Web Scraper：隔离的浏览器环境，用于安全的 Web 交互
- Pentesting Tools：包含 20 多种专业安全工具的全面套件
- Sandboxed Execution：所有操作均在隔离容器中运行
6. **记忆系统**
- 长期记忆：知识和经验的持久化存储
- 工作记忆：当前操作的活跃上下文和目标
- 情景记忆：历史动作和成功模式
- 知识库：结构化的领域专业知识和工具能力
- 上下文管理：使用链式摘要智能管理不断增长的 LLM 上下文窗口
系统使用 Docker 容器进行隔离和轻松部署，为核心服务、监控和分析设置独立的网络，以确保适当的安全边界。每个组件都设计为可水平扩展，并可在生产环境中配置为高可用性。
## 🚀 快速开始
### 系统要求
- Docker 和 Docker Compose (或 Podman - 参见 [Podman 配置](#running-pentagi-with-podman))
- 最低 2 vCPU
- 最低 4GB RAM
- 20GB 可用磁盘空间
- 互联网访问，用于下载镜像和更新
### 使用安装程序（推荐）
PentAGI 提供了一个带有基于终端 UI 的交互式安装程序，用于简化配置和部署。安装程序将引导您完成系统检查、LLM 提供商设置、搜索引擎配置和安全加固。
**支持的平台：**
- **Linux**: amd64 [下载](https://pentagi.com/downloads/linux/amd64/installer-latest.zip) | arm64 [下载](https://pentagi.com/downloads/linux/arm64/installer-latest.zip)
- **Windows**: amd64 [下载](https://pentagi.com/downloads/windows/amd64/installer-latest.zip)
- **macOS**: amd64 (Intel) [下载](https://pentagi.com/downloads/darwin/amd64/installer-latest.zip) | arm64 (M系列) [下载](https://pentagi.com/downloads/darwin/arm64/installer-latest.zip)
**快速安装 (Linux amd64):**
```
# 创建安装目录
mkdir -p pentagi && cd pentagi
# 下载安装程序
wget -O installer.zip https://pentagi.com/downloads/linux/amd64/installer-latest.zip
# 解压
unzip installer.zip
# 运行交互式安装程序
./installer
```
**先决条件与权限：**
安装程序需要适当的权限才能与 Docker API 交互以正常运行。默认情况下，它使用 Docker 套接字 (`/var/run/docker.sock`)，这需要：
- **选项 1 (生产环境推荐):** 以 root 身份运行安装程序：
sudo ./installer
- **选项 2 (开发环境):** 通过将用户添加到 `docker` 组来授予其对 Docker 套接字的访问权限：
# 将您的用户添加到 docker 组
sudo usermod -aG docker $USER
# 注销并重新登录，或立即激活该组
newgrp docker
# 验证 Docker 访问权限（应在不使用 sudo 的情况下运行）
docker ps
⚠️ **安全提示：** 将用户添加到 `docker` 组会授予等效于 root 的权限。请仅在受控环境中对受信任的用户执行此操作。对于生产部署，请考虑使用 rootless Docker 模式或使用 sudo 运行安装程序。
安装程序将：
1. **系统检查**：验证 Docker、网络连接和系统要求
2. **环境设置**：创建并配置具有最佳默认值的 `.env` 文件
3. **提供商配置**：设置 LLM 提供商
4. **搜索引擎**：配置 DuckDuckGo、Google、Tavily、Traversaal、Perplexity、Sploitus、Searx
5. **安全加固**：生成安全凭据并配置 SSL 证书
6. **部署**：使用 docker-compose 启动 PentAGI
**生产环境与增强安全性：**
对于生产部署或安全敏感环境，我们**强烈建议**使用分布式双节点架构，其中 Worker 操作在单独的服务器上隔离。这可以防止不受信任的代码执行和主系统上的网络访问问题。
👉 **查看详细指南**: [Worker 节点设置](examples/guides/worker_node.md)
双节点设置提供：
- **隔离执行**：Worker 容器在专用硬件上运行
- **网络隔离**：渗透测试的独立网络边界
- **安全边界**：具有 TLS 认证的 Docker-in-Docker
- **OOB 攻击支持**：用于带外技术的专用端口范围
### 手动安装
1. 创建工作目录或克隆仓库：
```
mkdir pentagi && cd pentagi
```
2. 将 `.env.example` 复制为 `.env` 或下载它：
```
curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example
```
3. 创建示例文件（`example.custom.provider.yml`、`example.ollama.provider.yml`）或下载它们：
```
curl -o example.custom.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/ollama-llama318b.provider.yml
```
4. 在 `.env` 文件中填写所需的 API 密钥。
```
# 必需：至少其中一个 LLM 提供商
OPEN_AI_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
# 可选：AWS Bedrock 提供商（企业级模型）
BEDROCK_REGION=us-east-1
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
# 可选：本地 LLM 提供商（零成本推理）
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=your_model_name
# 可选：额外搜索功能
DUCKDUCKGO_ENABLED=true
SPLOITUS_ENABLED=true
GOOGLE_API_KEY=your_google_key
GOOGLE_CX_KEY=your_google_cx
TAVILY_API_KEY=your_tavily_key
TRAVERSAAL_API_KEY=your_traversaal_key
PERPLEXITY_API_KEY=your_perplexity_key
PERPLEXITY_MODEL=sonar-pro
PERPLEXITY_CONTEXT_SIZE=medium
# Searxng 元搜索引擎（聚合多个来源的结果）
SEARXNG_URL=http://your-searxng-instance:8080
SEARXNG_CATEGORIES=general
SEARXNG_LANGUAGE=
SEARXNG_SAFESEARCH=0
SEARXNG_TIME_RANGE=
## Graphiti 知识图谱设置
GRAPHITI_ENABLED=true
GRAPHITI_TIMEOUT=30
GRAPHITI_URL=http://graphiti:8000
GRAPHITI_MODEL_NAME=gpt-5-mini
# Neo4j 设置（由 Graphiti stack 使用）
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687
# Assistant 配置
ASSISTANT_USE_AGENTS=false # Default value for agent usage when creating new assistants
```
5. 更改 `.env` 文件中所有与安全相关的环境变量以提高安全性。
6. 如果要在 VSCode 或其他 IDE 中将 `.env` 文件用作 envFile 选项，请删除其中的所有行内注释：
```
perl -i -pe 's/\s+#.*$//' .env
```
7. 运行 PentAGI 栈：
```
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml
docker compose up -d
```
访问 [localhost:8443](https://localhost:8443) 以进入 PentAGI Web UI (默认为 `admin@pentagi.com` / `admin`)
### 从外部网络访问 PentAGI
默认情况下，出于安全考虑，PentAGI 绑定到 `127.0.0.1` (仅 localhost)。要从网络上的其他机器访问 PentAGI，您需要配置外部访问。
#### 配置步骤
1. 使用服务器的 IP 地址**更新 `.env` 文件**：
```
# 网络绑定 - 允许外部连接
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443
# Public URL - 使用您的实际服务器 IP 或主机名
# 将 192.168.1.100 替换为您的服务器 IP 地址
PUBLIC_URL=https://192.168.1.100:8443
# CORS origins - 列出所有将访问 PentAGI 的 URL
# 包含 localhost 用于本地访问，以及您的服务器 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 pentagi
```
您应该看到 `0.0.0.0:8443->8443/tcp` 或 `:::8443->8443/tcp`。
如果您看到 `127.0.0.1:8443->8443/tcp`，说明环境变量未被拾取。在这种情况下，直接编辑 `docker-compose.yml` 第 31 行：
```
ports:
- "0.0.0.0:8443:8443"
```
然后再次重建容器。
4. **配置防火墙**以允许端口 8443 上的传入连接：
```
# Ubuntu/Debian 使用 UFW
sudo ufw allow 8443/tcp
sudo ufw reload
# CentOS/RHEL 使用 firewalld
sudo firewall-cmd --permanent --add-port=8443/tcp
sudo firewall-cmd --reload
```
5. **访问 PentAGI**：
- **本地访问**：`https://localhost:8443`
- **网络访问**：`https://your-server-ip:8443`
### 使用 Podman 运行 PentAGI
PentAGI 完全支持 Podman 作为 Docker 的替代品。但是，当在 **rootless 模式下使用 Podman** 时，scraper 服务需要特殊配置，因为 rootless 容器无法绑定特权端口（1024 以下的端口）。
#### Podman Rootless 配置
默认的 scraper 配置使用端口 443 (HTTPS)，这是一个特权端口。对于 Podman rootless，请重新配置 scraper 以使用非特权端口：
**1. 编辑 `docker-compose.yml`** - 修改 `scraper` 服务（约第 199 行）：
```
scraper:
image: vxcontrol/scraper:latest
restart: unless-stopped
container_name: scraper
hostname: scraper
expose:
- 3000/tcp # Changed from 443 to 3000
ports:
- "${SCRAPER_LISTEN_IP:-127.0.0.1}:${SCRAPER_LISTEN_PORT:-9443}:3000" # Map to port 3000
environment:
- MAX_CONCURRENT_SESSIONS=${LOCAL_SCRAPER_MAX_CONCURRENT_SESSIONS:-10}
- USERNAME=${LOCAL_SCRAPER_USERNAME:-someuser}
- PASSWORD=${LOCAL_SCRAPER_PASSWORD:-somepass}
logging:
options:
max-size: 50m
max-file: "7"
volumes:
- scraper-ssl:/usr/src/app/ssl
networks:
- pentagi-network
shm_size: 2g
```
**2. 更新 `.env` 文件** - 将 scraper URL 更改为使用 HTTP 和端口 3000：
```
# Podman rootless 的 Scraper 配置
SCRAPER_PRIVATE_URL=http://someuser:somepass@scraper:3000/
LOCAL_SCRAPER_USERNAME=someuser
LOCAL_SCRAPER_PASSWORD=somepass
```
**3. 重建容器**：
```
podman-compose down
podman-compose up -d --force-recreate
```
**4. 测试 scraper 连接**：
```
# 在 pentagi 容器内部进行测试
podman exec -it pentagi wget -O- "http://someuser:somepass@scraper:3000/html?url=http://example.com"
```
如果您看到 HTML 输出，说明 scraper 工作正常。
#### Podman Rootful 模式
如果您以 rootful 模式（使用 sudo）运行 Podman，则可以使用默认配置而无需修改。Scraper 将按预期在端口 443 上工作。
#### Docker 兼容性
所有 Podman 配置仍与 Docker 完全兼容。非特权端口方法在两个容器运行时上的工作方式相同。
### 助手配置
PentAGI 允许您配置助手的默认行为：
| Variable | Default | Description |
| ---------------------- | ------- | ----------------------------------------------------------------------- |
| `ASSISTANT_USE_AGENTS` | `false` | Controls the default value for agent usage when creating new assistants |
创建新助手时，`ASSISTANT_USE_AGENTS` 设置会影响 "Use Agents" 切换按钮的初始状态：
- `false` (默认)：默认情况下，新助手在创建时禁用智能体委托
- `true`：默认情况下，新助手在创建时启用智能体委托
请注意，用户在创建或编辑助手时，始终可以通过在 UI 中切换 "Use Agents" 按钮来覆盖此设置。此环境变量仅控制初始默认状态。
## 🔌 API 访问
PentAGI 通过 REST 和 GraphQL API 提供全面的程序化访问，允许您将渗透测试工作流集成到自动化流水线、CI/CD 流程和自定义应用程序中。
### 生成 API Token
API Token 通过 PentAGI Web 界面进行管理：
1. 在 Web UI 中导航至 **Settings** → **API Tokens**
2. 点击 **Create Token** 以生成新的 API Token
3. 配置 Token 属性：
- **Name** (可选)：Token 的描述性名称
- **Expiration Date**：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-pentagi-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-pentagi-instance:8443/api/v1/flows \
-H "Authorization: Bearer YOUR_API_TOKEN"
```
### API 探索与测试
PentAGI 提供交互式文档用于探索和测试 API 端点：
#### GraphQL Playground
访问 GraphQL Playground：`https://your-pentagi-instance:8443/api/v1/graphql/playground`
1. 点击底部的 **HTTP Headers** 标签页
2. 添加您的授权标头：
{
"Authorization": "Bearer YOUR_API_TOKEN"
}
3. 交互式探索 schema、运行查询和测试变更
#### Swagger UI
访问 REST API 文档：`https://your-pentagi-instance:8443/api/v1/swagger/index.html`
1. 点击 **Authorize** 按钮
2. 以以下格式输入您的 Token：`Bearer YOUR_API_TOKEN`
3. 点击 **Authorize** 以应用
4. 直接从 Swagger UI 测试端点
### 生成 API 客户端
您可以使用 PentAGI 附带的 schema 文件为您喜欢的编程语言生成类型安全的 API 客户端：
#### GraphQL 客户端
GraphQL schema 位于：
- **Web UI**：导航至 Settings 下载 `schema.graphqls`
- **Direct file**：仓库中的 `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-pentagi-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-pentagi-instance:8443/api/v1/swagger/doc.json \
-g python \
-o ./pentagi-client
- **Swagger Codegen**: [https://github.com/swagger-api/swagger-codegen](https://github.com/swagger-api/swagger-codegen)
swagger-codegen generate \
-i https://your-pentagi-instance:8443/api/v1/swagger/doc.json \
-l typescript-axios \
-o ./pentagi-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-pentagi-instance:8443/api/v1/swagger/doc.json \
-o ./src/api \
-n pentagi-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 PentAGIClient(
'https://your-pentagi-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 使用情况** - 在 Settings 页面查看 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（唯一标识符）
- 状态（active/revoked/expired）
- 创建日期
- 过期日期
### 自定义 LLM 提供商配置
当使用带有 `LLM_SERVER_*` 变量的自定义 LLM 提供商时，您可以微调请求中使用的推理格式：
| Variable | Default | Description |
| ------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `LLM_SERVER_URL` | | Base URL for the custom LLM API endpoint |
| `LLM_SERVER_KEY` | | API key for the custom LLM provider |
| `LLM_SERVER_MODEL` | | Default model to use (can be overridden in provider config) |
| `LLM_SERVER_CONFIG_PATH` | | Path to the YAML configuration file for agent-specific models |
| `LLM_SERVER_PROVIDER` | | Provider name prefix for model names (e.g., `openrouter`, `deepseek` for LiteLLM proxy) |
| `LLM_SERVER_LEGACY_REASONING` | `false` | Controls reasoning format in API requests |
| `LLM_SERVER_PRESERVE_REASONING` | `false` | Preserve reasoning content in multi-turn conversations (required by some providers) |
`LLM_SERVER_PROVIDER` 设置在使用 **LiteLLM proxy** 时特别有用，它会为模型名称添加提供商前缀。例如，当通过 LiteLLM 连接到 Moonshot API 时，像 `kimi-2.5` 这样的模型会变成 `moonshot/kimi-2.5`。通过设置 `LLM_SERVER_PROVIDER=moonshot`，您可以对直接 API 访问和 LiteLLM 代理访问使用相同的提供商配置文件，而无需修改。
`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" 的错误。如果您的提供商需要保留推理内容，请启用此设置。
### 本地 LLM 提供商配置
PentAGI 支持 Ollama 用于本地 LLM 推理，提供零成本操作和增强的隐私性：
| Variable | Default | Description |
| ----------------------------------- | --------------------------- | --------------------------------------- |
| `OLLAMA_SERVER_URL` | | URL of your Ollama server |
| `OLLAMA_SERVER_MODEL` | `llama3.1:8b-instruct-q8_0` | Default model for inference |
| `OLLAMA_SERVER_CONFIG_PATH` | | Path to custom agent configuration file |
| `OLLAMA_SERVER_PULL_MODELS_TIMEOUT` | `600` | Timeout for model downloads (seconds) |
| `OLLAMA_SERVER_PULL_MODELS_ENABLED` | `false` | Auto-download models on startup |
| `OLLAMA_SERVER_LOAD_MODELS_ENABLED` | `false` | Query server for available models |
配置示例：
```
# 使用默认模型的基本 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
# 带有特定 agent 模型的自定义配置
OLLAMA_SERVER_CONFIG_PATH=/path/to/ollama-config.yml
# Docker 容器内的默认配置文件
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
```
**性能注意事项：**
- **模型发现** (`OLLAMA_SERVER_LOAD_MODELS_ENABLED=true`)：查询 Ollama API 会增加 1-2 秒的启动延迟
- **自动拉取** (`OLLAMA_SERVER_PULL_MODELS_ENABLED=true`)：首次启动可能需要几分钟来下载模型
- **拉取超时** (`OLLAMA_SERVER_PULL_MODELS_TIMEOUT=900`)：15 分钟（以秒为单位）
- **静态配置**：禁用这两个标志并在配置文件中指定模型，以实现最快的启动
#### 创建具有扩展上下文的自定义 Ollama 模型
PentAGI 需要比默认 Ollama 配置具有更大上下文窗口的模型。您需要通过 Modelfile 创建具有增加的 `num_ctx` 参数的自定义模型。虽然典型的智能体工作流消耗约 64K token，但 PentAGI 使用 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/pentagi/conf/` 中包含的预构建提供商配置文件（`ollama-qwen332b-fp16-tc.provider.yml` 和 `ollama-qwq32b-fp16-tc.provider.yml`）中被引用。
### OpenAI 提供商配置
PentAGI 支持 OpenAI 的高级语言模型，包括专为复杂分析任务设计的最新推理能力 o 系列模型：
| Variable | Default | Description |
| -------------------- | --------------------------- | --------------------------- |
| `OPEN_AI_KEY` | | API key for OpenAI services |
| `OPEN_AI_SERVER_URL` | `https://api.openai.com/v1` | OpenAI API endpoint |
配置示例：
```
# 基本 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
```
OpenAI 提供商提供尖端功能，包括：
- **推理模型**：具有逐步分析思维的高级 o 系列模型 (o1, o3, o4-mini)
- **最新 GPT-4.1 系列**：为复杂的安全研究和漏洞利用开发优化的旗舰模型
- **具有成本效益的选项**：从用于大批量扫描的 nano 模型到用于深度分析的强大推理模型
- **多功能性能**：快速、智能的模型，非常适合多步骤安全分析和渗透测试
- **经过验证的可靠性**：行业领先的模型，在各种安全场景中具有一致的性能
系统会根据任务复杂性自动选择适当的 OpenAI 模型，从而优化性能和成本效益。
### Anthropic 提供商配置
PentAGI 与 Anthropic 的 Claude 模型集成，以其卓越的安全性、推理能力和对复杂安全上下文的复杂理解而闻名：
| Variable | Default | Description |
| ---------------------- | ------------------------------ | ------------------------------ |
| `ANTHROPIC_API_KEY` | | API key for Anthropic services |
| `ANTHROPIC_SERVER_URL` | `https://api.anthropic.com/v1` | Anthropic API endpoint |
配置示例：
```
# 基本 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
```
Anthropic 提供商提供卓越的功能，包括：
- **高级推理**：具有卓越推理能力的 Claude 4 系列，用于复杂的渗透测试
- **扩展思考**：Claude 3.7 具有逐步思考能力，用于有条不紊的安全研究
- **高速性能**：Claude 3.5 Haiku，用于极快的漏洞扫描和实时监控
- **全面分析**：Claude Sonnet 模型，用于复杂的安全分析和威胁搜寻
- **安全优先设计**：内置安全机制，确保负责任的安全测试实践
该系统利用 Claude 对安全上下文的高级理解，提供全面且负责任的渗透测试指导。
### Google AI (Gemini) 提供商配置
PentAGI 通过 Google AI API 支持 Google 的 Gemini 模型，提供最先进的推理能力和多模态功能：
| Variable | Default | Description |
| ------------------- | ------------------------------------------- | ------------------------------ |
| `GEMINI_API_KEY` | | API key for Google AI services |
| `GEMINI_SERVER_URL` | `https://generativelanguage.googleapis.com` | Google AI API endpoint |
配置示例：
```
# 基本 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
```
Gemini 提供商提供高级功能，包括：
- **思考能力**：具有逐步分析的高级推理模型 (Gemini 2.5 系列)
- **多模态支持**：文本和图像处理，用于全面的安全评估
- **大上下文窗口**：高达 2M token，用于分析大量代码库和文档
- **具有成本效益的选项**：从高性能 pro 模型到经济的 flash 变体
- **专注于安全的模型**：为渗透测试工作流优化的专用配置
系统会根据智能体需求自动选择适当的 Gemini 模型，平衡性能、功能和成本效益。
### AWS Bedrock 提供商配置
PentAGI 与 Amazon Bedrock 集成，提供来自领先 AI 公司（包括 Anthropic、AI21、Cohere、Meta 和 Amazon 自有模型）的广泛基础模型访问：
| Variable | Default | Description |
| --------------------------- | ----------- | ------------------------------------------------------- |
| `BEDROCK_REGION` | `us-east-1` | AWS region for Bedrock service |
| `BEDROCK_ACCESS_KEY_ID` | | AWS access key ID for authentication |
| `BEDROCK_SECRET_ACCESS_KEY` | | AWS secret access key for authentication |
| `BEDROCK_SESSION_TOKEN` | | AWS session token as alternative way for authentication |
| `BEDROCK_SERVER_URL` | | Optional custom Bedrock endpoint URL |
配置示例：
```
# 带有凭证的基本 AWS Bedrock 设置
BEDROCK_REGION=us-east-1
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
# 使用代理以增强安全性
BEDROCK_REGION=us-east-1
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
PROXY_URL=http://your-proxy:8080
# 使用自定义 endpoint（用于 VPC endpoints 或测试）
BEDROCK_REGION=us-east-1
BEDROCK_ACCESS_KEY_ID=your_aws_access_key
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key
BEDROCK_SERVER_URL=https://bedrock-runtime.us-east-1.amazonaws.com
```
AWS Bedrock 提供商提供全面的功能，包括：
- **多提供商访问**：通过单一接口访问来自 Anthropic (Claude)、AI21 (Jamba)、Cohere (Command)、Meta (Llama)、Amazon (Nova, Titan) 和 DeepSeek (R1) 的模型
- **高级推理**：支持 Claude 4 和其他具有逐步思考能力的推理模型
- **多模态模型**：支持文本、图像和视频处理的 Amazon Nova 系列，用于全面的安全分析
- **企业安全**：AWS 原生安全控制、VPC 集成和合规性认证
- **成本优化**：广泛的模型尺寸和功能范围，用于具有成本效益的渗透测试
- **区域可用性**：在您首选的 AWS 区域中部署模型，以实现数据驻留和性能
- **高性能**：通过 AWS 全球基础设施进行低延迟推理
系统根据任务复杂性和要求自动选择适当的 Bedrock 模型，利用全方位的可用基础模型以获得最佳安全测试结果。
有关高级配置选项和详细设置说明，请访问我们的 [文档](https://docs.pentagi.com)。
## 🔧 高级设置
### Langfuse 集成
Langfuse 为监控和分析 AI 智能体操作提供高级功能。
1. 在现有的 `.env` 文件中配置 Langfuse 环境变量。
2. 在 `.env` 文件中启用 PentAGI 服务的 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/vxcontrol/pentagi/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` 文件中启用 PentAGI 的 OpenTelemetry 和所有可观测性服务的集成。
```
OTEL_HOST=otelcol:8148
```
2. 运行可观测性栈：
```
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/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。
### 知识图谱集成
PentAGI 与 [Graphiti](https://github.com/vxcontrol/pentagi-graphiti) 集成，这是一个由 Neo4j 支持的时间知识图谱系统，可为 AI 智能体操作提供高级语义理解和关系跟踪。vxcontrol fork 提供了专用于渗透测试目的的自定义实体和边缘类型。
#### 什么是 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 stack 使用）
NEO4J_USER=neo4j
NEO4J_DATABASE=neo4j
NEO4J_PASSWORD=devpassword
NEO4J_URI=bolt://neo4j:7687
# OpenAI API key（Graphiti 实体提取所需）
OPEN_AI_KEY=your_openai_api_key
```
2. 与主 PentAGI 服务一起运行 Graphiti 栈：
```
# 如果需要，下载 Graphiti compose 文件
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose-graphiti.yml
# 启动带有 Graphiti 的 PentAGI
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 文档
```
#### 存储内容
启用后，PentAGI 会自动捕获：
- **智能体响应**：所有智能体推理、分析和决策
- **工具执行**：执行的命令、使用的工具及其结果
- **上下文信息**：Flow、Task 和 Subtask 层次结构
### 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 镜像配置
PentAGI 允许您配置用于执行各种任务的 Docker 镜像选择。系统会根据任务类型自动选择最合适的镜像，但您可以通过指定您喜欢的镜像来限制此选择：
| Variable | Default | Description |
| ---------------------------------- | ---------------------- | ----------------------------------------------------------- |
| `DOCKER_DEFAULT_IMAGE` | `debian:latest` | Default Docker image for general tasks and ambiguous cases |
| `DOCKER_DEFAULT_IMAGE_FOR_PENTEST` | `vxcontrol/kali-linux` | Default Docker image for security/penetration testing tasks |
设置这些环境变量后，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/pentagi
```
之前通过
```
go install github.com/swaggo/swag/cmd/swag@v1.8.7
```
安装 `swag` 包。
要生成 graphql resolver 文件，必须运行
```
go run github.com/99designs/gqlgen --config ./gqlgen/gqlgen.yml
```
之后您可以在 `pkg/graph` 文件夹中看到生成的文件。
要从 sqlc 配置生成 ORM 方法（数据库包）
```
docker run --rm -v $(pwd):/src -w /src --network pentagi-network -e DATABASE_URL="{URL}" sqlc/sqlc 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/pentagidb?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`）
- `VITE_USE_HTTPS` - 为服务器启用 SSL（默认：`false`）
- `VITE_PORT` - 运行服务器的端口（默认：`8000`）
- `VITE_HOST` - 运行服务器的主机（默认：`0.0.0.0`）
### 运行应用程序
#### 后端
在 `backend` 文件夹中运行命令：
- 使用 `.env` 文件设置环境变量，例如 `source .env`
- 运行 `go run cmd/pentagi/main.go` 以启动服务器
#### 前端
在 `frontend` 文件夹中运行命令：
- 运行 `npm install` 以安装依赖项
- 运行 `npm run dev` 以运行 Web 应用程序
- 运行 `npm run build` 以构建 Web 应用程序
打开浏览器并访问 Web 应用程序 URL。
## 🧪 测试 LLM 智能体
PentAGI 包含一个名为 `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/pentagi/.env vxcontrol/pentagi /opt/pentagi/bin/ctester -verbose
# 使用您的自定义 provider 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
-v $(pwd)/my-config.yml:/opt/pentagi/config.yml \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/config.yml -agents simple,primary_agent,coder -verbose
# 生成详细报告
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
-v $(pwd):/opt/pentagi/output \
vxcontrol/pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/output/report.md
```
#### 使用预配置的提供商
Docker 镜像内置了对主要提供商的支持，并包含针对其他服务的预配置提供商文件：
```
# 使用 OpenRouter 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/openrouter.provider.yml
# 使用 DeepInfra 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepinfra.provider.yml
# 使用 DeepSeek 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/deepseek.provider.yml
# 使用 Moonshot 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/moonshot.provider.yml
# 使用 OpenAI 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -type openai
# 使用 Anthropic 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -type anthropic
# 使用 Gemini 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -type gemini
# 使用 AWS Bedrock 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -type bedrock
# 使用自定义 OpenAI 配置进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml
# 使用 Ollama 配置（本地推理）进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-llama318b.provider.yml
# 使用 Ollama Qwen3 32B 配置（需要创建自定义模型）进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/ollama-qwen332b-fp16-tc.provider.yml
# 使用 Ollama QwQ 32B 配置（需要创建自定义模型和 71.3GB VRAM）进行测试
docker run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/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.deepseek.com or https://api.openai.com/v1 or https://api.moonshot.ai/v1
LLM_SERVER_KEY=your_api_key
LLM_SERVER_MODEL= # Leave empty, as models are specified in the config
LLM_SERVER_CONFIG_PATH=/opt/pentagi/conf/openrouter.provider.yml # or deepinfra.provider.yml or deepseek.provider.yml or custom-openai.provider.yml or moonshot.provider.yml
LLM_SERVER_PROVIDER= # Provider name for LiteLLM proxy (e.g., openrouter, deepseek, moonshot)
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
BEDROCK_ACCESS_KEY_ID=your_aws_access_key # AWS access key ID
BEDROCK_SECRET_ACCESS_KEY=your_aws_secret_key # AWS secret access key
BEDROCK_SESSION_TOKEN=your_aws_session_token # AWS session token (alternative auth method)
BEDROCK_SERVER_URL= # Optional custom Bedrock endpoint
# 对于 Ollama（本地推理）
OLLAMA_SERVER_URL=http://localhost:11434
OLLAMA_SERVER_MODEL=llama3.1:8b-instruct-q8_0
OLLAMA_SERVER_CONFIG_PATH=/opt/pentagi/conf/ollama-llama318b.provider.yml
OLLAMA_SERVER_PULL_MODELS_ENABLED=false
OLLAMA_SERVER_LOAD_MODELS_ENABLED=false
```
#### 使用未验证组织的 OpenAI
对于有权访问最新推理模型（o1、o3、o4-mini）的未验证组织的 OpenAI 帐户，您需要使用自定义配置。
要将 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/pentagi/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 run --rm \
-v $(pwd)/.env:/opt/pentagi/.env \
vxcontrol/pentagi /opt/pentagi/bin/ctester -config /opt/pentagi/conf/custom-openai.provider.yml
```
#### 使用 LiteLLM Proxy
当使用 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/pentagi/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/pentagi/conf/moonshot.provider.yml
LLM_SERVER_PROVIDER=moonshot # Provider prefix for LiteLLM
```
使用 `LLM_SERVER_PROVIDER=moonshot`，系统会自动为配置文件中的所有模型名称添加 `moonshot/` 前缀，使其与 LiteLLM 的模型命名约定兼容。
**LiteLLM 支持的提供商名称：**
- `openai` - 通过 LiteLLM 访问 OpenAI 模型
- `anthropic` - 通过 LiteLLM 访问 Anthropic/Claude 模型
- `gemini` - 通过 LiteLLM 访问 Google Gemini 模型
- `openrouter` - 用于 OpenRouter 聚合器
- `deepseek` - 用于 DeepSeek 模型
- `deepinfra` - 用于 DeepInfra 托管
- `moonshot` - 用于 Moonshot AI (Kimi)
- 您的 LiteLLM 实例中配置的任何其他提供商名称
这种方法允许您：
- 对直接和代理访问使用相同的配置文件
- 在不修改配置文件的情况下在提供商之间切换
- 轻松使用 LiteLLM 测试不同的路由策略
#### 在生产环境中运行测试
如果您已经有一个正在运行的 PentAGI 容器并想测试当前配置：
```
# 使用当前环境变量在现有容器中运行 ctester
docker exec -it pentagi /opt/pentagi/bin/ctester -verbose
# 以确定性顺序测试特定 agent 类型
docker exec -it pentagi /opt/pentagi/bin/ctester -agents simple,primary_agent,pentester -groups basic,knowledge -verbose
# 在容器内生成报告文件
docker exec -it pentagi /opt/pentagi/bin/ctester -report /opt/pentagi/data/agent-test-report.md
# 从主机访问报告
docker cp pentagi:/opt/pentagi/data/agent-test-report.md ./
```
### 命令行选项
该实用程序接受几个选项：
- `-env ` - 环境文件的路径（默认：`.env`）
- `-type ` - 提供商类型：`custom`、`openai`、`anthropic`、`ollama`、`bedrock`、`gemini`（默认：`custom`）
- `-config ` - 自定义提供商配置的路径（默认：来自 `LLM_SERVER_CONFIG_PATH` 环境变量）
- `-tests ` - 自定义测试 YAML 文件的路径（可选）
- `-report ` - 写入报告文件的路径（可选）
- `-agents
Penetration testing Artificial General Intelligence
[](https://discord.gg/2xrMh7qX6m)⠀[](https://t.me/+Ka9i6CNwe71hMWQy)
## 📖 目录
- [概述](#-overview)
- [功能特性](#-features)
- [快速开始](#-quick-start)
- [API 访问](#-api-access)
- [高级设置](#-advanced-setup)
- [开发](#-development)
- [测试 LLM 智能体](#-testing-llm-agents)
- [Embedding 配置与测试](#-embedding-configuration-and-testing)
- [使用 ftester 进行功能测试](#-function-testing-with-ftester)
- [构建](#%EF%B8%8F-building)
- [致谢](#-credits)
- [许可证](#-license)
## 🎯 概述
PentAGI 是一款利用尖端人工智能技术的创新性自动化安全测试工具。该项目专为信息安全专业人员、研究人员和爱好者设计，提供了一个强大且灵活的渗透测试解决方案。
您可以观看 **PentAGI 概述** 视频：
[](https://youtu.be/R70x5Ddzs1o)
## ✨ 功能特性
- 🛡️ 安全隔离。所有操作均在完全隔离的沙箱化 Docker 环境中执行。
- 🤖 完全自主。由 AI 驱动的智能体，自动确定并执行渗透测试步骤。
- 🔬 专业渗透测试工具。内置 20 多种专业安全工具套件，包括 nmap、metasploit、sqlmap 等。
- 🧠 智能记忆系统。长期存储研究成果和成功方法，以供将来使用。
- 📚 知识图谱集成。基于 Graphiti 的知识图谱，使用 Neo4j 进行语义关系跟踪和高级上下文理解。
- 🔍 Web 智能。通过 [scraper](https://hub.docker.com/r/vxcontrol/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 智能体负责研究、开发和基础设施任务。
- 📊 全面监控。详细的日志记录，并与 Grafana/Prometheus 集成，实现实时系统观测。
- 📝 详细报告。生成包含漏洞利用指南的详尽漏洞报告。
- 📦 智能容器管理。根据特定任务要求自动选择 Docker 镜像。
- 📱 现代界面。简洁直观的 Web UI，用于系统管理和监控。
- 🔌 全面的 API。具有 Bearer token 认证的全功能 REST 和 GraphQL API，便于自动化和集成。
- 💾 持久化存储。所有命令和输出均存储在带有 [pgvector](https://hub.docker.com/r/vxcontrol/pgvector) 扩展的 PostgreSQL 中。
- 🎯 可扩展架构。基于微服务的设计，支持水平扩展。
- 🏠 自托管解决方案。完全控制您的部署和数据。
- 🔑 灵活认证。支持各种 LLM 提供商（[OpenAI](https://platform.openai.com/)、[Anthropic](https://www.anthropic.com/)、[Ollama](https://ollama.com/)、[AWS Bedrock](https://aws.amazon.com/bedrock/)、[Google AI/Gemini](https://ai.google.dev/)、[Deep Infra](https://deepinfra.com/)、[OpenRouter](https://openrouter.ai/)、[DeepSeek](https://www.deepseek.com/en)）、[Moonshot](https://platform.moonshot.ai/)）及自定义配置。
- 🔐 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)"]
pentagi["✨ PentAGI
(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| pentagi
pentester --> |Monitors AI HTTPS| langfuse
pentester --> |Monitors System HTTPS| grafana
pentagi --> |Tests Various protocols| target
pentagi --> |Queries HTTPS| llm
pentagi --> |Searches HTTPS| search
pentagi --> |Reports HTTPS| langfuse
pentagi --> |Reports HTTPS| grafana
class pentester person
class pentagi 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 } ```🤖 智能体交互 (点击展开)
``` 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 ``` 该算法基于对话链的结构化表示 运行，该结构保留了消息类型，包括工具调用及其响应。所有摘要操作在减少上下文大小的同时，都保持了关键的对话流程。 ### 全局摘要器配置选项 | 参数 | 环境变量 | 默认值 | 描述 | | ---------------------- | --------------------------------- | ------ | ---------------------------------------------- | | Preserve Last | `SUMMARIZER_PRESERVE_LAST` | `true` | 是否保留最后部分中的所有消息 | | Use QA Pairs | `SUMMARIZER_USE_QA` | `true` | 是否使用 QA 对摘要策略 | | Summarize Human in QA | `SUMMARIZER_SUM_MSG_HUMAN_IN_QA` | `false`| 是否摘要 QA 对中的人类消息 | | Last Section Size | `SUMMARIZER_LAST_SEC_BYTES` | `51200`| 最后部分的最大字节数 (50KB) | | Max Body Pair Size | `SUMMARIZER_MAX_BP_BYTES` | `16384`| 单个主体对的最大字节数 (16KB) | | Max QA Sections | `SUMMARIZER_MAX_QA_SECTIONS` | `10` | 保留的最大 QA 对部分数 | | Max QA Size | `SUMMARIZER_MAX_QA_BYTES` | `65536`| QA 对部分的最大字节数 (64KB) | | Keep QA Sections | `SUMMARIZER_KEEP_QA_SECTIONS` | `1` | 不进行摘要的最近 QA 部分数量 | ### 助手摘要器配置选项 助手实例可以使用自定义摘要设置来微调上下文管理行为： | Parameter | Environment Variable | Default | Description | | ------------------ | --------------------------------------- | ------- | -------------------------------------------------------------------- | | Preserve Last | `ASSISTANT_SUMMARIZER_PRESERVE_LAST` | `true` | Whether to preserve all messages in the assistant's last section | | Last Section Size | `ASSISTANT_SUMMARIZER_LAST_SEC_BYTES` | `76800` | Maximum byte size for assistant's last section (75KB) | | Max Body Pair Size | `ASSISTANT_SUMMARIZER_MAX_BP_BYTES` | `16384` | Maximum byte size for a single body pair in assistant context (16KB) | | Max QA Sections | `ASSISTANT_SUMMARIZER_MAX_QA_SECTIONS` | `7` | Maximum QA sections to preserve in assistant context | | Max QA Size | `ASSISTANT_SUMMARIZER_MAX_QA_BYTES` | `76800` | Maximum byte size for assistant's QA sections (75KB) | | Keep QA Sections | `ASSISTANT_SUMMARIZER_KEEP_QA_SECTIONS` | `3` | Number of recent QA sections to preserve without summarization | 与全局设置相比，助手摘要器配置提供了更多的上下文保留内存，保留了更多最近的对话历史，同时仍确保高效的 token 使用。 ### 摘要器环境配置 ``` # 全局 summarizer 逻辑的默认值 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 逻辑的默认值 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 ```安全相关的环境变量
### 主要安全设置 - `COOKIE_SIGNING_SALT` - Cookie 签名盐，更改为随机值 - `PUBLIC_URL` - 服务器的公共 URL (例如 `https://pentagi.example.com`) - `SERVER_SSL_CRT` 和 `SERVER_SSL_KEY` - 现有 SSL 证书和密钥的自定义路径，用于 HTTPS (这些路径应在 docker-compose.yml 文件中用作挂载卷) ### Scraper 访问 - `SCRAPER_PUBLIC_URL` - 如果要使用不同的 scraper 服务器处理公共 URL，则为 Scraper 的公共 URL - `SCRAPER_PRIVATE_URL` - Scraper 的私有 URL (docker-compose.yml 文件中的本地 scraper 服务器，用于访问本地 URL) ### 访问凭据 - `PENTAGI_POSTGRES_USER` 和 `PENTAGI_POSTGRES_PASSWORD` - PostgreSQL 凭据 - `NEO4J_USER` 和 `NEO4J_PASSWORD` - Neo4j 凭据 (用于 Graphiti 知识图谱)创建新 Flow (GraphQL)
``` mutation CreateFlow { createFlow( modelProvider: "openai" input: "Test the security of https://example.com" ) { id title status createdAt } } ```列出 Flows (REST API)
``` curl https://your-pentagi-instance:8443/api/v1/flows \ -H "Authorization: Bearer YOUR_API_TOKEN" \ | jq '.flows[] | {id, title, status}' ```Python 客户端示例
``` import requests class PentAGIClient: 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 = PentAGIClient( "https://your-pentagi-instance:8443", "your_api_token_here" ) # 创建新的 flow flow = client.create_flow("openai", "Scan https://example.com for vulnerabilities") print(f"Created flow: {flow}") # 列出所有 flow 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 PentAGIClient { 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 密钥和 Token - `LANGFUSE_INIT_PROJECT_PUBLIC_KEY` - 项目公共密钥（也从 PentAGI 侧使用） - `LANGFUSE_INIT_PROJECT_SECRET_KEY` - 项目秘密密钥（也从 PentAGI 侧使用） ### 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. **分析特定于智能体的性能**：查看确定性的智能体顺序以识别表现不佳的智能体
- 使用提供商特定的配置为每种智能体类型试验不同的模型
4. **关注领域知识**：特别关注网络安全专业知识的知识组测试
5. **验证函数调用**：确保关键智能体类型的基于工具的测试一致通过
6. **比较结果**：在所有测试组中寻找最佳成功率和性能
7. **部署最佳配置**：在具有优化设置的生产环境中使用
此工具有助于确保您的 AI 智能体为其特定任务使用最有效的模型，在优化成本的同时提高可靠性。
## 🧮 Embedding 配置和测试
PentAGI 使用向量 Embedding 进行语义搜索、知识存储和记忆管理。系统支持多种 Embedding 提供商，可以根据您的需求和偏好进行配置。
### 支持的 Embedding 提供商
PentAGI 支持以下 Embedding 提供商：
- **OpenAI** (默认)：使用 OpenAI 的文本 Embedding 模型
- **Ollama**：通过 Ollama 的本地 Embedding 模型
- **Mistral**：Mistral AI 的 Embedding 模型
- **Jina**：Jina AI 的 Embedding 服务
- **HuggingFace**：来自 HuggingFace 的模型
- **GoogleAI**：Google 的 Embedding 模型
- **VoyageAI**：VoyageAI 的 Embedding 模型
Embedding 提供商配置 (点击展开)
### 环境变量 要配置 Embedding 提供商，请在 `.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 # SSL/TLS 证书配置（用于与 LLM 后端和工具服务器的外部通信） EXTERNAL_SSL_CA_PATH= # Path to custom CA certificate file (PEM format) inside the container # Must point to /opt/pentagi/ssl/ directory (e.g., /opt/pentagi/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 目录中： ``` # 默认位置（如果未设置 PENTAGI_SSL_DIR） cp ca-bundle.pem ./pentagi-ssl/ # 或自定义位置（如果在 docker-compose.yml 中使用 PENTAGI_SSL_DIR） cp ca-bundle.pem /path/to/your/ssl/dir/ ``` **步骤 3：** 在 `.env` 文件中设置路径（路径必须在容器内）： ``` # 卷 pentagi-ssl 挂载到容器内的 /opt/pentagi/ssl EXTERNAL_SSL_CA_PATH=/opt/pentagi/ssl/ca-bundle.pem EXTERNAL_SSL_INSECURE=false ``` **步骤 4：** 重启 PentAGI： ``` docker compose restart pentagi ``` **注意：** - `pentagi-ssl` 卷挂载到容器内的 `/opt/pentagi/ssl` - 您可以使用 docker-compose.yml 中的 `PENTAGI_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 中运行 PentAGI，则可以在容器内使用 etester： ``` # 测试 embedding provider docker exec -it pentagi /opt/pentagi/bin/etester test # 显示详细的数据库信息 docker exec -it pentagi /opt/pentagi/bin/etester info -verbose ``` ### 高级搜索选项 `search` 命令支持各种过滤器以缩小结果范围： ``` # 按文档类型筛选 docker exec -it pentagi /opt/pentagi/bin/etester search -query "Security vulnerability" -doc_type guide -threshold 0.8 # 按 flow ID 筛选 docker exec -it pentagi /opt/pentagi/bin/etester search -query "Code examples" -doc_type code -flow_id 42 # 所有可用的搜索选项 docker exec -it pentagi /opt/pentagi/bin/etester search -help ``` 可用的搜索参数： - `-query STRING`：搜索查询文本（必需） - `-doc_type STRING`：按文档类型过滤 - `-flow_id NUMBER`：按 Flow ID 过滤（正数） - `-answer_type STRING`：按答案类型过滤 - `-guide_type STRING`：按指南类型过滤 - `-limit NUMBER`：最大结果数（默认：3） - `-threshold NUMBER`：相似度阈值（0.0-1.0，默认：0.7） ### 常见故障排除场景 1. **更改 Embedding 提供商后**：始终运行 `flush` 或 `reindex` 以确保一致性 2. **搜索结果不佳**：尝试调整相似度阈值或检查 Embedding 是否正确生成 3. **数据库连接问题**：验证 PostgreSQL 是否正在运行并安装了 pgvector 扩展 4. **缺少 API 密钥**：检查您选择的 Embedding 提供商的环境变量可用的函数 (点击展开)
### 环境函数 - **terminal**：在容器中执行命令并返回输出 - **file**：在容器中执行文件操作（读取、写入、列出） ### 搜索函数 - **browser**：访问网站并截取屏幕截图 - **google**：使用 Google Custom Search 搜索网络 - **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**：显示关于 Flow、Task 和 Subtask 的信息调试 Flow 上下文 (点击展开)
`describe` 函数提供有关 Flow 中 Task 和 Subtask 的详细信息。这对于在 PentAGI 遇到问题或卡住时诊断问题特别有用。 ``` # 列出系统中的所有 flow go run cmd/ftester/main.go describe # 显示特定 flow 的所有 task 和 subtask 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 ``` 此函数允许您识别 Flow 可能卡住的确切点，并通过直接调用适当的智能体函数来恢复处理。函数帮助和发现 (点击展开)
每个函数都有一个帮助模式，显示可用的参数： ``` # 获取特定函数的帮助 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]**：指示 Mock 模式操作 - **洋红色值**：函数参数和结果 JSON 和 Markdown 响应会自动格式化以提高可读性。高级使用场景 (点击展开)
### 调试卡住的 AI Flow 当 PentAGI 在 Flow 中卡住时： 1. 通过 UI 暂停 Flow 2. 使用 `describe` 识别当前的 Task 和 Subtask 3. 使用相同的 task/subtask ID 直接调用智能体函数 4. 检查详细输出以识别问题 5. 根据需要恢复 Flow 或手动干预 ### 测试环境变量 验证 API 密钥和外部服务配置是否正确： ``` # 测试 Google search API 配置 go run cmd/ftester/main.go google -query "pentesting tools" # 测试对外部网站的 browser 访问 go run cmd/ftester/main.go browser -url "https://example.com" ``` ### 开发新的 AI 智能体行为 开发新的提示模板或智能体行为时： 1. 在 UI 中创建测试 Flow 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 中运行 PentAGI，则可以在容器内使用 ftester： ``` # 在运行中的 PentAGI 容器内运行 ftester docker exec -it pentagi /opt/pentagi/bin/ftester [arguments] # 示例： docker exec -it pentagi /opt/pentagi/bin/ftester -flow 123 describe docker exec -it pentagi /opt/pentagi/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`） - 检查终端输出以获取即时函数结果和错误标签：AGI, CISA项目, Cybersecurity, DLL 劫持, Docker容器, EVTX分析, EVTX分析, LLM智能体, Penetration Testing, PE 加载器, Python, Red Teaming, 人工智能, 大语言模型, 密码管理, 恶意样本开发, 插件系统, 攻击面发现, 攻防模拟, 无后门, 日志审计, 测试用例, 用户模式Hook绕过, 网络安全, 自主代理, 自动化攻防, 请求拦截, 防御绕过, 隐私保护