IOCX

Extração de IOC Determinística e Sem Risco para Pipelines de Segurança Modernos

_{Extração estática de IOC de um arquivo PE usando a CLI do IOCX}

Projeto Oficial IOCX

Este é o motor IOCX original para extração estática determinística de IOC e análise de PE. Quaisquer outros repositórios que usem o nome "iocx" não são afiliados a este projeto.

Links oficiais:

• PyPI: https://pypi.org/project/iocx/
• Github: https://github.com/iocx-dev/iocx
• Website: https://iocx.dev/

Por Que o IOCX é Importante

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 inseguros 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 IOC — 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 inteligência de ameaças em larga escala.

Diferente de extratores baseados apenas em 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 moderna e escalável de ameaças.

Experimente o IOCX em 10 Segundos

echo "http://malicious.example" | iocx -

Ou analise um arquivo PE com segurança:

iocx suspicious.exe -a deep

Por Que o IOCX Existe

Equipes de segurança enfrentam três problemas persistentes:

1. Extratores baseados em 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 resultados sutilmente diferentes entre execuções

O IOCX resolve isso com um motor determinístico e exclusivamente estático, projetado para automação, segurança e escala.

O Que o IOCX Não É

O IOCX intencionalmente não é:

• um 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. É exclusivamente estático por design — para 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 acima de ambiguidade

Saída estável e reproduzível — sem aleatoriedade, sem volatilidade.

2. Estático acima de dinâmico

Execução é insegura. Análise estática é previsível, escalável e amigável a CI.

3. Engenharia adversarial em primeiro lugar

PEs malformados, RVAs corrompidos, strings hostis — o IOCX os trata como entrada normal.

4. Estabilidade de esquema como contrato

Sistemas downstream nunca devem quebrar em atualizações.

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 no pior caso.

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 o comportamento do loader do Windows como oráculo de correção. Consulte docs/methodology.md para a metodologia completa e paax.dev para a taxonomia adversarial de PE mais ampla e o conjunto comercial de fixtures.

O Que Torna o IOCX Diferente

Em resumo: o IOCX é construído para a realidade adversarial real, não para entrada idealizada.

Casos de Uso

CI/CD & DevSecOps

• Analise binários antes do lançamento
• Detecte URLs, IPs ou segredos acidentais em builds
• Imponha portões de segurança com risco zero de execução

SOC & Resposta a Incidentes

• Extraia indicadores de alertas ou texto da área de transferência do analista
• Inspecione amostras de malware com segurança, sem execução
• Normalize IOCs em JSON estruturado

Inteligência de Ameaças

• Processe feeds em escala
• Analise relatórios não estruturados
• Construa pipelines de enriquecimento com saída determinística

Automação & Scripting

• Envie logs ou artefatos por pipes através do IOCX
• Use a API Python para ETL ou fluxos em lote
• Estenda com detectores personalizados

Perfis de Desempenho

1. Extração Bruta de IOC (Texto, Logs, Buffers)

150–300 MB/s de throughput sustentado Caminho rápido — sem parsing de PE.

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
• Aciona anomalias de TLS, anomalias estruturais, padrões anti-debug

4. Motor Completo (Não-PE)

• 1 MB: 0.038 s

Destaques de Versão

Início Rápido

Instalação

pip install iocx

Extraia IOCs de um arquivo

iocx suspicious.exe

Extraia de texto

echo "Visit http://bad.example.com" | iocx -

Habilite a análise de PE

iocx suspicious.exe -a

API 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 resumida de uma amostra adversarial real de PE. Ele demonstra a forma e a profundidade do esquema, mantendo o tamanho gerenciável para fins de documentação.

{
    "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"
                }
            }
        ]
    }
}

Arquitetura

iocx/
├── examples/
├── docs/
├── tests/
└── iocx
    ├── detectors/
    ├── parsers/
    ├── plugins/
    ├── cli/
    └── analysis/

Ecossistema de Plugins e Extensibilidade

O IOCX é projetado para ser estendido com segurança e previsibilidade. Plugins são cidadãos de primeira classe, validados pelos mesmos testes determinísticos de snapshot que o motor central.

Você pode construir:

• detectores de IOC personalizados
• regras de 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 do que um único binário — é um ecossistema modular:

• Motor Central — extração determinística de IOC + análise de PE
• Sistema de Plugins — detectores personalizados e módulos de análise
• Corpus Adversarial — PEs malformados, strings hostis, amostras de fuzzing
• Framework de Testes de Snapshot — garante saída determinística
• Benchmarks de Desempenho — aplicados no 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
• Portões de segurança em CI/CD
• Plataformas de inteligência de ameaças
• Laboratórios de pesquisa de malware
• Equipes de engenharia de segurança

Em qualquer lugar onde indicadores precisam ser extraídos com segurança, de forma determinística 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 aplica limites estritos de desempenho no CI para garantir:

• Sem travamentos por backtracking de regex
• Sem lentidões patológicas
• Desempenho estável entre versões

Consulte:

• docs/performance.md

Identidade do Projeto e Nomenclatura

O nome IOCX refere-se exclusivamente ao motor oficial publicado em:

• PyPI: https://pypi.org/project/iocx/
• GitHub: 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-<nome>
• iocx-detector-<recurso>

Repositórios Oficiais do IOCX

• Motor Central: https://github.com/iocx-dev/iocx
• Meta-Repositório de Plugins: https://github.com/iocx-dev/iocx-plugins
• Documentação: https://github.com/iocx-dev/iocx/tree/main/docs/specs
• Pacote PyPI: 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 trabalho de OSINT, DFIR e inteligência de ameaças
• Extração de metadados de ELF e Mach-O
• Modo de análise em lote para fluxos de trabalho com múltiplos artefatos
• Modos de saída estilo YARA e hooks de enriquecimento
• Análise estática agnóstica de binário
• Ecossistema de plugins multiplataforma
• Bindings de linguagem para Rust, Go e Node.js

Contribuindo

Aceitamos:

• Novos detectores
• Melhorias de parsers
• 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.