iocx-dev/iocxEine erweiterbare, deterministische Static-Analysis-Engine, die hochwertige IOCs aus PE-Binärdateien und Text extrahiert – entwickelt für die SOC-Automatisierung und moderne Threat-Analysis-Pipelines.
# IOCX
### **Deterministische, risikofreie IOC-Extraktion für moderne Sicherheits-Pipelines**
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/7470/35e58092394d24631c5bf5a2ef49c2c64bb1726cc5798d35bdaa36800597e402.gif" width="720" alt="IOCX Demo">
</p>
<p align="center"><sub>Statische IOC-Extraktion aus einer PE-Datei mit der IOCX-CLI</sub></p>
<p align="center">
<a href="https://pypi.org/project/iocx/"><img src="https://img.shields.io/pypi/v/iocx?logo=pypi&logoColor=white"></a>
<img src="https://img.shields.io/badge/tests-2802_passed-brightgreen">
<img src="https://img.shields.io/badge/coverage-100%25-brightgreen">
<img src="https://img.shields.io/badge/python-3.12-blue">
<a href="https://github.com/iocx-dev/iocx/actions"><img src="https://img.shields.io/github/actions/workflow/status/iocx-dev/iocx/ci.yml?label=build"></a>
<a href="https://github.com/iocx-dev/iocx/blob/main/LICENSE"><img src="https://img.shields.io/github/license/iocx-dev/iocx"></a>
</p>
# Offizielles IOCX-Projekt
Dies ist die originale IOCX-Engine für deterministische statische IOC-Extraktion und PE-Analyse.
Alle anderen Repositories, die den Namen „iocx“ verwenden, sind **nicht mit diesem Projekt verbunden**.
**Offizielle Links:**
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- Github: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Website: [https://iocx.dev/](https://iocx.dev/)
---
# Warum IOCX wichtig ist
Moderne Malware ist **standardmäßig adversarial** — fehlerhaft, evasiv und darauf ausgelegt, naive Extraktoren zu brechen.
- **Binär-unbewusste Tools** kollabieren bei fehlerhaften PEs
- **Sandboxes** sind unsicher und in CI/CD nicht nutzbar
- **Reproduzierbarkeit** ist für automatisierte Pipelines unerlässlich
**IOCX ist für Umgebungen gebaut, in denen Korrektheit und Determinismus wirklich zählen.**
---
# Die IOCX-Engine
**IOCX ist die offizielle statische IOC-Extraktionsengine** — ein deterministisches, binär-bewusstes System, das für DFIR, SOC-Automatisierung, CI/CD-Sicherheit und groß angelegte Threat-Intel-Pipelines entwickelt wurde.
Im Gegensatz zu reinen Regex-Extraktoren oder sandbox-abhängigen Tools führt IOCX Folgendes durch:
- **reine statische Analyse**
- **kein Ausführungsrisiko**
- **stabile, deterministische Ausgabe**
- **adversarial getestete Heuristiken**
Es ist eine Kernkomponente des MalX Labs-Ökosystems für skalierbare, moderne Bedrohungsanalyse.
---
# IOCX in 10 Sekunden ausprobieren
```bash
echo "http://malicious.example" | iocx -
```
Oder eine PE-Datei sicher scannen:
```bash
iocx suspicious.exe -a deep
```
---
# Warum IOCX existiert
Sicherheitsteams stehen vor drei hartnäckigen Problemen:
1. **Regex-Extraktoren** brechen bei adversarialer Eingabe zusammen
2. **Sandboxing** ist unsicher, langsam und für Automatisierung ungeeignet
3. **Die meisten IOC-Tools** sind inkonsistent, langsam oder erzeugen zwischen Läufen subtil unterschiedliche Ausgaben
IOCX löst dies mit einer **deterministischen, rein statischen Engine**, die für Automatisierung, Sicherheit und Skalierung entwickelt wurde.
---
# Was IOCX *nicht* ist
IOCX ist bewusst **kein**:
- eine Sandbox
- ein Tool zur Verhaltensanalyse
- ein Emulator
- eine Anreicherungs-Engine
Es führt niemals nicht vertrauenswürdigen Code aus.
Es führt niemals dynamische Analysen durch.
Es ist **von Grund auf rein statisch** — für Sicherheit, Determinismus und CI/CD-Kompatibilität.
---
# Designphilosophie
IOCX ist für die Realitäten moderner Malware entwickelt, nicht für die Annahmen veralteter Tools.
### **1. Determinismus statt Mehrdeutigkeit**
Stabile, reproduzierbare Ausgabe — keine Zufälligkeit, keine Volatilität.
### **2. Statisch statt dynamisch**
Ausführung ist unsicher. Statische Analyse ist vorhersehbar, skalierbar und CI-freundlich.
### **3. Adversarial-First-Engineering**
Fehlerhafte PEs, beschädigte RVAs, feindselige Strings — IOCX behandelt sie als normale Eingabe.
### **4. Schema-Stabilität als Vertrag**
Nachgelagerte Systeme sollten bei einem Upgrade niemals brechen.
### **5. Performance ohne Kompromisse**
150–300 MB/s bei reinem Text.
6–15 MB/s bei typischen PEs.
Vorhersehbar selbst unter worst-case-adversarialer Last.
---
Diese Verpflichtungen leiten sich aus einer veröffentlichten Forschungsmethodik zur PE-Strukturanalyse ab — deterministische Fixture-Konstruktion, Single-Anomaly-Disziplin und Windows-Loader-Verhalten als Korrektheits-Orakel. Siehe docs/methodology.md für die vollständige Methodik und [paax.dev](https://paax.dev) für die breitere adversarial-PE-Taxonomie und kommerzielle Fixture-Suite.
# Was IOCX anders macht
| Fähigkeit | **IOCX** | Typische IOC-Extraktoren | Sandbox / Dynamische Tools |
|-----------|-----------|------------------------|--------------------------|
| **Sicherheit** | Zero-Execution, rein statisch | Nur Regex, keine Binärsicherheit | Führt nicht vertrauenswürdigen Code aus (hohes Risiko) |
| **Determinismus** | Vollständig deterministische Ausgabe | Nicht-deterministisch bei Rauschen | Von Grund auf nicht-deterministisch |
| **Binär-Bewusstsein** | Vollständiges PE-Parsing, Heuristiken | Keine Binärunterstützung | Ja, aber unsicher + langsam |
| **Adversariale Resilienz** | Getestet gegen fehlerhafte PEs, feindselige Strings | Leicht zu umgehen | Stürzt oft ab oder klassifiziert falsch |
| **Performance** | 150–300 MB/s (Text), 6–15 MB/s (PE) | Hoch variabel | Extrem langsam |
| **CI/CD-freundlich** | Ja — sicher, deterministisch, schnell | Teilweise | Nein — unsicher für Pipelines |
| **Schema-Stabilität** | Garantiert | Selten | Keine |
**Kurz gesagt:** IOCX ist für die *echte adversariale Realität* gebaut, nicht für idealisierte Eingaben.
---
# Anwendungsfälle
### CI/CD & DevSecOps
- Binärdateien vor dem Release scannen
- Versehentliche URLs, IPs oder Secrets in Builds erkennen
- Sicherheitsgates mit null Ausführungsrisiko durchsetzen
### SOC & Incident Response
- Indikatoren aus Alerts oder Analysten-Zwischenablage-Text extrahieren
- Malware-Samples sicher ohne Ausführung inspizieren
- IOCs in strukturiertes JSON normalisieren
### Threat Intelligence
- Feeds im großen Maßstab verarbeiten
- Unstrukturierte Berichte parsen
- Anreicherungs-Pipelines auf deterministischer Ausgabe aufbauen
### Automatisierung & Skripting
- Logs oder Artefakte durch IOCX leiten
- Die Python-API für ETL- oder Batch-Workflows verwenden
- Mit benutzerdefinierten Detektoren erweitern
---
# Performance-Profile
### **1. Rohe IOC-Extraktion (Text, Logs, Puffer)**
**150–300 MB/s** anhaltender Durchsatz
Schneller Pfad — kein PE-Parsing.
| Detektor | 1 MB Zeit | Durchsatz |
|-----------|-----------|------------|
| Crypto | 0.0037 s | ~270 MB/s |
| Filepaths | 0.0041 s | ~250 MB/s |
| IP | 0.0065 s | ~156 MB/s |
| Domains | 0.0035 s | ~300 MB/s |
---
### **2. Typische PE-Dateien (~39 KB)**
- **0.0122 s** (typisch)
- **0.0145 s** (mit Heuristiken)
- **6–15 MB/s** Durchsatz
---
### **3. Adversariale dichte PE (1,5 MB)**
- **0.192 s**
- **~7,6 MB/s** Durchsatz
- Löst TLS-Anomalien, strukturelle Anomalien, Anti-Debug-Muster aus
---
### **4. Vollständige Engine (Nicht-PE)**
- **1 MB:** 0.038 s
---
# Versions-Highlights
<details>
<summary><strong>Versionshistorie anzeigen</strong></summary>
<br>
### v0.7.6.2 — Import Table Validator
- Neuer deterministischer **struktureller Import-Table-Validator** (`IMPORT_*` Reason Codes).
- `version_info` wird jetzt auf **jeder** Analyseebene geparst und bereitgestellt (nicht nur bei `-a full`), über eine neue begrenzte öffentliche Projektion.
- CLI neu aufgebaut: gebrandete `--version`-Ausgabe, klarere `--help`-Texte, neu organisierte Argumentgruppen.
- Behoben: ein Relocation-Parser-Absturz, der von jedem Eintrag aus erreichbar war, ein PE32+-Data-Directory-Offset-Bug und mehrere stille Export-/Resource-Fehlerausfälle.
- Neuer statischer CI-Check, der verhindert, dass Parser-Fehler-Tags stillschweigend von Validatoren unverarbeitet bleiben.
- Testsuite: 2.136 → 2.802 Tests.
---
### v0.7.6.1 — Exception Directory Validator
- Fügt tiefe semantische Validierung des PE-Exception-Verzeichnisses (`.pdata`) hinzu; 14 neue Reason Codes; 15 Validatoren insgesamt.
- Behebt einen Defekt, der strukturelle Befunde in der gesamten Engine unterdrückt hatte.
- Vier weitere Checks als in Produktion tot identifiziert: zwei Directory-Platzierungen, eine Section-Mapping- und eine Resource-Directory-Bounds-Prüfung.
- **Ausgabesichtbar:** Zuvor unterdrückte oder falsch gekennzeichnete Befunde erscheinen nun.
- Tests: 1620 → 2136. Coverage: 100%.
---
### **v0.7.6 — Erweiterung der strukturellen Validatoren: Debug- und Relocations-Verzeichnisse**
- Zwei neue PE-strukturelle Validatoren — Relocations und Debug
- WIN_CERTIFICATE- und TLS-Validatoren beziehen strukturelle Wahrheit jetzt aus dedizierten Struct-Parsern, unabhängig von pefile
- 12 neue Reason Codes mit prioritätsaufgelösten Sub-Reason-Taxonomien
- Deterministisches Byte-Level-Parsing — keine Abhängigkeit von pefiles lazy Interpretation
- 1620 Tests bei 100% Coverage
---
### **v0.7.5 — Erweiterung der strukturellen Validatoren**
- Vier neue PE-strukturelle Validatoren — Exports, Delay-Load-Imports, VS_VERSIONINFO und Resource-Hierarchie
- 24 neue Reason Codes mit prioritätsaufgelösten Sub-Reason-Taxonomien
- Deterministisches Byte-Level-Parsing — keine Abhängigkeit von pefiles lazy Interpretation
- Sicherheitsrelevante Metadaten — DLL-Characteristics, Subsystem-/Machine-Name-Dekodierung, Entropie pro Resource
- 1370 Tests bei 100% Coverage — End-to-End verifiziert gegen `dumpbin` auf echten Binärdateien
---
### **v0.7.4.1 — Windows-Kompatibilitäts-Hotfix**
- Die `python-magic`-Abhängigkeit entfernt, die auf Windows-Systemen Importfehler verursachte
- Einen reinen Python-Dateityp-Detektor für vollständige plattformübergreifende Portabilität hinzugefügt
- PE-Erkennungslogik durch erzwungene strikte Windows-kompatible PE-Validierung verbessert.
- Keine Verhaltensänderungen bei der IOC-Extraktion
- Der `--min-length`-Konsistenz-Fix ist für **v0.7.5** geplant
---
### **v0.7.4 — Erweitertes Directory-Parsing**
- Vollständiges **Load Config Directory**-Parsing und -Validierung
- Erweiterte Optional-Header-Metadaten für nachgelagerte Heuristiken
- Neue GuardCF-, Cookie-, Anomalie-Heuristiken
- Schnellere PE-Analyse
- 99 PE-Fixtures in der Testsuite; 45 vollständig spezifikationsvalidiert
---
### **v0.7.3 — Strukturelle Korrektheit & deterministische Heuristiken**
- Umfassende Härtung aller PE-strukturellen Validatoren
- Deterministisches, snapshot-stabiles Verhalten
- Klare, konsistente ReasonCodes
- Stärkere Heuristiken auf Basis struktureller Wahrheit
---
### **v0.7.2 — Abhängigkeits-Fix**
- Fehlende `idna`-Abhängigkeit hinzugefügt
- Keine Verhaltens- oder Schemaänderungen
---
### **v0.7.1 — Erweiterung adversarialer Heuristiken & Parser-Härtung**
- Sechs neue PE-Heuristiken
- Erweiterter adversarialer PE-Korpus
- Gehärtete Domain-/URL-/Crypto-/Hash-Extraktoren
- Deterministische, snapshot-validierte Ausgabe
---
### **v0.7.0 — Deterministische Heuristiken & Grundlage für adversariales Testen**
- Deterministische Heuristiken
- Layer-3-adversariale Samples
- Snapshot-Contract-Tests
- Rich-Header-Absturz behoben
---
### **v0.6.0 — Stabiles Ausgabeschema & deterministische Metadaten**
- Vollständig stabiles JSON-Schema
- Normalisierte PE-Metadaten
- Formalisierte Analyseebenen
---
### **v0.5.0 — Analyseebenen, PE-Section-Analyse, Obfuskationshinweise**
- Neues Analyseebenen-System
- PE-Strukturanalyse
- Obfuskationsheuristiken
---
### **v0.4.0 — Plugin-Architektur**
- Plugin-fähige Rule-Engine
- Vereinheitlichter Erkennungsablauf
---
### **v0.3.0 — Crypto-IOC-Erkennung**
- Ethereum- & Bitcoin-Wallet-Erkennung
---
### **v0.2.0 — Hochzuverlässige IP-Erkennung**
- Wesentliche IPv4/IPv6-Verbesserungen
</details>
---
# Schnellstart
### Installation
```bash
pip install iocx
```
### IOCs aus einer Datei extrahieren
```bash
iocx suspicious.exe
```
### Aus Text extrahieren
```bash
echo "Visit http://bad.example.com" | iocx -
```
### PE-Analyse aktivieren
```bash
iocx suspicious.exe -a
```
### Python-API
```python
from iocx.engine import Engine
engine = Engine()
results = engine.extract("suspicious.exe")
print(results)
```
---
# Beispielausgabe
> IOCX erzeugt strukturiertes, deterministisches JSON, das IOCs, PE-Metadaten, Section-Analyse, Heuristiken und Obfuskationsindikatoren enthält.
>
> Das folgende Beispiel ist eine gekürzte Ausgabe eines echten adversarialen PE-Samples. Es demonstriert die Form und Tiefe des Schemas und hält die Größe für Dokumentationszwecke handhabbar.
<details>
<summary><strong>Beispiel-JSON-Ausgabe anzeigen</strong></summary>
```json
{
"file": "heuristic_rich.full.exe",
"type": "PE",
"iocs": {
"urls": ["http://not-a-real-domain.test/payload"],
"domains": ["example-malware.com"],
"ips": ["192.0.2.123"],
"hashes": [
"abcd1234ef567890abcd1234ef567890",
"1234567890",
"3333333333333333"
],
"filepaths": [
"/usr/src/mingw-w64-11.0.1-3build1/mingw-w64-crt/crt/crtexe.c",
"/usr/x86_64-w64-mingw32/include",
"/usr/src/mingw-w64-11.0.1-3build1/mingw-w64-crt/crt/pseudo-reloc.c"
]
},
"metadata": {
"file_type": "PE",
"imports": ["KERNEL32.dll", "msvcrt.dll", "USER32.dll"],
"sections": [
".text", ".data", ".rwx", ".rdata",
"UPX0", ".pdata", ".xdata", ".tls"
],
"resources": [],
"resource_strings": [],
"delayed_imports": [],
"bound_imports": [],
"exports": [],
"signatures": [],
"has_signature": false,
"tls": {
"start_address": 5368758272,
"end_address": 5368758280,
"callbacks": 5368754232
},
"header": {
"entry_point": 5088,
"image_base": 5368709120,
"machine": "AMD64",
"subsystem": "Windows GUI"
},
"optional_header": {
"section_alignment": 4096,
"file_alignment": 512,
"size_of_image": 155648
}
},
"analysis": {
"sections": [
{ "name": ".text", "entropy": 5.92 },
{ "name": ".rwx", "entropy": 0 },
{ "name": "UPX0", "entropy": 0.34 },
{ "name": ".rdata", "entropy": 4.03 }
],
"obfuscation": [
{
"value": "abnormal_section_layout_virtual_only",
"category": "obfuscation_hint",
"metadata": {
"section": ".bss",
"raw_size": 0,
"virtual_size": 384
}
}
],
"extended": [
{
"value": "summary",
"category": "pe_metadata",
"metadata": {
"dll_count": 3,
"import_count": 45,
"resource_count": 0,
"has_tls": true,
"has_signature": false
}
}
],
"heuristics": [
{
"value": "packer_suspected",
"metadata": {
"reason": "packer_section_name",
"section": "UPX0"
}
},
{
"value": "anti_debug_heuristic",
"metadata": {
"reason": "anti_debug_api_import",
"dll": "kernel32.dll",
"function": "CheckRemoteDebuggerPresent"
}
},
{
"value": "anti_debug_heuristic",
"metadata": {
"reason": "timing_api_import",
"dll": "kernel32.dll",
"function": "GetTickCount"
}
},
{
"value": "pe_structure_anomaly",
"metadata": {
"reason": "section_overlaps_headers",
"section": ".bss",
"raw_address": 0,
"size_of_headers": 1536
}
},
{
"value": "pe_structure_anomaly",
"metadata": {
"reason": "data_directory_overlap",
"directory_a": "IMAGE_DIRECTORY_ENTRY_IMPORT",
"directory_b": "IMAGE_DIRECTORY_ENTRY_IAT"
}
}
]
}
}
```
</details>
---
# Architektur
```
iocx/
├── examples/
├── docs/
├── tests/
└── iocx
├── detectors/
├── parsers/
├── plugins/
├── cli/
└── analysis/
```
---
# Plugin-Ökosystem & Erweiterbarkeit
IOCX ist darauf ausgelegt, sicher und vorhersehbar erweitert zu werden.
Plugins sind **erstklassige Bürger**, validiert durch dieselben deterministischen Snapshot-Tests wie die Kern-Engine.
Du kannst Folgendes bauen:
- benutzerdefinierte IOC-Detektoren
- benutzerdefinierte Regex-Regeln
- binär-bewusste Plugins
- interne Heuristiken
- pipelinespezifische Extraktoren
Siehe:
- `docs/specs/overlap-suppression.md`
- `docs/specs/plugin-authoring-guidelines.md`
---
# Ökosystem-Überblick
IOCX ist mehr als eine einzelne Binärdatei — es ist ein modulares Ökosystem:
- **Core Engine** — deterministische IOC-Extraktion + PE-Analyse
- **Plugin-System** — benutzerdefinierte Detektoren und Analysemodule
- **Adversarialer Korpus** — fehlerhafte PEs, feindselige Strings, Fuzz-Samples
- **Snapshot-Testing-Framework** — gewährleistet deterministische Ausgabe
- **Performance-Benchmarks** — in CI erzwungen
- **Dokumentations-Suite** — Spezifikationen, Verträge und Plugin-Anleitungen
---
# Wer verwendet IOCX?
IOCX wird verwendet in:
- DFIR-Teams
- SOC-Automatisierungs-Pipelines
- CI/CD-Sicherheitsgates
- Threat-Intel-Plattformen
- Malware-Forschungslaboren
- Sicherheitsengineering-Teams
Überall dort, wo Indikatoren **sicher**, **deterministisch** und **im großen Maßstab** extrahiert werden müssen, passt IOCX.
---
# Sicheres Testen (keine Malware erforderlich)
Alle Test-Samples sind:
- Synthetisch
- Benign
- Öffentlich sicher (EICAR, GTUBE)
- Darauf ausgelegt, versehentliche Malware-Handhabung zu vermeiden
---
# Performance-Garantien
IOCX erzwingt strenge Performance-Schwellenwerte in CI, um Folgendes sicherzustellen:
- Keine Regex-Backtracking-Blockaden
- Keine pathologischen Verlangsamungen
- Stabile Performance über Releases hinweg
Siehe:
- `docs/performance.md`
---
# Projektidentität & Namensgebung
Der Name **IOCX** bezieht sich ausschließlich auf die offizielle Engine, die veröffentlicht ist auf:
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- GitHub: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
### Nicht erlaubt
- Repositories mit dem Namen `iocx`
- Tools mit dem Namen „iocx“, die nicht Teil dieses Projekts sind
- Andeutung einer Zugehörigkeit ohne Erlaubnis
### Erlaubt
- `iocx-<plugin>`
- `iocx-extension-<name>`
- `iocx-detector-<feature>`
---
# Offizielle IOCX-Repositories
- Core Engine: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Plugins Meta-Repo: [https://github.com/iocx-dev/iocx-plugins](https://github.com/iocx-dev/iocx-plugins)
- Dokumentation: [https://github.com/iocx-dev/iocx/tree/main/docs/specs](https://github.com/iocx-dev/iocx/tree/main/docs/specs)
- PyPI-Paket: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
---
# Roadmap
Die IOCX-Entwicklung konzentriert sich auf Stabilität, Erweiterbarkeit und tiefergehende statische Analyseabdeckung.
Die folgenden Punkte repräsentieren laufende Arbeits- und Erkundungsbereiche.
- **Erweiterte PE-Heuristiken** (Delay-Load-Verhalten, strukturelle Anomalien, Relocation-Muster)
- **Selektive Unterdrückungsregeln** für OSINT-, DFIR- und Threat-Intel-Workflows
- **ELF- und Mach-O-Metadatenextraktion**
- **Batch-Analysemodus** für Multi-Artefakt-Workflows
- **YARA-artige Ausgabemodi** und Anreicherungs-Hooks
- **Binär-agnostische statische Analyse**
- **Plattformübergreifendes Plugin-Ökosystem**
- **Sprachbindungen** für Rust, Go und Node.js
---
# Mitwirken
Wir begrüßen:
- Neue Detektoren
- Parser-Verbesserungen
- Dokumentationsaktualisierungen
- Synthetische adversariale Samples
Siehe `CONTRIBUTING.md` für Richtlinien.
---
# Sicherheit
Wenn du ein Sicherheitsproblem entdeckst, **öffne kein GitHub-Issue**.
Befolge die Anweisungen in `SECURITY.md`.
---
# Lizenz
MPL-2.0-Lizenz — siehe `LICENSE`.