Extractor Independiente TDO

Una herramienta de línea de comandos potente e independiente para extraer Inteligencia de Amenazas Cibernéticas (CTI) de documentos mediante Modelos de Lenguaje de Gran Tamaño con capacidades avanzadas de salida estructurada.

🚀 Características

• Soporte de documentos multi-formato: archivos PDF, DOCX, TXT y Markdown
• Integración avanzada de LLM: modelos de Google Gemini con salida estructurada y análisis de respaldo automático
• Esquema CTI integral: 12 tipos de entidades y 24 tipos de relaciones con propiedades enriquecidas
• Generación de oportunidades de detección: crea reglas de detección de amenazas accionables respaldadas por evidencia
• Síntesis de flujos de ataque: genera diagramas de flujo MITRE ATT&CK basados en evidencia
• Fiabilidad de la salida estructurada: esquemas Pydantic con una tasa de éxito del 100 % en el análisis JSON
• Procesamiento en paralelo: procesa varios archivos simultáneamente con seguimiento del progreso
• Portátil y autocontenido: dependencias mínimas con configuración basada en variables de entorno

📋 Inicio rápido

1. Instalación

# Clone or download the standalone-tdo folder
cd standalone-tdo

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configuración

La herramienta utiliza variables de entorno cargadas desde un archivo .env para su configuración:

# Copy the example configuration
cp env.example .env

# Edit .env with your settings
# Required variables:
GEMINI_API_KEY=your-google-ai-api-key-here
GEMINI_MODEL=gemini-2.5-flash

Cómo obtener una clave de API de Gemini:

1. Visita Google AI Studio
2. Crea una nueva clave de API
3. Copia la clave en tu archivo .env

Modelos disponibles:

• gemini-2.5-flash-preview-05-20 (recomendado: rápido y rentable)
• gemini-2.5-pro-preview-06-05 (más potente, más lento)

3. Uso básico

# Process a single file with all features
python tdo_bulk.py report.pdf --flow --opps

# Process multiple files
python tdo_bulk.py file1.pdf file2.docx file3.txt

# Process all files in a directory with parallel workers
python tdo_bulk.py reports/ -j 4

# Generate comprehensive analysis with evaluation
python tdo_bulk.py report.pdf --flow --opps --eval-opps

🎯 Referencia de línea de comandos

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

Comandos de ejemplo

# Basic CTI extraction
python tdo_bulk.py threat_report.pdf

# Full analysis with all features
python tdo_bulk.py apt_report.pdf --flow --opps --eval-opps

# Batch processing with parallel workers
python tdo_bulk.py reports_folder/ -j 8 --flow --opps

# Export results to CSV
python tdo_bulk.py *.pdf --csv results.csv

# Quiet mode for automation
python tdo_bulk.py reports/ -q -o /var/soc/cti --opps

📊 Archivos de salida

Para cada archivo procesado, la herramienta genera:

Salidas principales

• {filename}_extracted.json: datos CTI estructurados con un esquema integral
• {filename}_{timestamp}.md: informe Markdown legible con todo el análisis

Salidas opcionales (con flags)

• JSON de flujo de ataque: estructura de flujo MITRE ATT&CK basada en evidencia (con --flow)
• Oportunidades de detección: reglas de detección accionables con evidencia (con --opps)

🔍 Descripción general del esquema CTI

Tipos de entidades (12 tipos)

Tipo de entidad	Descripción	Propiedades clave
ThreatActor	Grupos de amenazas cibernéticas	aliases, primary_motivation, first_seen
Tool	Software legítimo	family, capabilities, kill_chain_phases
Malware	Software malicioso	family, capabilities, first_seen, last_seen
Technique	Técnicas MITRE ATT&CK	id (T1234), description, kill_chain_phases
Tactic	Tácticas MITRE ATT&CK	id (TA0001), description
Infrastructure	Direcciones IP, dominios, URL	type, tags, first_seen, last_seen
Indicator	Hashes de archivos, patrones	value, pattern, valid_from, valid_until
Vulnerability	Entradas CVE	id, cvss_score, affected_software
Campaign	Campañas de ataque con nombre	objective, status, first_seen
Identity	Organizaciones objetivo	type, description
CourseOfAction	Mitigaciones, parches	type, description
Source	Procedencia del documento	filename, document_title, file_size_mb

Tipos de relaciones (24 tipos)

Relaciones de atribución y de actor:

• USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETS

Relaciones técnicas:

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

Relaciones avanzadas:

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

Todas las relaciones admiten propiedades como confidence, source, first_seen, last_seen.

💡 Oportunidades de detección

La herramienta genera oportunidades de detección basadas en evidencia con:

Características principales

• Mapeo de técnicas: enlaces a técnicas MITRE ATT&CK específicas
• Artefactos observables: indicadores específicos para detectar
• Patrones de comportamiento: secuencias y patrones a monitorear
• Citas de evidencia: citas directas de los informes de origen
• Puntuaciones de confianza: evaluación de fiabilidad (0.0-1.0)
• Evaluación de calidad: puntuación automática con desglose de criterios

Ejemplo de salida

{
  "id": "opp-001",
  "name": "Detect PowerShell Process Injection",
  "technique_id": "T1055",
  "artefacts": ["powershell.exe with WriteProcessMemory calls"],
  "behaviours": ["Process injection into legitimate processes"],
  "rationale": "APT groups commonly use PowerShell for process injection",
  "confidence": 0.8,
  "source": "PowerShell used for process injection (T1055)",
  "evidence": [
    "• PowerShell executes WriteProcessMemory calls (line 45)",
    "• Relationship: ThreatActor USES_TECHNIQUE T1055"
  ]
}

🔗 Síntesis de flujos de ataque

Los flujos de ataque mejorados proporcionan:

• Orden basado en evidencia: pasos respaldados por evidencia temporal y causal
• Referencias a entidades: cada paso hace referencia a entidades CTI extraídas
• Razonamiento explícito: justificación del orden de los pasos con citas
• Cobertura integral: hasta 25 pasos que cubren todo el ciclo de vida del ataque

Ejemplo de flujo de ataque