CEREBRO-RED v2 (Research Edition)

자율 로컬 LLM 레드 티밍 스위트

Agentic Fuzzing 및 Adaptive Adversarial Mutation (AAM)을 사용하여 로컬 LLM에서 자동 취약점 발견을 위한 연구 등급 프레임워크입니다.

연구 목표

• arxiv.org/abs/2310.08419의 PAIR 알고리즘(Prompt Automatic Iterative Refinement) 구현
• Chain-of-Thought 추론을 통한 LLM-as-a-Judge 의미 평가
• 백서 수준 분석을 위한 Telemetry-First 아키텍처
• 다중 제공자 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): CoT 평가를 사용한 LLM-as-a-Judge
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. Quick Tests 실행: ```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

   

   실험 관리 및 모니터링을 보여주는 프론트엔드 사용자 인터페이스

---

빠른 시작: 로컬 vs 클라우드 배포

로컬 배포 (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

##  세부 수준

Live Logs 및 Code Flow 추적에서 세부 정보의 양을 제어합니다.

| 레벨 | 이름 | 설명 | 사용 사례 |
|-------|------|-------------|----------|
| 0 | 최소 | 오류 및 취약점만 | 프로덕션 모니터링 |
| 1 | 표준 | + 진행 업데이트 | 일반 운영 |
| 2 | 디버그 | + LLM 요청/응답 | 문제 디버깅 |
| 3 | 디버그 + 코드 흐름 | + 작업 큐, 결정 포인트 | 전체 관찰 가능성 |

### 세부 수준 설정

**UI를 통해**: Experiment Monitor에서 "Verbosity" 드롭다운을 사용합니다.

**API를 통해**:```bash
# WebSocket connection with verbosity
ws://localhost:9000/ws/scan/{experiment_id}?verbosity=3

환경을 통해:```bash CEREBRO_VERBOSITY=3

### 코드 흐름 이벤트 (verbosity >= 3)

verbosity가 3으로 설정되면 다음을 볼 수 있습니다:
- **작업 시작/종료**: 각 작업이 시작되고 완료되는 시점
- **전략 선택**: 어떤 전략이 선택되었고 그 이유
- **결정 지점**: 임계값 확인, 대체 결정
- **성능 지표**: 단계별 지연 시간, 토큰, 점수

---

##  Circuit Breaker 구성

Circuit Breaker는 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

제공자별 권장 설정