Bandjacks

사이버 위협 방어 세계 모델링 시스템

개요

Bandjacks는 포괄적인 사이버 위협 인텔리전스(CTI) 시스템으로:

• 위협 보고서에서 MITRE ATT&CK 기술을 12-40초 안에 추출합니다
• 위협 행위자, 기술, 방어에 대한 지식 그래프를 구축합니다
• 완전한 출처 추적이 포함된 STIX 2.1 호환 번들을 생성합니다
• 방어 권장 사항을 위해 D3FEND 온톨로지를 통합합니다
• 벡터 검색 및 그래프 분석 기능을 제공합니다
• 기술 패턴을 식별하기 위해 동시 발생 분석을 계산합니다
• LLM 응답 캐싱을 통해 이전 버전보다 94% 더 빠른 추출 기능을 제공합니다
• 보고서 검토 및 분석 시각화를 위한 Next.js 프론트엔드를 포함합니다

📚 문서

가이드	설명
빠른 시작	5분 안에 실행하기
전체 설정	완전한 환경 설정
CLI 사용법	명령줄 인터페이스 가이드
API 참조	REST API 문서
동시 발생 분석	분석 문서
AttackFlow 생성	흐름 생성 가이드
검토 시스템	인간 참여 검토

아키텍처 하이라이트

TechniqueCache

• 시작 시 로드된 모든 MITRE ATT&CK 기술의 인메모리 캐시
• 즉각적인 이름 확인을 위해 external_id(예: T1557)로 O(1) 조회
• 전체 메타데이터(이름, 설명, 전술, 플랫폼)와 함께 1376개의 기술이 캐시됨
• 일관된 명명으로 검토 UI가 항상 사람이 읽을 수 있는 기술 이름을 표시하도록 보장

ActorCache

• 모든 침입 세트 및 위협 행위자의 인메모리 캐시
• 행위자 이름 확인 및 검색을 위한 빠른 조회
• 별칭 일치 및 퍼지 검색 지원

빠른 시작

전제 조건

• Python 3.11+
• Neo4j 5.x (그래프 데이터베이스)
• OpenSearch 2.x (벡터 저장소)
• Redis (선택 사항, 캐싱용)
• Node.js 18+ (프론트엔드용)
• LLM 액세스: 클라우드 API 키(Gemini 또는 OpenAI) 또는 로컬 OpenAI 호환 서버

설치```bash

Clone the repository

git clone https://github.com/yourusername/bandjacks.git cd bandjacks

Install Python dependencies with uv (recommended)

uv sync

Or with pip

pip install -e .

Install frontend dependencies

cd ui && npm install && cd ..

### 환경 설정

**중요:** 애플리케이션을 시작하기 전에 환경 변수를 설정해야 합니다. 애플리케이션은 `NEO4J_PASSWORD`가 설정되어 있어야 합니다.

프로젝트 루트에 `.env` 파일을 생성하세요:```bash
# Copy the sample file
cp infra/env.sample .env

# Edit .env and set your actual passwords
nano .env

.env에 필요한 구성:```bash

Neo4j Configuration (REQUIRED)

NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your-actual-neo4j-password # MUST BE SET - no default provided

OpenSearch Configuration

OPENSEARCH_URL=http://localhost:9200 OPENSEARCH_USER=admin OPENSEARCH_PASSWORD=your-opensearch-password # Optional if security is disabled

LLM Configuration — pick ONE of the options below:

Option A: Local OpenAI-compatible API (vLLM, llama.cpp, Ollama, LocalAI, LM Studio, etc.)

LOCAL_LLM_API_BASE=http://192.168.1.100:8080/v1 # Base URL of your local server LOCAL_LLM_MODEL=mistral-nemo # Model name as the server reports it LOCAL_LLM_API_KEY=no-key # Most local servers accept any value

Option B: Cloud LLM providers

PRIMARY_LLM=gemini GOOGLE_API_KEY=your-gemini-api-key

Optional: OpenAI as fallback (or primary if PRIMARY_LLM=openai)

OPENAI_API_KEY=your-openai-api-key

ATT&CK Configuration

ATTACK_INDEX_URL=https://raw.githubusercontent.com/mitre-attack/attack-stix-data/master/index.json ATTACK_COLLECTION=enterprise-attack ATTACK_VERSION=latest

Redis (optional, for caching)

REDIS_URL=redis://localhost:6379

**참고:** `NEO4J_PASSWORD`가 설정되지 않으면 애플리케이션이 시작되지 않습니다. 자세한 내용은 [환경 변수 수정](https://github.com/blevene/bandjacks/blob/main/ENV_VARIABLES_FIX.md)을 참조하세요.

### 서비스 시작```bash
# Start the FastAPI backend server
uv run uvicorn bandjacks.services.api.main:app --reload --port 8000

# In another terminal, start the Next.js frontend
cd ui && npm run dev

# Access the applications
open http://localhost:8000/docs    # API documentation
open http://localhost:3000         # Frontend UI

명령줄 인터페이스 (CLI)

Bandjacks는 위협 인텔리전스 작업을 위한 포괄적인 CLI를 포함합니다:```bash

Show all available commands

uv run python -m bandjacks.cli.main --help

> **참고:** CLI는 환경 변수(NEO4J_PASSWORD 등)가 설정되어 있어야 합니다. `.env` 파일이 있는 프로젝트 루트에서 실행하세요.

### 쿼리 명령어```bash
# Search for threat intelligence
uv run python -m bandjacks.cli.main query search "ransomware encryption techniques" --top-k 10

# Explore graph relationships
uv run python -m bandjacks.cli.main query graph "attack-pattern--abc123" --depth 2

검토 대기열 관리```bash

Show review queue

uv run python -m bandjacks.cli.main review queue --status pending --limit 20

Approve a candidate

uv run python -m bandjacks.cli.main review approve "candidate-123" --reviewer analyst-1

Reject with reason

uv run python -m bandjacks.cli.main review reject "candidate-456" --reviewer analyst-1 --reason "False positive"

### 문서 추출```bash
# Extract CTI from a document
uv run python -m bandjacks.cli.main extract document ./report.pdf --confidence-threshold 80 --show-evidence

분석 명령어

참고: 분석 명령어가 결과를 반환하려면 Neo4j에 AttackEpisode 데이터가 필요합니다.```bash

Show top co-occurring technique pairs

uv run python -m bandjacks.cli.main analytics top-cooccurrence --limit 25 --min-episode-size 2

Compute conditional co-occurrence P(B|A) for a technique

uv run python -m bandjacks.cli.main analytics conditional "attack-pattern--abc123" --limit 25

Analyze a specific threat actor

uv run python -m bandjacks.cli.main analytics actor "intrusion-set--xyz789" --metric npmi

Extract technique bundles

uv run python -m bandjacks.cli.main analytics bundles --min-support 3 --min-size 3 --max-size 5 --format json --output bundles.json

Global co-occurrence metrics

uv run python -m bandjacks.cli.main analytics global --min-support 2 --limit 50 --format csv --output pairs.csv

### 워크플로 명령```bash
# Process a directory of reports with analytics
uv run python -m bandjacks.cli.main workflow process-reports ./reports/ --workers 3 --analyze --export-dir ./results/

# Bulk export all analytics data
uv run python -m bandjacks.cli.main workflow bulk-export --export-dir ./analytics_export/

관리자 명령```bash

Check system health

uv run python -m bandjacks.cli.main admin health

View cache statistics

uv run python -m bandjacks.cli.main admin cache-stats

Clear cache

uv run python -m bandjacks.cli.main admin cache-clear --pattern "search:*"

Optimize database

uv run python -m bandjacks.cli.main admin optimize

## Frontend UI

Next.js 프론트엔드는 시스템 작업을 위한 현대적인 인터페이스를 제공합니다.

### Report Management (`/reports`)
- **Report List**: 모든 수집된 보고서를 상태 및 기법 카운트와 함께 확인
- **New Report** (`/reports/new`): PDF/TXT 파일 업로드 또는 보고서 내용 붙여넣기
- **Report Detail** (`/reports/[id]`): 추출된 기법, 엔터티 및 증거 확인
- **Review Interface** (`/reports/[id]/review`): 사람이 참여하는 검토 워크플로우

### Co-occurrence Analytics (`/analytics/cooccurrence`)

> **Note:** 이 페이지들은 Neo4j의 `AttackEpisode` 데이터가 필요합니다. 먼저 추출 파이프라인을 통해 보고서를 처리하거나, `POST /v1/flows/build`를 사용하여 침입 세트 데이터에서 에피소드를 생성하세요.

- **Hub Page**: 에피소드/기법/행위자 카운트 개요
- **Top Pairs** (`/pairs`): NPMI/Lift 메트릭으로 동시 발생 기법 쌍
- **Conditional** (`/conditional`): P(B|A) 조건부 확률
- **Bundles** (`/bundles`): 자주 동시 발생하는 기법 번들
- **Actors** (`/actors`): 행위자별 기법 패턴
- **Bridging** (`/bridging`): 여러 행위자에 걸쳐 사용된 기법

### System Health (`/health`)
- 모든 구성 요소(Neo4j, OpenSearch, Redis)의 실시간 상태
- 캐시 통계 및 메모리 사용량
- Kubernetes 호환 상태 엔드포인트

### Starting the Frontend```bash
cd ui
npm run dev     # Development mode with hot reload
npm run build   # Production build
npm run start   # Start production server

# Ensure backend is running
# API_URL defaults to http://localhost:8000/v1

사용 가이드

1. MITRE ATT&CK 데이터 로드

먼저, MITRE ATT&CK 프레임워크를 지식 그래프에 로드하십시오:```bash

Load the latest enterprise ATT&CK release

curl -X POST "http://localhost:8000/v1/stix/load/attack"
-H "Content-Type: application/json"
-d '{ "collection": "enterprise-attack", "version": "latest", "adm_strict": false }'

### 2. 보고서에서 기법 추출

위협 인텔리전스 보고서에서 MITRE ATT&CK 기법을 추출하세요:```python
import httpx
import time