Bandjacks

Cyber Threat Defense World Modeling System

Übersicht

Bandjacks ist ein umfassendes Cyber-Bedrohungsinformationssystem (CTI), das:

• MITRE ATT&CK-Techniken aus Bedrohungsberichten in 12-40 Sekunden extrahiert
• Einen Wissensgraphen von Bedrohungsakteuren, Techniken und Abwehrmaßnahmen erstellt
• STIX 2.1-konforme Bündel mit vollständiger Herkunftsverfolgung generiert
• Die D3FEND-Ontologie für Abwehrempfehlungen integriert
• Vektorsuche und Graphanalytik-Funktionen bereitstellt
• Ko-Vorkommensanalysen berechnet, um Technikmuster zu identifizieren
• 94% schnellere Extraktion als frühere Versionen mit LLM-Antwort-Caching
• Ein Next.js-Frontend zur Berichtsprüfung und Visualisierung von Analysen enthält

📚 Dokumentation

Anleitung	Beschreibung
Schnellstart	In 5 Minuten einsatzbereit
Vollständige Einrichtung	Vollständige Umgebungseinrichtung
CLI-Nutzung	Befehlszeilen-Anleitung
API-Referenz	REST-API-Dokumentation
Ko-Vorkommensanalysen	Dokumentation der Analysen
AttackFlow-Generierung	Anleitung zur Flussgenerierung
Überprüfungssystem	Überprüfung mit menschlichem Eingriff

Architektur-Highlights

TechniqueCache

• In-Memory-Cache aller MITRE ATT&CK-Techniken, die beim Start geladen werden
• O(1)-Lookups nach external_id (z.B. T1557) für sofortige Namensauflösung
• 1376 Techniken zwischengespeichert mit vollständigen Metadaten (Name, Beschreibung, Taktiken, Plattformen)
• Konsistente Benennung stellt sicher, dass die Überprüfungs-Benutzeroberfläche immer menschenlesbare Techniknamen anzeigt

ActorCache

• In-Memory-Cache aller Intrusion Sets und Bedrohungsakteure
• Schnelle Lookups für die Namensauflösung und Suche von Akteuren
• Unterstützt Alias-Abgleich und unscharfe Suche

Schnellstart

Voraussetzungen

• Python 3.11+
• Neo4j 5.x (Graphdatenbank)
• OpenSearch 2.x (Vektorspeicher)
• Redis (optional, für Caching)
• Node.js 18+ (für Frontend)
• LLM-Zugriff: Cloud-API-Schlüssel (Gemini oder OpenAI) oder ein lokaler OpenAI-kompatibler Server

Installation```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 ..

### Umgebungseinrichtung

**WICHTIG:** Sie müssen Umgebungsvariablen konfigurieren, bevor Sie die Anwendung starten. Die Anwendung benötigt `NEO4J_PASSWORD`.

Erstellen Sie eine `.env`-Datei im Projektstammverzeichnis:```bash
# Copy the sample file
cp infra/env.sample .env

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

Erforderliche Konfiguration in .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

**Hinweis:** Die Anwendung wird nicht starten, wenn `NEO4J_PASSWORD` nicht gesetzt ist. Siehe [Environment Variables Fix](https://github.com/blevene/bandjacks/blob/main/ENV_VARIABLES_FIX.md) für Details.

### Starten der Dienste```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

Command-Line Interface (CLI)

Bandjacks enthält eine umfassende CLI für Bedrohungsintelligenz-Operationen:```bash

Show all available commands

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

> **Hinweis:** Die CLI erfordert das Setzen von Umgebungsvariablen (NEO4J_PASSWORD, usw.). Führen Sie das Skript vom Projektstammverzeichnis aus, in dem sich `.env` befindet.

### Abfragebefehle```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

Verwaltung der Überprüfungswarteschlange```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"

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

Analytics-Befehle

Hinweis: Analytics-Befehle benötigen AttackEpisode-Daten in Neo4j, um Ergebnisse zurückzugeben.```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

### Workflow-Befehle```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/

Administratorbefehle```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-Benutzeroberfläche

Das Next.js-Frontend bietet eine moderne Schnittstelle für die Arbeit mit dem System.