# 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>使用 IOCX CLI 从 PE 文件进行静态 IOC 提取</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 官方项目
这是用于确定性静态 IOC 提取和 PE 分析的原始 IOCX 引擎。
任何其他使用“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)
- 网站: [https://iocx.dev/](https://iocx.dev/)
---
# 为什么 IOCX 很重要
现代恶意软件**默认具有对抗性**——畸形、规避性强，并且被设计用来破坏幼稚的提取器。
- **不了解二进制结构的工具**在畸形 PE 面前会崩溃
- **沙箱**不安全，且无法在 CI/CD 中使用
- **可复现性**对于自动化流水线至关重要
**IOCX 专为真正重视正确性和确定性的环境而构建。**
---
# IOCX 引擎
**IOCX 是官方静态 IOC 提取引擎**——一个确定性的、了解二进制结构的系统，专为 DFIR、SOC 自动化、CI/CD 安全和大规模威胁情报流水线而构建。
与仅使用正则的提取器或依赖沙箱的工具不同，IOCX 执行：
- **纯静态分析**
- **零执行风险**
- **稳定、确定性的输出**
- **经过对抗性测试的启发式规则**
它是 MalX Labs 生态系统的核心组件，用于可扩展的现代威胁分析。
---
# 10 秒试用 IOCX
```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 MB/s。
典型 PE 6–15 MB/s。
即使在最坏情况的对抗性负载下也可预测。
---
这些承诺源自一套已发布的 PE 结构分析方法论——确定性夹具构建、单异常原则，以及以 Windows 加载器行为作为正确性判据。完整方法论见 docs/methodology.md，更广泛的对抗性 PE 分类法和商业夹具套件见 [paax.dev](https://paax.dev)。
# IOCX 的与众不同之处
| 能力 | **IOCX** | 典型 IOC 提取器 | 沙箱 / 动态工具 |
|-----------|-----------|------------------------|--------------------------|
| **安全性** | 零执行，仅静态 | 仅正则，无二进制安全性 | 执行不受信任代码（高风险） |
| **确定性** | 完全确定性的输出 | 在噪声下非确定性 | 设计上非确定性 |
| **二进制感知** | 完整 PE 解析、启发式规则 | 不支持二进制 | 支持，但不安全且缓慢 |
| **对抗性韧性** | 已针对畸形 PE、恶意字符串测试 | 容易被绕过 | 经常崩溃或误分类 |
| **性能** | 150–300 MB/s（文本），6–15 MB/s（PE） | 高度可变 | 极其缓慢 |
| **CI/CD 友好** | 是——安全、确定性、快速 | 部分支持 | 否——对流水线不安全 |
| **模式稳定性** | 有保证 | 罕见 | 无 |
**简而言之：** IOCX 是为*真实的对抗性现实*而构建的，而不是为理想化输入而构建的。
---
# 使用场景
### CI/CD 与 DevSecOps
- 在发布前扫描二进制文件
- 检测构建中意外出现的 URL、IP 或密钥
- 以零执行风险强制执行安全门禁
### SOC 与事件响应
- 从告警或分析师剪贴板文本中提取指标
- 在不执行的情况下安全地检查恶意软件样本
- 将 IOC 规范化为结构化 JSON
### 威胁情报
- 大规模处理情报源
- 解析非结构化报告
- 基于确定性输出构建富化流水线
### 自动化与脚本
- 将日志或工件通过管道传给 IOCX
- 使用 Python API 进行 ETL 或批处理工作流
- 使用自定义检测器进行扩展
---
# 性能概况
### **1. 原始 IOC 提取（文本、日志、缓冲区）**
**150–300 MB/s** 持续吞吐量
快速路径——无 PE 解析。
| 检测器 | 1 MB 耗时 | 吞吐量 |
|-----------|-----------|------------|
| 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. 典型 PE 文件（约 39 KB）**
- **0.0122 s**（典型）
- **0.0145 s**（启用启发式规则）
- **6–15 MB/s** 吞吐量
---
### **3. 对抗性密集 PE（1.5 MB）**
- **0.192 s**
- **~7.6 MB/s** 吞吐量
- 触发 TLS 异常、结构异常、反调试模式
---
### **4. 完整引擎（非 PE）**
- **1 MB:** 0.038 s
---
# 版本亮点
<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 文件类型检测器，实现完全跨平台可移植性
- 通过强制执行严格的 Windows 兼容 PE 验证来改进 PE 检测逻辑。
- 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 安全门禁
- 威胁情报平台
- 恶意软件研究实验室
- 安全工程团队
任何需要**安全地**、**确定性地**、**大规模地**提取指标的场景，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 和威胁情报工作流的**选择性抑制规则**
- **ELF 和 Mach-O 元数据提取**
- 面向多工件工作流的**批量分析模式**
- **YARA 风格输出模式**和富化钩子
- **二进制无关的静态分析**
- **跨平台插件生态系统**
- 面向 Rust、Go 和 Node.js 的**语言绑定**
---
# 贡献
我们欢迎：
- 新检测器
- 解析器改进
- 文档更新
- 合成对抗性样本
指南见 `CONTRIBUTING.md`。
---
# 安全
如果你发现安全问题，**请不要打开 GitHub issue**。
请遵循 `SECURITY.md` 中的说明。
---
# 许可证
MPL-2.0 许可证——见 `LICENSE`。
