iocx-dev/iocxUm mecanismo de análise estática extensível e determinístico que extrai IOCs de alto sinal de binários PE e texto, criado para automação de SOC e pipelines modernos de análise de ameaças.
# IOCX
### **Extração Determinística e Sem Riscos de IOCs para Pipelines de Segurança 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>Extração estática de IOCs de um arquivo PE usando a CLI do 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>
# Projeto Oficial IOCX
Este é o motor IOCX original para extração estática determinística de IOCs e análise de PE.
Quaisquer outros repositórios usando o nome "iocx" **não são afiliados** a este projeto.
**Links oficiais:**
- 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/)
---
# Por Que o IOCX Importa
Malware moderno é **adversarial por padrão** — malformado, evasivo e projetado para quebrar extratores ingênuos.
- **Ferramentas sem consciência binária** colapsam sob PEs malformados
- **Sandboxes** são inseguras e inutilizáveis em CI/CD
- **Reprodutibilidade** é essencial para pipelines automatizados
**O IOCX é construído para ambientes onde correção e determinismo realmente importam.**
---
# O Motor IOCX
**O IOCX é o motor oficial de extração estática de IOCs** — um sistema determinístico e com consciência binária, construído para DFIR, automação de SOC, segurança em CI/CD e pipelines de threat-intel em larga escala.
Diferente de extratores apenas com regex ou ferramentas dependentes de sandbox, o IOCX realiza:
- **análise puramente estática**
- **risco zero de execução**
- **saída estável e determinística**
- **heurísticas testadas contra adversários**
É um componente central do ecossistema MalX Labs para análise de ameaças moderna e escalável.
---
# Experimente o IOCX em 10 Segundos
```bash
echo "http://malicious.example" | iocx -
```
Ou escaneie um arquivo PE com segurança:
```bash
iocx suspicious.exe -a deep
```
---
# Por Que o IOCX Existe
Equipes de segurança enfrentam três problemas persistentes:
1. **Extratores com regex** quebram sob entrada adversarial
2. **Sandboxing** é inseguro, lento e inadequado para automação
3. **A maioria das ferramentas de IOC** é inconsistente, lenta ou produz saídas sutilmente diferentes entre execuções
O IOCX resolve isso com um **motor determinístico e somente estático** projetado para automação, segurança e escala.
---
# O Que o IOCX *Não É*
O IOCX intencionalmente **não é**:
- uma sandbox
- uma ferramenta de análise comportamental
- um emulador
- um motor de enriquecimento
Ele nunca executa código não confiável.
Ele nunca realiza análise dinâmica.
Ele é **somente estático por design** — por segurança, determinismo e compatibilidade com CI/CD.
---
# Filosofia de Design
O IOCX é projetado para as realidades do malware moderno, não para as suposições de ferramentas legadas.
### **1. Determinismo sobre ambiguidade**
Saída estável e reproduzível — sem aleatoriedade, sem volatilidade.
### **2. Estático sobre dinâmico**
Execução é insegura. Análise estática é previsível, escalável e amigável para CI.
### **3. Engenharia com foco adversarial**
PEs malformados, RVAs corrompidos, strings hostis — o IOCX os trata como entrada normal.
### **4. Estabilidade de schema como contrato**
Sistemas downstream nunca devem quebrar em uma atualização.
### **5. Desempenho sem concessões**
150–300 MB/s em texto bruto.
6–15 MB/s em PEs típicos.
Previsível mesmo sob carga adversarial extrema.
---
Esses compromissos derivam de uma metodologia de pesquisa publicada para análise estrutural de PE — construção determinística de fixtures, disciplina de anomalia única e comportamento do loader do Windows como oráculo de correção. Consulte docs/methodology.md para a metodologia completa, e [paax.dev](https://paax.dev) para a taxonomia mais ampla de PE adversarial e o conjunto comercial de fixtures.
# O Que Torna o IOCX Diferente
| Capacidade | **IOCX** | Extratores de IOC Típicos | Ferramentas de Sandbox / Dinâmicas |
|-----------|-----------|------------------------|--------------------------|
| **Segurança** | Zero execução, somente estático | Apenas regex, sem segurança binária | Executa código não confiável (alto risco) |
| **Determinismo** | Saída totalmente determinística | Não determinístico sob ruído | Não determinístico por design |
| **Consciência Binária** | Parsing completo de PE, heurísticas | Sem suporte binário | Sim, mas inseguro + lento |
| **Resiliência Adversarial** | Testado contra PEs malformados, strings hostis | Facilmente contornado | Frequentemente trava ou classifica incorretamente |
| **Desempenho** | 150–300 MB/s (texto), 6–15 MB/s (PE) | Altamente variável | Extremamente lento |
| **Amigável para CI/CD** | Sim — seguro, determinístico, rápido | Parcial | Não — inseguro para pipelines |
| **Estabilidade de Schema** | Garantida | Rara | Nenhuma |
**Em resumo:** o IOCX é construído para a *realidade adversarial real*, não para entrada idealizada.
---
# Casos de Uso
### CI/CD & DevSecOps
- Escaneie binários antes do release
- Detecte URLs, IPs ou segredos acidentais em builds
- Imponha gates de segurança com risco zero de execução
### SOC & Resposta a Incidentes
- Extraia indicadores de alertas ou do texto da área de transferência do analista
- Inspecione amostras de malware com segurança, sem execução
- Normalize IOCs em JSON estruturado
### Threat Intelligence
- Processe feeds em escala
- Faça parsing de relatórios não estruturados
- Construa pipelines de enriquecimento sobre saída determinística
### Automação & Scripting
- Faça pipe de logs ou artefatos pelo IOCX
- Use a API Python para ETL ou fluxos em lote
- Estenda com detectores personalizados
---
# Perfis de Desempenho
### **1. Extração de IOC Bruta (Texto, Logs, Buffers)**
**150–300 MB/s** de throughput sustentado
Caminho rápido — sem parsing de PE.
| Detector | Tempo para 1 MB | Throughput |
|-----------|-----------|------------|
| 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. Arquivos PE Típicos (~39 KB)**
- **0.0122 s** (típico)
- **0.0145 s** (com heurísticas)
- **6–15 MB/s** de throughput
---
### **3. PE Adversarial Denso (1.5 MB)**
- **0.192 s**
- **~7.6 MB/s** de throughput
- Dispara anomalias de TLS, anomalias estruturais, padrões anti-debug
---
### **4. Motor Completo (Não-PE)**
- **1 MB:** 0.038 s
---
# Destaques de Versão
<details>
<summary><strong>Mostrar Histórico de Versões</strong></summary>
<br>
### v0.7.6.2 — Validador de Tabela de Importação
- Novo **validador estrutural determinístico da tabela de importação** (códigos de razão `IMPORT_*`).
- `version_info` agora é parseado e exposto em **todos** os níveis de análise (não apenas `-a full`), via uma nova projeção pública limitada.
- CLI reconstruída: saída `--version` com marca, texto de `--help` mais claro, grupos de argumentos reorganizados.
- Corrigido um crash do parser de relocação alcançável a partir de qualquer entrada, um bug de offset de data-directory em PE32+ e várias quedas silenciosas de erros de export/resource.
- Nova verificação estática de CI que impede que tags de erro do parser fiquem silenciosamente não consumidas pelos validadores.
- Suíte de testes: 2.136 → 2.802 testes.
---
### v0.7.6.1 — Validador de Diretório de Exceções
- Adiciona validação semântica profunda do diretório de exceções (`.pdata`) do PE; 14 novos códigos de razão; 15 validadores no total.
- Corrige um defeito que vinha suprimindo achados estruturais em todo o motor.
- Mais quatro verificações consideradas mortas em produção: duas de posicionamento de diretório, uma de mapeamento de seção e uma verificação de limites do diretório de recursos.
- **Visível na saída:** achados anteriormente suprimidos ou rotulados incorretamente agora aparecerão.
- Testes: 1620 → 2136. Cobertura: 100%.
---
### **v0.7.6 — Expansão do Validador Estrutural: diretórios de debug e relocations**
- Dois novos validadores estruturais de PE — relocations e debug
- Validadores WIN_CERTIFICATE e tls agora obtêm a verdade estrutural de parsers de struct dedicados, independentes do pefile
- 12 novos códigos de razão com taxonomias de sub-razão resolvidas por prioridade
- Parsing determinístico em nível de byte — sem dependência da interpretação preguiçosa do pefile
- 1620 testes com 100% de cobertura
---
### **v0.7.5 — Expansão do Validador Estrutural**
- Quatro novos validadores estruturais de PE — exports, delay-load imports, VS_VERSIONINFO e hierarquia de recursos
- 24 novos códigos de razão com taxonomias de sub-razão resolvidas por prioridade
- Parsing determinístico em nível de byte — sem dependência da interpretação preguiçosa do pefile
- Metadados relevantes para segurança — características de DLL, decodificação de subsystem/machine, entropia por recurso
- 1370 testes com 100% de cobertura — verificados de ponta a ponta contra `dumpbin` em binários reais
---
### **v0.7.4.1 — Hotfix de Compatibilidade com Windows**
- Removida a dependência `python-magic`, que causava falhas de importação em sistemas Windows
- Adicionado um detector de tipo de arquivo em Python puro para portabilidade total entre plataformas
- Melhoria na lógica de detecção de PE ao impor validação estrita de PE compatível com Windows.
- Sem mudanças comportamentais na extração de IOC
- A correção de consistência do `--min-length` está planejada para a **v0.7.5**
---
### **v0.7.4 — Parsing Avançado de Diretórios**
- Parsing e validação completos do **Load Config Directory**
- Metadados estendidos do Optional Header para heurísticas downstream
- Novas heurísticas de GuardCF, cookie e anomalias
- Análise de PE mais rápida
- 99 fixtures de PE na suíte de testes; 45 totalmente validadas pela especificação
---
### **v0.7.3 — Correção Estrutural & Heurísticas Determinísticas**
- Fortalecimento significativo de todos os validadores estruturais de PE
- Comportamento determinístico e estável em snapshots
- ReasonCodes claros e consistentes
- Heurísticas mais fortes construídas sobre a verdade estrutural
---
### **v0.7.2 — Correção de Dependência**
- Adicionada a dependência `idna` ausente
- Sem mudanças comportamentais ou de schema
---
### **v0.7.1 — Expansão de Heurísticas Adversariais & Fortalecimento do Parser**
- Seis novas heurísticas de PE
- Corpus adversarial de PE expandido
- Extratores de domínio/URL/crypto/hash fortalecidos
- Saída determinística validada por snapshot
---
### **v0.7.0 — Fundação de Heurísticas Determinísticas & Testes Adversariais**
- Heurísticas determinísticas
- Amostras adversariais de Camada 3
- Testes de contrato de snapshot
- Correção de crash do Rich Header
---
### **v0.6.0 — Schema de Saída Estável & Metadados Determinísticos**
- Schema JSON totalmente estável
- Metadados de PE normalizados
- Níveis de análise formalizados
---
### **v0.5.0 — Níveis de Análise, Análise de Seções de PE, Dicas de Ofuscação**
- Novo sistema de níveis de análise
- Análise estrutural de PE
- Heurísticas de ofuscação
---
### **v0.4.0 — Arquitetura de Plugins**
- Motor de regras pronto para plugins
- Fluxo de detecção unificado
---
### **v0.3.0 — Detecção de IOC de Criptomoedas**
- Detecção de carteiras Ethereum & Bitcoin
---
### **v0.2.0 — Detecção de IP de Alta Confiabilidade**
- Melhorias significativas em IPv4/IPv6
</details>
---
# Início Rápido
### Instalação
```bash
pip install iocx
```
### Extrair IOCs de um arquivo
```bash
iocx suspicious.exe
```
### Extrair de texto
```bash
echo "Visit http://bad.example.com" | iocx -
```
### Habilitar análise de PE
```bash
iocx suspicious.exe -a
```
### API Python
```python
from iocx.engine import Engine
engine = Engine()
results = engine.extract("suspicious.exe")
print(results)
```
---
# Exemplo de Saída
> O IOCX produz JSON estruturado e determinístico que inclui IOCs, metadados de PE, análise de seções, heurísticas e indicadores de ofuscação.
>
> O exemplo abaixo é uma saída abreviada de uma amostra real de PE adversarial. Ele demonstra a forma e a profundidade do schema, mantendo o tamanho gerenciável para fins de documentação.
<details>
<summary><strong>Mostrar Exemplo de Saída 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>
---
# Arquitetura
```
iocx/
├── examples/
├── docs/
├── tests/
└── iocx
├── detectors/
├── parsers/
├── plugins/
├── cli/
└── analysis/
```
---
# Ecossistema de Plugins & Extensibilidade
O IOCX é projetado para ser estendido de forma segura e previsível.
Plugins são **cidadãos de primeira classe**, validados pelos mesmos testes determinísticos de snapshot que o motor principal.
Você pode construir:
- detectores de IOC personalizados
- regras regex personalizadas
- plugins com consciência binária
- heurísticas internas
- extratores específicos de pipeline
Consulte:
- `docs/specs/overlap-suppression.md`
- `docs/specs/plugin-authoring-guidelines.md`
---
# Visão Geral do Ecossistema
O IOCX é mais que um único binário — é um ecossistema modular:
- **Motor Principal** — extração determinística de IOC + análise de PE
- **Sistema de Plugins** — detectores e módulos de análise personalizados
- **Corpus Adversarial** — PEs malformados, strings hostis, amostras de fuzz
- **Framework de Testes por Snapshot** — garante saída determinística
- **Benchmarks de Desempenho** — aplicados em CI
- **Suíte de Documentação** — especificações, contratos e guias de plugins
---
# Quem Usa o IOCX?
O IOCX é usado em:
- equipes de DFIR
- pipelines de automação de SOC
- gates de segurança em CI/CD
- plataformas de threat-intel
- laboratórios de pesquisa de malware
- equipes de engenharia de segurança
Onde quer que indicadores precisem ser extraídos **com segurança**, **deterministicamente** e **em escala**, o IOCX se encaixa.
---
# Testes Seguros (Sem Necessidade de Malware)
Todas as amostras de teste são:
- Sintéticas
- Benignas
- Publicamente seguras (EICAR, GTUBE)
- Projetadas para evitar manuseio acidental de malware
---
# Garantias de Desempenho
O IOCX impõe limites estritos de desempenho em CI para garantir:
- Sem travamentos por backtracking de regex
- Sem lentidões patológicas
- Desempenho estável entre releases
Consulte:
- `docs/performance.md`
---
# Identidade & Nomenclatura do Projeto
O nome **IOCX** refere-se exclusivamente ao motor oficial publicado em:
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- GitHub: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
### Não permitido
- Repositórios chamados `iocx`
- Ferramentas chamadas "iocx" que não fazem parte deste projeto
- Implicar afiliação sem permissão
### Permitido
- `iocx-<plugin>`
- `iocx-extension-<name>`
- `iocx-detector-<feature>`
---
# Repositórios Oficiais do IOCX
- Motor Principal: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Meta-Repositório de Plugins: [https://github.com/iocx-dev/iocx-plugins](https://github.com/iocx-dev/iocx-plugins)
- Documentação: [https://github.com/iocx-dev/iocx/tree/main/docs/specs](https://github.com/iocx-dev/iocx/tree/main/docs/specs)
- Pacote PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
---
# Roadmap
O desenvolvimento do IOCX foca em estabilidade, extensibilidade e cobertura mais profunda de análise estática.
Os itens abaixo representam áreas contínuas de trabalho e exploração.
- **Heurísticas estendidas de PE** (comportamento de delay-load, anomalias estruturais, padrões de relocação)
- **Regras de supressão seletiva** para fluxos de OSINT, DFIR e threat-intel
- **Extração de metadados de ELF e Mach-O**
- **Modo de análise em lote** para fluxos com múltiplos artefatos
- **Modos de saída estilo YARA** e hooks de enriquecimento
- **Análise estática agnóstica a binários**
- **Ecossistema de plugins multiplataforma**
- **Bindings de linguagem** para Rust, Go e Node.js
---
# Contribuindo
Acolhemos:
- Novos detectores
- Melhorias no parser
- Atualizações de documentação
- Amostras adversariais sintéticas
Consulte `CONTRIBUTING.md` para diretrizes.
---
# Segurança
Se você descobrir um problema de segurança, **não abra uma issue no GitHub**.
Siga as instruções em `SECURITY.md`.
---
# Licença
Licença MPL-2.0 — consulte `LICENSE`.