Repository navigation
Development
For: contributors. The binding rules are in CONTRIBUTING.md; the module map and request flow are in docs/architecture.md.
- Read-only towards Wazuh. A feature that changes Wazuh belongs in a separate, explicitly privileged component. Open an issue first.
-
Never commit real data. Use the documentation IP ranges (
192.0.2.0/24,198.51.100.0/24,203.0.113.0/24,2001:db8::/32) and invented host names in tests, demo data, examples and screenshots. - Deterministic first. What a query can compute belongs in the collector. The model interprets; it does not count.
- Few dependencies. No provider SDKs, no front-end build step.
python -m venv .venv && . .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt -r requirements-dev.txt
WDT_DEMO=true APP_PASSWORD=x uvicorn app.main:app --reloadOpen http://127.0.0.1:8000. The demo mode needs no Wazuh and no model. The application does not read .env
by itself; export variables in the shell. Python 3.11 or newer.
What CI runs on every push, for Python 3.11, 3.12, 3.13 and 3.15:
ruff check .
pytest -q --cov=app --cov-report=term-missing
mypyCI also audits the dependencies (pip-audit), lints and renders the Helm chart, and installs it into a kind
cluster. A pull request should pass the three commands above locally first.
app/demo.py contains a small OpenSearch query engine, a fake Wazuh API and a mock model, with synthetic
alerts. The test suite and the demo both run on it, so neither needs a cluster. If your change uses a query
feature the demo engine does not support, extend the engine and add a test. app/demo_seed.py provides the
sample report, watch events and settings the demo starts with.
Tests show that the code works; they do not show that the diagnosis is good. For changes to prompts, tools or model handling, run the evaluation on cases with known answers:
python -m app.eval config/eval/demo.yaml
python -m app.eval cases.yaml --repeat 3 --out results.jsonIt reports recall, missed items, noise reported as incidents, tool steps, tokens and time per case (docs/eval.md). CI does not run it: it needs a model and your data.
| To add | Where |
|---|---|
| A tool for the model | a handler and a spec in app/agent/tools.py; new fields go to the allow-list in app/query_guard.py. MCP exposes it automatically. It must be read-only |
| A data source | a client in app/sources.py, registered on the environment runtime, exposed through a tool |
| A notification channel | configuration and a sender in app/notify.py (docs/notifications.md) |
| A model provider | most providers work through the OpenAI-compatible client; a different wire format is a new client in app/llm/
|
| A watch trigger |
app/watch.py; it must decide locally, without a model call |
UI strings are dictionaries in app/i18n.py and app/i18n_v10.py. Add a dictionary with exactly the same keys
(a test enforces this), register it in CATALOG, LANG_NAMES and OUTPUT_LANGUAGE, and add the code to
LANGUAGES in app/config.py. The report language follows the environment's language.
- One topic per pull request, with tests.
- New source files start with the SPDX header:
# SPDX-License-Identifier: AGPL-3.0-only # Copyright (C) 2026 <your name> - Sign off your commits (
git commit -s). Contributions are licensed under AGPL-3.0-only. - Security problems are reported privately, not as an issue or pull request.
- The wiki source is
docs/wiki/in the main repository; the wiki repository is a copy. Edit there and sync (docs/wiki/README.md). - Every page has an English and a Turkish version and is listed in
_Sidebar.md. - A page states who it is for, gives commands that were run against the stated version, and ends with the version and review date.
- Write "tested", "expected" and "not supported" with the meanings on the Compatibility page.
- Dangerous operations state their effect, prerequisite, confirmation and rollback.
- Screenshots come from the demo, never from a real environment.
Applies to 0.11.0 · reviewed 2026-11-11