DetectMateLibrary

Main library to run the different components in DetectMate.

Main structure

The library contains the next components:

• Parsers: parse the logs received from the reader.
• Detectors: return alerts if anomalies are detected.
• Alert Aggregation: aggregate the alerts produced by the detectors.
• Schemas: standard data classes use in DetectMate.

 +--------+     +-----------+    +-------------------+
 | Parser | --> |  Detector | -> | Alert Aggregation |
 +--------+     +-----------+    +-------------------+

Developer setup:

Step 1: Install python dependencies

Set up the dev environment and install pre-commit hooks:

uv sync --dev
uv run prek install

Step 2: Install Protobuf dependencies

To install in Linux do:

sudo apt install -y protobuf-compiler
protoc --version

This dependency is only needed if a proto file is modified. To compile the proto file do:

protoc --proto_path=src/detectmatelibrary/schemas/ --python_out=src/detectmatelibrary/schemas/ src/detectmatelibrary/schemas/schemas.proto

Step 3: Run unit tests

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

Workspace generator (mate create)

DetectMateLibrary includes a small CLI helper to bootstrap standalone workspaces for custom parsers and detectors. This is useful if you want to develop and test components in isolation while still using the same library and schemas.

Usage

The CLI entry point is mate with a create command:

mate create --type <parser|detector> --name <workspace_name> --dir <target_dir>

What gets generated

For example:

mate create --type parser --name custom_parser --dir ./workspaces/custom_parser

will create:

workspaces/custom_parser/          # workspace root
├── custom_parser/                 # Python package
│   ├── __init__.py
│   └── custom_parser.py           # CoreParser-based template
├── tests/
│   └── test_custom_parser.py      # generated from template to test custom_parser
├── data.json                      # example data to run the code
├── LICENSE.md                     # copied from main project
├── .gitignore                     # copied from main project
├── .pre-commit-config.yaml        # copied from main project
├── pyproject.toml                 # minimal project + dev extras
└── README.md                      # setup instructions

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