iocx-dev/iocxРасширяемый детерминированный движок статического анализа, извлекающий высокосигнальные IOC из PE-файлов и текста, созданный для автоматизации SOC и современных конвейеров анализа угроз.
# IOCX
### **Детерминированное извлечение IOC с нулевым риском для современных конвейеров безопасности**
<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>Статическое извлечение IOC из PE-файла с помощью IOCX CLI</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>
# Официальный проект IOCX
Это оригинальный движок IOCX для детерминированного статического извлечения IOC и анализа PE.
Любые другие репозитории, использующие имя "iocx", **не связаны** с этим проектом.
**Официальные ссылки:**
- 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/)
---
# Почему IOCX важен
Современное вредоносное ПО **по умолчанию является состязательным** — искажённым, уклончивым и спроектированным так, чтобы ломать наивные экстракторы.
- **Инструменты, не учитывающие бинарный формат**, рушатся на искажённых PE
- **Песочницы** небезопасны и неприменимы в CI/CD
- **Воспроизводимость** критична для автоматизированных конвейеров
**IOCX создан для сред, где корректность и детерминизм действительно имеют значение.**
---
# Движок IOCX
**IOCX — это официальный движок статического извлечения IOC** — детерминированная система, учитывающая бинарный формат, созданная для DFIR, автоматизации SOC, безопасности CI/CD и крупномасштабных конвейеров threat-intel.
В отличие от экстракторов, основанных только на регулярных выражениях, или инструментов, зависящих от песочницы, IOCX выполняет:
- **чистый статический анализ**
- **нулевой риск выполнения**
- **стабильный, детерминированный вывод**
- **эвристики, протестированные на состязательных данных**
Это ключевой компонент экосистемы MalX Labs для масштабируемого современного анализа угроз.
---
# Попробуйте IOCX за 10 секунд
```bash
echo "http://malicious.example" | iocx -
```
Или безопасно просканируйте PE-файл:
```bash
iocx suspicious.exe -a deep
```
---
# Зачем существует IOCX
Команды безопасности сталкиваются с тремя постоянными проблемами:
1. **Экстракторы на регулярных выражениях** ломаются при состязательных входных данных
2. **Песочницы** небезопасны, медленны и непригодны для автоматизации
3. **Большинство инструментов IOC** непоследовательны, медленны или дают незаметно различающийся вывод между запусками
IOCX решает это с помощью **детерминированного движка, работающего только статически**, спроектированного для автоматизации, безопасности и масштаба.
---
# Чем IOCX *не является*
IOCX намеренно **не является**:
- песочницей
- инструментом поведенческого анализа
- эмулятором
- движком обогащения
Он никогда не выполняет недоверенный код.
Он никогда не выполняет динамический анализ.
Он **по своей конструкции работает только статически** — ради безопасности, детерминизма и совместимости с CI/CD.
---
# Философия проектирования
IOCX спроектирован для реалий современного вредоносного ПО, а не для допущений устаревших инструментов.
### **1. Детерминизм вместо неоднозначности**
Стабильный, воспроизводимый вывод — без случайности, без волатильности.
### **2. Статика вместо динамики**
Выполнение небезопасно. Статический анализ предсказуем, масштабируем и удобен для CI.
### **3. Проектирование с приоритетом состязательности**
Искажённые PE, повреждённые RVA, враждебные строки — IOCX воспринимает их как обычные входные данные.
### **4. Стабильность схемы как контракт**
Нижестоящие системы никогда не должны ломаться при обновлении.
### **5. Производительность без компромиссов**
150–300 МБ/с на сыром тексте.
6–15 МБ/с на типичных PE.
Предсказуемость даже при наихудшей состязательной нагрузке.
---
Эти обязательства основаны на опубликованной исследовательской методологии структурного анализа PE — детерминированное построение фикстур, дисциплина единичной аномалии и поведение загрузчика Windows в качестве оракула корректности. Полную методологию см. в docs/methodology.md, а более широкую таксономию состязательных PE и коммерческий набор фикстур — на [paax.dev](https://paax.dev).
# Что отличает IOCX
| Возможность | **IOCX** | Типичные экстракторы IOC | Песочницы / динамические инструменты |
|-----------|-----------|------------------------|--------------------------|
| **Безопасность** | Нулевое выполнение, только статика | Только регулярные выражения, без бинарной безопасности | Выполняет недоверенный код (высокий риск) |
| **Детерминизм** | Полностью детерминированный вывод | Недетерминирован при шуме | Недетерминирован по своей природе |
| **Учёт бинарного формата** | Полный разбор PE, эвристики | Нет поддержки бинарных форматов | Да, но небезопасно и медленно |
| **Устойчивость к состязательным данным** | Протестирован на искажённых PE, враждебных строках | Легко обходится | Часто падает или неверно классифицирует |
| **Производительность** | 150–300 МБ/с (текст), 6–15 МБ/с (PE) | Крайне изменчива | Чрезвычайно медленно |
| **Дружелюбность к CI/CD** | Да — безопасно, детерминированно, быстро | Частично | Нет — небезопасно для конвейеров |
| **Стабильность схемы** | Гарантирована | Редко | Отсутствует |
**Коротко:** IOCX создан для *реальной состязательной действительности*, а не для идеализированных входных данных.
---
# Сценарии использования
### CI/CD и DevSecOps
- Сканирование бинарных файлов перед релизом
- Обнаружение случайных URL, IP или секретов в сборках
- Обеспечение безопасности с нулевым риском выполнения
### SOC и реагирование на инциденты
- Извлечение индикаторов из оповещений или текста буфера обмена аналитика
- Безопасная проверка образцов вредоносного ПО без выполнения
- Нормализация IOC в структурированный JSON
### Threat Intelligence
- Обработка фидов в масштабе
- Разбор неструктурированных отчётов
- Построение конвейеров обогащения на детерминированном выводе
### Автоматизация и скриптинг
- Передача логов или артефактов через IOCX
- Использование Python API для ETL или пакетных рабочих процессов
- Расширение с помощью пользовательских детекторов
---
# Профили производительности
### **1. Извлечение сырых IOC (текст, логи, буферы)**
**150–300 МБ/с** устойчивой пропускной способности
Быстрый путь — без разбора PE.
| Детектор | Время на 1 МБ | Пропускная способность |
|-----------|-----------|------------|
| Crypto | 0.0037 с | ~270 МБ/с |
| Filepaths | 0.0041 с | ~250 МБ/с |
| IP | 0.0065 с | ~156 МБ/с |
| Domains | 0.0035 с | ~300 МБ/с |
---
### **2. Типичные PE-файлы (~39 КБ)**
- **0.0122 с** (типично)
- **0.0145 с** (с эвристиками)
- **6–15 МБ/с** пропускной способности
---
### **3. Состязательный плотный PE (1.5 МБ)**
- **0.192 с**
- **~7.6 МБ/с** пропускной способности
- Активирует аномалии TLS, структурные аномалии, паттерны anti-debug
---
### **4. Полный движок (не PE)**
- **1 МБ:** 0.038 с
---
# Основные изменения версий
<details>
<summary><strong>Показать историю версий</strong></summary>
<br>
### v0.7.6.2 — Валидатор таблицы импорта
- Новый детерминированный **структурный валидатор таблицы импорта** (коды причин `IMPORT_*`).
- `version_info` теперь разбирается и отображается на **каждом** уровне анализа (не только `-a full`), через новую ограниченную публичную проекцию.
- Переработан CLI: брендированный вывод `--version`, более понятный текст `--help`, реорганизованные группы аргументов.
- Исправлено падение парсера релокаций, достижимое из любой точки входа, ошибка смещения каталога данных PE32+ и несколько молчаливых потерь ошибок экспорта/ресурсов.
- Новая статическая проверка CI, предотвращающая молчаливое неиспользование тегов ошибок парсера валидаторами.
- Набор тестов: 2,136 → 2,802 тестов.
---
### v0.7.6.1 — Валидатор каталога исключений
- Добавлена глубокая семантическая валидация каталога исключений PE (`.pdata`); 14 новых кодов причин; всего 15 валидаторов.
- Исправлен дефект, который подавлял структурные находки по всему движку.
- Ещё четыре проверки оказались мёртвыми в продакшене: две по размещению каталогов, одна по отображению секций и одна по границам каталога ресурсов.
- **Видимо в выводе:** находки, ранее подавленные или неверно помеченные, теперь будут появляться.
- Тесты: 1620 → 2136. Покрытие: 100%.
---
### **v0.7.6 — Расширение структурных валидаторов: каталоги отладки и релокаций**
- Два новых структурных валидатора PE — релокации и отладка
- Валидаторы WIN_CERTIFICATE и tls теперь берут структурную истину из выделенных парсеров структур, независимо от pefile
- 12 новых кодов причин с таксономиями подпричин, разрешаемых по приоритету
- Детерминированный побайтовый разбор — без опоры на ленивую интерпретацию pefile
- 1620 тестов при 100% покрытии
---
### **v0.7.5 — Расширение структурных валидаторов**
- Четыре новых структурных валидатора PE — экспорты, импорты с отложенной загрузкой, VS_VERSIONINFO и иерархия ресурсов
- 24 новых кода причин с таксономиями подпричин, разрешаемых по приоритету
- Детерминированный побайтовый разбор — без опоры на ленивую интерпретацию pefile
- Значимые для безопасности метаданные — характеристики DLL, декодирование имён подсистемы/машины, энтропия по каждому ресурсу
- 1370 тестов при 100% покрытии — сквозная проверка против `dumpbin` на реальных бинарных файлах
---
### **v0.7.4.1 — Хотфикс совместимости с Windows**
- Удалена зависимость `python-magic`, вызывавшая сбои импорта в системах Windows
- Добавлен чистый на Python детектор типа файла для полной кросс-платформенной переносимости
- Улучшена логика обнаружения PE за счёт строгой проверки PE, совместимой с Windows.
- Никаких изменений в поведении извлечения IOC
- Исправление согласованности `--min-length` запланировано на **v0.7.5**
---
### **v0.7.4 — Расширенный разбор каталогов**
- Полный разбор и валидация **Load Config Directory**
- Расширенные метаданные Optional Header для нижестоящих эвристик
- Новые эвристики GuardCF, cookie, аномалий
- Более быстрый анализ PE
- 99 PE-фикстур в наборе тестов; 45 полностью валидированы по спецификации
---
### **v0.7.3 — Структурная корректность и детерминированные эвристики**
- Существенное усиление всех структурных валидаторов PE
- Детерминированное, стабильное относительно снимков поведение
- Чёткие, согласованные ReasonCodes
- Более сильные эвристики, построенные на структурной истине
---
### **v0.7.2 — Исправление зависимостей**
- Добавлена отсутствующая зависимость `idna`
- Никаких изменений в поведении или схеме
---
### **v0.7.1 — Расширение состязательных эвристик и усиление парсера**
- Шесть новых эвристик PE
- Расширенный корпус состязательных PE
- Усилены экстракторы доменов/URL/крипто/хешей
- Детерминированный вывод, валидируемый по снимкам
---
### **v0.7.0 — Детерминированные эвристики и основа состязательного тестирования**
- Детерминированные эвристики
- Состязательные образцы уровня 3
- Контрактные тесты по снимкам
- Исправление падения Rich Header
---
### **v0.6.0 — Стабильная схема вывода и детерминированные метаданные**
- Полностью стабильная JSON-схема
- Нормализованные метаданные PE
- Формализованные уровни анализа
---
### **v0.5.0 — Уровни анализа, анализ секций PE, подсказки об обфускации**
- Новая система уровней анализа
- Структурный анализ PE
- Эвристики обфускации
---
### **v0.4.0 — Архитектура плагинов**
- Готовый к плагинам движок правил
- Унифицированный поток обнаружения
---
### **v0.3.0 — Обнаружение крипто-IOC**
- Обнаружение кошельков Ethereum и Bitcoin
---
### **v0.2.0 — Высоконадёжное обнаружение IP**
- Существенные улучшения IPv4/IPv6
</details>
---
# Быстрый старт
### Установка
```bash
pip install iocx
```
### Извлечение IOC из файла
```bash
iocx suspicious.exe
```
### Извлечение из текста
```bash
echo "Visit http://bad.example.com" | iocx -
```
### Включение анализа PE
```bash
iocx suspicious.exe -a
```
### Python API
```python
from iocx.engine import Engine
engine = Engine()
results = engine.extract("suspicious.exe")
print(results)
```
---
# Пример вывода
> IOCX выдаёт структурированный, детерминированный JSON, включающий IOC, метаданные PE, анализ секций, эвристики и индикаторы обфускации.
>
> Приведённый ниже пример — сокращённый вывод реального состязательного PE-образца. Он демонстрирует форму и глубину схемы, сохраняя размер удобным для документации.
<details>
<summary><strong>Показать пример вывода 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>
---
# Архитектура
```
iocx/
├── examples/
├── docs/
├── tests/
└── iocx
├── detectors/
├── parsers/
├── plugins/
├── cli/
└── analysis/
```
---
# Экосистема плагинов и расширяемость
IOCX спроектирован для безопасного и предсказуемого расширения.
Плагины — **полноправные граждане**, валидируемые теми же детерминированными тестами по снимкам, что и ядро движка.
Вы можете создавать:
- пользовательские детекторы IOC
- пользовательские правила регулярных выражений
- плагины, учитывающие бинарный формат
- внутренние эвристики
- экстракторы для конкретных конвейеров
См.:
- `docs/specs/overlap-suppression.md`
- `docs/specs/plugin-authoring-guidelines.md`
---
# Обзор экосистемы
IOCX — это больше, чем один бинарный файл — это модульная экосистема:
- **Ядро движка** — детерминированное извлечение IOC + анализ PE
- **Система плагинов** — пользовательские детекторы и модули анализа
- **Состязательный корпус** — искажённые PE, враждебные строки, фаззинг-образцы
- **Фреймворк тестирования по снимкам** — обеспечивает детерминированный вывод
- **Бенчмарки производительности** — применяются в CI
- **Набор документации** — спецификации, контракты и руководства по плагинам
---
# Кто использует IOCX?
IOCX используется в:
- командах DFIR
- конвейерах автоматизации SOC
- шлюзах безопасности CI/CD
- платформах threat-intel
- лабораториях исследования вредоносного ПО
- командах security engineering
Везде, где индикаторы нужно извлекать **безопасно**, **детерминированно** и **в масштабе**, IOCX подходит.
---
# Безопасное тестирование (вредоносное ПО не требуется)
Все тестовые образцы:
- Синтетические
- Безвредные
- Публично безопасные (EICAR, GTUBE)
- Спроектированы так, чтобы избежать случайной работы с вредоносным ПО
---
# Гарантии производительности
IOCX применяет строгие пороги производительности в CI, чтобы обеспечить:
- Отсутствие задержек из-за бэктрекинга регулярных выражений
- Отсутствие патологических замедлений
- Стабильную производительность между релизами
См.:
- `docs/performance.md`
---
# Идентичность и именование проекта
Имя **IOCX** относится исключительно к официальному движку, опубликованному на:
- PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
- GitHub: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
### Не разрешается
- Репозитории с именем `iocx`
- Инструменты с именем "iocx", не являющиеся частью этого проекта
- Подразумевание аффилированности без разрешения
### Разрешается
- `iocx-<plugin>`
- `iocx-extension-<name>`
- `iocx-detector-<feature>`
---
# Официальные репозитории IOCX
- Ядро движка: [https://github.com/iocx-dev/iocx](https://github.com/iocx-dev/iocx)
- Мета-репозиторий плагинов: [https://github.com/iocx-dev/iocx-plugins](https://github.com/iocx-dev/iocx-plugins)
- Документация: [https://github.com/iocx-dev/iocx/tree/main/docs/specs](https://github.com/iocx-dev/iocx/tree/main/docs/specs)
- Пакет PyPI: [https://pypi.org/project/iocx/](https://pypi.org/project/iocx/)
---
# Дорожная карта
Разработка IOCX сосредоточена на стабильности, расширяемости и более глубоком покрытии статического анализа.
Пункты ниже представляют текущие направления работы и исследования.
- **Расширенные эвристики PE** (поведение отложенной загрузки, структурные аномалии, паттерны релокаций)
- **Избирательные правила подавления** для рабочих процессов OSINT, DFIR и threat-intel
- **Извлечение метаданных ELF и Mach-O**
- **Режим пакетного анализа** для рабочих процессов с несколькими артефактами
- **Режимы вывода в стиле YARA** и хуки обогащения
- **Бинарно-агностический статический анализ**
- **Кросс-платформенная экосистема плагинов**
- **Языковые привязки** для Rust, Go и Node.js
---
# Участие в разработке
Мы приветствуем:
- Новые детекторы
- Улучшения парсеров
- Обновления документации
- Синтетические состязательные образцы
См. `CONTRIBUTING.md` для руководств.
---
# Безопасность
Если вы обнаружите проблему безопасности, **не открывайте issue на GitHub**.
Следуйте инструкциям в `SECURITY.md`.
---
# Лицензия
Лицензия MPL‑2.0 — см. `LICENSE`.