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

**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

> **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

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

### 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/

## Frontend-Benutzeroberfläche

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

### Berichtsverwaltung (`/reports`)
- **Berichtsliste**: Alle importierten Berichte mit Status und Technikzahlen anzeigen
- **Neuer Bericht** (`/reports/new`): PDF-/TXT-Dateien hochladen oder Berichtsinhalt einfügen
- **Berichtsdetail** (`/reports/[id]`): Extrahierte Techniken, Entitäten und Beweise anzeigen
- **Überprüfungsschnittstelle** (`/reports/[id]/review`): Human-in-the-Loop-Prüfworkflow

### Co-Occurrence-Analysen (`/analytics/cooccurrence`)

> **Hinweis:** Diese Seiten erfordern `AttackEpisode`-Daten in Neo4j. Verarbeiten Sie Berichte zuerst durch die Extraktionspipeline oder verwenden Sie `POST /v1/flows/build`, um Episoden aus Angriffssatzdaten zu generieren.

- **Übersichtsseite**: Übersicht mit Episoden-/Techniken-/Akteurzahlen
- **Top-Paare** (`/pairs`): Gleichzeitig auftretende Technikpaare mit NPMI/Lift-Metriken
- **Bedingt** (`/conditional`): Bedingte Wahrscheinlichkeiten P(B|A)
- **Bündel** (`/bundles`): Häufig gleichzeitig auftretende Technikbündel
- **Akteure** (`/actors`): Akteursspezifische Technikmuster
- **Brücken** (`/bridging`): Techniken, die über mehrere Akteure hinweg verwendet werden

### Systemzustand (`/health`)
- Echtzeit-Status aller Komponenten (Neo4j, OpenSearch, Redis)
- Cache-Statistiken und Speicherauslastung
- Kubernetes-kompatible Health-Endpunkte

### Frontend starten```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

### 2. Techniken aus Berichten extrahieren

Extrahieren Sie MITRE ATT&CK-Techniken aus Berichten zur Bedrohungsanalyse:```python
import httpx
import time

# For small reports (<5KB) - synchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest",
    json={
        "content": "APT29 used spearphishing emails with malicious attachments...",
        "title": "APT29 Campaign Analysis",
        "config": {
            "use_optimized_extractor": True,
            "span_score_threshold": 0.7,
            "top_k": 5
        }
    }
)

result = response.json()
print(f"Extracted {len(result['extraction']['techniques'])} techniques")

# For large reports (>5KB) - asynchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest_async",
    json={
        "content": large_report_text,
        "title": "Large Report Analysis"
    }
)

job_id = response.json()["job_id"]

# Check job status
status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")
while status.json()["status"] == "processing":
    time.sleep(2)
    status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")

# Get results from completed job
result = status.json()["result"]
print(f"Extracted {result['techniques_count']} techniques in {result['elapsed_time']} seconds")

## Architektur der Extraktions-Pipeline

Die Bandjacks-Extraktions-Pipeline verwendet eine Multi-Agenten-Architektur zur Extraktion strukturierter Bedrohungsinformationen:

### Pipeline-Komponenten

Die Extraktions-Pipeline verwendet 9 spezialisierte Agenten in sequenzieller Reihenfolge:

#### 1. **EntityExtractionAgent** - Entitätserkennung
- Extrahiert Bedrohungsakteure, Malware, Tools und Kampagnen
- Läuft zuerst, um Kontext für die Technik-Extraktion bereitzustellen
- Verwendet Few-Shot-Prompting mit JSON-Schema-Validierung
- Verarbeitet chunkierte Dokumente mit progressiver, fensterbasierter Extraktion

#### 2. **SpanFinderAgent** - Erkennung verhaltensbezogener Texte
- Erkennt Textabschnitte, die Bedrohungsverhalten enthalten, anhand von 14 taktik-spezifischen Regex-Mustern
- Identifiziert explizite Technik-IDs (T1566.001) und Verhaltensmuster
- Bewertet Textabschnitte nach Konfidenz mit Keyword-Index-Boosting
- Keine LLM-Aufrufe – reines Pattern-Matching für Geschwindigkeit

#### 3. **BatchRetrieverAgent** - Kandidatenabruf
- Verwendet OpenSearch KNN-Vektorsuche, um Kandidatentechniken pro Textabschnitt zu finden
- Dedupliziert identische Textabschnitte vor der Kodierung, um redundante Embeddings zu vermeiden
- Gibt für jeden Textabschnitt die Top-k-Kandidaten mit Ähnlichkeitswerten zurück

#### 4. **Pre-filter** - Abschnittsreduzierung
- Begrenzt Textabschnitte auf `max_spans_per_technique` (Standard 2) pro Kandidatentechnik
- Behält die am höchsten bewerteten Abschnitte pro Kandidat bei, um die Beweisqualität zu erhalten
- Reduziert Mapper-LLM-Aufrufe um ~46 % bei minimalem Technikverlust

#### 5. **DiscoveryAgent** - LLM-Erkennung (bedingt)
- Wird ausgelöst, wenn die Abrufkonfidenz niedrig ist (<0,7 Durchschnitt)
- Verwendet LLM, um Techniken zu entdecken, die die Vektorsuche übersehen hat
- Einzelner Batch-Aufruf für alle Abschnitte mit niedriger Konfidenz

#### 6. **BatchMapperAgent** - Technik-Mapping (LLM)
- Verarbeitet Textabschnitte in Batches von bis zu 10 (`MAX_MAPPER_BATCH_SIZE`, Standard seit 2026-05 von 25 reduziert, um Cloud-LLM-Abschneiden zu begrenzen)
- Extrahiert ALLE relevanten Techniken pro Abschnitt mit Konfidenzwerten
- Verwendet JSON-Schema-Validierung für strukturierte Ausgabe

#### 7. **EvidenceVerifierAgent** - Beweisvalidierung
- Musterbasierte Überprüfung von Zitaten und Zeilenreferenzen
- Bewertet die Beweisqualität auf einer 40-100-Punkte-Skala
- Keine LLM-Aufrufe – Regex- und Textabgleich

#### 8. **ConsolidatorAgent** - Beweiskonsolidierung
- Führt doppelte Techniken zusammen, die in mehreren Abschnitten gefunden wurden
- Aggregiert Beweise mittels Jaccard-Ähnlichkeit (>85 % Schwelle)
- Erzeugt endgültige Technikliste mit konsolidierten Konfidenzwerten

#### 9. **AttackFlowSynthesizer** - Sequenzgenerierung (LLM)
- Analysiert zeitliche Marker („zuerst“, „dann“, „nachdem“)
- Leitet kausale Beziehungen aus der Erzählung ab
- Erstellt STIX-Attack-Flow-Objekte mit probabilistischen Kanten
- Fällt auf Co-Occurrence-Modellierung zurück, wenn die Sequenz unklar ist

### Leistungsoptimierungen

- **Smart Chunking**: Dokumente in 2KB-Chunks mit Überlappung aufgeteilt
- **Batch-Verarbeitung**: Mapper verarbeitet bis zu 25 Textabschnitte pro LLM-Aufruf
- **Parallele Verarbeitung**: Chunks werden gleichzeitig über Worker-Threads verarbeitet
- **Response-Caching**: LLM-Antworten werden zwischengespeichert, um doppelte Aufrufe zu vermeiden
- **Früher Abbruch**: Hochkonfidente Extraktionen überspringen die Verifikation
- **TechniqueCache**: Alle ATT&CK-Techniken werden beim Start geladen für O(1)-Lookups
- **Pre-filter**: Begrenzt Textabschnitte pro Kandidatentechnik vor dem LLM-Mapper (46 % weniger Aufrufe)
- **Batch-Embedding**: Technik-Embeddings werden in Batches generiert (2-5x schneller)
- **Verbindungspooling**: Gemeinsame Neo4j/OpenSearch-Verbindungen über verschiedene Anfragen hinweg
- **UNWIND-Batches**: Neo4j-Schreibvorgänge werden über UNWIND in Batches zusammengefasst (30-40 Abfragen → 6-7)
- **Modell-Vorwärmen**: Embedding-Modell wird beim Start geladen, um Kaltstartverzögerungen zu vermeiden

### Verarbeitungszeiten

| Dokumentengröße | Verarbeitungszeit | Extrahierte Techniken |
|--------------|-----------------|---------------------|
| Klein (<5KB) | 10-20 Sekunden | 5-10 Techniken |
| Mittel (5-15KB) | 20-40 Sekunden | 10-15 Techniken |
| Groß (>15KB) | 30-60 Sekunden | 15-25 Techniken |

## Co-Occurrence-Analyse

Bandjacks bietet Analysen zum Verständnis von Technikbeziehungen. 

> **Hinweis:** Analysen erfordern `AttackEpisode`- und `AttackAction`-Daten in Neo4j. Diese werden erstellt, wenn:
> - Berichte durch die Extraktions-Pipeline verarbeitet werden
> - Angriffsflüsse über `/v1/flows/build` erstellt werden
> - STIX-Bundles mit Angriffsepisoden importiert werden
>
> Wenn keine Episoden vorhanden sind, geben die Analysen leere Ergebnisse zurück.

### Globale Co-Occurrence

Berechne, welche Techniken häufig gemeinsam in allen Angriffsepisoden auftauchen:```python
# Via API
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/global",
    json={"min_support": 2, "min_episodes_per_pair": 2, "limit": 50}
)

for pair in response.json()["pairs"]:
    print(f"{pair['name_a']} + {pair['name_b']}: NPMI={pair['npmi']:.3f}")

### Technikbündel

Identifizieren Sie häufig gemeinsam auftretende Technikbündel (3-5 Techniken):```python
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/bundles",
    json={"min_support": 3, "min_size": 3, "max_size": 5}
)

## Human-in-the-Loop-Überprüfungssystem

Bandjacks umfasst ein umfassendes Überprüfungssystem zur Validierung extrahierter Informationen:

### Einheitliche Überprüfungsoberfläche

Das Überprüfungssystem präsentiert alle extrahierten Elemente in einer einzigen Oberfläche:```typescript
// Review workflow
1. Upload/ingest report → Extraction pipeline runs
2. Navigate to /reports/{id}/review
3. Review extracted items across three tabs:
   - Entities (threat actors, malware, tools)
   - Techniques (ATT&CK mappings with evidence)
   - Attack Flow (sequenced steps)
4. Take actions on each item:
   - Approve: Accept as correct
   - Reject: Mark as incorrect
   - Edit: Modify details (name, confidence, etc.)
5. Submit all decisions atomically

### 4. Suche nach Techniken

Suche nach ATT&CK-Techniken mit natürlicher Sprache:```python
# Vector search for similar techniques
response = httpx.post(
    "http://localhost:8000/v1/search/ttx",
    json={
        "query": "ransomware that encrypts files and demands payment",
        "top_k": 5
    }
)

techniques = response.json()["results"]
for tech in techniques:
    print(f"{tech['external_id']}: {tech['name']} (score: {tech['score']:.2f})")

### 6. Erstellen von AttackFlow Modellen

Erstellen Sie Ko-Vorkommensmodelle, die zeigen, wie Bedrohungsakteure Techniken gemeinsam einsetzen:```python
# Generate flow for a specific intrusion set (e.g., APT29)
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "intrusion_set_id": "intrusion-set--899ce53f-13a0-479b-a0e4-67d46e241542"
    }
)

flow = response.json()
print(f"Generated flow '{flow['name']}' with {len(flow['steps'])} techniques")
print(f"Co-occurrence edges: {len(flow['edges'])}")

AttackFlow-Modelle verwenden **Ko-Vorkommen** anstelle einer sequenziellen Reihenfolge, da Angriffssätze keine inhärenten Sequenzinformationen enthalten. Techniken werden verbunden durch:
- **Intra-Taktik-Kanten**: Zwischen Techniken innerhalb derselben Kill-Chain-Taktik
- **Cross-Taktik-Kanten**: Zwischen Techniken über benachbarte Taktiken hinweg
- **Hub-Spoke-Muster**: Für große Technikmengen, um Kantenexplosion zu vermeiden

Siehe den [AttackFlow Generation Guide](https://github.com/blevene/bandjacks/blob/main/docs/ATTACKFLOW_GENERATION.md) für detaillierte Nutzung.

## Unterstützte Eingabeformate

Die Extraktionspipeline unterstützt mehrere Eingabeformate:

- **Plain Text** - Direkter Textinhalt
- **Markdown** - Formatierte Markdown-Dokumente
- **PDF** - Über pdfplumber-Extraktion
- **HTML** - Über BeautifulSoup-Parsing
- **JSON** - Strukturierte Datenextraktion

### Aus Plain Text extrahieren```python
# Direct text extraction
plaintext_report = """
The threat actors used spearphishing emails with malicious attachments.
After gaining access, they deployed Mimikatz to harvest credentials and
used RDP for lateral movement across the network.
"""

result = asyncio.run(run_agentic_v2_async(plaintext_report, {
    "cache_llm_responses": True,
    "single_pass_threshold": 500
}))

### Auszug aus PDF```python
import pdfplumber
from bandjacks.llm.extraction_pipeline import run_extraction_pipeline

# Read PDF with pdfplumber (recommended)
with pdfplumber.open("threat_report.pdf") as pdf:
    text = ""
    for page in pdf.pages:
        page_text = page.extract_text()
        if page_text:
            text += page_text + "\n"

# Extract techniques using extraction pipeline
result = run_extraction_pipeline(text, {
    "use_optimized_extractor": True,
    "span_score_threshold": 0.7,
    "chunk_size": 2000
}, source_id="threat_report")

print(f"Found {len(result['techniques'])} techniques")

results.append({
    "file": pdf_file.name,
    "techniques": list(result["techniques"].keys()),
    "count": len(result["techniques"])
})

### Erstellen von Angriffsflüssen```python
# Generate attack flow from extracted techniques
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "source_id": "report-123",
        "technique_ids": ["T1566.001", "T1059.001", "T1003.001"]
    }
)

flow = response.json()
print(f"Generated flow with {len(flow['steps'])} steps")

## API-Endpunkte

### Kern-Endpunkte

- `POST /v1/stix/load/attack` - Lade MITRE ATT&CK-Daten
- `POST /v1/reports/ingest` - Synchrones Berichts-Einlesen (<5KB)
- `POST /v1/reports/ingest_async` - Asynchrones Berichts-Einlesen (>5KB)
- `POST /v1/reports/ingest/upload` - PDF/TXT-Dateien hochladen
- `GET /v1/reports/jobs/{id}/status` - Jobstatus prüfen
- `POST /v1/reports/{id}/unified-review` - Überprüfungsentscheidungen einreichen
- `POST /v1/search/ttx` - Nach Techniken suchen
- `GET /v1/graph/technique/{id}` - Technikdetails abrufen

### Angriffsflüsse

- `POST /v1/flows/build` - Generiere AttackFlow-Kooccurrenz-Modelle
- `GET /v1/flows/{flow_id}` - Rufe spezifische AttackFlow-Details ab
- `POST /v1/flows/search` - Suche nach ähnlichen Angriffsflüssen
- `GET /v1/flows/dump` - Massenexport von Flüssen mit Paginierung und Filterung

### Analysen

- `GET /v1/analytics/cooccurrence/global` - Globale Kooccurrenz-Metriken
- `GET /v1/analytics/cooccurrence/conditional` - Bedingte Wahrscheinlichkeiten
- `GET /v1/analytics/cooccurrence/bundles` - Technikbündel
- `GET /v1/analytics/cooccurrence/actor` - Akteur-spezifische Muster
- `GET /v1/coverage/gaps` - Technik-Abdeckungslücken

### Verteidigung & Erkennung

- `GET /v1/defense/technique/{id}` - Verteidigungsempfehlungen abrufen
- `GET /v1/detections/technique/{id}` - Erkennungsstrategien
- `POST /v1/sigma/validate` - Sigma-Regeln validieren

### Überwachung

- `GET /health` - Basis-Gesundheitscheck
- `GET /health/live` - Kubernetes-Liveness-Probe
- `GET /health/ready` - Kubernetes-Readiness-Probe
- `GET /health/components/{component}` - Einzelne Komponenten-Gesundheit
- `GET /v1/costs/stats` - LLM-Kostenverfolgung (tägliche Aggregation nach Modell)
- `GET /v1/cache/stats` - LLM-Cache-Statistiken abrufen
- `POST /v1/cache/clear` - LLM-Cache leeren
- `GET /v1/compliance/report` - Compliance-Metriken
- `GET /v1/drift/status` - Drift-Erkennungsstatus
- `GET /v1/ml-metrics/performance` - ML-Modellmetriken

### Akteure & Herkunft

- `GET /v1/actors` - Bedrohungsakteure auflisten
- `GET /v1/actors/{id}` - Akteurdetails abrufen
- `GET /v1/provenance/{object_id}` - Objekt-Herkunft
- `GET /v1/provenance/{object_id}/lineage` - Vollständige Abstammungskette
- `GET /v1/provenance/{object_id}/evidence` - Beweisschnipsel

### Nur-API-Funktionen (Keine UI/CLI)

Diese Endpunkte sind voll funktionsfähig, werden aber nur über die REST-API aufgerufen (keine Frontend-Seiten oder CLI-Befehle):

#### Angriffspfad-Simulation
- `POST /v1/simulation/paths` - Simuliere Angriffspfade von einer Starttechnik/-gruppe
- `POST /v1/simulation/predict` - Sage die nächsten wahrscheinlichen Techniken basierend auf dem aktuellen Zustand voraus
- `POST /v1/simulation/whatif` - Was-wäre-wenn-Analyse für Verteidigungsszenarien
- `POST /v1/simulation/scenario` - Simuliere aus Gruppen/Software/Techniken-Sets
- `GET /v1/simulation/statistics/{technique_id}` - Techniknutzungsstatistiken
- `GET /v1/simulation/groups/{group_id}/patterns` - Gruppenangriffsmuster
- `POST /v1/simulation/compare` - Vergleiche mehrere Angriffspfade

#### MDP-Richtlinie & Rollout
- `POST /v1/simulate/rollout` - PTG-Rollout-Simulation
- `POST /v1/simulate/mdp` - Berechne die optimale MDP-Verteidigungsrichtlinie
- `GET /v1/simulate/models` - Liste verfügbare PTG-Modelle auf

#### Drift-Erkennung & Überwachung
- `GET /v1/drift/status` - Aktueller Drift-Status über alle Metriken
- `POST /v1/drift/analyze` - Drift-Analyse mit benutzerdefinierten Schwellwerten ausführen
- `GET /v1/drift/alerts` - Aktive Drift-Warnungen abrufen
- `POST /v1/drift/alerts/{alert_id}/acknowledge` - Warnung bestätigen
- `GET /v1/drift/metrics/{metric_name}` - Spezifische Drift-Metrik abrufen

#### ML-Metrikverfolgung
- `POST /v1/ml-metrics/prediction` - Modellvorhersage zur Nachverfolgung aufzeichnen
- `POST /v1/ml-metrics/review` - Metriken zu Überprüfungsentscheidungen aufzeichnen
- `POST /v1/ml-metrics/coverage-gap` - Abdeckungslücke aufzeichnen
- `GET /v1/ml-metrics/performance` - Modellleistungsmetriken abrufen
- `GET /v1/ml-metrics/dashboard` - Dashboard-Metriken exportieren

#### Benachrichtigungen
- `GET /v1/notifications/history` - Benachrichtigungsverlauf abrufen
- `POST /v1/notifications/clear-history` - Benachrichtigungsverlauf löschen
- `GET /v1/notifications/config` - Benachrichtigungskonfiguration abrufen
- `POST /v1/notifications/test` - Testbenachrichtigung senden

#### Vektoraktualisierungsmanagement
- `GET /v1/vectors/status` - Status des Vektoraktualisierungssystems
- `GET /v1/vectors/metrics` - Detaillierte Vektoraktualisierungsmetriken
- `POST /v1/vectors/update` - Vektoraktualisierung manuell auslösen
- `POST /v1/vectors/process-batch` - Batch-Verarbeitung erzwingen
- `DELETE /v1/vectors/queue` - Ausstehende Aktualisierungswarteschlange leeren
- `GET /v1/vectors/health` - Gesundheitscheck des Vektorsystems

#### Entitäts-Ignorierliste
- `GET /v1/ignorelist` - Aktuellen Ignorierlistenstatus abrufen
- `POST /v1/ignorelist/add` - Entität zur Ignorierliste hinzufügen
- `DELETE /v1/ignorelist/remove` - Entität aus der Ignorierliste entfernen
- `POST /v1/ignorelist/reload` - Ignorierliste von der Festplatte neu laden

#### Kandidatenmuster-Überprüfung
- `GET /v1/review/candidates` - Kandidaten-Angriffsmuster auflisten
- `POST /v1/review/candidates` - Kandidatenmuster erstellen
- `GET /v1/review/candidates/{id}` - Kandidatendetails abrufen
- `POST /v1/review/candidates/{id}/approve` - Kandidaten genehmigen
- `POST /v1/review/candidates/{id}/reject` - Kandidaten ablehnen
- `GET /v1/review/candidates/{id}/similar` - Ähnliche Muster finden
- `GET /v1/review/candidates/stats/summary` - Kandidatenstatistiken

### Vollständige API-Dokumentation

Greifen Sie auf die vollständige API-Dokumentation zu unter:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## Architektur

### Projektstruktur```
bandjacks/
├── bandjacks/
│   ├── analysis/         # Graph analysis & interdiction
│   │   ├── graph_analyzer.py
│   │   └── interdiction.py
│   ├── analytics/        # Co-occurrence & clustering
│   │   ├── clustering.py
│   │   ├── cooccurrence.py
│   │   └── detection_bundles.py
│   ├── cli/              # Command-line interface
│   │   ├── main.py       # CLI entry point
│   │   ├── batch_extract.py
│   │   ├── formatters.py
│   │   └── workflows.py
│   ├── config/           # Configuration files
│   │   └── entity_ignorelist.yaml
│   ├── core/             # Core utilities
│   │   ├── cache.py      # Redis caching
│   │   ├── connection_pool.py
│   │   └── query_optimizer.py
│   ├── llm/              # Extraction pipeline
│   │   ├── extraction_pipeline.py
│   │   ├── agents_v2.py  # Core extraction agents
│   │   ├── chunked_extractor.py
│   │   ├── optimized_chunked_extractor.py
│   │   ├── entity_extractor.py
│   │   ├── flow_builder.py
│   │   ├── cache.py      # LLM response caching
│   │   └── experimental/ # Experimental features
│   ├── loaders/          # Data loading & indexing
│   │   ├── attack_catalog.py
│   │   ├── attack_upsert.py
│   │   ├── opensearch_index.py
│   │   ├── hybrid_search.py
│   │   └── sigma_loader.py
│   ├── monitoring/       # Metrics & monitoring
│   │   ├── compliance_metrics.py
│   │   ├── defense_metrics.py
│   │   ├── drift_detector.py
│   │   └── ml_metrics.py
│   ├── services/         # API & services
│   │   ├── api/          # FastAPI application
│   │   │   ├── main.py
│   │   │   ├── routes/   # API route handlers
│   │   │   └── middleware/
│   │   ├── technique_cache.py
│   │   └── actor_cache.py
│   ├── simulation/       # Attack simulation
│   │   ├── attack_simulator.py
│   │   ├── mdp_solver.py
│   │   └── ptg_rollout.py
│   └── store/            # Data stores
│       ├── report_store.py
│       ├── candidate_store.py
│       └── review_store.py
├── ui/                   # Next.js frontend
│   ├── app/              # App Router pages
│   │   ├── reports/      # Report management
│   │   ├── analytics/    # Analytics dashboards
│   │   └── health/       # Health monitoring
│   ├── components/       # React components
│   └── hooks/            # Custom React hooks
├── tests/                # Test suite
├── samples/              # Sample reports
├── scripts/              # Utility scripts
└── docs/                 # Documentation

**Priorität der Anbieter:** Local API > Gemini > OpenAI > LiteLLM Proxy.
Wenn ein lokaler Server konfiguriert ist, werden Cloud-Anbieter automatisch als Fallbacks hinzugefügt.

#### Allgemeine Beispiele für lokale Server

| Server | `LOCAL_LLM_API_BASE` | `LOCAL_LLM_MODEL` |
|--------|---------------------|-------------------|
| vLLM | `http://host:8000/v1` | `mistralai/Mistral-Nemo-Instruct-2407` |
| llama.cpp | `http://host:8080/v1` | `mistral-nemo` |
| Ollama | `http://host:11434/v1` | `mistral-nemo` |
| LM Studio | `http://host:1234/v1` | `mistral-nemo` |
| LocalAI | `http://host:8080/v1` | `mistral-nemo` |

### Extraktionskonfiguration

Das System verwendet eine einzelne leistungsstarke asynchrone Pipeline mit konfigurierbaren Optionen:```python
{
    "cache_llm_responses": True,         # Enable LLM caching (default: True)
    "single_pass_threshold": 500,        # Max words for single-pass (default: 500)
    "early_termination_confidence": 90,  # Skip verification above this (default: 90)
    "disable_discovery": False,          # Disable LLM discovery agent
    "max_spans": 20,                     # Maximum spans to process
    "span_score_threshold": 0.7,         # Minimum span quality
    "top_k": 5,                          # Candidates per span

    # Cost optimization options
    "max_spans_per_technique": 2,        # Pre-filter: max spans per candidate technique (0=disable, default=2)
    "enable_span_dedup": False,          # Text-based span dedup before mapping (default=False)
}

### Konfidenzschwellen

Steuern Sie die Extraktionsqualität:```python
{
    "confidence_threshold": 50.0,  # Minimum confidence (0-100)
    "auto_ingest": True            # Auto-add high-confidence results
}

### Beispiel für eine Gesundheitsantwort```json
{
  "status": "healthy",
  "timestamp": "2025-01-28T17:43:30.184036Z",
  "version": "1.0.0",
  "components": {
    "neo4j": {
      "status": "healthy",
      "latency_ms": 5
    },
    "opensearch": {
      "status": "degraded",
      "cluster_status": "yellow",
      "indices": {
        "attack_nodes": false,
        "bandjacks_reports": true
      }
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 2,
      "memory_mb": 1.69
    },
    "caches": {
      "status": "healthy",
      "technique_cache": {
        "count": 993,
        "loaded": true
      },
      "actor_cache": {
        "count": 145,
        "loaded": true
      }
    },
    "system": {
      "status": "healthy",
      "memory": {
        "available_gb": 8.84,
        "percent_used": 72.4
      },
      "disk": {
        "available_gb": 353.11,
        "percent_used": 2.9
      },
      "cpu": {
        "percent_used": 7.7
      }
    }
  }
}

## Leistungsoptimierung

### Caching

Das System beinhaltet automatisches LLM-Antwort-Caching für verbesserte Leistung:```python
# Check cache statistics
response = httpx.get("http://localhost:8000/v1/cache/stats")
stats = response.json()
print(f"Cache hit rate: {stats['hit_rate']}")

# Clear cache if needed
httpx.post("http://localhost:8000/v1/cache/clear")

## Sicherheit

### Eingabevalidierung

- **Prävention von Cypher-Injection**: Alle Graph-Abfrage-Endpunkte validieren benutzerseitig bereitgestellte `relationship_types`-Parameter gegen eine Whitelist bekannter Beziehungstypen (USES, MITIGATES, HAS_TACTIC, etc.) sowie ein strenges Regex-Muster (`^[A-Z][A-Z0-9_]*$`). Ungültige Eingaben geben 400 zurück, bevor die Abfrage erstellt wird.
- **JSON-Schema-Validierung**: LLM-Antworten werden gegen JSON-Schemata validiert, um fehlerhafte Daten am Eintritt in die Pipeline zu hindern.
- **ADM-Validierung**: Alle STIX-Inhalte müssen vor der Aufnahme die ATT&CK-Datenmodell-Validierung bestehen.

### Authentifizierung & Autorisierung

- **JWT-Authentifizierung**: Optionale Middleware für die API-Authentifizierung (`JWTAuthMiddleware`)
- **Ratenbegrenzung**: Pro-Endpunkt-Ratenbegrenzung mit konfigurierbaren Schwellenwerten
- **CORS**: Konfigurierbares Cross-Origin Resource Sharing

## Erweiterte Funktionen

### Herkunftsverfolgung

Jede extrahierte Entität enthält die vollständige Herkunft:```python
# Get provenance for an object
response = httpx.get(
    "http://localhost:8000/v1/provenance/attack-pattern--abc123"
)

### Abdeckungsanalysen

Analysieren Sie Ihre Threat-Intelligence-Abdeckung:```python
# Get coverage analysis
response = httpx.get("http://localhost:8000/v1/analytics/coverage")
coverage = response.json()

print(f"Summary: {coverage['summary']}")
for tactic in coverage['tactics']:
    print(f"  {tactic['tactic']}: {tactic['coverage_percentage']}%")

## Feature Status

Dieser Abschnitt bietet Transparenz über den Implementierungsstatus verschiedener Funktionen:

### Voll funktionsfähig ✅
- **Report Extraction Pipeline** - LLM-basierte Technik-Extraktion funktioniert durchgängig
- **MITRE ATT&CK Loading** - Lädt Enterprise/Mobile/ICS ATT&CK-Daten in Neo4j
- **Vector Search** - OpenSearch-basierte semantische Suche nach Techniken
- **Review System** - Human-in-the-Loop-Review-Workflow über API und UI
- **Health Monitoring** - Komponenten-Gesundheitschecks und Kubernetes-Probes
- **CLI Query/Admin Commands** - Suche, Graph-Traversal, Cache-Verwaltung
- **Attack Flow Generation** - Ko-Okkurrenz-basierte Flow-Erstellung für Intrusion-Sets
- **Attack Simulation** - MDP-basierte Pfadsimulation über `/simulation/*` und `/simulate/*`
- **Coverage Reports** - JSON-Berichte für Executive, Technical, Tactical, Operational Views

### Funktional mit Datenabhängigkeiten ⚠️
- **Co-occurrence Analytics** - Benötigt `AttackEpisode`-Knoten aus der Report-Verarbeitung
- **Actor Analytics** - Benötigt Episoden, die Intrusion-Sets zugeordnet sind
- **Technique Bundles** - Benötigt ausreichende Episodendaten für Mustererkennung
- **CLI Analytics Commands** - Funktioniert, gibt aber leer zurück, wenn keine Episoden existieren

### Nur API (keine UI/CLI) 🔌
Diese Funktionen sind vollständig implementiert und nur über die REST-API zugänglich:
- **Attack Path Simulation** - `/simulation/*`-Routen für Pfadvorhersage und Was-wäre-wenn-Analyse
- **MDP Policy Solver** - `/simulate/mdp` zur optimalen Berechnung von Abwehrstrategien
- **Drift Detection** - `/drift/*`-Routen zur Überwachung von Datenqualitätsdrift
- **ML Metrics** - `/ml-metrics/*` zur Verfolgung der Modellleistung im Zeitverlauf
- **Vector Management** - `/vectors/*` zur Verwaltung von Vektor-Embeddings
- **Entity Ignorelist** - `/ignorelist/*` zum Filtern von False-Positive-Entitäten
- **Candidate Patterns** - `/review/candidates/*` für neuartige Technikkandidaten
- **Notifications** - `/notifications/*` zur Alarmkonfiguration und -historie
- **Provenance** - `/provenance/*` zur Nachverfolgung der Extraktionsherkunft
- **Compliance** - `/compliance/*` zur Berichterstattung von Compliance-Kennzahlen

### Experimentell (in `llm/experimental/`) 🧪
- **PTG (Probabilistic Threat Graph)** - Kernlogik implementiert, begrenzte Tests
- **Judge Integration** - LLM-basierte Sequenzvalidierung
- **Attack Flow Simulator** - Flow-basierte Simulationsengine
- **Sequence Extractor** - Sequenzen aus Flows extrahieren

### Entfernt/Bereinigt 🗑️
Die folgenden Stub-Funktionen wurden aus der API entfernt:
- ~~Platform Coverage Analysis~~ - Gab hartcodierte Stub-Daten zurück
- ~~Trend Analysis~~ - Gab zufällige synthetische Daten zurück
- ~~CSV/PDF Report Export~~ - Gab 501 zurück; jetzt nur noch JSON
- ~~Gemini Sequence Inference~~ - War 501-Stub; stattdessen `/sequence/propose` verwenden

### Konnektivitätsmatrix

| Feature Area | Frontend UI | CLI | REST API |
|--------------|-------------|-----|----------|
| Report Management | ✅ | ✅ | ✅ |
| Review Workflow | ✅ | ✅ | ✅ |
| Search (TTX) | ✅ | ✅ | ✅ |
| Co-occurrence Analytics | ✅ | ✅ | ✅ |
| Coverage Analytics | ✅ | - | ✅ |
| Health Monitoring | ✅ | - | ✅ |
| Detections/Sigma | ✅ | - | ✅ |
| Attack Flows | ✅ | - | ✅ |
| Defense Overlay | ✅ | - | ✅ |
| Sequences/PTG | ✅ | - | ✅ |
| Actors | ✅ | - | ✅ |
| Attack Simulation | - | - | ✅ |
| Drift Detection | - | - | ✅ |
| ML Metrics | - | - | ✅ |
| Vector Management | - | - | ✅ |
| Entity Ignorelist | - | - | ✅ |
| Candidate Patterns | - | - | ✅ |
| Notifications | - | - | ✅ |
| Provenance | - | - | ✅ |
| Compliance | - | - | ✅ |

### Frontend-Seiten
| Seite | Status | Anmerkungen |
|------|--------|-------|
| `/reports` | ✅ Funktioniert | Reports auflisten, erstellen, anzeigen |
| `/reports/[id]/review` | ✅ Funktioniert | Vollständiger Review-Workflow |
| `/analytics/cooccurrence` | ⚠️ Datenabhängig | Zeigt KPIs, wenn Episoden existieren |
| `/analytics/cooccurrence/pairs` | ⚠️ Datenabhängig | Ruft echte API auf |
| `/analytics/cooccurrence/bundles` | ⚠️ Datenabhängig | Ruft echte API auf |
| `/analytics/cooccurrence/actors` | ⚠️ Datenabhängig | Ruft echte API auf |
| `/health` | ✅ Funktioniert | Echtzeit-Gesundheitsstatus |

## Fehlerbehebung

### Häufige Probleme

1. **OpenSearch-Verbindung fehlgeschlagen**
   - Stellen Sie sicher, dass OpenSearch läuft: `curl http://localhost:9200`
   - Überprüfen Sie, ob der Index existiert: `curl http://localhost:9200/bandjacks_attack_nodes-v1`

2. **Neo4j-Verbindung fehlgeschlagen**
   - Überprüfen Sie, ob Neo4j läuft: `neo4j status`
   - Stellen Sie sicher, dass `NEO4J_PASSWORD` in der `.env`-Datei gesetzt ist
   - Stellen Sie sicher, dass das Passwort mit Ihrer Neo4j-Instanz übereinstimmt
   - Falls "NEO4J_PASSWORD environment variable is required" angezeigt wird, setzen Sie es in Ihrer `.env`-Datei

3. **Niedriger Extraktions-Recall**
   - Stellen Sie sicher, dass Sie die Methode `agentic_v2` verwenden
   - Überprüfen Sie, ob der LLM-API-Key gültig ist
   - Überprüfen Sie, ob der Modellname korrekt ist (`gemini-flash-latest`)

4. **Timeout-Fehler**
   - Erhöhen Sie die Timeout-Einstellungen für große Dokumente
   - Erwägen Sie, sehr große Reports in Chunks aufzuteilen

5. **Frontend verbindet sich nicht mit der API**
   - Stellen Sie sicher, dass die API auf Port 8000 läuft
   - Überprüfen Sie die CORS-Einstellungen in der API-Konfiguration

### Debug-Modus

Aktivieren Sie detailliertes Logging:```python
import logging
logging.basicConfig(level=logging.DEBUG)

# Run extraction with debug output
result = run_agentic_v2(text, config)

### Mitwirken

1. Repository forken
2. Feature-Branch erstellen
3. Änderungen vornehmen
4. Tests ausführen: `uv run pytest`
5. Linting ausführen: `uv run ruff check`
6. Pull-Request einreichen

### Codequalität```bash
# Format code
uv run ruff format

# Check linting
uv run ruff check

# Type checking
uv run mypy bandjacks