iocx-plugin-template

A minimal template for building detectors, transformers, and enrichers for the iocx engine.

This repository provides a ready-to-use starting point for creating an iocx plugin.

Clone it, rename it, and focus on your detection logic instead of boilerplate.

---

🧩 What this template gives you

• Structured plugin layout (src package, tests, config)
• Example detector implementation
• Entry point wiring for iocx plugin discovery
• Basic test scaffold
• Packaging setup for local use or PyPI publishing

---

📁 Repository structure

iocx-plugin-template/
├─ src/
│ └─ iocx_plugin_template/
│  ├─ __init__.py
│  ├─ plugin.py # main plugin implementation
├─ tests/
│ └─ test_plugin.py
├─ pyproject.toml
├─ README.md
└─ LICENSE

🚀 Getting started

1. Use this template

Create a new repository from this template (or clone and rename):

• Replace all occurrences of iocx-plugin-template and iocx_plugin_template
• Choose a meaningful name, e.g. iocx-mutex-detector

Update:

• pyproject.toml (name, description, author, version)
• README.md (plugin purpose, examples)
• src/iocx_plugin_template/ → rename package folder

2. Install in editable mode

From the root of your new plugin repo:

python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows

pip install -e .

This makes the plugin available to iocx via entry points.

3. How the plugin is registered

In pyproject.toml:

[project]
name = "iocx-plugin-template"
version = "0.1.0"
description = "Template plugin for the iocx engine"
requires-python = ">=3.9"
dependencies = [
    "iocx>=0.4.0",
]

[project.entry-points."iocx.plugins"]
iocx-plugin-template = "iocx_plugin_template.plugin:Plugin"

The iocx.plugins entry point group is how iocx discovers plugins.

The value points to a callable that returns plugin metadata and handlers.

🧠 Plugin implementation

src/iocx_plugin_template/plugin.py:

from __future__ import annotations
from typing import Iterable, Dict, Any
from iocx.plugins.api import IOCXPlugin
from iocx.plugins.metadata import PluginMetadata
from iocx.models import Detection, PluginContext


# Adjust these types to match the iocx plugin API in your core project.
# This is intentionally minimal and illustrative.

PLUGIN_NAME = "iocx-plugin-template"
PLUGIN_VERSION = "0.1.0"

class Plugin(PluginContext):
    metadata = PluginMetadata(
        id=PLUGIN_NAME,
        name="Template plugin",
        version=PLUGIN_VERSION,
        description="Boilerplate code for creating your first plugin",
        author="MalX Labs",
        capabilities=["detector"],
        iocx_min_version="0.4.0",
    )

    def detect(self, text: str, ctx: PluginContext):
        """
        Example detector function.

        Replace this with your own logic. It should return a list of Detections
        e.g. {"type": "mutex", "value": "..."} or whatever your engine expects.
        """
        # Dummy example: detect the word "MUTEX" as a fake IOC.
        values = []
        if "MUTEX" in text:
            values.append(
                Detection(
                    value="MUTEX",
                    start=21,
                    end=25,
                    category="mutex.pattern",
                )
            )
        return {
            "mutex.pattern": values,
        }

🧪 Tests

tests/test_plugin.py:

from iocx_plugin_template.plugin import Plugin

def run(text):
    plugin = Plugin()
    return plugin.detect(text, ctx=None)

def test_get_plugin_structure():
    plugin = Plugin()

    assert hasattr(plugin, "metadata")
    assert hasattr(plugin.metadata, "name")
    assert hasattr(plugin.metadata, "id")
    assert hasattr(plugin.metadata, "version")
    assert hasattr(plugin.metadata, "description")
    assert hasattr(plugin.metadata, "author")
    assert hasattr(plugin.metadata, "capabilities")
    assert hasattr(plugin.metadata, "iocx_min_version")

    assert(plugin.metadata.capabilities == ["detector"])


def test_example_detector():
    text = "This sample contains MUTEX artifact."
    results = run(text)

    assert len(results) == 1
    assert any(r.category == "mutex.pattern" for r in results["mutex.pattern"])

Run tests with:

pytest

📦 Publishing (optional)

To publish to PyPI (or a private index):

pip install build twine
python -m build
twine upload dist/*

Make sure you’ve updated:

• project.name
• project.description
• project.urls
• project.authors

in pyproject.toml.

🤝 Contributing

If you have ideas to improve this template (better patterns, examples, or helpers), open an issue or PR in the main iocx-plugin-template repository.

Code

---

pyproject.toml (minimal example)

[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "iocx-plugin-template"
version = "0.1.0"
description = "Template plugin for the iocx engine"
authors = [{ name = "MalX Labs" }]
readme = "README.md"
requires-python = ">=3.9"
dependencies = [
    "iocx>=0.4.0",
]

[project.entry-points."iocx.plugins"]
iocx-plugin-template = "iocx_plugin_template.plugin:Plugin"

[tool.setuptools]
package-dir = {"" = "src"}

[tool.setuptools.packages.find]
where = ["src"]