DetectMate Service

DetectMate Service is a framework for building modular services that communicate via NNG messaging.

Setup

With uv (recommended):

uv sync --dev

With pip and virtualenv:

python -m venv venv
source venv/bin/activate
pip install -e .

Developer setup

If you plan to contribute to the development of this package, follow these steps to set up the dev environment and install pre-commit hooks (using prek)

uv sync --dev
uv run --dev prek install

Run the tests:

uv run --dev pytest -q

Run the tests with coverage (add --cov-report=html to generate an HTML report):

uv run --dev pytest --cov=. --cov-report=term-missing

Usage

To use the Service class, you can create a subclass that implements the process method. Here's an example:

import pynng
from service.core import Service

class DemoService(Service):
    def process(self, raw_message: bytes) -> bytes | None:
        return None  # No actual processing in this demo

service = DemoService()

with service:
    with pynng.Req0(dial=service.settings.manager_addr) as req:
        for cmd in ("ping", "status", "stop"):
            print(f">>> {cmd}")
            req.send(cmd.encode("utf-8"))
            reply = req.recv().decode("utf-8", "ignore")
            print(f"<<< {reply}")

CLI

You can also run the service using the command line interface (CLI). It takes configuration files as arguments:

Example configuration files can be found in the tests/config directory.

Start the service:

uv run detectmate --settings examples/service_settings.yaml

To survey the state of your component and interact with the running service, use the detectmate-client tool.

Get the service status:

uv run detectmate-client status --url <http_host:http_port>

Stop the engine:

uv run detectmate-client stop --url <http_host:http_port>

Start the engine:

uv run detectmate-client start --url <http_host:http_port>

Request prometheus metrics:

uv run detectmate-client metrics --url <http_host:http_port>

Shutdown entire service:

uv run detectmate-client shutdown --url <http_host:http_port>

Demo pipeline run with Docker

A containerized demonstration of the DetectMate log analysis pipeline. The demo runs three services (reader, parser, detector) that process audit logs to detect anomalies, with a test script that feeds log lines through the complete pipeline and reports detected anomalies.

Terminal 1 (keep running to see service logs):

docker compose up reader parser detector

Terminal 2 (run after services are up):

# Wait a few seconds for services to be ready, then:
docker compose up demo

Documentation

• Project Documentation

Contribution

We're happily taking patches and other contributions. Please see the following links for how to get started:

• GitHub Workflow

If you encounter any bugs, please create an issue on Github.

License

EUPL-1.2