TDO Extrator Autônomo

Uma ferramenta poderosa e autônoma de linha de comando para extrair Inteligência de Ameaças Cibernéticas (CTI) de documentos usando Modelos de Linguagem de Grande Escala (LLMs) com capacidades avançadas de saída estruturada.

🚀 Recursos

• Suporte Multiformato de Documentos: Arquivos PDF, DOCX, TXT e Markdown
• Integração Avançada com LLM: Modelos Google Gemini com saída estruturada e análise de fallback automática
• Esquema CTI Abrangente: 12 tipos de entidade e 24 tipos de relacionamento com propriedades ricas
• Geração de Oportunidades de Detecção: Cria regras acionáveis de detecção de ameaças com respaldo em evidências
• Síntese de Fluxo de Ataque: Gera diagramas de fluxo MITRE ATT&CK baseados em evidências
• Confiabilidade de Saída Estruturada: Esquemas Pydantic com 100% de taxa de sucesso no parsing de JSON
• Processamento Paralelo: Processa vários arquivos simultaneamente com rastreamento de progresso
• Portátil e Autossuficiente: Dependências mínimas com configuração baseada em ambiente

📋 Início Rápido

1. Instalação

# 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. Configuração

A ferramenta usa variáveis de ambiente carregadas de um arquivo .env para configuração:

# 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

Obtendo uma chave de API do Gemini:

1. Visite Google AI Studio
2. Crie uma nova chave de API
3. Copie a chave para o seu arquivo .env

Modelos Disponíveis:

• gemini-2.5-flash-preview-05-20 (recomendado - rápido e econômico)
• gemini-2.5-pro-preview-06-05 (mais poderoso, mais 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

🎯 Referência da Linha de 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

Exemplos de Comandos

# 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

📊 Arquivos de Saída

Para cada arquivo processado, a ferramenta gera:

Saídas Principais

• {filename}_extracted.json: Dados CTI estruturados com esquema abrangente
• {filename}_{timestamp}.md: Relatório markdown legível com toda a análise

Saídas Opcionais (com flags)

• Attack Flow JSON: Estrutura de fluxo MITRE ATT&CK baseada em evidências (com --flow)
• Oportunidades de Detecção: Regras de detecção acionáveis com evidências (com --opps)

🔍 Visão Geral do Esquema CTI

Tipos de Entidade (12 Tipos)

Tipo de Entidade	Descrição	Propriedades Principais
ThreatActor	Grupos de ameaças 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áticas MITRE ATT&CK	id (TA0001), description
Infrastructure	IPs, domínios, URLs	type, tags, first_seen, last_seen
Indicator	Hashes de arquivo, padrões	value, pattern, valid_from, valid_until
Vulnerability	Entradas CVE	id, cvss_score, affected_software
Campaign	Campanhas de ataque nomeadas	objective, status, first_seen
Identity	Organizações alvo	type, description
CourseOfAction	Mitigações, correções (patches)	type, description
Source	Proveniência do documento	filename, document_title, file_size_mb

Tipos de Relacionamento (24 Tipos)

Relacionamentos de Atribuição e Ator:

• USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETS

Relacionamentos Técnicos:

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

Relacionamentos Avançados:

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

Todos os relacionamentos suportam propriedades como confidence, source, first_seen, last_seen.

💡 Oportunidades de Detecção

A ferramenta gera oportunidades de detecção baseadas em evidências com:

Recursos Principais

• Mapeamento de Técnicas: Vínculos a técnicas MITRE ATT&CK específicas
• Artefatos Observáveis: Indicadores específicos para detectar
• Padrões Comportamentais: Sequências e padrões para monitorar
• Citações de Evidências: Citações diretas dos relatórios de origem
• Pontuações de Confiança: Avaliação de confiabilidade (0.0-1.0)
• Avaliação de Qualidade: Pontuação automatizada com detalhamento de critérios

Exemplo de Saída

{
  "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íntese de Fluxo de Ataque

Fluxos de ataque aprimorados oferecem:

• Ordenação Baseada em Evidências: Etapas respaldadas por evidências temporais e causais
• Referência a Entidades: Cada etapa referencia entidades CTI extraídas
• Raciocínio Explícito: Justificativa para a ordenação das etapas com citações
• Cobertura Abrangente: Até 25 etapas cobrindo todo o ciclo de vida do ataque