IOCX

Deterministic, Zero‑Risk IOC Extraction for Modern Security Pipelines

_{Static IOC extraction from a PE file using the IOCX CLI}

Official IOCX Project

This is the original IOCX engine for deterministic static IOC extraction and PE analysis. Any other repositories using the name "iocx" are not affiliated with this project.

Official links:

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

---

Why IOCX Matters

Modern malware is adversarial by default — malformed, evasive, and engineered to break naive extractors.

• Binary‑unaware tools collapse under malformed PEs
• Sandboxes are unsafe and unusable in CI/CD
• Reproducibility is essential for automated pipelines

IOCX is built for environments where correctness and determinism actually matter.

---

The IOCX Engine

IOCX is the official static IOC extraction engine — a deterministic, binary‑aware system built for DFIR, SOC automation, CI/CD security, and large‑scale threat‑intel pipelines.

Unlike regex‑only extractors or sandbox‑dependent tools, IOCX performs:

• pure static analysis
• zero execution risk
• stable, deterministic output
• adversarial‑tested heuristics

It is a core component of the MalX Labs ecosystem for scalable, modern threat analysis.

---

Try IOCX in 10 Seconds

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

Or scan a PE file safely:

iocx suspicious.exe -a deep

---

Why IOCX Exists

Security teams face three persistent problems:

1. Regex extractors break under adversarial input
2. Sandboxing is unsafe, slow, and unsuitable for automation
3. Most IOC tools are inconsistent, slow, or produce subtly different output between runs

IOCX solves this with a deterministic, static‑only engine designed for automation, safety, and scale.

---

What IOCX Is Not

IOCX is intentionally not:

• a sandbox
• a behavioural analysis tool
• an emulator
• an enrichment engine

It never executes untrusted code. It never performs dynamic analysis. It is static‑only by design — for safety, determinism, and CI/CD compatibility.

---

Design Philosophy

IOCX is engineered for the realities of modern malware, not the assumptions of legacy tools.

1. Determinism over ambiguity

Stable, reproducible output — no randomness, no volatility.

2. Static over dynamic

Execution is unsafe. Static analysis is predictable, scalable, and CI‑friendly.

3. Adversarial‑first engineering

Malformed PEs, corrupted RVAs, hostile strings — IOCX treats them as normal input.

4. Schema stability as a contract

Downstream systems should never break on upgrade.

5. Performance without compromise

150–300 MB/s on raw text. 6–15 MB/s on typical PEs. Predictable even under worst‑case adversarial load.

---

These commitments are derived from a published research methodology for PE structural analysis — deterministic fixture construction, single-anomaly discipline, and Windows loader behaviour as the correctness oracle. See docs/methodology.md for the full methodology, and paax.dev for the broader adversarial-PE taxonomy and commercial fixture suite.

What Makes IOCX Different

Capability	IOCX	Typical IOC Extractors	Sandbox / Dynamic Tools
Safety	Zero‑execution, static‑only	Regex‑only, no binary safety	Executes untrusted code (high‑risk)
Determinism	Fully deterministic output	Non‑deterministic under noise	Non‑deterministic by design
Binary Awareness	Full PE parsing, heuristics	No binary support	Yes, but unsafe + slow
Adversarial Resilience	Tested against malformed PEs, hostile strings	Easily bypassed	Often crashes or misclassifies
Performance	150–300 MB/s (text), 6–15 MB/s (PE)	Highly variable	Extremely slow
CI/CD Friendly	Yes — safe, deterministic, fast	Partial	No — unsafe for pipelines
Schema Stability	Guaranteed	Rare	None

In short: IOCX is built for real adversarial reality, not idealized input.

---

Use Cases

CI/CD & DevSecOps

• Scan binaries before release
• Detect accidental URLs, IPs, or secrets in builds
• Enforce security gates with zero execution risk

SOC & Incident Response

• Extract indicators from alerts or analyst clipboard text
• Safely inspect malware samples without execution
• Normalize IOCs into structured JSON

Threat Intelligence

• Process feeds at scale
• Parse unstructured reports
• Build enrichment pipelines on deterministic output

Automation & Scripting

• Pipe logs or artifacts through IOCX
• Use the Python API for ETL or batch workflows
• Extend with custom detectors

---

Performance Profiles

1. Raw IOC Extraction (Text, Logs, Buffers)

150–300 MB/s sustained throughput Fast path — no PE parsing.

Detector	1 MB Time	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. Typical PE Files (~39 KB)

• 0.0122 s (typical)
• 0.0145 s (with heuristics)
• 6–15 MB/s throughput

---

3. Adversarial Dense PE (1.5 MB)

• 0.192 s
• ~7.6 MB/s throughput
• Triggers TLS anomalies, structural anomalies, anti‑debug patterns

---

4. Full Engine (Non‑PE)

• 1 MB: 0.038 s

---

Version Highlights

Show Version History

v0.7.6.2 — Import Table Validator

• New deterministic import table structural validator (IMPORT_* reason codes).
• version_info now parsed and surfaced at every analysis level (not just -a full), via a new bounded public projection.
• Rebuilt CLI: branded --version output, clearer --help text, reorganised argument groups.
• Fixed a relocation-parser crash reachable from any entry, a PE32+ data-directory offset bug, and several silent export/resource error drops.
• New static CI check that prevents parser error tags from silently going unconsumed by validators.
• Test suite: 2,136 → 2,802 tests.

---

v0.7.6.1 — Exception Directory Validator

• Adds deep semantic validation of the PE exception (.pdata) directory; 14 new reason codes; 15 validators total.
• Fixes a defect that had been suppressing structural findings across the engine.
• Four further checks found to be dead in production: two directory placement, a section-mapping, and a resource-directory bounds check.
• Output-visible: findings previously suppressed or mislabelled will now appear.
• Tests: 1620 → 2136. Coverage: 100%.

---