v0.7.2

Dependency fix

Added missing idna dependency required for punycode and Unicode domain handling.

v0.7.1

IOCX v0.7.1 — Heuristics Expansion, Parser Hardening & Full Adversarial Coverage

v0.7.1 is a robustness‑focused release that expands IOCX’s PE heuristics layer, hardens the static parser, and introduces a comprehensive adversarial corpus covering both malformed binaries and hostile IOC‑like strings. The goal is to ensure deterministic, JSON‑safe behaviour even under intentionally corrupted conditions.

New Structural Heuristics (PE Analysis Layer)

Six new heuristics were added to improve detection of malformed or inconsistent PE structures:

• Section Overlap Analysis:
  _analyse_section_overlap
• Section Alignment Validation:
  _analyse_section_alignment
• Optional Header Consistency Checks:
  _analyse_optional_header_consistency
• Entrypoint Mapping Validation:
  _analyse_entrypoint_mapping
• Data Directory Anomaly Detection:
  _analyse_data_directory_anomalies
• Import Directory Validity Checks:
  _analyse_import_directory_validity

These heuristics provide clearer, reason‑coded anomaly reporting while avoiding false positives.

Expanded Adversarial PE Corpus

New malformed and corrupted PE samples were added under
tests/contract/fixtures/layer3_adversarial/, including:

• broken RVAs and invalid addressing
• overlapping or misaligned sections
• corrupted data directories
• malformed import tables
• invalid optional headers (PE32 & PE32+)
• truncated Rich headers
• packed‑lookalike binaries (high entropy, fake UPX names)
• franken‑PE hybrids combining multiple structural faults (PE32 & PE32+)

All outputs are snapshot‑validated for determinism.

Full Adversarial Coverage for All IOC Categories

New adversarial string fixtures now stress every extractor:

• Crypto wallets: reversed, embedded, noisy, base58‑adjacent
• Domains: Unicode homoglyphs, mixed‑script lookalikes
• URLs: broken schemes, nested encodings, truncated fragments
• IPs: malformed IPv4/IPv6, concatenated segments, invalid scopes
• Filepaths: MAX_PATH‑breaking Windows paths, malformed UNC prefixes
• Hashes: truncated or near‑miss hex sequences
• Base64: invalid padding, embedded noise
• Emails: malformed local parts, Unicode variants

Each fixture includes a locked snapshot to guarantee reproducibility.

Parser & Heuristic Hardening

• Parser remains stable on malformed PE structures
• All errors are structured, JSON‑safe, and deterministic
• Heuristics validated to avoid false positives under corruption
• No crashes or nondeterministic output across platforms

Extractor hardening

Domain

• Expanded TLD domain lists and refined boundary detection
• Punycode + IDN homoglyph analysis and expanded detection metadata
• Improved regex structure for stability and predictable linear performance

URL

• Added support for ftp, ftps, and sftp and RFC‑compliant userinfo parsing
• Punycode domain support

Crypto

• Added full Base58Check validation for Bitcoin

Hash

• Increased short‑hex minimum length from 8 → 10 characters

Representative Fixtures Added

• broken_rva_addresses.full.exe
• overlapping_sections.full.exe
• invalid_optional_header.full.exe / .pe32.full.exe
• malformed_import_table.full.exe
• corrupted_data_directories.full.exe
• truncated_rich_header.full.exe
• packed_lookalike.full.exe
• upx_name_only.full.exe
• franken_malformed_pe.full.exe / .pe32.full.exe
• malformed_url.full.exe
• malformed_domain.full.exe
• malformed_ip.full.exe
• crypto_strings_adversarial.full.bin
• homoglyph_domains_adversarial.full.bin
• filepaths_strings_adversarial.full.bin
• emails_strings_adversarial.full.bin
• hashes_strings_adversarial.full.bin
• long_paths_adversarial.full.bin
• malformed_urls_adversarial.full.bin
• base64_strings_adversarial.full.bin

Non‑Goals

v0.7.1 does not introduce:

• dynamic execution
• unpacking or emulation
• behavioural tracing
• ML/AI models
• sandboxing
• network access

IOCX remains static‑only and deterministic.

Summary

v0.7.1 delivers:

• a stronger heuristics layer
• a hardened PE parser
• hardened extractors
• full adversarial coverage across all IOC categories
• deterministic, JSON‑safe behaviour under hostile inputs
• comprehensive snapshot tests to prevent regressions

This release significantly improves IOCX’s resilience and structural awareness without altering extractor behaviour.

v0.7.0

IOCX v0.7.0 — Deterministic Heuristics & Adversarial Testing Foundation

v0.7.0 introduces IOCX’s first deterministic heuristic analysis engine, a new adversarial testing layer, and a snapshot‑driven contract testing framework. This release marks the point where IOCX moves beyond structural parsing into behavioural-signal analysis, with a focus on stability, determinism, and adversarial resilience.

This version also includes an important fix to ensure IOCX remains robust when analysing malformed or high‑entropy PE metadata.

New: Heuristic Analysis Engine (v0.7.0)

A new subsystem that performs deterministic heuristic evaluation when analysis_level = full.

Initial heuristics include:

• Anti‑debug API detection
• TLS callback anomaly detection
• Packer‑like behaviour (entropy, section names, layout)
• RWX section detection
• Import‑table anomalies
• Signature anomalies

These heuristics are intentionally conservative and fully snapshot‑tested to ensure deterministic output.

New: Layer 3 Adversarial Testing (initial samples)

v0.7.0 introduces the first adversarial samples in the new Layer 3 test suite. These samples are designed to validate IOCX’s resilience against intentionally difficult or malformed inputs.

Initial samples:

heuristic_rich.full.exe

A PE with an intentionally rich layout and atypical import patterns.

Used to validate:

• deterministic heuristic behaviour
• packer-like heuristics
• IOC extraction
• absence of false‑positive heuristics

crypto_entropy_payload.full.exe

A PE containing a high‑entropy .crypt section and a Rich Header with non‑UTF8 byte sequences.
This sample exposed a crash in IOCX’s Rich Header parsing, where nested byte structures could not be serialized to JSON.

Used to validate:

• entropy analysis
• Rich Header sanitisation
• deterministic output under malformed metadata

This is the sample that originally broke IOCX during adversarial testing.

string_obfuscation_tricks.full.exe

A PE containing split strings, reversed strings, null‑interspersed sequences, and random bytes.
Used to ensure IOCX extracts only literal IOCs and does not reconstruct obfuscated content.

(Additional samples will be added in v0.7.1.)

Bug Fix: Rich Header Serialization Crash

During adversarial testing, IOCX encountered a crash when parsing PE Rich Headers containing non‑UTF8 or malformed byte sequences.

This manifested as:

TypeError: Object of type bytes is not JSON serializable

Fix included in v0.7.0:

• Added a deep recursive sanitiser for Rich Header structures
• All nested bytes and bytearray values are now hex‑encoded
• Ensures deterministic, JSON‑safe output for all PE files
• Prevents crashes on malformed or adversarial Rich Headers
• Added contract tests to guarantee this behaviour going forward

This fix significantly improves IOCX’s robustness when analysing real‑world and adversarial binaries.

New: Snapshot‑Driven Contract Testing

v0.7.0 introduces a new contract testing framework:

• Each sample has a corresponding JSON snapshot
• Output must match snapshots byte‑for‑byte
• Deterministic ordering of sections, imports, heuristics, and IOCs
• All current contract tests pass

This framework will expand as more adversarial samples are added.

Documentation Updates

• New contract-safe testing strategy including a four-layer test matrix
• New appendices for the three adversarial samples
• “Contract Tests: Passing” badge

The documentation now reflects the long‑term structure of the test suite.

What’s Next (v0.7.1 and beyond)

Future releases will expand the adversarial suite with additional samples, including:

• malformed PE headers
• corrupted section tables
• broken RVAs
• packed‑looking but not packed binaries
• embedded crypto wallet addresses
• homoglyph domains
• malformed URLs
• extremely long paths

These will further harden IOCX’s parser, heuristics, and IOC extraction logic.

v0.6.0

IOCX v0.6.0 — PE Metadata Expansion

This release introduces a major upgrade to IOCX’s static PE analysis pipeline.
v0.6.0 adds a comprehensive, deterministic metadata extraction layer for Portable Executable (PE) files — enabling deeper structural insight while preserving IOCX’s core philosophy:

• purely static
• offline
• deterministic
• safe for untrusted input
• no dynamic analysis or unpacking

This metadata forms the foundation for the behavioural-signal heuristics planned for v0.7.0 (packer detection, anti‑debug heuristics, TLS callback analysis, import anomaly scoring, etc.).

What’s New in v0.6.0

1. Import Table Extraction

IOCX now extracts detailed import information:

• DLL names
• imported functions
• ordinal imports
• delayed imports
• bound imports

2. Export Table Extraction

For DLLs and export‑bearing executables, IOCX now extracts:

• exported function names
• ordinals
• forwarded exports

Useful for triage, reverse engineering, and tooling analysis.

3. Resource Directory Extraction

IOCX now parses the PE resource tree and extracts:

• resource types (ICON, VERSION, RCDATA, etc.)
• resource sizes
• resource entropy
• language codes

High‑entropy resources often indicate embedded payloads or obfuscation.

4. TLS Directory (Raw Extraction)

TLS directory metadata is now extracted, including:

• start/end addresses
• callback table pointer

No heuristics are applied in this version — interpretation arrives in v0.7.0.

5. Extended PE Header Metadata

IOCX now surfaces a richer set of header fields:

• timestamp
• subsystem
• machine type
• characteristics flags
• entry point
• image base
• section alignment
• compiler/toolchain hints
• digital signature presence (raw only)

This metadata is deterministic and safe to parse.

6. Unified Metadata Output

All new metadata is returned as structured Detection objects. This format is stable, predictable, and compatible with downstream tooling.

Security & Safety Guarantees

v0.6.0 maintains IOCX’s strict safety model:

• no execution
• no unpacking
• no emulation
• no behavioural analysis
• no network access
• no heavy dependencies
• no ML/AI models
• All analysis is deterministic and offline.

Testing Improvements

The v0.6.0 test suite includes:

• deterministic import/export/resource extraction tests
• TLS directory extraction tests
• extended header metadata tests
• negative tests for corrupted or malformed PEs
• stability tests ensuring identical output across runs
• synthetic PE fixtures (pure Python, no external dependencies)

This ensures reliability across platforms and Python versions.

Internal Architecture Changes

New module: iocx/analysis/extended.py

Clean integration into the PE pipeline:

• after PE parsing
• before IOC detectors
• No changes to existing extractors
• No impact on v0.5.0 obfuscation heuristics

This keeps the pipeline modular and ready for v0.7.0.

Looking Ahead: v0.7.0

The metadata introduced in v0.6.0 enables the next major feature set:

• packer detection
• TLS callback heuristics
• anti‑debug heuristics
• import anomaly scoring
• signature anomaly detection
• control‑flow hints

These will build on the structural data added in this release.

Thank You

Thank you to everyone contributing tests, fixtures, and feedback.
v0.6.0 is a foundational release that significantly expands IOCX’s static analysis capabilities while keeping the tool safe, deterministic, and lightweight.

v0.5.1

IOCX v0.5.1 — Documentation Hardening & Full Test Coverage

This is a refinement release focused on strengthening IOCX’s security posture, improving contributor experience, and completing our test suite.

No behavioural changes were introduced — v0.5.1 is entirely about quality, clarity, and correctness.

What’s New in v0.5.1

1. Full Threat Model Documentation Added

A complete STRIDE‑based threat model is now included in the repository, covering:

• trust boundaries
• data flows
• attacker entry points
• component‑level STRIDE tables
• mitigations and non‑goals

This provides a clear, auditable security foundation for future releases.

2. SECURITY.md Tightened and Expanded

The security policy has been clarified and hardened:

• clearer disclosure process
• explicit guidance on handling untrusted samples
• stronger language around safe development practices
• improved structure and readability

This ensures contributors and users follow safe, consistent workflows.

3. README.md & CONTRIBUTING.md Overhauled

Both documents have been rewritten for clarity and precision:

• simplified onboarding instructions
• clearer architecture overview
• strict core vs plugin boundaries
• improved extractor guidelines
• explicit testing expectations
• reduced repetition and ambiguity

The project now feels more polished and contributor‑friendly.

4. Test Coverage Reached 100%

All modules — including edge‑case paths — are now fully covered by deterministic tests.

Highlights:

• synthetic PE fixtures
• negative tests for malformed input
• stability tests for deterministic output
• extractor validation tests
• obfuscation heuristics tests

This milestone significantly increases confidence in the codebase and future changes.

5. Internal Improvements

• Minor cleanup of unused code paths
• Improved consistency in Detection object metadata
• Better separation between core logic and test fixtures
• Documentation synced with v0.5.0 feature set

Looking Ahead

v0.6.0 will introduce the PE Metadata Expansion layer:

• imports
• exports
• resources
• TLS directory
• extended headers
• v0.7.0 will build on that with behavioural-signal heuristics.

Thank You

Thank you to everyone contributing feedback, tests, and documentation improvements.
v0.5.1 is a foundational quality release that sets the stage for the deeper analysis features coming next.

v0.5.0

IOCX v0.5.0 — Static PE Analysis Engine Release

Overview

IOCX v0.5.0 is a major milestone release introducing the full static PE analysis engine.
This expands IOCX beyond raw text extraction and enables deep, deterministic static analysis of Windows Portable Executable (PE) files — without executing or emulating code.

This release also formalises the project’s identity, updates documentation, and prepares the engine for future binary‑analysis features.

New: Static PE Analysis Engine

v0.5.0 introduces IOCX’s first full binary‑aware analysis pipeline:

Section‑level analysis

• Section table parsing
• Entropy calculation
• Extraction of embedded strings and byte sequences
• Obfuscation hints

IOC scanning within section data

• Embedded IOC extraction

• URLs, domains, IPv4/IPv6
• File paths and registry paths
• Hashes (MD5/SHA1/SHA256)
• Emails
• Base64 sequences
• Crypto wallet identifiers

• Deterministic, safe, static‑only

• No execution
• No sandboxing
• No dynamic loading
• Suitable for DFIR, SOC pipelines, CI/CD, and malware triage

This is the largest functional expansion of IOCX to date.

Updated CLI

• Basic, deep and full (future-proof) analysis modes

Engine Improvements

• Unified extraction pipeline for text and PE inputs
• More consistent normalisation of IOC values
• Improved performance on large binaries
• Reduced memory usage during section scanning
• More deterministic ordering of extracted IOCs

Documentation & Identity Updates

This release formalises the IOCX project identity to prevent confusion with unrelated tools using the IOCX name.

New documentation includes:

• Official IOCX Project banner
• Project Identity & Naming policy
• Official Repositories list

These changes clarify that:

• IOCX refers exclusively to this project and its PyPI package
• Third‑party tools must not use iocx as their repository name
• Plugins should follow the iocx- naming pattern
• The project is maintained under the iocx‑dev organisation

Testing

• All tests pass
• New tests added for PE parsing and section scanning
• Coverage slightly reduced due to new code paths (to be improved in v0.5.1)

Packaging & Distribution

• Updated readme-pypi.md with identity banner and naming policy
• Improved PyPI metadata
• Wheel and sdist builds include all PE analysis components

v0.4.0

IOCX v0.4.0 — New Plugin Capability System, Faster Engine, Cleaner CLI

IOCX v0.4.0 is a major feature release that introduces a brand‑new plugin capability model, improves developer ergonomics, and delivers significant performance gains across all detectors. The engine is now faster, more extensible, and backed by a fully green test suite across CI.

New: Plugin Capability System

This release introduces a new structured plugin capability model, enabling plugins to declare exactly what they provide:

• transformer
• detector
• enricher

Each plugin now includes rich metadata:

• capability type
• version
• author
• description
• minimum IOCX version

This system lays the foundation for a more powerful and extensible plugin ecosystem, ensuring safe loading, compatibility checks, and future expansion.

CLI Enhancements

• Cleaner, more consistent argument handling
• Improved error messages and exit codes
• New --dev mode for plugin authors
• Subtle stderr‑only dev banner that never pollutes JSON output

These changes make IOCX more predictable and pleasant to use in both interactive and automated environments.

Performance Improvements

Extensive profiling and tuning across detectors resulted in major speed gains:

Test	Results
Engine end‑to‑end (1MB)	0.035s
Crypto detectors (1MB)	0.0021s
Filepath detectors (1MB)	0.0038s
IP detectors (1MB)	0.0066s
Pathological cases	All stable, no regex backtracking

Real‑world throughput now reaches ~28 MB/s, making IOCX one of the fastest static IOC extraction engines available.

Test Suite Expansion

• 536 tests total
• Full integration tests for plugin loading and transformation
• Deterministic CI‑safe plugin tests
• Performance tests for all major detector classes
• Coverage at 97%
• All tests passing in CI

This release significantly strengthens the reliability and maintainability of the codebase.

Internal Improvements

• More robust detector registry
• Cleaner separation between built‑in and plugin detectors
• Simplified transformation pipeline
• Reduced overhead in detector dispatch
• Better engine configuration model
• Improved plugin discovery logic

These changes make the engine easier to extend and reason about.

Installation

pip install iocx

Links

• Homepage: https://iocx.dev/
• Repository: https://github.com/iocx-dev/iocx
• Issues: https://github.com/iocx-dev/iocx/issues

v0.3.0

v0.3.0 — Stronger Architecture, New Crypto IOC Detection, Same Blazing Performance

v0.3.0 is a foundational release that tightens the engine’s architecture, expands IOC coverage, and preserves the extractor’s extremely fast performance even on multi‑megabyte inputs. This release makes the engine more predictable, extensible, and resilient for the long term extensibility.

New in 0.3.0

✔ Bitcoin & Ethereum IOC detection

The extractor now identifies BTC and ETH wallet addresses alongside existing URL, IP, domain, email, hash, file path, and Base64 detectors. Crypto indicators are increasingly common in malware, threat intel, and log analysis, and this release brings first‑class support.

✔ Self‑initialising detector registry

The registry now guarantees that all detectors load exactly once, regardless of import order, test isolation, or runtime environment. This removes subtle bugs caused by Python’s module caching and makes detector discovery fully deterministic.

✔ Unified deduplication and IOC normalisation

The engine now applies consistent, type‑safe dedupe and normalisation rules across all IOC categories. Domains, emails, and hashes are normalised; crypto, Base64, filepaths, and URLs retain their exact case. This produces cleaner, more predictable output without altering semantics.

✔ Cleaner, more scalable project layout

The engine, detectors, registry, and CLI are now clearly separated. This improves maintainability and sets the stage for future plugin support and additional IOC families.

Performance remains excellent

Despite the architectural improvements, extraction speed is unchanged. Benchmarks show the same ultra‑fast performance:
• 1MB mixed‑content filepaths: 0.0040s
• 1MB mixed‑content IPs: 0.0070s
• Pathological cases remain stable and predictable
• Linear scaling across all detectors

Detector execution remains the dominant cost, and that path is untouched.

Why this release matters

v0.3.0 strengthens the foundation for everything that comes next:

• deterministic, safer detector loading
• unified, predictable IOC handling
• architecture ready for new IOC types and plugin systems
• consistent behaviour across CLI, library usage, and tests
• fewer surprises for contributors and integrators

It’s the kind of behind‑the‑scenes work that makes future features easier, faster, and safer to build.

v0.2.0

v0.2.0 — Chaos‑Hardened, Fuzz‑Tested, and Performance‑Proven IP detection

This release marks a major milestone for iocx. v0.2.0 focuses on IP detection robustness, predictability, and real‑world resilience — ensuring the extractor behaves correctly even under adversarial, malformed, or pathological input.

Highlights

✔ Salvage‑First Extraction Model (Documented & Enforced)

The extractor now follows a clearly defined behaviour:

• If a valid IP exists anywhere inside a malformed or obfuscated string, extract it.
• If not, return nothing.
• Never crash.

This applies to:

• IPv4
• full IPv6
• compressed IPv6
• bracketed IPv6
• IPv6 with ports
• IPv6 with zone indices
• valid IPs buried inside attacker‑style junk

Testing Enhancements

v0.2.0 introduces a comprehensive, adversarial test suite designed to reflect real SOC and DFIR conditions.

✔ Chaos Corpus

A curated set of malformed indicators inspired by:

• malware configs
• corrupted logs
• obfuscated payloads
• protocol fragments
• encoding tricks

The extractor must salvage valid IPs and ignore the rest.

✔ Random Fuzzing

Thousands of randomized samples across:

• IPv4
• IPv6
• compressed IPv6
• zone‑indexed IPv6
• random noise

Ensures robustness and crash‑free behaviour.

✔ Mutation‑Based Fuzzing

Starting from realistic IOC seeds, we apply:

• delimiter corruption
• bracket abuse
• hex mangling
• prefix/suffix junk
• reversed strings
• zone index injection

The extractor must remain stable and predictable.

✔ CIDR‑Aware Fuzzing

CIDR notation is a common source of parsing bugs.

We fuzz:

• valid masks
• invalid masks (/999, /abc, /-1, ///)
• compressed IPv6 + CIDR
• zone indices + CIDR
• junk‑wrapped CIDR

The extractor must salvage the IP when possible — and never crash.

Performance Benchmarks

The extractor is now validated under large‑scale and pathological conditions.

1MB mixed-content:        0.0053s
Pathological IPv6 blob:   0.0005s
100KB:                    0.0006s
300KB:                    0.0017s
600KB:                    0.0031s
1000KB:                   0.0055s

These results confirm:

• no catastrophic backtracking
• no exponential blowups
• stable performance under malformed input
• predictable linear scaling
• throughput suitable for high‑volume log ingestion

Internal Improvements

• unreachable branches removed for coverage clarity
• clearer internal documentation
• improved test structure and naming
• performance tests added under pytest -m performance

Why v0.2.0 matters

This release makes the extractor:

• more resilient
• more predictable
• more aligned with real‑world DFIR workflows
• safer to use in automated pipelines
• ready for high‑volume SOC ingestion

If you work in threat intel, DFIR, or detection engineering, your logs are messy — this extractor is now built for that reality.

v0.1.0

v0.1.0 — Initial MVP Release

This is the first public release of iocx, the core IOC extraction engine powering the MalX Labs ecosystem.
It delivers a clean, test‑driven foundation for extracting indicators of compromise from Windows PE files and plain text.

Key Features

• Extracts IOCs from both PE binaries and raw text input

• Supports detection of:

  • URLs
  • Domains
  • IP addresses
  • Email addresses
  • Windows file paths
  • Hashes
  • Base64 strings

• Parses multiple PE sections, including:

  • .text
  • .rdata
  • .rsrc (resource strings)

• Deterministic integration tests using synthetic, committed PE fixtures

• Clean, API‑first design suitable for SOC automation workflows

• Lightweight CLI:

    iocx <file>

Project Goals for the MVP

• Provide a reliable, extensible IOC extraction core
• Ensure deterministic, dependency‑free test coverage
• Establish the foundation for future enrichment and analysis modules

Notes

This release focuses on correctness, clarity, and testability.
Future versions will expand into enrichment, metadata extraction, and deeper PE analysis.