Merge pull request #12 from malx-labs/feature/plugin-eco

v0.4.0 release - Feature/plugin eco into main

Author: malx-labs

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Welcome
 
-Thank you for your interest in contributing to malx‑ioc‑extractor. This project is part of the MalX Labs ecosystem — a collection of modern, developer‑friendly security tools focused on safe, scalable analysis.
+Thank you for your interest in contributing to IOCX. This project is part of the MalX Labs ecosystem — a collection of modern, developer‑friendly security tools focused on safe, scalable analysis.
 
 We appreciate improvements of all kinds — bug fixes, new extractors, documentation updates, and thoughtful discussions.
 
@@ -27,7 +27,7 @@ Open an issue or submit a PR with a clear description.
 
 ### Add new IOC detectors
 
-Regex‑based detectors live under `extractors/`.
+Regex‑based detectors live under `detectors/extractors/`.
 Please include:
 
 - a clear regex
@@ -55,7 +55,7 @@ Better examples, diagrams, or explanations are always appreciated.
 Create your own fork and clone it locally:
 ```bash
 
-git clone https://github.com/malx-labs/malx-ioc-extractor.git
+git clone https://github.com/iocx-dev/iocx.git
 
 ```
 
@@ -148,7 +148,7 @@ We use pytest for the test suite.
 Extractor modules live in:
 ```plaintext
 
-iocx/extractors/
+iocx/detectors/extractors/
 
 ```
 

README-pypi.md

@@ -0,0 +1,58 @@
+# IOCX — Static IOC Extraction Engine
+
+IOCX is a fast, safe, deterministic engine for extracting Indicators of Compromise (IOCs) from binaries, text, and logs.
+It performs **pure static analysis** — no execution, no sandboxing, no risk.
+
+## Features
+
+- Extracts IOCs from Windows PE files and raw text
+- Detects URLs, domains, IPv4/IPv6, file paths, hashes, emails, Base64
+- Crypto wallet detection (Ethereum, Bitcoin)
+- Deterministic output suitable for automation
+- Minimal dependencies and safe for enterprise environments
+- CLI and Python API
+
+## Installation
+
+```bash
+pip install iocx
+```
+
+## CLI Usage
+
+```bash
+iocx suspicious.exe
+```
+
+```bash
+echo "Visit http://bad.example.com" | iocx -
+```
+
+## Python API
+
+```python
+from iocx.engine import Engine
+
+engine = Engine()
+results = engine.extract("suspicious.exe")
+print(results)
+```
+
+## Why IOCX?
+
+- Static‑only design (never executes untrusted code)
+- Binary‑aware IOC extraction
+- Stable JSON schema
+- High performance (~200 MB/s throughput)
+- Ideal for DFIR, SOC automation, CI/CD, and threat‑intel pipelines
+
+## Extensibility
+
+IOCX includes a lightweight plugin system that allows you to add custom detectors, parsers, and transformation rules.
+Plugins can emit new IOC categories, override built-in behaviour, or integrate IOCX into larger analysis pipelines.
+
+See the documentation for details on writing detectors and plugins.
+
+## License
+
+MIT License

README.md

@@ -3,88 +3,97 @@
     <img src="https://img.shields.io/pypi/v/iocx?logo=pypi&logoColor=white" alt="PyPI Version">
   </a>
   <img src="https://img.shields.io/badge/coverage-97%25-brightgreen" alt="Coverage">
-  <img src="https://img.shields.io/badge/tests-273_passed-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-313_passed-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/python-3.12-blue" alt="Python Version">
-  <a href="https://github.com/malx-labs/malx-ioc-extractor/blob/main/LICENSE">
-    <img src="https://img.shields.io/github/license/malx-labs/malx-ioc-extractor" alt="License">
+  <a href="https://github.com/iocx-dev/iocx/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/iocx-dev/iocx" alt="License">
   </a>
-  <a href="https://github.com/malx-labs/malx-ioc-extractor/actions">
-    <img src="https://img.shields.io/github/actions/workflow/status/malx-labs/malx-ioc-extractor/ci.yml?label=build" alt="Build Status">
+  <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" alt="Build Status">
   </a>
   <img src="https://img.shields.io/badge/v0.2.0_performance-1MB_in_0.0053s-brightgreen" alt="Performance">
   <img src="https://img.shields.io/badge/v0.2.0_throughput-~200MB%2Fs-brightgreen" alt="Throughput">
   <img src="https://img.shields.io/badge/v0.2.0_pathological_IPv6-0.0005s-brightgreen" alt="Pathological IPv6 Timing">
 </p>
 
-# malx‑ioc‑extractor
+# IOCX — Static IOC Extraction for Binaries, Text, and Artifacts
 
-**Static IOC extraction for binaries, text, and artifacts — fast, safe, and open‑source.**
+**Fast, safe, deterministic IOC extraction for DFIR, SOC automation, and large-scale threat analysis.**
 
-malx‑ioc‑extractor is a lightweight, extensible engine for extracting Indicators of Compromise (IOCs) using pure static analysis. No execution. No sandboxing. No risk.
-Built for DFIR workflows, SOC automation, and large‑scale threat analysis.
+IOCX is a lightweight, extensible engine for extracting Indicators of Compromise (IOCs) using **pure static analysis**. No execution. No sandboxing. No risk.
 
-It’s designed to be:
+Built for:
 
-- **Safe** — never executes untrusted code
-- **Fast** — built for automation and pipelines
-- **Extensible** — plug in your own regexes, parsers, and rules
-- **Developer‑friendly** — clean API, CLI, and examples
-- **Open‑source** — the extraction engine is free; enrichment lives in the MalX cloud platform
+- DFIR workflows
+- SOC automation
+- Threat-intel pipelines
+- CI/CD security checks
+- Large‑scale batch processing
 
 This project is the foundation of the MalX Labs ecosystem for scalable, modern threat‑analysis tooling.
 
-## Why malx‑ioc‑extractor?
+## Why IOCX?
 
-malx‑ioc‑extractor is designed for environments where safety, determinism, and automation matter. While many IOC extractors operate only on raw text, malx‑ioc‑extractor includes binary‑aware static analysis and an extensible rule system, making it suitable for DFIR pipelines, CI systems, and high‑volume threat‑intel processing.
+IOCX is designed for environments where **safety, determinism, and automation** matter. Unlike extractors that operate only on raw text, IOCX includes **binary‑aware static analysis**, a **plugin-friendly rule system**, and a **stable JSON schema**.
 
-**Key advantages**
+### Key advantages
 
-- **Static‑only design** — no execution, no sandboxing, and no risk of running untrusted code
-- **Binary parsing** — extracts indicators from Windows PE files in addition to raw text
-- **Deterministic behaviour** — stable output and predictable performance, ideal for automated workflows
-- **Extensible rule engine** — plug in custom detectors, parsers, and enrichment logic
-- **Consistent JSON schema** — uniform output that integrates cleanly with SIEM, SOAR, and log pipelines
-- **Low dependency footprint** — minimal attack surface and safe for enterprise environments
-- **Designed for pipelines** — fast start‑up, fast throughput, and no heavyweight runtime requirements
+- **Static‑only design** — never executes untrusted code
+- **Binary parsing** — extracts IOCs from Windows PE files in addition to raw text
+- **Deterministic behaviour** — stable output and predictable performance, ideal for pipelines
+- **Extensible rule engine** — custom detectors, parsers, and plugins
+- **Consistent JSON schema** — clean integration with SIEM/SOAR
+- **Low dependency footprint** — safe for enterprise environments
+- **Pipeline-ready** — fast start‑up, fast throughput
 
-## Use Cases
+---
+
+## What IOCX *Is Not*
+
+To avoid confusion:
 
-malx‑ioc‑extractor fits naturally into DFIR, security automation, and threat‑intelligence workflows. Typical usage patterns include:
+- Not a sandbox
+- Not a malware emulator
+- Not a behavioural analysis tool
+- Not an enrichment engine (that lives in the MalX Cloud platform)
+
+IOCX is **static extraction only**, by design.
+
+## Use Cases
 
 ### SOC & Incident Response
-- Extract indicators from suspicious emails, alerts, or analyst clipboard text
-- Parse IOCs from incident reports and triage notes into structured JSON
-- Safely inspect malware samples statically without executing anything
+- Extract indicators from emails, alerts, or analyst clipboard text
+- Parse IOCs from reports into structured JSON
+- Safely inspect malware samples without execution
 
 ### Threat Intelligence Processing
-- Normalize indicators from threat‑intel feeds
-- Batch‑process dumps of unstructured text into machine‑readable IOC sets
-- Build enrichment pipelines on top of the deterministic output format
+- Normalize indicators from feeds
+- Batch‑process unstructured text
+- Build enrichment pipelines on top of deterministic output
 
 ### CI/CD & DevSecOps
-- Scan new binaries for embedded indicators before publishing artifacts
-- Integrate IOC extraction into automated security checks
-- Detect accidental inclusion of URLs or addresses during build steps
+- Scan binaries for embedded indicators before publishing
+- Integrate IOC extraction into automated checks
+- Detect accidental inclusion of URLs or addresses in builds
 
 ### Bulk Automation & Scripting
-- Pipe logs, artifacts, or telemetry through malx‑ioc‑extractor to extract actionable indicators
-- Use the Python API for batch workflows, ETL pipelines, or custom tooling
-- Combine with rule extensions to tailor detection to internal patterns or datasets
+- Pipe logs or artifacts through IOCX
+- Use the Python API for ETL or batch workflows
+- Extend with custom detectors for internal patterns
 
-## v0.3.0 — Stronger Architecture, New Crypto IOC Detection, Same Blazing Performance
+## Version Highlights
 
-Version 0.3.0 is a foundational release that tightens the engine’s architecture, expands IOC coverage with Ethereum and Bitcoin wallet detection, 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.
+### v0.3.0 — Stronger Architecture, New Crypto IOC Detection
 
-## v0.2.0 — High‑Reliability IP Detection in Hostile Data
+- Ethereum & Bitcoin wallet detection
+- Improved architecture for long-term extensibility
+- Same blazing performance on multi-MB inputs
 
-Version 0.2.0 significantly improves IPv4/IPv6 extraction in noisy, malformed, mixed-content environments — the kind often seen in:
+### v0.2.0 — High‑Reliability IP Detection
 
-- SIEM log lines
-- network captures
-- DFIR corpus samples
-- pasted analyst dumps
+Significant improvements to IPv4/IPv6 extraction in noisy, malformed, mixed-content environments
 
-### Real CLI Output (Chaos Corpus Sample)
+## Real CLI Output (Chaos Corpus Sample)
 
 ```json
 $ iocx chaos_corpus.json
@@ -165,26 +174,21 @@ All measurements from the latest performance suite:
 
 | Sample Type	               | Time     |
 |------------------------------|----------|
-| IP                           |          |
-|==============================|==========|
+|            **IP**            |          |
 | 1 MB mixed‑content sample	   | 0.0070s  |
 | Pathological IPv6 blob	   | 0.0004s  |
 | 100 KB sample	               | 0.0008s  |
 | 300 KB sample	               | 0.0021s  |
 | 600 KB sample	               | 0.0038s  |
 | 1 MB sample	               | 0.0068s  |
-|------------------------------|----------|
-| Filepath                     |          |
-|==============================|==========|
+|         **Filepath**         |          |
 | 1 MB mixed‑content sample	   | 0.0040s  |
 | Pathological deep unix path  | 0.0237s  |
 | 300 KB sample	               | 0.0011s  |
 | 600 KB sample	               | 0.0022s  |
 | 1000 KB sample               | 0.0038s  |
 | 1500 KB sample	           | 0.0055s  |
-|------------------------------|----------|
-| Crypto                       |          |
-|==============================|==========|
+|           **Crypto**         |          |
 | 1 MB mixed‑content sample	   | 0.0021s  |
 | Pathological ETH-like blob   | 0.0012s  |
 | 300 KB sample	               | 0.0006s  |
@@ -217,7 +221,7 @@ All measurements from the latest performance suite:
 - Hashes (MD5 / SHA1 / SHA256 / SHA512 / Generic Hex)
 - Email addresses
 - Base64
-- Crypto wallets (Ethereum, Bitcoin) (new in v0.3.0)
+- Crypto wallets (Ethereum / Bitcoin)
 
 ### Static PE Parsing
 
@@ -338,64 +342,28 @@ print(results)
 ## Architecture
 ```plaintext
 
-malx-ioc-extractor/
+iocx/
 │
 ├── examples/        # Sample files + generators
-├── tests/           # Unit and integration tests
+├── docs/            # Detector contracts, overlap suppression rules, and plugin authoring guidelines
+├── tests/           # Unit, integration, fuzz, robustness, and performance tests
 ├── iocx
     ├── detectors/   # Regex-based IOC detectors
     ├── parsers/     # PE parsing, string extraction
+    ├── plugins/     # Plugin API and registry
     ├── cli/         # Command-line interface
 
 ```
 
 The engine is intentionally modular so components can be extended or replaced easily.
 
-## Extending the Engine
-
-You can add custom:
-
-- Regex detectors
-- File parsers
-- Normalisation logic
-
-### Register a custom detector
-As an example, the following detector extracts the word "SECRET" from a string of text:
-```python
-
-import re
-from iocx.models import Detection
-from iocx.detectors.registry import register_detector
-
-SECRET_REGEX = re.compile(r"\bSECRET\b")
-
-@register_detector("custom.secret")
-def detect_secret(text: str):
-    results = []
-    for m in SECRET_REGEX.finditer(text):
-        results.append(
-            Detection(
-                value=m.group(0),
-                start=m.start(),
-                end=m.end(),
-                category="custom.secret"
-            )
-        )
-    return results
-
-```
-Assuming the detector was saved as `my_detector.py`, consume the custom detector - if the detector fires, its results will be added to the list of detected IOCs:
-```python
-
-from iocx.engine import Engine
-import my_detector
-
-engine = Engine()
+## Extending IOCX
 
-results = engine.extract("This is a SECRET message.")
-print(results)
+See `docs/specs/` for:
 
-```
+- Detector contracts
+- Overlap suppression rules
+- Plugin authoring guidelines
 
 ## Safe Testing (No Malware Required)
 
@@ -423,14 +391,6 @@ See CONTRIBUTING.md for full guidelines.
 If you discover a security issue, do not open a GitHub issue.
 Please follow the instructions in SECURITY.md.
 
-## Related Projects (MalX Labs)
-
-- malx-core — foundational primitives
-- malx-utils — shared utilities
-- malx-sandbox — dynamic analysis environment
-- malx-forge — adversarial payload tooling
-- malx-archive — research + PoCs
-
 ## License
 
 Licensed under the MIT License. See LICENSE for details.

SECURITY.md

@@ -1,6 +1,6 @@
 # Security Policy
 
-Thank you for your interest in the security of malx-ioc-extractor.
+Thank you for your interest in the security of IOCX.
 We take security seriously and aim to provide a trustworthy, minimal‑dependency tool for static IOC extraction across binaries, text, and logs.
 
 This document explains how we handle security, how to report vulnerabilities, and what you can expect from us.