An AI-native layer
on top of Wazuh.

Introduction

A single mid-size Wazuh deployment produces more alerts in a day than an analyst can read in a week. Most are noise, a few are the start of something, and the difference is buried in correlation nobody has time to do by hand. So the queue gets skimmed, then ignored, then muted.

zuumb sits between the Wazuh indexer and the analyst. It does not replace Wazuh, change agents, or rewrite rules. It reads the alert stream Wazuh already produces and turns it into a small, ranked list of incidents with the reasoning attached.

What zuumb is not

• It is not a SIEM. Wazuh stays the system of record.
• It is not an autonomous responder. Every containment action is proposed, then waits for a person. See Automated mitigation.
• It is not built for scale testing. The whole thing runs on Docker Compose with SQLite or a single Postgres. No Kafka, no clustering.

How it works

One pipeline, five stages. Each stage takes the output of the one before it.

Correlation is two layers, not one

The Correlation row above is only the first, always-on layer: deterministic entity/time grouping, no model involved, and it's what actually forms an incident. A second, separate layer sits beside it — a local embedding model that flags incidents which read as the same campaign even when they share no host, IP, or user, surfaced as an advisory hint an analyst can confirm into an explicit record. It never drives correlation, severity, or attack chains. See Finding related incidents for both, plus the human-confirm action.

The feedback loop

When an analyst overrides a verdict in the dashboard, that correction is stored. The next triage prompt includes the last few overrides as worked examples, so the noise floor drops as the deployment is used. The effect is measured, not assumed. See Evaluation.

The system in three diagrams

Three views of the same system, drawn from the code. Select an image for the interactive version, where every box carries a SRC badge linking to the exact source lines it was drawn from, pinned to commit 65b1ecb.

Requirements

Triage calls are mockable, so the test suite and the offline demo run with no API key and no network.

Install

With Docker

No local build. This pulls the published image from the GitHub Container Registry.

git clone https://github.com/NucleiAv/zuumb && cd zuumb
cp .env.example .env            # fill in ANTHROPIC_API_KEY and the WAZUH_* creds
docker compose up -d            # pulls ghcr.io/nucleiav/zuumb:latest

Open http://localhost:8000. The SQLite database lives in a named volume called zuumb-data, so there is nothing else to set up.

Contributors who want to build from source and live-reload can use the dev compose file:

docker compose -f docker-compose.dev.yml up --build

From source

cp .env.example .env           # then put your ANTHROPIC_API_KEY in .env

python -m venv .venv
. .venv/Scripts/activate       # Windows;  ".venv/bin/activate" on macOS or Linux
pip install -r requirements.txt
pytest -q

Run it on the bundled synthetic Wazuh alerts. No live Wazuh, no Docker. SQLite is created automatically.

python -m scripts.run_poc [--offline]
.venv/Scripts/python -m uvicorn app.main:app --reload   # http://localhost:8000

--offline swaps the LLM triage agent for a keyword scorer, so the demo runs with no API key. For a live feed, work through Connecting a live Wazuh and then set WAZUH_LIVE_POLLING=true.

Configuration

All settings come from environment variables, read from .env at the repo root. .env is gitignored. .env.example holds placeholders only.

Anthropic

Wazuh indexer, for live ingestion

Database

Correlation and attack chains

Active response

Connecting a live Wazuh

zuumb reads alerts from an existing stack's indexer. The full copy-and-paste walkthrough, including standing up a Wazuh 4.9.2 single-node stack under Docker, lives in the project README. The shape of it is four steps.

1. Stand up or point at a Wazuh 4.9.x single-node stack. The indexer answers on port 9200.
2. Create a read-only ingestion user on the indexer's OpenSearch security API, scoped to read and search on wazuh-alerts-* and nothing else. Confirm that a write is refused.
3. Enrol at least one agent so alerts are actually landing. A wazuh-alerts-4.x-* index with a non-zero document count means the feed is live.
4. Put the indexer URL and the ingestion credential in .env, set WAZUH_LIVE_POLLING=true, and start the app.

The console logs each cycle. The first run triages the whole backlog in batches, so incidents and charts fill in progressively.

Adding agents

Attack chains only form when activity spans more than one source, so zuumb wants several agents reporting. There are two ways to add them.

Container agents, the multi-host lab

There is no wazuh/wazuh-agent image for 4.9.x, so docker/agent/ builds one from the official package. docker-compose.agents.yml runs two of them, agent-lab-01 and agent-lab-02. Run every docker compose -f docker-compose.agents.yml command from the repo root.

# the Wazuh stack must be up first, it owns the network the agents join
docker compose -f docker-compose.agents.yml up -d --build

• They join the manager's network and enrol automatically on first start.
• Each keeps its enrolment key in a volume, so restart and recreate reconnect instead of re-enrolling. To force a clean re-enrol, run the same command with down -v.
• LAB_NOISE=1 seeds realistic sshd auth-failure traffic with rotating source IPs so the pipeline has data while real traffic builds. Remove it when the agents monitor real hosts.
• To add a third agent, copy a service block in docker-compose.agents.yml, give it a new hostname and its own volume, then bring the file up again.

A real host

Install the Wazuh 4.9.x agent from packages.wazuh.com, set WAZUH_MANAGER to the manager's address and WAZUH_AGENT_NAME to something distinct, and start the service. The first start auto-enrols against the manager's authd on port 1515.

Checking how many agents are running

# canonical count from the Manager API: active / disconnected / never_connected / total
TOKEN=$(curl -sk -u wazuh-wui:'MyS3cr37P450r.*-' -X POST \
  "https://localhost:55000/security/user/authenticate?raw=true")
curl -sk -H "Authorization: Bearer $TOKEN" "https://localhost:55000/agents/summary/status"

A stuck "Never connected" agent has a key but cannot reach the manager on 1514/tcp. Check the address it is using and that the port is published.

The dashboard

Served by the app on port 8000. It is server-rendered, with a light and dark theme that follows your system setting and remembers a manual choice.

Charts are exportable to CSV from the panel menu. The time series and the hour-by-weekday heatmap bucket in the viewer's own timezone.

Rule-based, ML, or LLM

Worth being precise here, since "AI detection" gets used loosely enough elsewhere that it stops meaning much. Wazuh's own alerts are rule-based, signature and threshold matching, exactly what Wazuh always did, nothing zuumb adds changes that.

Exactly one piece in the whole pipeline is a language model, the primary triage verdict. Everything else that isn't a plain rule is a small, local, deterministic model, the same input twice always returns the same output, no free-form generation, no per-call API cost.

Detection engines

Wazuh alerts are the main feed, but zuumb also runs a couple of its own detectors that look for things a static rule set tends to miss. Both write alerts through the same path Wazuh alerts use, so they show up in the dashboard, get triaged, and get correlated into incidents just like anything else. You can tell them apart by rule id, and by the fact that their reasoning talks about statistics rather than a signature match.

To try the beacon detector against a Zeek or Suricata style connection log

python -m detectors.netflow.run --conn /path/to/conn.log

The auth-log detector can also be pointed at a plain log file the same way, for a one-off check instead of the continuous mode.

python -m detectors.authlog.run --log /var/log/auth.log

Second opinion and retrain

The classifier is intentionally simple, word patterns weighted by a linear model, because the amount of labeled data on hand is nowhere near enough to justify anything heavier. It starts out trained on a small curated set of examples and gets better as analysts use the dashboard. Every time someone records a verdict on an alert, that correction becomes a training example the next retrain can learn from.

A retrain runs on its own schedule, weekly by default, as a separate container so the training work never competes with the dashboard for CPU. Each run folds the accumulated corrections into training, then checks the resulting model against a fixed held-out slice of the original labeled set, the same slice every time, so scores are comparable across runs. If the new version scores at least as well as the one currently live, it takes over. If it doesn't, it gets thrown away and the old one keeps serving, so a bad batch of feedback can never make the live model worse.

The incidents page shows the currently promoted version, its held-out accuracy, how many corrections it learned from, and a drift number, how different recent alert traffic looks from what the model was trained on. Drift is informational only, nothing acts on it automatically.

To trigger a one-off retrain by hand, or run it continuously yourself outside the container

python -m app.triage.retrain
python -m app.triage.retrain --live

Testing it against an attack

A model that scores well on a clean eval set has never actually been tested against someone trying to fool it, a different question. The second-opinion classifier was run through the Adversarial Robustness Toolbox, crafting the smallest possible nudge to every alert it currently calls malicious or suspicious correctly, aimed specifically at flipping the prediction to benign, the one flip an attacker actually wants.

python -m eval.adversarial

Full numbers and reasoning live in the repository's eval/ADVERSARIAL.md. This doesn't change how the classifier is used today, it stays advisory only, but it matters more for the one mode where this classifier becomes the primary verdict, the toggle just below.

Turning AI detection off

The nav bar carries a switch, AI ON or AI OFF, next to the theme toggle. Any logged in analyst can click it, and it applies to the whole deployment at once rather than to just the person looking at the screen, since triage runs once in the background as alerts arrive.

Finding related incidents

Correlation groups alerts by a shared host, IP, or user, which catches most real intrusions but misses a real shape too, the same campaign spread across machines with nothing literal in common between them. Nothing in the deterministic engine can see that, by construction, since it only looks for a matching identifier.

Confirming a link by hand

The similarity hint is a suggestion, not a conclusion, so an analyst can turn one into an explicit record: a "confirm this is related" action on the banner writes a row noting who confirmed it, when, and an optional note, e.g. "confirmed via manual log review, same attacker IP range not captured in our entity fields."

Attack chains and tuning

Every chain carries a confidence score (high / medium / low), computed when the chain is built and shown on the chains list and detail pages. It is downgraded when the only link is a single shared host (jump-box shape), when stages are linked only transitively, when there is a large time gap between linked stages, when tactic labels are guessed from technique ids rather than taken from Wazuh's own mapping, or when the whole chain rests on one shared entity. A low-confidence chain shows an unmissable warning on its detail page. An analyst can also mark a chain confirmed-narrative or false-chain — that human causation call is kept separate from the system's score.

The CLI diagnostic prints the same signals for every stored chain:

python -m scripts.chain_quality

Tune with CORRELATION_WINDOW_MINUTES, CHAIN_MAX_ENTITY_SPREAD, CHAIN_STRONG_LINK_HOURS, and CHAIN_MAX_LINK_HOURS from the configuration table.

Automated mitigation

zuumb groups alerts into incidents and, for each incident, suggests response tasks like "block that IP" or "lock that account". A person can click one button and have zuumb carry the task out on the affected machine, by asking Wazuh to do it, never by running commands itself.

Three things are always true

• Nothing happens on its own. A human clicks Approve first.
• zuumb can only do a few specific things, listed below, never "run any command".
• Out of the box it runs in practice mode, RESPONSE_DRY_RUN=true. The button works, writes a record, and touches nothing.

The safety rules, and why each one exists

The two actions zuumb can take

Any other response task stays a manual to-do. zuumb will not dispatch it.

What happens when you click Approve

1.  Wazuh agent  ->  zuumb pulls the alert  ->  scores it  ->  groups it into an incident

2.  zuumb proposes response tasks. A task that maps to an allowlisted action is
    tagged with  action + target + agent id   (e.g.  block-ip / 198.51.100.77 / 006)

3.  you click Approve on that task

4a. IF RESPONSE_DRY_RUN = true  (the default)
        write one audit row marked "dry-run", send nothing. Done.

4b. IF RESPONSE_DRY_RUN = false
        check the rate limit
        POST /active-response to the manager, logged in as zuumb-ar
        the manager tells the agent to run the script
        write one audit row marked "live", with the HTTP result

5.  the row shows at /audit and in the incident's "Dispatched actions"

Setting up the zuumb-ar login

Create an empty Wazuh role, attach only the built-in policy that permits active-response commands, create the zuumb-ar user, and give it that role. The README walkthrough has the exact commands, plus a check that proves the login can dispatch active response and nothing else, and a full dry-run then live then revert exercise against a throwaway agent.

Evaluation

Triage quality is measured against a hand-labelled set of synthetic Wazuh alerts, currently 104 of them (44 benign, 30 suspicious, 30 malicious), covering auth brute force including low-and-slow, web exploitation, privilege escalation, lateral movement, data staging, exfiltration, ransomware precursors, identity abuse, and a spread of routine benign noise.

python -m eval.run_eval [--few-shot]

• No malicious alert was ever called benign in either run. The safety-critical failure mode is clean on this larger, more varied set too.
• Baseline misses are all one severity level low, the model under-calling an exploit attempt or a credential-access technique as merely suspicious rather than malicious.
• The few-shot row above is not actually exercising the feedback loop. It reads real analyst corrections from the live database, and that database currently has none on record, so the two rows differ only by the model's own sampling noise, not by the loop doing anything. An earlier run, back when the set was 34 alerts, paired with one staged correction and showed the loop's real effect, accuracy up 12 points and malicious recall 0.70 to 0.90. Full writeup and that earlier result are both in eval/RESULTS.md.

Five questions for any "AI-powered" claim

A useful gut-check for any product that says "AI-powered," including this one: ask these five questions, and if the answers are vague, that's the actual finding. Here's zuumb's, answered plainly.

Compatibility

Roadmap

• Wazuh 5.x and OCSF schema support in the alert normaliser.
• Continued tuning of the correlation window and chain-spread limits against long runs of real traffic.

zuumb is a portfolio and demo project built on top of prior Wazuh detection-rule work. It is deliberately small.