Feature/v0.5.1 into main

.coveragerc

@@ -1,6 +1,7 @@
 [run]
 omit =
     */.iocx/*
+    */iocx-archive/*
     */site-packages/*
     */distutils/*
     */tests/*

CONTRIBUTING.md

@@ -1,38 +1,41 @@
 # Contributing to IOCX
 
-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.
+Thank you for your interest in contributing to IOCX.
+IOCX is part of the MalX Labs ecosystem — a family of modern, deterministic, developer‑friendly security tools designed for safe analysis of untrusted data.
 
-We welcome improvements of all kinds: bug fixes, new extractors, static‑analysis enhancements, documentation updates, and thoughtful discussions. This guide explains how to contribute effectively while keeping the project consistent, deterministic, and maintainable.
+We welcome contributions of all kinds: bug fixes, static‑analysis improvements, new extractors, documentation updates, and thoughtful design discussions.
+This guide explains how to contribute effectively while keeping IOCX predictable, secure, and maintainable.
 
 ## Project Philosophy
 
 IOCX is intentionally:
 
-- Minimal — very small dependency footprint
+- Minimal — extremely small dependency footprint
 - Secure — safe handling of untrusted input
-- Predictable — deterministic behaviour, no network access
-- Extensible — new extractors and static‑analysis modules can be added cleanly
+- Deterministic — no network access, no non-deterministic behaviour
+- Extensible — new static‑analysis modules can be added cleanly
 
 All contributions must align with these principles.
 
 ## Core vs Plugins
 
-IOCX is built around a clear separation between core functionality and plugin‑based extensions. This boundary keeps the project focused and deterministic while allowing contributors to extend it safely.
+IOCX has a strict boundary between core functionality and plugin‑based extensions.
+This keeps the core predictable and universally safe while allowing users to extend IOCX for their own environments.
 
 ### What Belongs in the Core
 
-Core functionality is:
+Core functionality must be:
 
 - derived entirely from the input file or text
 - deterministic and reproducible
-- universally useful to all users
+- universally useful
 - lightweight and dependency‑minimal
-- fundamental to static IOC extraction and analysis
+- fundamental to static IOC extraction
 
 Examples:
 
 - PE metadata extraction
-- entropy scoring
+- entropy calculations
 - section/structure heuristics
 - import/API heuristics
 - phishing/lure string heuristics
@@ -45,45 +48,61 @@ If the information comes from the file itself, it belongs in the core.
 
 Plugins are for functionality that is:
 
-- optional
-- environment‑specific
-- user‑provided or user‑maintained
+- optional or environment‑specific
 - based on external data
-- not universally applicable
-- likely to evolve independently of the core
+- organisation‑specific
+- user-maintained
+- likely to evolve independently
 
 Examples:
 
 - offline reputation matching (local hash/domain/IP lists)
 - organisation‑specific heuristics
-- custom keyword or lure lists
+- custom lure or keyword lists
 - internal threat‑intel integrations
 
 If the information comes from the user’s environment, it belongs in a plugin.
 
-This separation ensures IOCX remains clean, predictable, and safe to run anywhere, while still enabling powerful extensions.
+This separation keeps IOCX clean, predictable, and safe to run anywhere.
 
 ## How to Contribute
 
 ### Fix bugs
 
-Open an issue or submit a PR with a clear description and reproduction steps.
+Open an issue or submit a PR with:
+
+- a clear description
+- reproduction steps
+- expected vs actual behaviour
 
 ### Add new IOC extractors
 
-Regex‑based extractors live under `detectors/extractors/`.
+Regex‑based extractors live under:
+
+```
+detectors/extractors/
+```
 
 Please include:
 
 - a clear, well-scoped regex
 - validation logic
 - test cases
-- test cases
 - example inputs
 
+Extractors must be:
+
+- deterministic
+- side‑effect‑free
+- safe for untrusted input
+
 ### Improve PE parsing
 
-Enhancements to metadata extraction, imports, sections, or resources are welcome — provided they remain deterministic and static.
+Enhancements to metadata extraction, imports, sections, or resources are welcome — provided they remain:
+
+- static
+- deterministic
+- dependency-minimal
 
 ### Add synthetic test samples
 
@@ -92,7 +111,7 @@ See the “Testing” section below.
 
 ### Improve documentation
 
-Better examples, diagrams, or explanations are always appreciated.
+Better examples, diagrams, and explanations are always appreciated.
 
 ### Contribution Process
 
@@ -131,8 +150,6 @@ pip-audit --skip-editable
 
 6. Open a Pull Request
 
-When your changes are ready:
-
 - Target the main branch
 - Describe what you changed and why
 - Link any related issues
@@ -174,16 +191,18 @@ We use pytest.
 
 ## Adding New Extractors
 
+Extractors live in:
+
 ```plaintext
 iocx/detectors/extractors/
 ```
 
-To add a new extractor:
+To add one:
 
 - Create a new file in that directory
 - Follow existing patterns
 - Ensure it registers itself on import
-- Add tests under tests/unit/extractors/
+- Add tests under `tests/unit/extractors/`
 
 Extractors must be:
 

README.md

@@ -2,8 +2,8 @@
   <a href="https://pypi.org/project/iocx/">
     <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-327_passed-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/coverage-100%25-brightgreen" alt="Coverage">
+  <img src="https://img.shields.io/badge/tests-576_passed-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/python-3.12-blue" alt="Python Version">
   <a href="https://github.com/iocx-dev/iocx/blob/main/LICENSE">
     <img src="https://img.shields.io/github/license/iocx-dev/iocx" alt="License">

SECURITY.md

@@ -3,26 +3,26 @@
 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.
+This document describes our security posture, how we handle vulnerabilities, and how to report issues responsibly.
 
 ## Supported Versions
 
-We currently support and maintain the latest release of this project.
+We currently support and maintain only the latest released version of IOCX.
 
-| Version        | Supported        |
+| Version        | Status           |
 |----------------|------------------|
-| Latest release | Active           |
-| Older versions | Not supported    |
+| Latest release | Supported        |
+| Older versions | Unsupported      |
 
-Security fixes are applied only to the most recent version.
+Security fixes are applied exclusively to the most recent version.
 
 ## Security Posture
 
-The project is designed with security and simplicity in mind.
+IOCX is designed with security and simplicity in mind. The tool processes untrusted input by design, so the architecture prioritises isolation, defensive parsing, and minimal attack surface.
 
 ### Minimal Runtime Dependencies
 
-To reduce attack surface, the project intentionally uses only two runtime dependencies:
+To reduce supply‑chain risk and minimise the attack surface, IOCX intentionally uses only two runtime dependencies:
 
 - pefile - PE parsing
 - python-magic - file‑type detection
@@ -31,52 +31,71 @@ No additional libraries are required for core functionality.
 
 ### Automated Security Scanning
 
-Every commit and pull request triggers automated checks:
+All commits and pull requests undergo automated security checks:
 
 - pip‑audit — dependency vulnerability scanning
 - Bandit — static analysis of Python code
 - Pytest — full test suite execution
 
-These checks run in CI to prevent regressions and catch issues early.
+These checks run in CI to catch regressions early.
 
 ### Safe Handling of Untrusted Input
 
-The tool is designed to process potentially malicious files. To reduce risk:
+IOCX is designed to process potentially malicious files safely. To reduce risk:
 
 - No dynamic code execution
 - No deserialization of untrusted data
 - No network access
 - Strict parsing of binary formats
 - Defensive exception handling in extractors and parsers
+- No mutation of input files
 
 ### No Elevated Privileges Required
 
-The tool runs entirely in user space and does not require:
+IOCX runs entirely in user space and does not require:
 
 - root/admin privileges
 - kernel extensions
 - system‑level hooks
 
+This reduces the impact of potential vulnerabilities.
+
+## Threat Model (Scope & Limitations)
+
+IOCX is a static extraction tool, not a sandbox or malware analysis framework.
+
+The following are out of scope:
+
+- Detecting or preventing active exploitation
+- Executing or emulating malware
+- Analysing runtime behaviour
+- Guaranteeing correctness of third‑party plugins
+- Protecting against malicious Python environments or compromised dependencies
+
+Users should run IOCX in a controlled environment when analysing untrusted binaries.
+
+Refer to the [threat model overview](/docs/security/threat-model.md) for Data Flow and STRIDE‑Oriented Threat Interaction Diagrams.
+
 ## Reporting a Vulnerability
 
-If you discover a security issue, we appreciate responsible disclosure.
+We appreciate responsible disclosure and welcome reports from the community.
 
 ### How to report
 
 Please email: security@malx.io
 
 Include:
 
-- Description of the issue
+- A clear description of the issue
 - Steps to reproduce
 - Potential impact
-- Any suggested fixes
+- Any suggested fixes or patches
 
 We aim to acknowledge reports within 72 hours.
 
-### Please do not open public GitHub issues for security problems
+### Do Not Open Public GitHub Issues
 
-This helps protect users while we investigate and patch the issue.
+Please avoid filing public issues for security problems. This protects users while we investigate and patch the issue.
 
 ## Vulnerability Disclosure Process
 
@@ -85,14 +104,15 @@ This helps protect users while we investigate and patch the issue.
 3. We develop and test a fix.
 4. We release a patched version.
 5. We publish a security advisory (if applicable).
-6. We credit the reporter.
+6. We credit the reporter (unless anonymity is requested).
 
 ## Responsible Disclosure
 
-We ask that you:
+We ask that reporters:
 
-- Give us reasonable time to fix the issue before public disclosure
+- Allow reasonable time for us to develop a fix
 - Avoid exploiting the vulnerability beyond what is necessary for proof‑of‑concept
 - Avoid accessing or modifying user data
+- Refrain from public disclosure until a fix is released
 
-We appreciate your help in keeping the project secure.
+We appreciate your help in keeping IOCX secure.