CEREBRO-RED v2（研究版）

自主本地 LLM 红队测试套件

一个用于使用 Agentic Fuzzing 和自适应对抗变异（AAM）自动化发现本地 LLM 漏洞的研究级框架。

研究目标

• 实现 PAIR 算法（提示自动迭代精炼），参考 arxiv.org/abs/2310.08419
• LLM作为评委的语义评估，附带思维链推理
• 遥测优先架构，用于白皮书级分析
• 多提供商 LLM 支持（Ollama、Azure OpenAI、OpenAI）

架构

技术栈

• 后端：FastAPI（async/await）、Pydantic（严格类型）、Uvicorn
• LLM 网关：litellm（适用于 Ollama/Azure/OpenAI 的通用适配器）
• 数据库：SQLite（实验）+ JSONL（审计日志）
• 前端：React + Vite + TailwindCSS + ShadcnUI + Recharts
• 容器：Docker + Docker Compose

系统架构展示主要组件和数据流

核心模块

1. 编排器 (backend/core/engine.py)：异步批量处理，带指数退避策略
2. 变异器 (backend/core/mutator.py)：PAIR 算法，包含变异策略
3. 裁判 (backend/core/judge.py)：LLM作为评委，带 CoT 评估
4. 遥测 (backend/core/telemetry.py)：线程安全的 JSONL 审计日志记录器

前端仪表板

基于 React 的前端提供了用于管理实验、监控进度和分析结果的综合界面。

主仪表板界面，展示实验概览和统计数据

实验管理视图，实时状态更新和实验列表

完整的用户界面概览，展示所有可用功能

实验结果与分析

结果视图，展示实验输出、漏洞发现和详细分析

设置与配置面板，用于自定义实验参数

实时监控

实时监控仪表板，带有实验进度和状态指示器

遥测视图，展示详细审计日志、系统事件和性能指标

详细日志视图，具有过滤和搜索功能

性能指标和统计仪表板

系统状态概览，展示健康检查和组件状态

API 文档

交互式 API 文档界面，带端点浏览器

有关详细架构文档，请参见 docs/ARCHITECTURE.md。

快速开始

先决条件

• Docker 24.0+
• Docker Compose 2.20+
• 主机上运行的 Ollama（或 Azure/OpenAI API 密钥）

Docker 设置

如果 Docker 未运行，请启动 Docker 守护进程：```bash

Start Docker daemon

sudo systemctl start docker

Enable Docker to start on boot

sudo systemctl enable docker

Add your user to the docker group (to run Docker without sudo)

sudo usermod -aG docker $USER

Apply group changes (logout/login or use newgrp)

newgrp docker

OR logout and login again for changes to take effect

**验证Docker是否正在运行**：```bash
docker --version
docker compose version

安装

1. 克隆仓库： ```bash git clone https://github.com/Leviticus-Triage/cerebro-red-v2.git cd cerebro-red-v2

2. 配置环境: ```bash cp .env.example .env

   Edit .env with your LLM provider credentials

3. 重要：检查 Port 8000 ```bash

   Falls Port 8000 belegt ist:

   lsof -i :8000 # Finde Prozess

   Oder ändere Port in .env: CEREBRO_PORT=8001

4. 启动后端 (重要 - 必须运行！): ```bash

   Option 1: Automatisch (empfohlen)

   ./START_BACKEND.sh

   Option 2: Docker

   docker compose up -d cerebro-backend

   Option 3: Lokal

   cd backend uvicorn main:app --reload --port 9000

5. 检查后端状态： ```bash curl http://localhost:9000/health

   Sollte {"status": "healthy", ...} zurückgeben

6. 执行快速测试： ```bash ./QUICK_TEST_EXAMPLES.sh

7. 访问仪表盘：

   • 后端API：http://localhost:9000
   • 前端UI：http://localhost:3000 (可选：docker compose up -d cerebro-frontend)
   • API文档：http://localhost:9000/docs

   

   前端用户界面，展示实验管理与监控

---

快速开始：本地与云端部署

本地部署（Ollama）

最适合：隐私优先的测试、无API费用、离线操作。```bash

1. Install and start Ollama

curl -fsSL https://ollama.ai/install.sh | sh ollama pull llama3.2:3b ollama serve

2. Configure .env for local

cat > .env << 'EOF' TARGET_MODEL=ollama/llama3.2:3b ATTACKER_MODEL=ollama/llama3.2:3b JUDGE_MODEL=ollama/llama3.2:3b OLLAMA_BASE_URL=http://host.docker.internal:11434

Relaxed circuit breaker for local (slower responses)

CIRCUIT_BREAKER_FAILURE_THRESHOLD=15 CIRCUIT_BREAKER_TIMEOUT=120 CIRCUIT_BREAKER_JITTER_ENABLED=true EOF

3. Start services

docker compose up -d

4. Verify

curl http://localhost:9000/health | jq

### 云部署（OpenAI）

最佳适用场景：更快的响应速度、更高质量的变异、生产环境测试。```bash
# 1. Configure .env for cloud
cat > .env << 'EOF'
TARGET_MODEL=openai/gpt-4o-mini
ATTACKER_MODEL=openai/gpt-4o-mini
JUDGE_MODEL=openai/gpt-4o-mini
OPENAI_API_KEY=sk-your-key-here

# Standard circuit breaker for cloud
CIRCUIT_BREAKER_FAILURE_THRESHOLD=10
CIRCUIT_BREAKER_TIMEOUT=60
CIRCUIT_BREAKER_JITTER_ENABLED=true
EOF

# 2. Start services
docker compose up -d

# 3. Verify
curl http://localhost:9000/health | jq

混合部署（多提供商）

最佳适用于：成本优化（廉价目标，优质攻击者/评判者）。```bash

Configure .env for hybrid

cat > .env << 'EOF'

Target on local Ollama (cheap, many requests)

TARGET_MODEL=ollama/llama3.2:3b OLLAMA_BASE_URL=http://host.docker.internal:11434

Attacker and Judge on OpenAI (quality matters)

ATTACKER_MODEL=openai/gpt-4o-mini JUDGE_MODEL=openai/gpt-4o-mini OPENAI_API_KEY=sk-your-key-here

Balanced circuit breaker

CIRCUIT_BREAKER_FAILURE_THRESHOLD=12 CIRCUIT_BREAKER_TIMEOUT=90 EOF

---

##  详细程度级别

控制实时日志和代码流跟踪中的详细信息量。

| 级别 | 名称 | 描述 | 使用场景 |
|-------|------|-------------|----------|
| 0 | 最小化 | 仅错误和漏洞 | 生产监控 |
| 1 | 标准 | + 进度更新 | 正常操作 |
| 2 | 调试 | + LLM 请求/响应 | 调试问题 |
| 3 | 调试 + 代码流 | + 任务队列、决策点 | 完全可观测性 |

### 设置详细程度

**通过用户界面**：使用实验监视器中的“详细程度”下拉菜单。

**通过 API**：```bash
# WebSocket connection with verbosity
ws://localhost:9000/ws/scan/{experiment_id}?verbosity=3

通过环境:```bash CEREBRO_VERBOSITY=3

### Code Flow Events (verbosity >= 3)

当详细程度设置为 3 时，您将看到：
- **任务开始/结束**：每个任务开始和完成的时间
- **策略选择**：选择哪个策略及原因
- **决策点**：阈值检查、回退决策
- **性能指标**：每个步骤的延迟、令牌数、分数

---

##  熔断器配置

熔断器可防止在 LLM 提供商过载时发生级联故障。

### 配置选项```bash
# .env settings
CIRCUIT_BREAKER_FAILURE_THRESHOLD=10   # Failures before circuit opens
CIRCUIT_BREAKER_SUCCESS_THRESHOLD=3    # Successes to close circuit
CIRCUIT_BREAKER_TIMEOUT=60             # Seconds before half-open attempt
CIRCUIT_BREAKER_JITTER_ENABLED=true    # Randomize retry delays
CIRCUIT_BREAKER_MAX_JITTER_MS=1000     # Max jitter in milliseconds

按提供商推荐设置

提供商	失败阈值	超时	抖动
Ollama (本地)	15	120s	启用
OpenAI	10	60s	启用
Azure OpenAI	10	60s	启用
Groq	8	45s	启用

监控断路器```bash

Check circuit breaker status

curl http://localhost:9000/health/circuit-breakers | jq

Expected output

{ "data": { "ollama": { "state": "closed", "failures": 2, "successes": 48, "failure_rate": 0.04, "threshold": 15 } } }

### 高失败率故障排除

如果断路器频繁打开（失败率 > 20%）：

1. **增加阈值**：`CIRCUIT_BREAKER_FAILURE_THRESHOLD=20`
2. **增加超时**：`CIRCUIT_BREAKER_TIMEOUT=120`
3. **检查提供商状态**：确认 Ollama/OpenAI 响应正常
4. **减少并发**：在实验配置中降低 `MAX_CONCURRENT_ATTACKS`

---

### 快速重启检查清单

在代码变更或故障排除后重启服务时，使用此检查清单：

#### 后端重启