iocx-dev/iocxUn motore di analisi statica estensibile e deterministico che estrae IOC ad alto segnale da binari PE e testo, progettato per l'automazione SOC e le pipeline moderne di analisi delle minacce.
# IOCX
### **Estrazione IOC deterministica e a rischio zero per le pipeline di sicurezza moderne**
<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>Estrazione statica di IOC da un file PE tramite la CLI di 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>
# Progetto ufficiale IOCX
Questo è il motore IOCX originale per l'estrazione statica deterministica di IOC e l'analisi PE.
Qualsiasi altro repository che utilizzi il nome "iocx" **non è affiliato** a questo progetto.
**Link ufficiali:**
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- Github: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Sito web: [https://iocx.dev/](https://iocx.dev/)
---
# Perché IOCX è importante
Il malware moderno è **adversarial per impostazione predefinita** — malformato, evasivo e progettato per rompere gli estrattori ingenui.
- **Gli strumenti ignari dei binari** collassano di fronte a PE malformati
- **Le sandbox** sono insicure e inutilizzabili in CI/CD
- **La riproducibilità** è essenziale per le pipeline automatizzate
**IOCX è costruito per ambienti in cui correttezza e determinismo contano davvero.**
---
# Il motore IOCX
**IOCX è il motore ufficiale di estrazione statica di IOC** — un sistema deterministico e consapevole dei binari, costruito per DFIR, automazione SOC, sicurezza CI/CD e pipeline di threat-intel su larga scala.
A differenza degli estrattori basati solo su regex o degli strumenti dipendenti da sandbox, IOCX esegue:
- **analisi puramente statica**
- **rischio di esecuzione zero**
- **output stabile e deterministico**
- **euristiche testate in modo adversariale**
È un componente centrale dell'ecosistema MalX Labs per un'analisi delle minacce moderna e scalabile.
---
# Prova IOCX in 10 secondi
```bash
echo "http://malicious.example" | iocx -
```
Oppure analizza un file PE in sicurezza:
```bash
iocx suspicious.exe -a deep
```
---
# Perché esiste IOCX
I team di sicurezza affrontano tre problemi persistenti:
1. **Gli estrattori regex** si rompono con input adversarial
2. **Il sandboxing** è insicuro, lento e inadatto all'automazione
3. **La maggior parte degli strumenti IOC** è incoerente, lenta o produce output leggermente diversi tra un'esecuzione e l'altra
IOCX risolve questo con un **motore deterministico e puramente statico** progettato per automazione, sicurezza e scala.
---
# Cosa IOCX *non è*
IOCX è intenzionalmente **non**:
- una sandbox
- uno strumento di analisi comportamentale
- un emulatore
- un motore di enrichment
Non esegue mai codice non attendibile.
Non esegue mai analisi dinamica.
È **puramente statico per progettazione** — per sicurezza, determinismo e compatibilità con CI/CD.
---
# Filosofia di progettazione
IOCX è progettato per le realtà del malware moderno, non per le assunzioni degli strumenti legacy.
### **1. Determinismo invece di ambiguità**
Output stabile e riproducibile — nessuna casualità, nessuna volatilità.
### **2. Statico invece di dinamico**
L'esecuzione è insicura. L'analisi statica è prevedibile, scalabile e adatta alla CI.
### **3. Ingegneria adversarial-first**
PE malformati, RVA corrotti, stringhe ostili — IOCX li tratta come input normali.
### **4. Stabilità dello schema come contratto**
I sistemi a valle non dovrebbero mai rompersi con un aggiornamento.
### **5. Prestazioni senza compromessi**
150–300 MB/s su testo grezzo.
6–15 MB/s su PE tipici.
Prevedibile anche sotto carico adversarial nel caso peggiore.
---
Questi impegni derivano da una metodologia di ricerca pubblicata per l'analisi strutturale dei PE — costruzione deterministica di fixture, disciplina dell'anomalia singola e comportamento del loader di Windows come oracolo di correttezza. Vedi docs/methodology.md per la metodologia completa, e [paax.dev](https://paax.dev) per la tassonomia più ampia dei PE adversarial e la suite commerciale di fixture.
# Cosa rende IOCX diverso
| Capacità | **IOCX** | Estrattori IOC tipici | Strumenti sandbox / dinamici |
|-----------|-----------|------------------------|--------------------------|
| **Sicurezza** | Zero esecuzione, puramente statico | Solo regex, nessuna sicurezza sui binari | Esegue codice non attendibile (alto rischio) |
| **Determinismo** | Output completamente deterministico | Non deterministico sotto rumore | Non deterministico per progettazione |
| **Consapevolezza dei binari** | Parsing PE completo, euristiche | Nessun supporto ai binari | Sì, ma insicuro + lento |
| **Resilienza adversarial** | Testato contro PE malformati, stringhe ostili | Facilmente aggirabile | Spesso va in crash o classifica erroneamente |
| **Prestazioni** | 150–300 MB/s (testo), 6–15 MB/s (PE) | Altamente variabili | Estremamente lento |
| **Compatibilità CI/CD** | Sì — sicuro, deterministico, veloce | Parziale | No — insicuro per le pipeline |
| **Stabilità dello schema** | Garantita | Rara | Nessuna |
**In breve:** IOCX è costruito per la *realtà adversarial concreta*, non per input idealizzati.
---
# Casi d'uso
### CI/CD & DevSecOps
- Analizza i binari prima del rilascio
- Rileva URL, IP o segreti accidentali nelle build
- Applica gate di sicurezza con rischio di esecuzione zero
### SOC & Incident Response
- Estrai indicatori da alert o dal testo negli appunti dell'analista
- Ispeziona campioni di malware in sicurezza senza esecuzione
- Normalizza gli IOC in JSON strutturato
### Threat Intelligence
- Elabora feed su larga scala
- Analizza report non strutturati
- Costruisci pipeline di enrichment su output deterministico
### Automazione & Scripting
- Invia log o artefatti attraverso IOCX tramite pipe
- Usa l'API Python per flussi ETL o batch
- Estendi con rilevatori personalizzati
---
# Profili di prestazioni
### **1. Estrazione IOC grezza (testo, log, buffer)**
**150–300 MB/s** di throughput sostenuto
Percorso veloce — nessun parsing PE.
| Rilevatore | Tempo per 1 MB | Throughput |
|-----------|-----------|------------|
| Crypto | 0.0037 s | ~270 MB/s |
| Filepaths | 0.0041 s | ~250 MB/s |
| IP | 0.0065 s | ~156 MB/s |
| Domini | 0.0035 s | ~300 MB/s |
---
### **2. File PE tipici (~39 KB)**
- **0.0122 s** (tipico)
- **0.0145 s** (con euristiche)
- **6–15 MB/s** di throughput
---
### **3. PE adversarial denso (1.5 MB)**
- **0.192 s**
- **~7.6 MB/s** di throughput
- Attiva anomalie TLS, anomalie strutturali, pattern anti-debug
---
### **4. Motore completo (non-PE)**
- **1 MB:** 0.038 s
---
# Punti salienti delle versioni
<details>
<summary><strong>Mostra cronologia versioni</strong></summary>
<br>
### v0.7.6.2 — Validatore della tabella di importazione
- Nuovo **validatore strutturale deterministico della tabella di importazione** (codici motivo `IMPORT_*`).
- `version_info` ora viene analizzato e reso disponibile a **ogni** livello di analisi (non solo con `-a full`), tramite una nuova proiezione pubblica limitata.
- CLI ricostruita: output `--version` brandizzato, testo `--help` più chiaro, gruppi di argomenti riorganizzati.
- Corretto un crash del parser di rilocazione raggiungibile da qualsiasi entry, un bug dell'offset della data-directory PE32+ e diverse perdite silenziose di errori su export/risorse.
- Nuovo controllo CI statico che impedisce ai tag di errore del parser di rimanere silenziosamente non consumati dai validatori.
- Suite di test: da 2.136 a 2.802 test.
---
### v0.7.6.1 — Validatore della directory delle eccezioni
- Aggiunge una validazione semantica approfondita della directory delle eccezioni PE (`.pdata`); 14 nuovi codici motivo; 15 validatori in totale.
- Corregge un difetto che sopprimeva i risultati strutturali in tutto il motore.
- Quattro ulteriori controlli sono risultati morti in produzione: due sul posizionamento delle directory, uno sulla mappatura delle sezioni e uno sul controllo dei limiti della directory delle risorse.
- **Visibile nell'output:** i risultati precedentemente soppressi o etichettati erroneamente ora appariranno.
- Test: da 1620 a 2136. Copertura: 100%.
---
### **v0.7.6 — Espansione dei validatori strutturali: directory debug e relocations**
- Due nuovi validatori strutturali PE - relocations e debug
- I validatori WIN_CERTIFICATE e tls ora ricavano la verità strutturale da parser di struct dedicati, indipendenti da pefile
- 12 nuovi codici motivo con tassonomie di sotto-motivi risolte per priorità
- Parsing deterministico a livello di byte - nessuna dipendenza dall'interpretazione lazy di pefile
- 1620 test con copertura al 100%
---
### **v0.7.5 — Espansione dei validatori strutturali**
- Quattro nuovi validatori strutturali PE — exports, delay-load imports, VS_VERSIONINFO e gerarchia delle risorse
- 24 nuovi codici motivo con tassonomie di sotto-motivi risolte per priorità
- Parsing deterministico a livello di byte — nessuna dipendenza dall'interpretazione lazy di pefile
- Metadati rilevanti per la sicurezza — caratteristiche DLL, decodifica di subsystem/machine, entropia per risorsa
- 1370 test con copertura al 100% — verificati end-to-end rispetto a `dumpbin` su binari reali
---
### **v0.7.4.1 — Hotfix di compatibilità Windows**
- Rimossa la dipendenza `python-magic`, che causava errori di importazione sui sistemi Windows
- Aggiunto un rilevatore di tipo di file in puro Python per la piena portabilità multipiattaforma
- Migliorata la logica di rilevamento PE applicando una validazione PE rigorosa e compatibile con Windows.
- Nessuna modifica comportamentale all'estrazione degli IOC
- La correzione di coerenza di `--min-length` è pianificata per la **v0.7.5**
---
### **v0.7.4 — Parsing avanzato delle directory**
- Parsing e validazione completi della **Load Config Directory**
- Metadati estesi dell'Optional Header per euristiche a valle
- Nuove euristiche GuardCF, cookie, anomalie
- Analisi PE più veloce
- 99 fixture PE nella suite di test; 45 completamente validate rispetto alla specifica
---
### **v0.7.3 — Correttezza strutturale ed euristiche deterministiche**
- Rafforzamento importante di tutti i validatori strutturali PE
- Comportamento deterministico e stabile rispetto agli snapshot
- ReasonCodes chiari e coerenti
- Euristiche più solide costruite sulla verità strutturale
---
### **v0.7.2 — Correzione delle dipendenze**
- Aggiunta la dipendenza `idna` mancante
- Nessuna modifica comportamentale o allo schema
---
### **v0.7.1 — Espansione delle euristiche adversarial e rafforzamento del parser**
- Sei nuove euristiche PE
- Corpus PE adversarial ampliato
- Estrattori domain/URL/crypto/hash rafforzati
- Output deterministico validato tramite snapshot
---
### **v0.7.0 — Euristiche deterministiche e fondazione del testing adversarial**
- Euristiche deterministiche
- Campioni adversarial di livello 3
- Test con contratto su snapshot
- Correzione del crash di Rich Header
---
### **v0.6.0 — Schema di output stabile e metadati deterministici**
- Schema JSON completamente stabile
- Metadati PE normalizzati
- Livelli di analisi formalizzati
---
### **v0.5.0 — Livelli di analisi, analisi delle sezioni PE, indizi di offuscamento**
- Nuovo sistema di livelli di analisi
- Analisi strutturale PE
- Euristiche di offuscamento
---
### **v0.4.0 — Architettura a plugin**
- Motore di regole pronto per i plugin
- Flusso di rilevamento unificato
---
### **v0.3.0 — Rilevamento IOC crypto**
- Rilevamento di wallet Ethereum e Bitcoin
---
### **v0.2.0 — Rilevamento IP ad alta affidabilità**
- Miglioramenti importanti a IPv4/IPv6
</details>
---
# Avvio rapido
### Installazione
```bash
pip install iocx
```
### Estrai IOC da un file
```bash
iocx suspicious.exe
```
### Estrai da testo
```bash
echo "Visit http://bad.example.com" | iocx -
```
### Abilita l'analisi PE
```bash
iocx suspicious.exe -a
```
### API Python
```python
from iocx.engine import Engine
engine = Engine()
results = engine.extract("suspicious.exe")
print(results)
```
---
# Esempio di output
> IOCX produce JSON strutturato e deterministico che include IOC, metadati PE, analisi delle sezioni, euristiche e indicatori di offuscamento.
>
> L'esempio seguente è un output abbreviato di un campione PE adversarial reale. Dimostra la forma e la profondità dello schema mantenendo una dimensione gestibile per scopi di documentazione.
<details>
<summary><strong>Mostra esempio di output 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>
---
# Architettura
```
iocx/
├── examples/
├── docs/
├── tests/
└── iocx
├── detectors/
├── parsers/
├── plugins/
├── cli/
└── analysis/
```
---
# Ecosistema di plugin ed estensibilità
IOCX è progettato per essere esteso in modo sicuro e prevedibile.
I plugin sono **cittadini di prima classe**, validati dagli stessi test deterministici su snapshot del motore principale.
Puoi costruire:
- rilevatori IOC personalizzati
- regole regex personalizzate
- plugin consapevoli dei binari
- euristiche interne
- estrattori specifici per pipeline
Vedi:
- `docs/specs/overlap-suppression.md`
- `docs/specs/plugin-authoring-guidelines.md`
---
# Panoramica dell'ecosistema
IOCX è più di un singolo binario — è un ecosistema modulare:
- **Motore principale** — estrazione IOC deterministica + analisi PE
- **Sistema di plugin** — rilevatori e moduli di analisi personalizzati
- **Corpus adversarial** — PE malformati, stringhe ostili, campioni fuzz
- **Framework di snapshot testing** — garantisce output deterministico
- **Benchmark di prestazioni** — applicati in CI
- **Suite di documentazione** — specifiche, contratti e guide ai plugin
---
# Chi usa IOCX?
IOCX è utilizzato in:
- team DFIR
- pipeline di automazione SOC
- gate di sicurezza CI/CD
- piattaforme di threat-intel
- laboratori di ricerca sul malware
- team di security engineering
Ovunque gli indicatori debbano essere estratti **in sicurezza**, **in modo deterministico** e **su larga scala**, IOCX è adatto.
---
# Test sicuri (nessun malware richiesto)
Tutti i campioni di test sono:
- Sintetici
- Benigni
- Pubblicamente sicuri (EICAR, GTUBE)
- Progettati per evitare la gestione accidentale di malware
---
# Garanzie di prestazioni
IOCX applica soglie di prestazioni rigorose in CI per garantire:
- Nessun blocco da backtracking regex
- Nessun rallentamento patologico
- Prestazioni stabili tra le release
Vedi:
- `docs/performance.md`
---
# Identità e denominazione del progetto
Il nome **IOCX** si riferisce esclusivamente al motore ufficiale pubblicato su:
- 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 consentito
- Repository chiamati `iocx`
- Strumenti chiamati "iocx" non facenti parte di questo progetto
- Insinuare un'affiliazione senza permesso
### Consentito
- `iocx-<plugin>`
- `iocx-extension-<name>`
- `iocx-detector-<feature>`
---
# Repository ufficiali IOCX
- Motore principale: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Meta-repo dei plugin: [https://github.com/iocx-dev/iocx-plugins](https://github.com/iocx-dev/iocx-plugins)
- Documentazione: [https://github.com/iocx-dev/iocx/tree/main/docs/specs](https://github.com/iocx-dev/iocx/tree/main/docs/specs)
- Pacchetto PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
---
# Roadmap
Lo sviluppo di IOCX si concentra su stabilità, estensibilità e copertura più profonda dell'analisi statica.
Gli elementi seguenti rappresentano aree di lavoro ed esplorazione in corso.
- **Euristiche PE estese** (comportamento delay-load, anomalie strutturali, pattern di rilocazione)
- **Regole di soppressione selettiva** per flussi OSINT, DFIR e threat-intel
- **Estrazione di metadati ELF e Mach-O**
- **Modalità di analisi batch** per flussi multi-artefatto
- **Modalità di output in stile YARA** e hook di enrichment
- **Analisi statica indipendente dal tipo di binario**
- **Ecosistema di plugin multipiattaforma**
- **Binding linguistici** per Rust, Go e Node.js
---
# Contribuire
Accogliamo con favore:
- Nuovi rilevatori
- Miglioramenti ai parser
- Aggiornamenti alla documentazione
- Campioni adversarial sintetici
Vedi `CONTRIBUTING.md` per le linee guida.
---
# Sicurezza
Se scopri un problema di sicurezza, **non aprire una issue su GitHub**.
Segui le istruzioni in `SECURITY.md`.
---
# Licenza
Licenza MPL-2.0 — vedi `LICENSE`.