blevene/standalone_tdoExtrahiert strukturierte Cyber Threat Intelligence (CTI) aus PDF-, DOCX- und TXT-Dokumenten unter Verwendung von LLMs. Erzeugt MITRE ATT&CK-Angriffsabläufe, Erkennungsmöglichkeiten und umfassende Entity-Relationship-Graphen.
Ein leistungsstarkes, eigenständiges Kommandozeilen-Tool zur Extraktion von Cyber Threat Intelligence (CTI) aus Dokumenten unter Verwendung großer Sprachmodelle mit erweiterten strukturierten Ausgabefunktionen.
# Klonen oder herunterladen des standalone-tdo Ordners
cd standalone-tdo
# Virtuelle Umgebung erstellen (empfohlen)
python -m venv .venv
source .venv/bin/activate # Unter Windows: .venv\Scripts\activate
# Abhängigkeiten installieren
pip install -r requirements.txt
Das Tool verwendet Umgebungsvariablen, die aus einer .env-Datei geladen werden:
# Beispielkonfiguration kopieren
cp env.example .env
# .env mit Ihren Einstellungen bearbeiten
# Erforderliche Variablen:
GEMINI_API_KEY=Ihr-Google-AI-API-Key-hier
GEMINI_MODEL=gemini-2.5-flash
Einen Gemini-API-Key erhalten:
.env-DateiVerfügbare Modelle:
gemini-2.5-flash-preview-05-20 (empfohlen – schnell und kosteneffizient)gemini-2.5-pro-preview-06-05 (leistungsstärker, langsamer)# Einzelne Datei mit allen Funktionen verarbeiten
python tdo_bulk.py report.pdf --flow --opps
# Mehrere Dateien verarbeiten
python tdo_bulk.py file1.pdf file2.docx file3.txt
# Alle Dateien in einem Verzeichnis mit parallelen Arbeitern verarbeiten
python tdo_bulk.py reports/ -j 4
# Umfassende Analyse mit Bewertung generieren
python tdo_bulk.py report.pdf --flow --opps --eval-opps
usage: tdo_bulk.py [options] FILE [FILE ...]
Positionsargumente:
FILE Eine oder mehrere zu verarbeitende Dateien oder Verzeichnisse
Kernoptionen:
-o, --output DIR Ausgabeverzeichnis (Standard: ./extracted_data)
--csv FILE Zusammenfassung als CSV exportieren
-j, --jobs N Anzahl paralleler Arbeiter (Standard: 1)
--retries N LLM-Wiederholungsanzahl (Standard: 2)
--backoff SEC Exponentielle Backoff-Basis (Standard: 1.5)
Analysefunktionen:
--flow Attack-Flow JSON generieren
--opps Bedrohungserkennungsmöglichkeiten generieren
--eval-opps Qualität der Erkennungsmöglichkeiten bewerten
--debug-opps Debug-Informationen für die Generierung von Möglichkeiten anzeigen
Ausgabekontrolle:
-q, --quiet Minimale Konsolenausgabe
-v, --verbose Debug-Level-Logging
-h, --help Hilfemeldung anzeigen und beenden
# Grundlegende CTI-Extraktion
python tdo_bulk.py threat_report.pdf
# Vollständige Analyse mit allen Funktionen
python tdo_bulk.py apt_report.pdf --flow --opps --eval-opps
# Batch-Verarbeitung mit parallelen Arbeitern
python tdo_bulk.py reports_folder/ -j 8 --flow --opps
# Ergebnisse als CSV exportieren
python tdo_bulk.py *.pdf --csv results.csv
# Leiser Modus für Automatisierung
python tdo_bulk.py reports/ -q -o /var/soc/cti --opps
Für jede verarbeitete Datei generiert das Tool:
{filename}_extracted.json: Strukturierte CTI-Daten mit umfassendem Schema{filename}_{timestamp}.md: Lesbarer Markdown-Bericht mit allen Analysen--flow)--opps)| Entitätstyp | Beschreibung | Wichtige Eigenschaften |
|---|---|---|
| ThreatActor | Cyber-Bedrohungsgruppen | aliases, primary_motivation, first_seen |
| Tool | Legitime Software | family, capabilities, kill_chain_phases |
| Malware | Schadsoftware | family, capabilities, first_seen, last_seen |
| Technique | MITRE ATT&CK-Techniken | id (T1234), description, kill_chain_phases |
| Tactic | MITRE ATT&CK-Taktiken | id (TA0001), description |
| Infrastructure | IPs, Domains, URLs | type, tags, first_seen, last_seen |
| Indicator | Datei-Hashes, Muster | value, pattern, valid_from, valid_until |
| Vulnerability | CVE-Einträge | id, cvss_score, affected_software |
| Campaign | Benannte Angriffskampagnen | objective, status, first_seen |
| Identity | Zielorganisationen | type, description |
| CourseOfAction | Abwehrmaßnahmen, Patches | type, description |
| Source | Dokumentenherkunft | filename, , |
Attributions- & Akteursbeziehungen:
USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETSTechnische Beziehungen:
TOOL_IMPLEMENTS_TECHNIQUE, HOSTS_ON, COMMUNICATES_WITH, VARIANT_OFDROPS, DOWNLOADS, INDICATES, OBSERVED_ON, EXPLOITSErweiterte Beziehungen:
MITIGATES, DETECTS, IS_SUBTECHNIQUE_OF, FLOW_CONTAINS_STEPFLOW_USED_BY_ACTOR, OBSERVES, SOURCED_FROMAlle Beziehungen unterstützen Eigenschaften wie confidence, source, first_seen, last_seen.
Das Tool generiert evidenzbasierte Erkennungsmöglichkeiten mit:
{
"id": "opp-001",
"name": "Erkennung von PowerShell-Prozessinjektion",
"technique_id": "T1055",
"artefacts": ["powershell.exe mit WriteProcessMemory-Aufrufen"],
"behaviours": ["Prozessinjektion in legitime Prozesse"],
"rationale": "APT-Gruppen verwenden häufig PowerShell zur Prozessinjektion",
"confidence": 0.8,
"source": "PowerShell für Prozessinjektion verwendet (T1055)",
"evidence": [
"• PowerShell führt WriteProcessMemory-Aufrufe aus (Zeile 45)",
"• Beziehung: ThreatActor USES_TECHNIQUE T1055"
]
}
Erweiterte Angriffsabläufe bieten:
{
"flow": {
"label": "AttackFlow",
"pk": "attack-flow--uuid",
"properties": {
"name": "APT29 Mehrstufiger Angriff",
"description": "Sophisticated spear-phishing to data exfiltration flow"
}
},
"steps": [
{
"order": 1,
"entity": {"label": "Technique", "pk": "T1566.001"},
"description": "Lieferung von Spear-Phishing-Anhängen",
"reason": "Methode des Erstzugriffs, zitiert in Berichtsabschnitt 2.1"
}
]
}
tdo_bulk.py).env-Konfiguration mittels python-dotenvtdo_bulk_runner.py)tdo_core/extractors/report_processor.py)tdo_core/detection/opportunity_generator.py)tdo_core/flows/attack_flow_synthesizer.py)tdo_core/report/md_export.py)tdo_core/llm/prompts.py)Dokumenteneingabe → Textextraktion → LLM-Verarbeitung → Strukturierte Ausgabe
↓ ↓ ↓ ↓
PDF/DOCX Sauberer Text Gemini API JSON + Fallback
↓ ↓ ↓ ↓
Multi-Format Vorverarbeitung Pydantic-Schema Validierung
↓ ↓ ↓ ↓
Dateiunterstützung Textbereinigung Strukturierte Daten CTI-Graph
↓
Nachbearbeitung
↓ ↓
Angriffsabläufe Erkennungsmöglichkeiten
↓ ↓
Markdown-Bericht Export
| Variable | Erforderlich | Beschreibung | Beispiel |
|---|---|---|---|
GEMINI_API_KEY | ✅ | Google AI API-Schlüssel | AIza... |
GEMINI_MODEL | ✅ | Zu verwendendes Gemini-Modell | gemini-2.5-flash-preview-05-20 |
| Modell | Geschwindigkeit | Qualität | Kosten | Anwendungsfall |
|---|---|---|---|---|
gemini-2.5-flash-preview-05-20 | ⚡ Schnell | 🎯 Gut | 💰 Niedrig | Produktion, Stapelverarbeitung |
gemini-2.5-pro-preview-06-05 | 🐌 Langsam | 🏆 Exzellent | 💸 Hoch | Komplexe Analysen, Forschung |
Fehler: Erforderliche Umgebungsvariablen fehlen: GEMINI_API_KEY, GEMINI_MODEL
Lösung: Erstellen Sie eine .env-Datei mit beiden erforderlichen Variablen
Nicht unterstützte Datei wird übersprungen: document.rtf
Lösung: Konvertieren Sie in das Format PDF, DOCX, TXT oder MD
Strukturierter Gemini-API-Fehler: ...
Lösungen:
--verbose für detaillierte FehlerprotokolleDas Tool behandelt JSON-Parsing-Probleme automatisch mit:
-j für mehrere Dateien-q für Automatisierungsskripte# Ausführliches Logging aktivieren
python tdo_bulk.py report.pdf -v
# Erkennungsmöglichkeiten debuggen
python tdo_bulk.py report.pdf --opps --debug-opps
# Detaillierte Protokolle exportieren
python tdo_bulk.py report.pdf -v > processing.log 2>&1
Das Tool erfordert Python 3.9+ und diese wichtigen Pakete:
google-generativeai: Google AI (Gemini) API-Client mit strukturierter AusgabePyMuPDF: Hochleistungsfähige PDF-Textextraktionpython-docx: Microsoft Word-Dokumentenverarbeitungpandas: Datenmanipulation und CSV-Exportpydantic: Schema-Validierung und strukturierte Ausgabepython-dotenv: Verwaltung von Umgebungsvariablencleantext: Textvorverarbeitungs-WerkzeugeDiese eigenständige Version:
Sie enthält jedoch alle Kernfunktionen zur CTI-Extraktion und -Analyse, die für die meisten Anwendungsfälle erforderlich sind.
.env-Dateiverwaltung mit dotenv.env-Datei – sie wird durch .gitignore ausgeschlossenGEMINI_API_KEY sicher mithilfe von UmgebungsvariablenExtrahierte JSON- und Markdown-Dateien können enthalten:
Überprüfen Sie die Ausgaben immer vor der öffentlichen Weitergabe.
Bitte melden Sie Sicherheitslücken verantwortungsbewusst. Siehe SECURITY.md für Details.
Dieses Projekt ist unter der MIT-Lizenz lizenziert – siehe LICENSE für Details.
Beiträge sind willkommen! Bitte lesen Sie CONTRIBUTING.md für Richtlinien.
Hilfe benötigt? Führen Sie python tdo_bulk.py --help für eine Kurzreferenz aus oder lesen Sie den Abschnitt zur Fehlerbehebung oben.
document_titlefile_size_mb