iocx-dev/iocx拡張可能で決定論的な静的解析エンジン。PEバイナリとテキストから高シグナルのIOCを抽出し、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>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)
- Website: [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が存在する理由
セキュリティチームは3つの永続的な問題に直面しています:
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にパイプ
- ETLまたはバッチワークフローにPython APIを使用
- カスタム検出器で拡張
---
# パフォーマンスプロファイル
### **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のバリデータ。
- エンジン全体で構造的所見を抑制していた欠陥を修正。
- 本番環境でデッドであることが判明した4つのさらなるチェック: 2つのディレクトリ配置、1つのセクションマッピング、1つのリソースディレクトリ境界チェック。
- **出力に表示:** 以前に抑制または誤ラベル付けされた所見が表示されるようになります。
- テスト: 1620 → 2136。カバレッジ: 100%。
---
### **v0.7.6 — 構造バリデータの拡張: デバッグおよびリロケーションディレクトリ**
- 2つの新しいPE構造バリデータ - リロケーションとデバッグ
- WIN_CERTIFICATEおよびtlsバリデータが、pefileから独立した専用の構造体パーサーから構造的真実を取得するように
- 優先度解決されたサブ理由分類を持つ12の新しい理由コード
- 決定論的なバイトレベルの解析 - pefileの遅延解釈に依存しない
- 100%カバレッジで1620テスト
---
### **v0.7.5 — 構造バリデータの拡張**
- 4つの新しいPE構造バリデータ — エクスポート、遅延ロードインポート、VS_VERSIONINFO、リソース階層
- 優先度解決されたサブ理由分類を持つ24の新しい理由コード
- 決定論的なバイトレベルの解析 — pefileの遅延解釈に依存しない
- セキュリティ関連メタデータ — DLL特性、サブシステム/マシン名デコード、リソースごとのエントロピー
- 100%カバレッジで1370テスト — 実際のバイナリで`dumpbin`に対してエンドツーエンドで検証済み
---
### **v0.7.4.1 — Windows互換性ホットフィックス**
- Windowsシステムでインポート失敗を引き起こしていた`python-magic`依存関係を削除
- 完全なクロスプラットフォーム移植性のための純粋なPythonファイルタイプ検出器を追加
- 厳密なWindows互換PE検証を強制することでPE検出ロジックを改善
- IOC抽出への動作変更なし
- `--min-length`の一貫性修正は**v0.7.5**で予定
---
### **v0.7.4 — 高度なディレクトリ解析**
- 完全な**ロード構成ディレクトリ**の解析と検証
- ダウンストリームヒューリスティックのための拡張オプションヘッダーメタデータ
- 新しいGuardCF、Cookie、異常ヒューリスティック
- より高速なPE分析
- テストスイートに99のPEフィクスチャ。45が完全に仕様検証済み
---
### **v0.7.3 — 構造的正確性と決定論的ヒューリスティック**
- すべてのPE構造バリデータの大幅な強化
- 決定論的でスナップショット安定な動作
- 明確で一貫したReasonCodes
- 構造的真実に基づくより強力なヒューリスティック
---
### **v0.7.2 — 依存関係の修正**
- 欠落していた`idna`依存関係を追加
- 動作またはスキーマの変更なし
---
### **v0.7.1 — 敵対的ヒューリスティックの拡張とパーサーの強化**
- 6つの新しい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は、IOC、PEメタデータ、セクション分析、ヒューリスティック、難読化インジケーターを含む、構造化された決定論的なJSONを生成します。
>
> 以下の例は、実際の敵対的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`を参照してください。