TDO Standalone Extractor

Un potente strumento da riga di comando autonomo per estrarre Cyber Threat Intelligence (CTI) da documenti utilizzando Large Language Models con capacità di output strutturato avanzate.

🚀 Caratteristiche

• Supporto documenti multi-formato: PDF, DOCX, TXT e file Markdown
• Integrazione LLM avanzata: Modelli Google Gemini con output strutturato e parsing di fallback automatico
• Schema CTI completo: 12 tipi di entità e 24 tipi di relazione con proprietà ricche
• Generazione di Opportunità di Rilevamento: Crea regole di rilevamento delle minacce attuabili con supporto di prove
• Sintesi dei Flussi di Attacco: Genera diagrammi di flusso MITRE ATT&CK basati su prove
• Affidabilità dell'Output Strutturato: Schemi Pydantic con tasso di successo del parsing JSON del 100%
• Elaborazione Parallela: Elabora più file contemporaneamente con tracciamento del progresso
• Portabile e Autonomo: Dipendenze minime con configurazione basata su variabili d'ambiente

📋 Guida Rapida

1. Installazione

# Clona o scarica la cartella standalone-tdo
cd standalone-tdo

# Crea un ambiente virtuale (consigliato)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Installa le dipendenze
pip install -r requirements.txt

2. Configurazione

Lo strumento utilizza variabili d'ambiente caricate da un file .env per la configurazione:

# Copia la configurazione di esempio
cp env.example .env

# Modifica .env con le tue impostazioni
# Variabili richieste:
GEMINI_API_KEY=your-google-ai-api-key-here
GEMINI_MODEL=gemini-2.5-flash

Ottenere una Chiave API Gemini:

1. Visita Google AI Studio
2. Crea una nuova chiave API
3. Copia la chiave nel tuo file .env

Modelli Disponibili:

• gemini-2.5-flash-preview-05-20 (consigliato - veloce ed economico)
• gemini-2.5-pro-preview-06-05 (più potente, più lento)

3. Utilizzo Base

# Elabora un singolo file con tutte le funzionalità
python tdo_bulk.py report.pdf --flow --opps

# Elabora più file
python tdo_bulk.py file1.pdf file2.docx file3.txt

# Elabora tutti i file in una directory con lavoratori paralleli
python tdo_bulk.py reports/ -j 4

# Genera analisi completa con valutazione
python tdo_bulk.py report.pdf --flow --opps --eval-opps

🎯 Riferimento Riga di Comando

usage: tdo_bulk.py [options] FILE [FILE ...]

Positional Arguments:
  FILE                  One or more files or directories to process

Core Options:
  -o, --output DIR      Output directory (default: ./extracted_data)
  --csv FILE            Export summary to CSV file
  -j, --jobs N          Number of parallel workers (default: 1)
  --retries N           LLM retry count (default: 2)
  --backoff SEC         Exponential back-off base (default: 1.5)

Analysis Features:
  --flow                Generate Attack-Flow JSON
  --opps                Generate Threat Detection Opportunities
  --eval-opps           Evaluate detection opportunities quality
  --debug-opps          Show debug information for opportunity generation

Output Control:
  -q, --quiet           Minimal console output
  -v, --verbose         Debug-level logging
  -h, --help            Show help message and exit

Comandi di Esempio

# Estrazione CTI di base
python tdo_bulk.py threat_report.pdf

# Analisi completa con tutte le funzionalità
python tdo_bulk.py apt_report.pdf --flow --opps --eval-opps

# Elaborazione batch con lavoratori paralleli
python tdo_bulk.py reports_folder/ -j 8 --flow --opps

# Esporta risultati in CSV
python tdo_bulk.py *.pdf --csv results.csv

# Modalità silenziosa per automazione
python tdo_bulk.py reports/ -q -o /var/soc/cti --opps

📊 File di Output

Per ogni file elaborato, lo strumento genera:

Output Primari

• {filename}_extracted.json: Dati CTI strutturati con schema completo
• {filename}_{timestamp}.md: Report Markdown leggibile con tutta l'analisi

Output Opzionali (con flag)

• JSON del Flusso di Attacco: Struttura del flusso MITRE ATT&CK basata su prove (con --flow)
• Opportunità di Rilevamento: Regole di rilevamento attuabili con prove (con --opps)

🔍 Panoramica dello Schema CTI

Tipi di Entità (12 Tipi)

Tipo di Entità	Descrizione	Proprietà Chiave
ThreatActor	Gruppi di minacce informatiche	aliases, primary_motivation, first_seen
Tool	Software legittimo	family, capabilities, kill_chain_phases
Malware	Software maligno	family, capabilities, first_seen, last_seen
Technique	Tecniche MITRE ATT&CK	id (T1234), description, kill_chain_phases
Tactic	Tattiche MITRE ATT&CK	id (TA0001), description
Infrastructure	IP, domini, URL	type, tags, first_seen, last_seen
Indicator	Hash di file, pattern	value, pattern, valid_from, valid_until
Vulnerability	Voci CVE	id, cvss_score, affected_software
Campaign	Campagne di attacco nominate	objective, status, first_seen
Identity	Organizzazioni bersaglio	type, description
CourseOfAction	Mitigazioni, patch	type, description
Source	Provenienza del documento	filename, document_title, file_size_mb

Tipi di Relazione (24 Tipi)

Relazioni di Attribuzione e Attore:

• USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETS

Relazioni Tecniche:

• TOOL_IMPLEMENTS_TECHNIQUE, HOSTS_ON, COMMUNICATES_WITH, VARIANT_OF
• DROPS, DOWNLOADS, INDICATES, OBSERVED_ON, EXPLOITS

Relazioni Avanzate:

• MITIGATES, DETECTS, IS_SUBTECHNIQUE_OF, FLOW_CONTAINS_STEP
• FLOW_USED_BY_ACTOR, OBSERVES, SOURCED_FROM

Tutte le relazioni supportano proprietà come confidence, source, first_seen, last_seen.

💡 Opportunità di Rilevamento

Lo strumento genera opportunità di rilevamento basate su prove con:

Caratteristiche Principali

• Mappatura delle Tecniche: Collegamenti a specifiche tecniche MITRE ATT&CK
• Artefatti Osservabili: Indicatori specifici da rilevare
• Pattern Comportamentali: Sequenze e pattern da monitorare
• Citazioni delle Prove: Citazioni dirette dai report sorgente
• Punteggi di Confidenza: Valutazione dell'affidabilità (0.0-1.0)
• Valutazione della Qualità: Punteggio automatico con ripartizione dei criteri

Esempio di Output

{
  "id": "opp-001",
  "name": "Rileva Iniezione di Processo PowerShell",
  "technique_id": "T1055",
  "artefacts": ["powershell.exe con chiamate WriteProcessMemory"],
  "behaviours": ["Iniezione di processo in processi legittimi"],
  "rationale": "I gruppi APT usano comunemente PowerShell per l'iniezione di processo",
  "confidence": 0.8,
  "source": "PowerShell usato per l'iniezione di processo (T1055)",
  "evidence": [
    "• PowerShell esegue chiamate WriteProcessMemory (riga 45)",
    "• Relazione: ThreatActor USES_TECHNIQUE T1055"
  ]
}

🔗 Sintesi dei Flussi di Attacco

I flussi di attacco migliorati forniscono:

• Ordinamento Basato su Prove: Passaggi supportati da prove temporali e causali
• Riferimenti alle Entità: Ogni passaggio fa riferimento a entità CTI estratte
• Ragionamento Esplicito: Giustificazione dell'ordinamento dei passaggi con citazioni
• Copertura Completa: Fino a 25 passaggi che coprono l'intero ciclo di vita dell'attacco