Klaxon

The alarm tells you that. Klaxon tells you what.

Klaxon is a read-only proxy in front of your Wazuh 5 indexer. A language model asks questions in plain language; Klaxon queries the indexer, reads the schema, tests decoders, and reports what it actually found — including when it found nothing, and why. Works with Claude Desktop, Claude Code, local models through Ollama, and Open WebUI.

Every query runs through Klaxon, and the response is masked before it reaches an external LLM: a value under a configured field (user.name, source.ip, …) always becomes the same deterministic token ([USER_…], [IP_…]), aggregation keys included. This is pseudonymization, not anonymization — tokens are deterministic and reversible by anyone holding the salt (see LLM-safety guarantees).

Quick start

Requirements

• Wazuh 5.x indexer reachable over HTTPS (search/schema also work against 4.x)
• Python 3.11+ or Docker
• an MCP client — Claude Desktop, Claude Code, ollmcp, Open WebUI 0.6.31+

1. Install

python3 -m venv .venv
.venv/bin/pip install klaxon-mcp

Or build the Docker image (klaxon-mcp is the entry point):

docker build -t klaxon-mcp .

2. Point it at your indexer

export KLAXON_INDEXER_URL=https://indexer.example:9200
export KLAXON_INDEXER_USER=wazuh-readonly
export KLAXON_INDEXER_PASSWORD=...

KLAXON_INDEXER_URL is the only required variable. Add KLAXON_MANAGER_URL for manager/detectors and KLAXON_ENGINE_URL for tester_sessions; set KLAXON_VERIFY_SSL=false only for a self-signed lab cluster.

3. Enable masking (recommended for external LLMs)

Masking is off by default and opt-in:

export KLAXON_ANONYMIZE_EXTERNAL_LLM=true   # mask tool output for external models
export KLAXON_ANONYMIZATION_SALT=change-me-to-a-long-random-secret  # stable tokens

With the switch on, output is masked unless KLAXON_LLM_BASE_URL points at a loopback address (http://localhost:11434 for Ollama) — a local model keeps receiving unchanged data. An optional config.yaml (KLAXON_CONFIG) holds only what you change; environment variables always win:

anonymization:
  mask_fields:                 # or KLAXON_ANONYMIZATION_MASK_FIELDS
    - "source.ip"
    - "user.name"
    - "host.hostname"
  mask_aggregation_keys: true  # ON by default; false disables agg-key masking

4. Start it

klaxon-mcp    # stdio — your MCP client spawns it (klaxon is an alias)

With Docker: docker run --rm -i --env-file .env klaxon-mcp.

5. First masked result

Ask your client: "Show me the last login by user.name=alice in wazuh-events-v5-*." Klaxon runs search(index="wazuh-events-v5-*", body=…) and returns the masked response:

{
  "hits": { "hits": [ { "_source": {
      "user":    { "name": "[USER_9f2a1c467dd5e2b8]" },
      "source":  { "ip": "[IP_5c01e73f9a2b4c1d]" },
      "message": "user [USER_9f2a1c467dd5e2b8] logged in via ssh from [IP_5c01e73f9a2b4c1d]"
  } } ] }
}

The same value always maps to the same token. Masking is pseudonymization, not anonymization, and it has documented blind spots — see docs/llm-safety.md (in particular the verified leaks in "Known limitations") before pointing an external model at Klaxon.

Basic usage

The handful of tools a normal user needs (full reference: docs/TOOLS.md):

On an unfamiliar cluster, start with field_coverage. Every thin result gets a notice block before the data (empty aggregation, capped size, missing index — all return HTTP 200 with nothing).

Configuration (essentials)

The keys a normal user changes day to day. Full reference: docs/configuration.md.

Advanced topics

The deep material lives in dedicated docs — linked, not duplicated:

• GDPR plausibility checker (classification layers, custom rules, sampling, reports) → docs/gdpr-checker.md
• Ingest masking / Option B masked stream (pipeline, ISM, index templates, quarantine for masking failures, sync job) → docs/option-b-masked-stream.md
• Multi-tenant setup (fields.yaml, klaxon masking generate, salt, namespacing) → docs/multi-tenant.md
• Drift prevention & CI (pre-commit drift hook, provenance fingerprints, fail-closed startup, sync preflight, --verify-config) → docs/drift-prevention.md
• Token scheme & security model (HMAC, salt, self-test, why 16 hex) → docs/security-model.md
• Security concept: brute-force re-identification risk (pseudonymization vs anonymization, salt as secret) → docs/security-concept.md
• Salt rotation runbook (no scheduled rotation; only on suspicion; response-layer + masked-stream paths) → docs/salt-rotation-runbook.md
• LLM safety: using Klaxon safely with an LLM (masked-stream-first routing, ready-to-copy system prompt, pseudonymization boundary, residual gate) → docs/llm-safety.md
• Running it on another machine (HTTP transport, auth, TLS, CORS) → docs/TOOLS.md, ARCHITECTURE.md

Development

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest        # full suite
.venv/bin/mypy          # strict type check
.venv/bin/ruff check src

Option B generator self-tests (see docs/drift-prevention.md):

klaxon masking selftest --tenant customer-a
klaxon masking generate --check   # CI/pre-commit drift check

Deploy the masking artifacts to the indexer in one idempotent, ordered, self-verifying step (preflight + GET-back verification + a _simulate smoke test; --dry-run / --rollback):

klaxon masking deploy --tenant customer-a --dry-run   # plan only, no writes
klaxon masking deploy --tenant customer-a             # needs KLAXON_INDEXER_*

Remove the Option B masking infrastructure from the indexer cleanly, leaving the raw Wazuh streams untouched (destructive — preview with --dry-run; a mandatory verification phase proves nothing klaxon-* is left and the raw streams are intact):

klaxon masking teardown --tenant customer-a --dry-run       # plan only, no writes
klaxon masking teardown --tenant customer-a --yes           # needs KLAXON_INDEXER_*
klaxon masking teardown --tenant customer-a --yes --purge-sync-state
#   ^ also delete the sync checkpoint marker (default: keep it so a future
#     re-setup can resume from the last checkpoint)

The live integration test (klaxon masking test) needs real indexer credentials — see docs/option-b-masked-stream.md. Release history: CHANGELOG.md.

Documentation

• docs/TOOLS.md — full tool reference & parameters
• docs/configuration.md — complete configuration reference
• docs/gdpr-checker.md — the GDPR plausibility checker
• docs/option-b-masked-stream.md — ingest-side masking
• docs/multi-tenant.md — multi-tenant setup
• docs/drift-prevention.md — drift prevention & CI
• docs/security-model.md — token scheme & security model
• docs/security-concept.md — pseudonymization / brute-force re-identification risk
• docs/salt-rotation-runbook.md — salt rotation runbook (only on suspicion)
• docs/llm-safety.md — masking guarantees & limits
• ARCHITECTURE.md — design rationale
• CHANGELOG.md — release history

License

Apache-2.0 — see LICENSE.

Built by sec73 GmbH.

Wazuh is a registered trademark of Wazuh Inc. Klaxon is an independent project and is not affiliated with, endorsed by, or sponsored by Wazuh Inc.