### Configurazione dell'ambiente

**IMPORTANTE:** È necessario configurare le variabili d'ambiente prima di avviare l'applicazione. L'applicazione richiede che `NEO4J_PASSWORD` sia impostata.

Crea un file `.env` nella root del progetto:```bash
# Copy the sample file
cp infra/env.sample .env

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

**Nota:** L'applicazione non si avvierà se `NEO4J_PASSWORD` non è impostata. Vedere [Correzione delle variabili d'ambiente](https://github.com/blevene/bandjacks/blob/HEAD/ENV_VARIABLES_FIX.md) per i dettagli.

### Avvio dei servizi```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

> **Nota:** La CLI richiede che le variabili d'ambiente siano impostate (NEO4J_PASSWORD, ecc.). Eseguire dalla root del progetto dove si trova `.env`.

### Comandi di query```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

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

### Comandi del flusso di lavoro```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/

## Interfaccia frontend

Il frontend Next.js fornisce un'interfaccia moderna per lavorare con il sistema.

### Gestione dei report (`/reports`)
- **Elenco report**: Visualizza tutti i report acquisiti con stato e conteggi delle tecniche
- **Nuovo report** (`/reports/new`): Carica file PDF/TXT oppure incolla il contenuto del report
- **Dettaglio report** (`/reports/[id]`): Visualizza tecniche, entità ed evidenze estratte
- **Interfaccia di revisione** (`/reports/[id]/review`): Flusso di lavoro di revisione human-in-the-loop

### Analisi di co-occorrenza (`/analytics/cooccurrence`)

> **Nota:** Queste pagine richiedono dati `AttackEpisode` in Neo4j. Prima processa i report tramite la pipeline di estrazione, oppure usa `POST /v1/flows/build` per generare episodi dai dati degli intrusion set.

- **Pagina Hub**: Panoramica con conteggi di episodi/tecniche/attori
- **Coppie principali** (`/pairs`): Coppie di tecniche co-occorrenti con metriche NPMI/Lift
- **Condizionale** (`/conditional`): Probabilità condizionali P(B|A)
- **Bundle** (`/bundles`): Bundle di tecniche frequentemente co-occorrenti
- **Attori** (`/actors`): Modelli di tecniche specifici per attore
- **Collegamenti** (`/bridging`): Tecniche utilizzate da più attori

### Stato del sistema (`/health`)
- Stato di salute in tempo reale di tutti i componenti (Neo4j, OpenSearch, Redis)
- Statistiche della cache e utilizzo della memoria
- Endpoint di health compatibili con Kubernetes

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

### 2. Estrazione delle Tecniche dai Report

Estrai le tecniche MITRE ATT&CK dai report di threat intelligence:```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")

## Extraction Pipeline Architecture

La pipeline di estrazione di Bandjacks utilizza un'architettura multi-agente per estrarre intelligence strutturata sulle minacce:

### Componenti della pipeline

La pipeline di estrazione utilizza 9 agenti specializzati in sequenza:

#### 1. **EntityExtractionAgent** - Riconoscimento delle entità
- Estrae attori delle minacce, malware, strumenti e campagne
- Viene eseguito per primo per fornire contesto all'estrazione delle tecniche
- Utilizza few-shot prompting con validazione dello schema JSON
- Gestisce documenti in chunk con estrazione progressiva a finestre

#### 2. **SpanFinderAgent** - Rilevamento di testo comportamentale
- Rileva porzioni di testo (span) contenenti comportamenti di minaccia utilizzando 14 pattern regex specifici per tattica
- Identifica ID di tecniche espliciti (T1566.001) e pattern comportamentali
- Valuta gli span in base alla confidenza con potenziamento dell'indice di parole chiave
- Nessuna chiamata LLM — puro pattern matching per la velocità

#### 3. **BatchRetrieverAgent** - Recupero candidati
- Utilizza la ricerca vettoriale KNN di OpenSearch per trovare tecniche candidate per ogni span
- Deduplica i testi degli span identici prima della codifica per evitare embedding ridondanti
- Restituisce i top-k candidati con punteggi di similarità per ogni span

#### 4. **Pre-filter** - Riduzione degli span
- Limita gli span a `max_spans_per_technique` (default 2) per tecnica candidata
- Mantiene gli span con punteggio più alto per candidato per preservare la qualità delle evidenze
- Riduce le chiamate LLM del mapper di circa il 46% con una perdita minima di tecniche

#### 5. **DiscoveryAgent** - Scoperta LLM (condizionale)
- Attivato quando la confidenza del retriever è bassa (media <0.7)
- Utilizza l'LLM per scoprire tecniche che la ricerca vettoriale non ha rilevato
- Una singola chiamata batch per tutti gli span a bassa confidenza

#### 6. **BatchMapperAgent** - Mappatura delle tecniche (LLM)
- Elabora in batch gli span in gruppi fino a 10 (`MAX_MAPPER_BATCH_SIZE`, default ridotto da 25 a 10 nel 2026-05 per limitare il troncamento del cloud-LLM)
- Estrae TUTTE le tecniche rilevanti per ogni span con punteggi di confidenza
- Utilizza la validazione dello schema JSON per un output strutturato

#### 7. **EvidenceVerifierAgent** - Validazione delle evidenze
- Verifica basata su pattern di citazioni e riferimenti di riga
- Valuta la qualità delle evidenze su una scala da 40 a 100 punti
- Nessuna chiamata LLM — regex e corrispondenza testuale

#### 8. **ConsolidatorAgent** - Consolidamento delle evidenze
- Unisce le tecniche duplicate trovate in più span
- Aggrega le evidenze utilizzando la similarità di Jaccard (soglia >85%)
- Produce l'elenco finale delle tecniche con punteggi di confidenza consolidati

#### 9. **AttackFlowSynthesizer** - Generazione di sequenze (LLM)
- Analizza i marcatori temporali ("first", "then", "after")
- Inferisce relazioni causali dalla narrazione
- Crea oggetti STIX Attack Flow con archi probabilistici
- Torna al modello di co-occorrenza quando la sequenza non è chiara

### Ottimizzazioni delle prestazioni

- **Smart Chunking**: documenti divisi in chunk da 2KB con sovrapposizione
- **Elaborazione batch**: il mapper elabora fino a 25 span per chiamata LLM
- **Elaborazione parallela**: i chunk vengono elaborati in parallelo su thread di lavoro
- **Caching delle risposte**: le risposte LLM vengono memorizzate nella cache per evitare chiamate duplicate
- **Terminazione anticipata**: le estrazioni ad alta confidenza saltano la verifica
- **TechniqueCache**: tutte le tecniche ATT&CK caricate all'avvio per ricerche O(1)
- **Pre-filter**: limita gli span per tecnica candidata prima del mapper LLM (46% di chiamate in meno)
- **Embedding in batch**: embedding delle tecniche generati in batch (2-5 volte più veloce)
- **Pool di connessioni**: connessioni Neo4j/OpenSearch condivise tra le richieste
- **Batch UNWIND**: scritture Neo4j raggruppate tramite UNWIND (30-40 query → 6-7)
- **Pre-riscaldamento del modello**: modello di embedding caricato all'avvio per evitare la latenza di cold-start

### Tempi di elaborazione

| Dimensione documento | Tempo di elaborazione | Tecniche estratte |
|--------------|-----------------|---------------------|
| Piccolo (<5KB) | 10-20 secondi | 5-10 tecniche |
| Medio (5-15KB) | 20-40 secondi | 10-15 tecniche |
| Grande (>15KB) | 30-60 secondi | 15-25 tecniche |

## Analisi di co-occorrenza

Bandjacks fornisce analisi per comprendere le relazioni tra le tecniche.

> **Nota:** L'analisi richiede dati `AttackEpisode` e `AttackAction` in Neo4j. Questi vengono creati quando:
> - I report vengono elaborati attraverso la pipeline di estrazione
> - I flussi di attacco vengono creati tramite `/v1/flows/build`
> - I bundle STIX con episodi di attacco vengono importati
>
> Se non esistono episodi, l'analisi restituirà risultati vuoti.

### Co-occorrenza globale

Calcola quali tecniche compaiono frequentemente insieme in tutti gli episodi di attacco:```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}")

### Pacchetti di tecniche

Identifica i pacchetti di tecniche che co-occorrono frequentemente (3-5 tecniche):```python
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/bundles",
    json={"min_support": 3, "min_size": 3, "max_size": 5}
)

## Sistema di Revisione Human-in-the-Loop

Bandjacks include un sistema di revisione completo per la validazione delle informazioni estratte:

### Interfaccia di Revisione Unificata

Il sistema di revisione presenta tutti gli elementi estratti in un'unica interfaccia:```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. Ricerca delle Tecniche

Cerca le tecniche ATT&CK utilizzando il linguaggio naturale:```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. Generazione dei modelli AttackFlow

Crea modelli di co-occorrenza che mostrano come gli attori delle minacce utilizzano le tecniche insieme:```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'])}")

I modelli AttackFlow usano la **co-occorrenza** piuttosto che l'ordinamento sequenziale, poiché gli intrusion set non dispongono di informazioni intrinseche sulla sequenza. Le tecniche sono collegate da:
- **Archi intra-tattici**: Tra tecniche nella stessa tattica della kill chain
- **Archi inter-tattici**: Tra tecniche appartenenti a tattiche adiacenti
- **Pattern hub-spoke**: Per insiemi di tecniche di grandi dimensioni, per evitare l'esplosione degli archi

Consulta la [Guida alla generazione di AttackFlow](https://github.com/blevene/bandjacks/blob/HEAD/docs/ATTACKFLOW_GENERATION.md) per un uso dettagliato.

## Formati di Input Supportati

La pipeline di estrazione supporta molteplici formati di input:

- **Testo semplice** - Contenuto testuale diretto
- **Markdown** - Documenti markdown formattati
- **PDF** - Tramite estrazione con pdfplumber
- **HTML** - Tramite parsing con BeautifulSoup
- **JSON** - Estrazione di dati strutturati

### Estrazione da Testo Semplice```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
}))

### Estratto da 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"])
})

### Costruire flussi di attacco```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")

## Endpoint API

### Endpoint principali

- `POST /v1/stix/load/attack` - Carica i dati MITRE ATT&CK
- `POST /v1/reports/ingest` - Ingestione report sincrona (<5KB)
- `POST /v1/reports/ingest_async` - Ingestione report asincrona (>5KB)
- `POST /v1/reports/ingest/upload` - Carica file PDF/TXT
- `GET /v1/reports/jobs/{id}/status` - Controlla lo stato del job
- `POST /v1/reports/{id}/unified-review` - Invia le decisioni di revisione
- `POST /v1/search/ttx` - Cerca tecniche
- `GET /v1/graph/technique/{id}` - Ottieni i dettagli della tecnica

### Flussi di attacco

- `POST /v1/flows/build` - Genera modelli di co-occorrenza AttackFlow
- `GET /v1/flows/{flow_id}` - Recupera i dettagli di uno specifico AttackFlow
- `POST /v1/flows/search` - Cerca flussi di attacco simili
- `GET /v1/flows/dump` - Esportazione in blocco dei flussi con paginazione e filtri

### Analisi

- `GET /v1/analytics/cooccurrence/global` - Metriche globali di co-occorrenza
- `GET /v1/analytics/cooccurrence/conditional` - Probabilità condizionate
- `GET /v1/analytics/cooccurrence/bundles` - Bundle di tecniche
- `GET /v1/analytics/cooccurrence/actor` - Pattern specifici per attore
- `GET /v1/coverage/gaps` - Lacune nella copertura delle tecniche

### Difesa e rilevamento

- `GET /v1/defense/technique/{id}` - Ottieni raccomandazioni difensive
- `GET /v1/detections/technique/{id}` - Strategie di rilevamento
- `POST /v1/sigma/validate` - Valida regole Sigma

### Monitoraggio

- `GET /health` - Controllo di integrità di base
- `GET /health/live` - Sonda di liveness per Kubernetes
- `GET /health/ready` - Sonda di readiness per Kubernetes
- `GET /health/components/{component}` - Integrità del singolo componente
- `GET /v1/costs/stats` - Tracciamento dei costi LLM (aggregato giornaliero per modello)
- `GET /v1/cache/stats` - Ottieni statistiche cache LLM
- `POST /v1/cache/clear` - Svuota la cache LLM
- `GET /v1/compliance/report` - Metriche di conformità
- `GET /v1/drift/status` - Stato del rilevamento di deriva
- `GET /v1/ml-metrics/performance` - Metriche del modello ML

### Attori e provenienza

- `GET /v1/actors` - Elenca gli attori delle minacce
- `GET /v1/actors/{id}` - Ottieni i dettagli dell'attore
- `GET /v1/provenance/{object_id}` - Provenienza dell'oggetto
- `GET /v1/provenance/{object_id}/lineage` - Catena completa di discendenza
- `GET /v1/provenance/{object_id}/evidence` - Estratti di prove

### Funzionalità solo API (nessuna UI/CLI)

Questi endpoint sono pienamente funzionali ma sono accessibili esclusivamente tramite API REST (nessuna pagina frontend o comando CLI):

#### Simulazione dei percorsi di attacco
- `POST /v1/simulation/paths` - Simula percorsi di attacco a partire da tecnica/gruppo iniziale
- `POST /v1/simulation/predict` - Prevede le prossime tecniche più probabili dato lo stato attuale
- `POST /v1/simulation/whatif` - Analisi what-if per scenari difensivi
- `POST /v1/simulation/scenario` - Simula a partire da insiemi di gruppi/software/tecniche
- `GET /v1/simulation/statistics/{technique_id}` - Statistiche di utilizzo della tecnica
- `GET /v1/simulation/groups/{group_id}/patterns` - Pattern di attacco del gruppo
- `POST /v1/simulation/compare` - Confronta più percorsi di attacco

#### Politica MDP e rollout
- `POST /v1/simulate/rollout` - Simulazione di rollout PTG
- `POST /v1/simulate/mdp` - Calcola la politica difensiva ottimale MDP
- `GET /v1/simulate/models` - Elenca i modelli PTG disponibili

#### Rilevamento deriva e monitoraggio
- `GET /v1/drift/status` - Stato attuale della deriva su tutte le metriche
- `POST /v1/drift/analyze` - Esegui analisi della deriva con soglie personalizzate
- `GET /v1/drift/alerts` - Ottieni gli avvisi di deriva attivi
- `POST /v1/drift/alerts/{alert_id}/acknowledge` - Conferma avviso
- `GET /v1/drift/metrics/{metric_name}` - Ottieni una specifica metrica di deriva

#### Tracciamento metriche ML
- `POST /v1/ml-metrics/prediction` - Registra la previsione del modello per il tracciamento
- `POST /v1/ml-metrics/review` - Registra le metriche delle decisioni di revisione
- `POST /v1/ml-metrics/coverage-gap` - Registra una lacuna di copertura
- `GET /v1/ml-metrics/performance` - Ottieni le metriche di prestazione del modello
- `GET /v1/ml-metrics/dashboard` - Esporta le metriche della dashboard

#### Notifiche
- `GET /v1/notifications/history` - Ottieni la cronologia delle notifiche
- `POST /v1/notifications/clear-history` - Svuota la cronologia delle notifiche
- `GET /v1/notifications/config` - Ottieni la configurazione delle notifiche
- `POST /v1/notifications/test` - Invia notifica di test

#### Gestione aggiornamento vettori
- `GET /v1/vectors/status` - Stato del sistema di aggiornamento vettori
- `GET /v1/vectors/metrics` - Metriche dettagliate di aggiornamento vettori
- `POST /v1/vectors/update` - Attiva manualmente l'aggiornamento vettori
- `POST /v1/vectors/process-batch` - Forza l'elaborazione batch
- `DELETE /v1/vectors/queue` - Svuota la coda di aggiornamenti in sospeso
- `GET /v1/vectors/health` - Controllo di integrità del sistema vettori

#### Ignorelist entità
- `GET /v1/ignorelist` - Ottieni lo stato attuale della ignorelist
- `POST /v1/ignorelist/add` - Aggiungi entità alla ignorelist
- `DELETE /v1/ignorelist/remove` - Rimuovi entità dalla ignorelist
- `POST /v1/ignorelist/reload` - Ricarica la ignorelist dal disco

#### Revisione dei pattern candidati
- `GET /v1/review/candidates` - Elenca i pattern di attacco candidati
- `POST /v1/review/candidates` - Crea un pattern candidato
- `GET /v1/review/candidates/{id}` - Ottieni i dettagli del candidato
- `POST /v1/review/candidates/{id}/approve` - Approva il candidato
- `POST /v1/review/candidates/{id}/reject` - Rifiuta il candidato
- `GET /v1/review/candidates/{id}/similar` - Trova pattern simili
- `GET /v1/review/candidates/stats/summary` - Statistiche dei candidati

### Documentazione API completa

Accedi alla documentazione API completa all'indirizzo:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## Architettura

### Struttura del progetto```
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à provider:** API locale > Gemini > OpenAI > proxy LiteLLM.
Quando è configurato un server locale, i provider cloud vengono automaticamente aggiunti come fallback.

#### Esempi comuni di server locali

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

### Configurazione dell'estrazione

Il sistema utilizza una singola pipeline asincrona ad alte prestazioni con opzioni configurabili:```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)
}

### Soglie di confidenza

Controlla la qualità dell'estrazione:```python
{
    "confidence_threshold": 50.0,  # Minimum confidence (0-100)
    "auto_ingest": True            # Auto-add high-confidence results
}

### Esempio di risposta di salute```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
      }
    }
  }
}

## Performance Optimization

### Caching

Il sistema include la memorizzazione nella cache automatica delle risposte LLM per migliorare le prestazioni:```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")

## Sicurezza

### Validazione dell'input

- **Prevenzione dell'iniezione Cypher**: Tutti gli endpoint di query sui grafi validano i parametri `relationship_types` forniti dall'utente rispetto a un'allowlist di tipi di relazione noti (USES, MITIGATES, HAS_TACTIC, ecc.) oltre a un pattern regex rigoroso (`^[A-Z][A-Z0-9_]*$`). L'input non valido restituisce 400 prima della costruzione della query.
- **Validazione JSON Schema**: Le risposte LLM vengono validate rispetto agli schemi JSON per impedire che dati malformati entrino nella pipeline.
- **Validazione ADM**: Tutti i contenuti STIX devono superare la validazione del modello dati ATT&CK prima dell'ingestione.

### Autenticazione e autorizzazione

- **Autenticazione JWT**: Middleware opzionale per l'autenticazione API (`JWTAuthMiddleware`)
- **Limitazione della frequenza**: Limitazione della frequenza per endpoint con soglie configurabili
- **CORS**: Condivisione delle risorse cross-origin configurabile

## Funzionalità avanzate

### Tracciamento della provenienza

Ogni entità estratta include la provenienza completa:```python
# Get provenance for an object
response = httpx.get(
    "http://localhost:8000/v1/provenance/attack-pattern--abc123"
)

### Analisi della copertura

Analizza la copertura della tua threat intelligence:```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']}%")

## Stato delle Funzionalità

Questa sezione fornisce trasparenza sullo stato di implementazione delle varie funzionalità:

### Pienamente Funzionanti ✅
- **Pipeline di estrazione dei report** - L'estrazione delle tecniche basata su LLM funziona end-to-end
- **Caricamento MITRE ATT&CK** - Carica i dati ATT&CK enterprise/mobile/ICS in Neo4j
- **Ricerca vettoriale** - Ricerca semantica basata su OpenSearch per le tecniche
- **Sistema di revisione** - Flusso di lavoro di revisione con intervento umano tramite API e UI
- **Monitoraggio della salute** - Controlli di salute dei componenti e probe Kubernetes
- **Comandi CLI di query/amministrazione** - Ricerca, traversal del grafo, gestione della cache
- **Generazione di flussi di attacco** - Costruzione di flussi basata su co-occorrenze per set di intrusioni
- **Simulazione di attacchi** - Simulazione di percorsi basata su MDP tramite `/simulation/*` e `/simulate/*`
- **Report di copertura** - Report JSON per viste esecutiva, tecnica, tattica e operativa

### Funzionali con Dipendenze dai Dati ⚠️
- **Analisi di co-occorrenze** - Richiede nodi `AttackEpisode` dalla lavorazione dei report
- **Analisi degli attori** - Richiede episodi attribuiti a set di intrusioni
- **Bundle di tecniche** - Richiede dati di episodi sufficienti per il pattern mining
- **Comandi CLI di analisi** - Funzionano ma restituiscono dati vuoti se non esistono episodi

### Solo API (Nessuna UI/CLI) 🔌
Queste sono funzionalità completamente implementate accessibili solo tramite API REST:
- **Simulazione del percorso di attacco** - Route `/simulation/*` per previsione del percorso e analisi what-if
- **Risolutore di policy MDP** - `/simulate/mdp` per il calcolo della policy di difesa ottimale
- **Rilevamento del drift** - Route `/drift/*` per monitorare il drift di qualità dei dati
- **Metriche ML** - `/ml-metrics/*` per tracciare le prestazioni del modello nel tempo
- **Gestione dei vettori** - `/vectors/*` per la gestione degli embedding vettoriali
- **Ignorelist delle entità** - `/ignorelist/*` per filtrare le entità falso positive
- **Pattern candidati** - `/review/candidates/*` per i candidati di nuove tecniche
- **Notifiche** - `/notifications/*` per configurazione e cronologia degli avvisi
- **Provenienza** - `/provenance/*` per il tracciamento della discendenza dell'estrazione
- **Conformità** - `/compliance/*` per il reporting delle metriche di conformità

### Sperimentale (in `llm/experimental/`) 🧪
- **PTG (Probabilistic Threat Graph)** - Logica principale implementata, test limitati
- **Integrazione Judge** - Validazione delle sequenze basata su LLM
- **Simulatore di flussi di attacco** - Motore di simulazione basato su flussi
- **Estrattore di sequenze** - Estrae sequenze dai flussi

### Rimossi/Puliti 🗑️
Le seguenti funzionalità stub sono state rimosse dall'API:
- ~~Analisi della copertura della piattaforma~~ - Restituiva dati stub hardcoded
- ~~Analisi delle tendenze~~ - Restituiva dati sintetici casuali
- ~~Esportazione report CSV/PDF~~ - Restituiva 501; ora solo JSON
- ~~Inferenza di sequenze Gemini~~ - Era uno stub 501; usa invece `/sequence/propose`

### Matrice di Connettività

| Area funzionale | Frontend UI | CLI | API REST |
|--------------|-------------|-----|----------|
| Gestione dei report | ✅ | ✅ | ✅ |
| Flusso di revisione | ✅ | ✅ | ✅ |
| Ricerca (TTX) | ✅ | ✅ | ✅ |
| Analisi di co-occorrenze | ✅ | ✅ | ✅ |
| Analisi di copertura | ✅ | - | ✅ |
| Monitoraggio della salute | ✅ | - | ✅ |
| Rilevamenti/Sigma | ✅ | - | ✅ |
| Flussi di attacco | ✅ | - | ✅ |
| Overlay difensivo | ✅ | - | ✅ |
| Sequenze/PTG | ✅ | - | ✅ |
| Attori | ✅ | - | ✅ |
| Simulazione di attacchi | - | - | ✅ |
| Rilevamento del drift | - | - | ✅ |
| Metriche ML | - | - | ✅ |
| Gestione dei vettori | - | - | ✅ |
| Ignorelist delle entità | - | - | ✅ |
| Pattern candidati | - | - | ✅ |
| Notifiche | - | - | ✅ |
| Provenienza | - | - | ✅ |
| Conformità | - | - | ✅ |

### Pagine del Frontend
| Pagina | Stato | Note |
|------|--------|-------|
| `/reports` | ✅ Funzionante | Elenca, crea, visualizza report |
| `/reports/[id]/review` | ✅ Funzionante | Flusso di revisione completo |
| `/analytics/cooccurrence` | ⚠️ Dipende dai dati | Mostra KPI se esistono episodi |
| `/analytics/cooccurrence/pairs` | ⚠️ Dipende dai dati | Chiama l'API reale |
| `/analytics/cooccurrence/bundles` | ⚠️ Dipende dai dati | Chiama l'API reale |
| `/analytics/cooccurrence/actors` | ⚠️ Dipende dai dati | Chiama l'API reale |
| `/health` | ✅ Funzionante | Stato di salute in tempo reale |

## Risoluzione dei Problemi

### Problemi Comuni

1. **Connessione OpenSearch fallita**
   - Assicurati che OpenSearch sia in esecuzione: `curl http://localhost:9200`
   - Verifica che l'indice esista: `curl http://localhost:9200/bandjacks_attack_nodes-v1`

2. **Connessione Neo4j fallita**
   - Verifica che Neo4j sia in esecuzione: `neo4j status`
   - Controlla che `NEO4J_PASSWORD` sia impostata nel file `.env`
   - Assicurati che la password corrisponda alla tua istanza Neo4j
   - Se vedi "NEO4J_PASSWORD environment variable is required", devi impostarla nel tuo file `.env`

3. **Bassa recall di estrazione**
   - Assicurati di usare il metodo `agentic_v2`
   - Verifica che la chiave API LLM sia valida
   - Verifica che il nome del modello sia corretto (gemini-flash-latest)

4. **Errori di timeout**
   - Aumenta le impostazioni di timeout per documenti di grandi dimensioni
   - Considera di suddividere in chunk i report molto grandi

5. **Il frontend non si connette all'API**
   - Assicurati che l'API sia in esecuzione sulla porta 8000
   - Controlla le impostazioni CORS nella configurazione dell'API

### Modalità Debug

Abilita la registrazione dettagliata:```python
import logging
logging.basicConfig(level=logging.DEBUG)

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

### Contribuire

1. Fai un fork del repository
2. Crea un feature branch
3. Apporta le tue modifiche
4. Esegui i test: `uv run pytest`
5. Esegui il linting: `uv run ruff check`
6. Invia una pull request

### Qualità del codice```bash
# Format code
uv run ruff format

# Check linting
uv run ruff check

# Type checking
uv run mypy bandjacks