TDO Extracteur Autonome

Un outil en ligne de commande puissant et autonome pour extraire du renseignement sur les cybermenaces (CTI) à partir de documents à l'aide de grands modèles de langage avec des capacités de sortie structurée avancées.

🚀 Fonctionnalités

• Prise en charge multi-format : fichiers PDF, DOCX, TXT et Markdown
• Intégration LLM avancée : modèles Google Gemini avec sortie structurée et analyse de repli automatique
• Schéma CTI complet : 12 types d'entités et 24 types de relations avec des propriétés riches
• Génération d'opportunités de détection : crée des règles de détection de menaces exploitables avec preuves à l'appui
• Synthèse de flux d'attaque : génère des diagrammes de flux MITRE ATT&CK fondés sur des preuves
• Fiabilité de la sortie structurée : schémas Pydantic avec un taux de réussite d'analyse JSON de 100 %
• Traitement parallèle : traite plusieurs fichiers simultanément avec suivi de la progression
• Portable et autonome : dépendances minimales avec configuration basée sur l'environnement

📋 Démarrage rapide

1. Installation

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

The tool uses environment variables loaded from a .env file for configuration:

# 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

Obtenir une clé API Gemini :

1. Visitez Google AI Studio
2. Créez une nouvelle clé API
3. Copiez la clé dans votre fichier .env

Modèles disponibles :

• gemini-2.5-flash-preview-05-20 (recommandé – rapide et économique)
• gemini-2.5-pro-preview-06-05 (plus puissant, plus lent)

3. Utilisation de base

# 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

🎯 Référence de la ligne de commande

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

Exemples de commandes

# 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

📊 Fichiers de sortie

Pour chaque fichier traité, l'outil génère :

Sorties principales

• {filename}_extracted.json : Données CTI structurées avec schéma complet
• {filename}_{timestamp}.md : Rapport Markdown lisible avec toutes les analyses

Sorties optionnelles (avec options)

• JSON de flux d'attaque : Structure de flux MITRE ATT&CK fondée sur des preuves (avec --flow)
• Opportunités de détection : Règles de détection exploitables avec preuves (avec --opps)

🔍 Aperçu du schéma CTI

Types d'entités (12 types)

Types de relations (24 types)

Relations d'attribution et d'acteur :

• USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETS

Relations techniques :

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

Relations avancées :

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

Toutes les relations prennent en charge des propriétés comme confidence, source, first_seen, last_seen.

💡 Opportunités de détection

L'outil génère des opportunités de détection fondées sur des preuves avec :

Fonctionnalités principales

• Correspondance de technique : liens vers des techniques MITRE ATT&CK spécifiques
• Artefacts observables : indicateurs spécifiques à détecter
• Modèles comportementaux : séquences et motifs à surveiller
• Citations de preuves : citations directes des rapports sources
• Scores de confiance : évaluation de fiabilité (0,0-1,0)
• Évaluation de la qualité : notation automatique avec décomposition des critères

Exemple de sortie

{
  "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"
  ]
}

🔗 Synthèse de flux d'attaque

Les flux d'attaque améliorés fournissent :

• Ordonnancement fondé sur des preuves : étapes soutenues par des preuves temporelles et causales
• Référencement d'entités : chaque étape référence les entités CTI extraites
• Raisonnement explicite : justification de l'ordonnancement des étapes avec citations
• Couverture complète : jusqu'à 25 étapes couvrant l'ensemble du cycle de vie de l'attaque

Exemple de flux d'attaque

{
  "flow": {
    "label": "AttackFlow",
    "pk": "attack-flow--uuid",
    "properties": {
      "name": "APT29 Multi-stage Attack",
      "description": "Sophisticated spear-phishing to data exfiltration flow"
    }
  },
  "steps": [
    {
      "order": 1,
      "entity": {"label": "Technique", "pk": "T1566.001"},
      "description": "Spear-phishing attachment delivery",
      "reason": "Initial access method cited in report section 2.1"
    }
  ]
}

🏗️ Aperçu de l'architecture

Composants principaux

🎯 CLI principale (tdo_bulk.py)

• Point d'entrée avec analyse des arguments et validation de l'environnement
• Charge la configuration .env à l'aide de python-dotenv
• Orchestre le traitement en masse avec suivi de la progression

⚙️ Exécuteur en masse (tdo_bulk_runner.py)

• Gère le traitement parallèle avec ThreadPoolExecutor
• Coordonne les étapes du pipeline d'extraction
• Gère les rappels de progression et la récupération d'erreurs

🧠 Extracteur CTI (tdo_core/extractors/report_processor.py)

• Analyse de documents : prise en charge multi-format (PDF, DOCX, TXT, MD)
• Intégration LLM : Google Gemini avec sortie structurée
• Analyse de repli : analyse JSON manuelle en cas d'échec de la sortie structurée
• Gestion des tokens : découpage automatique pour les grands documents
• Validation de schéma : les modèles Pydantic assurent la cohérence des données

🔍 Générateur TDO (tdo_core/detection/opportunity_generator.py)

• Création d'opportunités de détection fondée sur des preuves
• Correspondance de techniques MITRE ATT&CK
• Évaluation de la qualité avec critères de notation
• Mode débogage pour une analyse détaillée

🌊 Synthétiseur de flux d'attaque (tdo_core/flows/attack_flow_synthesizer.py)

• Génération de flux pilotée par LLM avec preuves à l'appui
• Repli basé sur des règles pour les flux simples
• Ordonnancement des étapes avec raisonnement explicite
• Analyse des relations entre entités

📝 Générateur de rapport (tdo_core/report/md_export.py)

• Création de rapports Markdown lisibles par l'homme
• Présentation structurée des données
• Intégration de tous les composants d'analyse

🎨 Gestion des prompts (tdo_core/llm/prompts.py)

• Modèles de prompts centralisés
• Optimisation de la sortie structurée
• Bonnes pratiques pour l'interaction avec le LLM

Flux de données

Document Input → Text Extraction → LLM Processing → Structured Output
     ↓              ↓                 ↓               ↓
   PDF/DOCX      Clean Text       Gemini API     JSON + Fallback
     ↓              ↓                 ↓               ↓
 Multi-format    Preprocessing    Pydantic Schema  Validation
     ↓              ↓                 ↓               ↓
File Support   Text Cleaning    Structured Data   CTI Graph
                                      ↓
                              Post-Processing
                                 ↓         ↓
                          Attack Flows  Detection Opps
                                 ↓         ↓
                            Markdown Report Export

🛠️ Configuration avancée

Variables d'environnement

Guide de sélection du modèle

🔧 Dépannage

Problèmes courants

Variables d'environnement manquantes

Error: Required environment variables missing: GEMINI_API_KEY, GEMINI_MODEL

Solution : Créez un fichier .env avec les deux variables requises.

Format de fichier non pris en charge

Skipping unsupported file: document.rtf

Solution : Convertissez au format PDF, DOCX, TXT ou MD.

Erreurs de traitement LLM

Structured Gemini API error: ...

Solutions :

• Vérifiez la validité de la clé API
• Vérifiez l'orthographe du nom du modèle
• Essayez d'abord avec des documents plus petits
• Utilisez --verbose pour des journaux d'erreurs détaillés

Problèmes d'analyse JSON

L'outil gère automatiquement les problèmes d'analyse JSON avec :

• Sortie structurée comme méthode principale
• Repli sur l'analyse manuelle
• Réparation JSON pour les réponses tronquées
• Récupération gracieuse des erreurs

Optimisation des performances

• Traitement parallèle : utilisez l'option -j pour plusieurs fichiers
• Sélection du modèle : utilisez des modèles plus rapides pour le traitement en masse
• Mode silencieux : utilisez -q pour les scripts d'automatisation
• Gestion des sorties : organisez avec des répertoires de sortie personnalisés

Mode débogage

# Enable verbose logging
python tdo_bulk.py report.pdf -v

# Debug detection opportunities
python tdo_bulk.py report.pdf --opps --debug-opps

# Export detailed logs
python tdo_bulk.py report.pdf -v > processing.log 2>&1

📦 Dépendances

L'outil nécessite Python 3.9+ et ces packages clés :

• google-generativeai : Client API Google AI (Gemini) avec sortie structurée
• PyMuPDF : Extraction de texte PDF haute performance
• python-docx : Traitement de documents Microsoft Word
• pandas : Manipulation de données et export CSV
• pydantic : Validation de schéma et sortie structurée
• python-dotenv : Gestion des variables d'environnement
• cleantext : Utilitaires de prétraitement de texte

🚧 Limites

Cette version autonome :

• N'inclut pas l'intégration du graphe de connaissances ou Neo4j
• Ne prend pas en charge les fonctionnalités de base de données vectorielles pour la recherche de similarité
• Ne dispose pas de capacités d'augmentation de récupération en temps réel
• Simplifiée par rapport à la plateforme TDO complète

Cependant, elle inclut toutes les capacités d'extraction et d'analyse CTI de base nécessaires pour la plupart des cas d'utilisation.

🔄 Améliorations récentes

• Configuration par environnement : migration vers la gestion de fichiers .env avec dotenv
• Sortie structurée : analyse JSON fiable à 100 % avec sortie structurée Google Gemini
• Schémas améliorés : 12 types d'entités et 24 types de relations complets
• Opportunités de détection : génération de règles de détection fondée sur des preuves avec évaluation
• Améliorations des flux d'attaque : renforcés avec preuves à l'appui et raisonnement explicite
• Aucune valeur par défaut codée en dur : toute la configuration provient des variables d'environnement
• Gestion robuste des erreurs : analyse de repli automatique et récupération gracieuse des erreurs

🔒 Considérations de sécurité

Protection de la clé API

• Ne commettez jamais votre fichier .env – il est exclu par .gitignore
• Stockez GEMINI_API_KEY de manière sécurisée à l'aide de variables d'environnement
• Faites pivoter les clés API périodiquement
• Consultez SECURITY.md pour des conseils de sécurité détaillés

Confidentialité des données

• Le texte des documents est envoyé à l'API Gemini de Google pour traitement
• Examinez les politiques d'utilisation des données de Google avant de traiter des documents sensibles
• Les données extraites peuvent contenir des informations sensibles (IOC, noms d'organisation, chemins de fichiers)
• Examinez les sorties avant de les partager en dehors de votre organisation

Données de sortie

Les fichiers JSON et Markdown extraits peuvent contenir :

• Adresses IP et noms de domaine (indicateurs d'infrastructure)
• Hachages de fichiers et indicateurs techniques
• Informations sur les organisations et les cibles
• Données détaillées sur les acteurs de la menace et les campagnes

Examinez toujours les sorties avant tout partage public.

Signaler des problèmes de sécurité

Veuillez signaler les vulnérabilités de sécurité de manière responsable. Voir SECURITY.md pour plus de détails.

📄 Licence

Ce projet est sous licence MIT – voir LICENSE pour plus de détails.

🤝 Contribuer

Les contributions sont les bienvenues ! Veuillez lire CONTRIBUTING.md pour les directives.

Besoin d'aide ? Exécutez python tdo_bulk.py --help pour une référence rapide ou consultez la section de dépannage ci-dessus.