iocx-dev/iocxUn moteur d’analyse statique extensible et déterministe qui extrait des IOC à haute signalétique depuis des binaires PE et du texte, conçu pour l’automatisation des SOC et les pipelines modernes d’analyse des menaces.
# IOCX
### **Extraction déterministe et sans risque d'IOC pour les pipelines de sécurité modernes**
<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>Extraction statique d'IOC à partir d'un fichier PE à l'aide de la CLI IOCX</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>
# Projet officiel IOCX
Ceci est le moteur IOCX original pour l'extraction statique déterministe d'IOC et l'analyse PE.
Tout autre dépôt utilisant le nom « iocx » n'est **pas affilié** à ce projet.
**Liens officiels :**
- PyPI : [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- Github : [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Site web : [https://iocx.dev/](https://iocx.dev/)
---
# Pourquoi IOCX est important
Les malwares modernes sont **adversariaux par défaut** — malformés, évasifs et conçus pour mettre en échec les extracteurs naïfs.
- **Les outils non conscients du binaire** s'effondrent face à des PE malformés
- **Les sandboxes** sont dangereuses et inutilisables en CI/CD
- **La reproductibilité** est essentielle pour les pipelines automatisés
**IOCX est conçu pour les environnements où la correction et le déterminisme comptent réellement.**
---
# Le moteur IOCX
**IOCX est le moteur officiel d'extraction statique d'IOC** — un système déterministe et conscient du binaire, conçu pour le DFIR, l'automatisation SOC, la sécurité CI/CD et les pipelines de threat-intel à grande échelle.
Contrairement aux extracteurs uniquement basés sur des regex ou aux outils dépendants d'une sandbox, IOCX effectue :
- **une analyse purement statique**
- **un risque d'exécution nul**
- **une sortie stable et déterministe**
- **des heuristiques testées en conditions adversariales**
C'est un composant central de l'écosystème MalX Labs pour une analyse des menaces moderne et évolutive.
---
# Essayez IOCX en 10 secondes
```bash
echo "http://malicious.example" | iocx -
```
Ou analysez un fichier PE en toute sécurité :
```bash
iocx suspicious.exe -a deep
```
---
# Pourquoi IOCX existe
Les équipes de sécurité font face à trois problèmes persistants :
1. **Les extracteurs à base de regex** se cassent face à des entrées adversariales
2. **Le sandboxing** est dangereux, lent et inadapté à l'automatisation
3. **La plupart des outils IOC** sont incohérents, lents ou produisent des sorties subtilement différentes entre les exécutions
IOCX résout cela avec un **moteur déterministe, uniquement statique**, conçu pour l'automatisation, la sécurité et l'échelle.
---
# Ce qu'IOCX *n'est pas*
IOCX n'est intentionnellement **pas** :
- une sandbox
- un outil d'analyse comportementale
- un émulateur
- un moteur d'enrichissement
Il n'exécute jamais de code non fiable.
Il n'effectue jamais d'analyse dynamique.
Il est **uniquement statique par conception** — pour la sécurité, le déterminisme et la compatibilité CI/CD.
---
# Philosophie de conception
IOCX est conçu pour les réalités des malwares modernes, et non pour les hypothèses des outils hérités.
### **1. Le déterminisme plutôt que l'ambiguïté**
Une sortie stable et reproductible — sans aléatoire, sans volatilité.
### **2. Le statique plutôt que le dynamique**
L'exécution est dangereuse. L'analyse statique est prévisible, évolutive et adaptée à la CI.
### **3. Une ingénierie orientée adversaire d'abord**
PE malformés, RVA corrompus, chaînes hostiles — IOCX les traite comme des entrées normales.
### **4. La stabilité du schéma comme contrat**
Les systèmes en aval ne devraient jamais casser lors d'une mise à niveau.
### **5. La performance sans compromis**
150–300 Mo/s sur du texte brut.
6–15 Mo/s sur des PE typiques.
Prévisible même sous une charge adversariale dans le pire des cas.
---
Ces engagements découlent d'une méthodologie de recherche publiée pour l'analyse structurelle des PE — construction déterministe de fixtures, discipline du single-anomaly et comportement du loader Windows comme oracle de correction. Voir docs/methodology.md pour la méthodologie complète, et [paax.dev](https://paax.dev) pour la taxonomie élargie des PE adversariaux et la suite commerciale de fixtures.
# Ce qui rend IOCX différent
| Capacité | **IOCX** | Extracteurs IOC typiques | Outils Sandbox / Dynamiques |
|-----------|-----------|------------------------|--------------------------|
| **Sécurité** | Zéro-exécution, uniquement statique | Uniquement regex, aucune sécurité binaire | Exécute du code non fiable (haut risque) |
| **Déterminisme** | Sortie entièrement déterministe | Non déterministe sous bruit | Non déterministe par conception |
| **Conscience du binaire** | Analyse PE complète, heuristiques | Aucun support binaire | Oui, mais dangereux + lent |
| **Résilience adversariale** | Testé contre des PE malformés, chaînes hostiles | Facilement contourné | Plante ou classe mal souvent |
| **Performance** | 150–300 Mo/s (texte), 6–15 Mo/s (PE) | Très variable | Extrêmement lent |
| **Adapté à la CI/CD** | Oui — sûr, déterministe, rapide | Partiel | Non — dangereux pour les pipelines |
| **Stabilité du schéma** | Garantie | Rare | Aucune |
**En bref :** IOCX est conçu pour la *réalité adversariale concrète*, pas pour des entrées idéalisées.
---
# Cas d'usage
### CI/CD & DevSecOps
- Analyser les binaires avant publication
- Détecter les URL, IP ou secrets accidentels dans les builds
- Appliquer des barrières de sécurité avec un risque d'exécution nul
### SOC & Réponse aux incidents
- Extraire des indicateurs à partir d'alertes ou du texte du presse-papiers d'un analyste
- Inspecter en toute sécurité des échantillons de malware sans exécution
- Normaliser les IOC en JSON structuré
### Threat Intelligence
- Traiter des flux à grande échelle
- Analyser des rapports non structurés
- Construire des pipelines d'enrichissement sur une sortie déterministe
### Automatisation & Scripting
- Faire passer des logs ou des artefacts dans IOCX
- Utiliser l'API Python pour des workflows ETL ou par lots
- Étendre avec des détecteurs personnalisés
---
# Profils de performance
### **1. Extraction brute d'IOC (texte, logs, buffers)**
**150–300 Mo/s** de débit soutenu
Chemin rapide — sans analyse PE.
| Détecteur | Temps pour 1 Mo | Débit |
|-----------|-----------|------------|
| Crypto | 0.0037 s | ~270 Mo/s |
| Filepaths | 0.0041 s | ~250 Mo/s |
| IP | 0.0065 s | ~156 Mo/s |
| Domains | 0.0035 s | ~300 Mo/s |
---
### **2. Fichiers PE typiques (~39 Ko)**
- **0.0122 s** (typique)
- **0.0145 s** (avec heuristiques)
- **6–15 Mo/s** de débit
---
### **3. PE dense adversarial (1,5 Mo)**
- **0.192 s**
- **~7.6 Mo/s** de débit
- Déclenche des anomalies TLS, des anomalies structurelles, des motifs anti-debug
---
### **4. Moteur complet (non-PE)**
- **1 Mo :** 0.038 s
---
# Faits marquants des versions
<details>
<summary><strong>Afficher l'historique des versions</strong></summary>
<br>
### v0.7.6.2 — Validateur de table d'import
- Nouveau **validateur structurel déterministe de table d'import** (codes de raison `IMPORT_*`).
- `version_info` est désormais analysé et exposé à **chaque** niveau d'analyse (pas seulement `-a full`), via une nouvelle projection publique bornée.
- CLI reconstruite : sortie `--version` brandée, texte `--help` plus clair, groupes d'arguments réorganisés.
- Correction d'un crash du parseur de relocations atteignable depuis n'importe quelle entrée, d'un bug d'offset de répertoire de données PE32+, et de plusieurs erreurs silencieuses d'export/ressource.
- Nouvelle vérification CI statique qui empêche les tags d'erreur du parseur de rester silencieusement non consommés par les validateurs.
- Suite de tests : 2 136 → 2 802 tests.
---
### v0.7.6.1 — Validateur de répertoire d'exceptions
- Ajoute une validation sémantique approfondie du répertoire d'exceptions PE (`.pdata`) ; 14 nouveaux codes de raison ; 15 validateurs au total.
- Corrige un défaut qui supprimait les constats structurels à travers le moteur.
- Quatre autres vérifications se sont révélées mortes en production : deux de placement de répertoire, une de mappage de section, et une vérification des limites du répertoire de ressources.
- **Visible dans la sortie :** les constats précédemment supprimés ou mal étiquetés apparaîtront désormais.
- Tests : 1620 → 2136. Couverture : 100%.
---
### **v0.7.6 — Extension des validateurs structurels : répertoires debug et relocations**
- Deux nouveaux validateurs structurels PE — relocations et debug
- Les validateurs WIN_CERTIFICATE et tls tirent désormais la vérité structurelle de parseurs de structures dédiés, indépendamment de pefile
- 12 nouveaux codes de raison avec taxonomies de sous-raisons résolues par priorité
- Analyse déterministe au niveau de l'octet — aucune dépendance à l'interprétation paresseuse de pefile
- 1620 tests à 100% de couverture
---
### **v0.7.5 — Extension des validateurs structurels**
- Quatre nouveaux validateurs structurels PE — exports, imports à chargement différé, VS_VERSIONINFO et hiérarchie des ressources
- 24 nouveaux codes de raison avec taxonomies de sous-raisons résolues par priorité
- Analyse déterministe au niveau de l'octet — aucune dépendance à l'interprétation paresseuse de pefile
- Métadonnées pertinentes pour la sécurité — caractéristiques DLL, décodage des noms de sous-système/machine, entropie par ressource
- 1370 tests à 100% de couverture — vérifiés de bout en bout contre `dumpbin` sur de vrais binaires
---
### **v0.7.4.1 — Correctif de compatibilité Windows**
- Suppression de la dépendance `python-magic`, qui causait des échecs d'import sur les systèmes Windows
- Ajout d'un détecteur de type de fichier en pur Python pour une portabilité multiplateforme complète
- Amélioration de la logique de détection PE en imposant une validation PE stricte compatible Windows.
- Aucun changement de comportement pour l'extraction d'IOC
- Le correctif de cohérence `--min-length` est prévu pour **v0.7.5**
---
### **v0.7.4 — Analyse avancée des répertoires**
- Analyse et validation complètes du **Load Config Directory**
- Métadonnées étendues de l'Optional Header pour les heuristiques en aval
- Nouvelles heuristiques GuardCF, cookie, anomalie
- Analyse PE plus rapide
- 99 fixtures PE dans la suite de tests ; 45 entièrement validées selon la spécification
---
### **v0.7.3 — Correction structurelle & heuristiques déterministes**
- Durcissement majeur de tous les validateurs structurels PE
- Comportement déterministe et stable en snapshot
- ReasonCodes clairs et cohérents
- Heuristiques renforcées construites sur la vérité structurelle
---
### **v0.7.2 — Correction de dépendance**
- Ajout de la dépendance manquante `idna`
- Aucun changement de comportement ou de schéma
---
### **v0.7.1 — Extension des heuristiques adversariales & durcissement du parseur**
- Six nouvelles heuristiques PE
- Corpus PE adversarial élargi
- Extracteurs domain/URL/crypto/hash durcis
- Sortie déterministe validée par snapshot
---
### **v0.7.0 — Heuristiques déterministes & fondation de tests adversariaux**
- Heuristiques déterministes
- Échantillons adversariaux de niveau 3
- Tests de contrat par snapshot
- Correction du crash Rich Header
---
### **v0.6.0 — Schéma de sortie stable & métadonnées déterministes**
- Schéma JSON entièrement stable
- Métadonnées PE normalisées
- Niveaux d'analyse formalisés
---
### **v0.5.0 — Niveaux d'analyse, analyse des sections PE, indices d'obfuscation**
- Nouveau système de niveaux d'analyse
- Analyse structurelle PE
- Heuristiques d'obfuscation
---
### **v0.4.0 — Architecture de plugins**
- Moteur de règles prêt pour les plugins
- Flux de détection unifié
---
### **v0.3.0 — Détection d'IOC crypto**
- Détection de portefeuilles Ethereum & Bitcoin
---
### **v0.2.0 — Détection d'IP haute fiabilité**
- Améliorations majeures IPv4/IPv6
</details>
---
# Démarrage rapide
### Installation
```bash
pip install iocx
```
### Extraire les IOC d'un fichier
```bash
iocx suspicious.exe
```
### Extraire à partir de texte
```bash
echo "Visit http://bad.example.com" | iocx -
```
### Activer l'analyse PE
```bash
iocx suspicious.exe -a
```
### API Python
```python
from iocx.engine import Engine
engine = Engine()
results = engine.extract("suspicious.exe")
print(results)
```
---
# Exemple de sortie
> IOCX produit un JSON structuré et déterministe qui inclut les IOC, les métadonnées PE, l'analyse des sections, les heuristiques et les indicateurs d'obfuscation.
>
> L'exemple ci-dessous est une sortie abrégée d'un véritable échantillon PE adversarial. Il démontre la forme et la profondeur du schéma tout en gardant une taille gérable à des fins de documentation.
<details>
<summary><strong>Afficher un exemple de sortie JSON</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>
---
# Architecture
```
iocx/
├── examples/
├── docs/
├── tests/
└── iocx
├── detectors/
├── parsers/
├── plugins/
├── cli/
└── analysis/
```
---
# Écosystème de plugins & extensibilité
IOCX est conçu pour être étendu de manière sûre et prévisible.
Les plugins sont des **citoyens de première classe**, validés par les mêmes tests de snapshot déterministes que le moteur principal.
Vous pouvez construire :
- des détecteurs IOC personnalisés
- des règles regex personnalisées
- des plugins conscients du binaire
- des heuristiques internes
- des extracteurs spécifiques à un pipeline
Voir :
- `docs/specs/overlap-suppression.md`
- `docs/specs/plugin-authoring-guidelines.md`
---
# Aperçu de l'écosystème
IOCX est plus qu'un simple binaire — c'est un écosystème modulaire :
- **Moteur principal** — extraction déterministe d'IOC + analyse PE
- **Système de plugins** — détecteurs et modules d'analyse personnalisés
- **Corpus adversarial** — PE malformés, chaînes hostiles, échantillons de fuzz
- **Framework de tests par snapshot** — garantit une sortie déterministe
- **Benchmarks de performance** — appliqués en CI
- **Suite de documentation** — spécifications, contrats et guides de plugins
---
# Qui utilise IOCX ?
IOCX est utilisé à travers :
- les équipes DFIR
- les pipelines d'automatisation SOC
- les barrières de sécurité CI/CD
- les plateformes de threat-intel
- les laboratoires de recherche sur les malwares
- les équipes d'ingénierie sécurité
Partout où des indicateurs doivent être extraits **en toute sécurité**, **de manière déterministe** et **à grande échelle**, IOCX convient.
---
# Tests sécurisés (aucun malware requis)
Tous les échantillons de test sont :
- Synthétiques
- Bénins
- Publics et sûrs (EICAR, GTUBE)
- Conçus pour éviter toute manipulation accidentelle de malware
---
# Garanties de performance
IOCX applique des seuils de performance stricts en CI pour garantir :
- Aucun blocage par backtracking de regex
- Aucun ralentissement pathologique
- Des performances stables à travers les versions
Voir :
- `docs/performance.md`
---
# Identité du projet & nommage
Le nom **IOCX** désigne exclusivement le moteur officiel publié sur :
- PyPI : [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- GitHub : [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
### Non autorisé
- Les dépôts nommés `iocx`
- Les outils nommés « iocx » ne faisant pas partie de ce projet
- Laisser entendre une affiliation sans autorisation
### Autorisé
- `iocx-<plugin>`
- `iocx-extension-<name>`
- `iocx-detector-<feature>`
---
# Dépôts IOCX officiels
- Moteur principal : [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Méta-dépôt des plugins : [https://github.com/iocx-dev/iocx-plugins](https://github.com/iocx-dev/iocx-plugins)
- Documentation : [https://github.com/iocx-dev/iocx/tree/main/docs/specs](https://github.com/iocx-dev/iocx/tree/main/docs/specs)
- Paquet PyPI : [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
---
# Feuille de route
Le développement d'IOCX se concentre sur la stabilité, l'extensibilité et une couverture plus profonde de l'analyse statique.
Les éléments ci-dessous représentent des domaines de travail et d'exploration en cours.
- **Heuristiques PE étendues** (comportement de chargement différé, anomalies structurelles, motifs de relocation)
- **Règles de suppression sélectives** pour les workflows OSINT, DFIR et threat-intel
- **Extraction de métadonnées ELF et Mach-O**
- **Mode d'analyse par lots** pour les workflows multi-artefacts
- **Modes de sortie de style YARA** et hooks d'enrichissement
- **Analyse statique agnostique au binaire**
- **Écosystème de plugins multiplateforme**
- **Liaisons de langage** pour Rust, Go et Node.js
---
# Contribution
Nous accueillons :
- De nouveaux détecteurs
- Des améliorations de parseur
- Des mises à jour de documentation
- Des échantillons adversariaux synthétiques
Voir `CONTRIBUTING.md` pour les directives.
---
# Sécurité
Si vous découvrez un problème de sécurité, **n'ouvrez pas d'issue GitHub**.
Suivez les instructions dans `SECURITY.md`.
---
# Licence
Licence MPL‑2.0 — voir `LICENSE`.