iocx-dev/iocxUn motor de análisis estático, extensible y determinista, que extrae IOCs de alta señal de binarios PE y texto, construido para la automatización de SOC y pipelines modernos de análisis de amenazas.
# IOCX
### **Extracción de IOC determinista y sin riesgo para pipelines de seguridad modernos**
<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>Extracción estática de IOC de un archivo PE usando la CLI de 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>
# Proyecto Oficial IOCX
Este es el motor IOCX original para la extracción estática determinista de IOC y el análisis de PE.
Cualquier otro repositorio que use el nombre "iocx" **no está afiliado** a este proyecto.
**Enlaces oficiales:**
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- Github: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Sitio web: [https://iocx.dev/](https://iocx.dev/)
---
# Por qué IOCX importa
El malware moderno es **adversario por defecto** — malformado, evasivo y diseñado para romper extractores ingenuos.
- **Las herramientas que ignoran el binario** colapsan ante PEs malformados
- **Los sandboxes** son inseguros e inutilizables en CI/CD
- **La reproducibilidad** es esencial para pipelines automatizados
**IOCX está construido para entornos donde la corrección y el determinismo realmente importan.**
---
# El Motor IOCX
**IOCX es el motor oficial de extracción estática de IOC** — un sistema determinista y consciente del binario, construido para DFIR, automatización de SOC, seguridad en CI/CD y pipelines de threat-intel a gran escala.
A diferencia de los extractores basados solo en regex o las herramientas dependientes de sandbox, IOCX realiza:
- **análisis puramente estático**
- **riesgo de ejecución cero**
- **salida estable y determinista**
- **heurísticas probadas contra adversarios**
Es un componente central del ecosistema MalX Labs para el análisis de amenazas moderno y escalable.
---
# Prueba IOCX en 10 segundos
```bash
echo "http://malicious.example" | iocx -
```
O escanea un archivo PE de forma segura:
```bash
iocx suspicious.exe -a deep
```
---
# Por qué existe IOCX
Los equipos de seguridad enfrentan tres problemas persistentes:
1. **Los extractores de regex** se rompen ante entradas adversarias
2. **El sandboxing** es inseguro, lento e inadecuado para la automatización
3. **La mayoría de las herramientas de IOC** son inconsistentes, lentas o producen salidas sutilmente diferentes entre ejecuciones
IOCX resuelve esto con un **motor determinista y puramente estático** diseñado para la automatización, la seguridad y la escala.
---
# Lo que IOCX *no es*
IOCX intencionalmente **no** es:
- un sandbox
- una herramienta de análisis de comportamiento
- un emulador
- un motor de enriquecimiento
Nunca ejecuta código no confiable.
Nunca realiza análisis dinámico.
Es **puramente estático por diseño** — por seguridad, determinismo y compatibilidad con CI/CD.
---
# Filosofía de diseño
IOCX está diseñado para las realidades del malware moderno, no para las suposiciones de las herramientas heredadas.
### **1. Determinismo sobre ambigüedad**
Salida estable y reproducible — sin aleatoriedad, sin volatilidad.
### **2. Estático sobre dinámico**
La ejecución es insegura. El análisis estático es predecible, escalable y compatible con CI.
### **3. Ingeniería centrada en el adversario**
PEs malformados, RVAs corruptos, cadenas hostiles — IOCX los trata como entrada normal.
### **4. La estabilidad del esquema como contrato**
Los sistemas posteriores nunca deberían romperse al actualizar.
### **5. Rendimiento sin concesiones**
150–300 MB/s en texto sin procesar.
6–15 MB/s en PEs típicos.
Predecible incluso bajo la peor carga adversaria.
---
Estos compromisos se derivan de una metodología de investigación publicada para el análisis estructural de PE — construcción determinista de fixtures, disciplina de anomalía única y el comportamiento del cargador de Windows como oráculo de corrección. Consulta docs/methodology.md para la metodología completa, y [paax.dev](https://paax.dev) para la taxonomía más amplia de PE adversario y la suite comercial de fixtures.
# Qué hace diferente a IOCX
| Capacidad | **IOCX** | Extractores de IOC típicos | Herramientas de Sandbox / Dinámicas |
|-----------|-----------|------------------------|--------------------------|
| **Seguridad** | Cero ejecución, puramente estático | Solo regex, sin seguridad binaria | Ejecuta código no confiable (alto riesgo) |
| **Determinismo** | Salida totalmente determinista | No determinista bajo ruido | No determinista por diseño |
| **Conciencia del binario** | Análisis completo de PE, heurísticas | Sin soporte binario | Sí, pero inseguro + lento |
| **Resistencia a adversarios** | Probado contra PEs malformados, cadenas hostiles | Fácilmente evadible | A menudo falla o clasifica erróneamente |
| **Rendimiento** | 150–300 MB/s (texto), 6–15 MB/s (PE) | Altamente variable | Extremadamente lento |
| **Compatible con CI/CD** | Sí — seguro, determinista, rápido | Parcial | No — inseguro para pipelines |
| **Estabilidad del esquema** | Garantizada | Rara | Ninguna |
**En resumen:** IOCX está construido para la *realidad adversaria real*, no para entradas idealizadas.
---
# Casos de uso
### CI/CD y DevSecOps
- Escanear binarios antes del lanzamiento
- Detectar URLs, IPs o secretos accidentales en las compilaciones
- Aplicar barreras de seguridad con riesgo de ejecución cero
### SOC y respuesta a incidentes
- Extraer indicadores de alertas o del texto del portapapeles del analista
- Inspeccionar muestras de malware de forma segura sin ejecución
- Normalizar IOCs en JSON estructurado
### Threat Intelligence
- Procesar feeds a escala
- Analizar informes no estructurados
- Construir pipelines de enriquecimiento sobre salida determinista
### Automatización y scripting
- Canalizar logs o artefactos a través de IOCX
- Usar la API de Python para ETL o flujos de trabajo por lotes
- Extender con detectores personalizados
---
# Perfiles de rendimiento
### **1. Extracción de IOC sin procesar (Texto, Logs, Buffers)**
**150–300 MB/s** de rendimiento sostenido
Ruta rápida — sin análisis de PE.
| Detector | Tiempo por 1 MB | Rendimiento |
|-----------|-----------|------------|
| 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. Archivos PE típicos (~39 KB)**
- **0.0122 s** (típico)
- **0.0145 s** (con heurísticas)
- **6–15 MB/s** de rendimiento
---
### **3. PE denso adversario (1.5 MB)**
- **0.192 s**
- **~7.6 MB/s** de rendimiento
- Activa anomalías TLS, anomalías estructurales, patrones anti-debug
---
### **4. Motor completo (No-PE)**
- **1 MB:** 0.038 s
---
# Novedades de versiones
<details>
<summary><strong>Mostrar historial de versiones</strong></summary>
<br>
### v0.7.6.2 — Validador de tabla de importaciones
- Nuevo **validador estructural determinista de tabla de importaciones** (códigos de razón `IMPORT_*`).
- `version_info` ahora se analiza y se expone en **todos** los niveles de análisis (no solo en `-a full`), mediante una nueva proyección pública acotada.
- CLI reconstruida: salida de `--version` con marca, texto de `--help` más claro, grupos de argumentos reorganizados.
- Corregido un fallo del analizador de reubicaciones alcanzable desde cualquier entrada, un error de desplazamiento del directorio de datos PE32+ y varias caídas silenciosas de errores de exportación/recursos.
- Nueva comprobación estática de CI que evita que las etiquetas de error del analizador queden silenciosamente sin consumir por los validadores.
- Suite de pruebas: 2,136 → 2,802 pruebas.
---
### v0.7.6.1 — Validador de directorio de excepciones
- Añade validación semántica profunda del directorio de excepciones (`.pdata`) del PE; 14 nuevos códigos de razón; 15 validadores en total.
- Corrige un defecto que había estado suprimiendo hallazgos estructurales en todo el motor.
- Se descubrió que cuatro comprobaciones adicionales estaban muertas en producción: dos de ubicación de directorio, una de mapeo de sección y una de límites del directorio de recursos.
- **Visible en la salida:** los hallazgos previamente suprimidos o mal etiquetados ahora aparecerán.
- Pruebas: 1620 → 2136. Cobertura: 100%.
---
### **v0.7.6 — Expansión del validador estructural: directorios de depuración y reubicaciones**
- Dos nuevos validadores estructurales de PE - reubicaciones y depuración
- Los validadores WIN_CERTIFICATE y tls ahora obtienen la verdad estructural de analizadores de struct dedicados, independientes de pefile
- 12 nuevos códigos de razón con taxonomías de sub-razones resueltas por prioridad
- Análisis determinista a nivel de byte - sin depender de la interpretación perezosa de pefile
- 1620 pruebas con 100% de cobertura
---
### **v0.7.5 — Expansión del validador estructural**
- Cuatro nuevos validadores estructurales de PE — exportaciones, importaciones de carga diferida, VS_VERSIONINFO y jerarquía de recursos
- 24 nuevos códigos de razón con taxonomías de sub-razones resueltas por prioridad
- Análisis determinista a nivel de byte — sin depender de la interpretación perezosa de pefile
- Metadatos relevantes para la seguridad — características de DLL, decodificación de nombre de subsistema/máquina, entropía por recurso
- 1370 pruebas con 100% de cobertura — verificadas de extremo a extremo contra `dumpbin` en binarios reales
---
### **v0.7.4.1 — Hotfix de compatibilidad con Windows**
- Se eliminó la dependencia `python-magic`, que causaba fallos de importación en sistemas Windows
- Se añadió un detector de tipo de archivo en Python puro para portabilidad total multiplataforma
- Mejora de la lógica de detección de PE mediante la aplicación de una validación de PE estricta compatible con Windows.
- Sin cambios de comportamiento en la extracción de IOC
- La corrección de consistencia de `--min-length` está planificada para **v0.7.5**
---
### **v0.7.4 — Análisis avanzado de directorios**
- Análisis y validación completos del **Load Config Directory**
- Metadatos extendidos del Optional Header para heurísticas posteriores
- Nuevas heurísticas de GuardCF, cookie, anomalías
- Análisis de PE más rápido
- 99 fixtures de PE en la suite de pruebas; 45 totalmente validadas según especificación
---
### **v0.7.3 — Corrección estructural y heurísticas deterministas**
- Endurecimiento importante de todos los validadores estructurales de PE
- Comportamiento determinista y estable en snapshots
- ReasonCodes claros y consistentes
- Heurísticas más sólidas construidas sobre la verdad estructural
---
### **v0.7.2 — Corrección de dependencias**
- Se añadió la dependencia faltante `idna`
- Sin cambios de comportamiento ni de esquema
---
### **v0.7.1 — Expansión de heurísticas adversarias y endurecimiento del analizador**
- Seis nuevas heurísticas de PE
- Corpus de PE adversario ampliado
- Extractores de dominio/URL/crypto/hash endurecidos
- Salida validada por snapshots deterministas
---
### **v0.7.0 — Heurísticas deterministas y base de pruebas adversarias**
- Heurísticas deterministas
- Muestras adversarias de capa 3
- Pruebas de contrato de snapshots
- Corrección de fallo en Rich Header
---
### **v0.6.0 — Esquema de salida estable y metadatos deterministas**
- Esquema JSON totalmente estable
- Metadatos de PE normalizados
- Niveles de análisis formalizados
---
### **v0.5.0 — Niveles de análisis, análisis de secciones de PE, indicios de ofuscación**
- Nuevo sistema de niveles de análisis
- Análisis estructural de PE
- Heurísticas de ofuscación
---
### **v0.4.0 — Arquitectura de plugins**
- Motor de reglas preparado para plugins
- Flujo de detección unificado
---
### **v0.3.0 — Detección de IOC de criptomonedas**
- Detección de carteras Ethereum y Bitcoin
---
### **v0.2.0 — Detección de IP de alta fiabilidad**
- Mejoras importantes en IPv4/IPv6
</details>
---
# Inicio rápido
### Instalar
```bash
pip install iocx
```
### Extraer IOCs de un archivo
```bash
iocx suspicious.exe
```
### Extraer de texto
```bash
echo "Visit http://bad.example.com" | iocx -
```
### Habilitar el análisis de PE
```bash
iocx suspicious.exe -a
```
### API de Python
```python
from iocx.engine import Engine
engine = Engine()
results = engine.extract("suspicious.exe")
print(results)
```
---
# Ejemplo de salida
> IOCX produce JSON estructurado y determinista que incluye IOCs, metadatos de PE, análisis de secciones, heurísticas e indicadores de ofuscación.
>
> El ejemplo a continuación es una salida abreviada de una muestra de PE adversaria real. Demuestra la forma y la profundidad del esquema mientras mantiene el tamaño manejable para fines de documentación.
<details>
<summary><strong>Mostrar ejemplo de salida 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>
---
# Arquitectura
```
iocx/
├── examples/
├── docs/
├── tests/
└── iocx
├── detectors/
├── parsers/
├── plugins/
├── cli/
└── analysis/
```
---
# Ecosistema de plugins y extensibilidad
IOCX está diseñado para ser extendido de forma segura y predecible.
Los plugins son **ciudadanos de primera clase**, validados por las mismas pruebas de snapshot deterministas que el motor principal.
Puedes construir:
- detectores de IOC personalizados
- reglas regex personalizadas
- plugins conscientes del binario
- heurísticas internas
- extractores específicos de pipeline
Consulta:
- `docs/specs/overlap-suppression.md`
- `docs/specs/plugin-authoring-guidelines.md`
---
# Visión general del ecosistema
IOCX es más que un único binario — es un ecosistema modular:
- **Motor principal** — extracción determinista de IOC + análisis de PE
- **Sistema de plugins** — detectores personalizados y módulos de análisis
- **Corpus adversario** — PEs malformados, cadenas hostiles, muestras de fuzzing
- **Framework de pruebas de snapshot** — garantiza una salida determinista
- **Benchmarks de rendimiento** — aplicados en CI
- **Suite de documentación** — especificaciones, contratos y guías de plugins
---
# ¿Quién usa IOCX?
IOCX se usa en:
- equipos de DFIR
- pipelines de automatización de SOC
- barreras de seguridad en CI/CD
- plataformas de threat-intel
- laboratorios de investigación de malware
- equipos de ingeniería de seguridad
Dondequiera que los indicadores necesiten extraerse de forma **segura**, **determinista** y **a escala**, IOCX encaja.
---
# Pruebas seguras (sin necesidad de malware)
Todas las muestras de prueba son:
- Sintéticas
- Benignas
- Públicamente seguras (EICAR, GTUBE)
- Diseñadas para evitar la manipulación accidental de malware
---
# Garantías de rendimiento
IOCX aplica umbrales de rendimiento estrictos en CI para garantizar:
- Sin bloqueos por backtracking de regex
- Sin ralentizaciones patológicas
- Rendimiento estable entre versiones
Consulta:
- `docs/performance.md`
---
# Identidad y nomenclatura del proyecto
El nombre **IOCX** se refiere exclusivamente al motor oficial publicado en:
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- GitHub: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
### No permitido
- Repositorios llamados `iocx`
- Herramientas llamadas "iocx" que no formen parte de este proyecto
- Implicar afiliación sin permiso
### Permitido
- `iocx-<plugin>`
- `iocx-extension-<name>`
- `iocx-detector-<feature>`
---
# Repositorios oficiales de IOCX
- Motor principal: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Meta-repositorio de plugins: [https://github.com/iocx-dev/iocx-plugins](https://github.com/iocx-dev/iocx-plugins)
- Documentación: [https://github.com/iocx-dev/iocx/tree/main/docs/specs](https://github.com/iocx-dev/iocx/tree/main/docs/specs)
- Paquete PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
---
# Hoja de ruta
El desarrollo de IOCX se centra en la estabilidad, la extensibilidad y una cobertura más profunda del análisis estático.
Los elementos a continuación representan áreas de trabajo y exploración en curso.
- **Heurísticas de PE extendidas** (comportamiento de carga diferida, anomalías estructurales, patrones de reubicación)
- **Reglas de supresión selectiva** para flujos de trabajo de OSINT, DFIR y threat-intel
- **Extracción de metadatos de ELF y Mach-O**
- **Modo de análisis por lotes** para flujos de trabajo con múltiples artefactos
- **Modos de salida estilo YARA** y hooks de enriquecimiento
- **Análisis estático agnóstico del binario**
- **Ecosistema de plugins multiplataforma**
- **Bindings de lenguaje** para Rust, Go y Node.js
---
# Contribuir
Damos la bienvenida a:
- Nuevos detectores
- Mejoras en los analizadores
- Actualizaciones de documentación
- Muestras adversarias sintéticas
Consulta `CONTRIBUTING.md` para las directrices.
---
# Seguridad
Si descubres un problema de seguridad, **no abras un issue en GitHub**.
Sigue las instrucciones en `SECURITY.md`.
---
# Licencia
Licencia MPL-2.0 — consulta `LICENSE`.