Life and Shell

Writing · security

Extending Wazuh with a new alerting lane: NATS, Sigma and back into the Wazuh dashboard

By Mattias Hemmingsson · · 8 min read

Wazuh does a lot out of the box: agents on every host, decoders for hundreds of log formats, a ruleset, an indexer and a dashboard. This post is about adding to that, not replacing it.

We keep the whole Wazuh stack and add one more alerting lane beside it. A copy of the event stream leaves the Wazuh manager, goes through our own parsing and detection, and the results are written back into the Wazuh indexer. The analyst still works in the Wazuh dashboard. There are just more alerts in it, from rules and sources Wazuh did not have before.

An earlier post showed a stripped-down setup with only the manager and worker. That is a special case for small clusters. This post is the general one, and the one I would recommend to most people: full Wazuh, plus a lane.

The idea

Normal lane (unchanged):

  agents ──► manager/worker ──► Filebeat ──► Wazuh indexer ──► Wazuh dashboard
                                                  ▲
New lane (added):                                 │
                                                  │
  manager/worker ──► Vector ──► NATS JetStream ──► your parsing + Sigma ──► NATS ──► Vector
                     sidecar    samma.logs.wazuh                  samma.alerts.wazuh  write-back
                                      ▲
                                      │
                      any other source (osquery, Kubernetes audit, cloud logs)

Nothing in the normal lane changes. Filebeat still ships alerts.json to the indexer, the dashboard still shows it, vulnerability detection still works.

The new lane has three steps:

  1. Break out. A Vector sidecar on the manager copies events to NATS.
  2. Process. Anything that can read NATS can parse, enrich and detect. We run Sigma rules.
  3. Return. A second Vector reads the detections and writes them into the Wazuh indexer, shaped like Wazuh alerts.

Why add a lane

Wazuh rules are good, and for most detections you should write a Wazuh rule. The lane is for the cases where that gets hard:

  • Your own parsing. You have an application log that needs real code to parse, or a lookup against another system, before it is useful.
  • Rules you already have. Sigma is a vendor-neutral rule format with a large public rule library. With a lane you run those rules on Wazuh events as they are.
  • Sources with no agent. Cloud audit logs, SaaS logs, Kubernetes audit events. They can publish to the same NATS stream, go through the same rules, and end up in the same Wazuh dashboard.
  • Many Wazuh clusters. Several managers can publish to one stream and share one set of rules.
  • Try things safely. The lane only reads a copy. If your code breaks, Wazuh keeps running as before.

Step 1: get the log stream into Wazuh

This step is plain Wazuh. Add a log to the agent, either in the agent's ossec.conf or centrally in the group's agent.conf:

<localfile>
  <log_format>json</log_format>
  <location>/var/log/myapp/audit.json</location>
</localfile>

The agent sends each line to the manager. The manager decodes it and runs its rules.

There are two files on the manager you can take a copy from:

  • alerts.json has the events that matched a Wazuh rule. This is the smaller stream.
  • archives.json has every event, also the ones no rule matched. Turn it on with <logall_json>yes</logall_json> in the manager's ossec.conf. Use this when you want to write detections for logs Wazuh has no rule for. It grows fast, so plan for rotation.

Step 2: break the stream out with Vector

Each manager pod gets a small Vector sidecar. It tails the file, adds a small envelope and publishes one event per message to NATS JetStream. It runs next to Filebeat and does not touch it.

acknowledgements:
  enabled: true

sources:
  wazuh_alerts:
    type: file
    include: [/var/ossec/logs/alerts/alerts.json]
  # optional: every event, not only alerts
  wazuh_archives:
    type: file
    include: [/var/ossec/logs/archives/archives.json]

transforms:
  wazuh_envelope:
    type: remap
    inputs: [wazuh_alerts, wazuh_archives]
    source: |
      feed = if contains(string!(.file), "archives") { "archives" } else { "alerts" }
      . = object!(parse_json!(string!(.message)))
      .source = "wazuh"
      .feed = feed
      if exists(.full_log) { .search_text = .full_log }

sinks:
  nats_logs_wazuh:
    type: nats
    inputs: [wazuh_envelope]
    url: ${NATS_URL}
    subject: samma.logs.wazuh
    jetstream: true
    encoding:
      codec: json
    buffer:
      type: disk
      when_full: block

The event is still the Wazuh JSON, with agent, rule, data and full_log as Wazuh wrote them. The envelope only adds source and feed.

End-to-end acknowledgements and the disk buffer mean Vector moves its file position forward only when the event is safely buffered for NATS. A pod restart continues where it stopped.

Our Helm chart (samma-io/wazuh-kubernetes) ships this sidecar in its collector mode today, and the same container works beside the full stack. It runs as the Wazuh user (uid 999) with a read-only root filesystem, and uses about 20m CPU.

Step 3: your own parsing and detection

Once the events are on NATS, the lane is yours. A JetStream consumer in any language can read samma.logs.wazuh, do its work, and publish a result.

We use detection-engine, a stateless Sigma engine. A Wazuh event is plain JSON, so a Sigma rule can match on any field:

title: Failed Login On A Wazuh Agent
id: ab336644-2a31-4d06-8625-5d8e42bc29ab
level: low
tags:
  - attack.credential-access
  - attack.t1110.001
logsource:
  product: wazuh
  service: alerts
detection:
  selection:
    feed: alerts
    rule.id: ['5503', '5504', '5557', '5710', '5716', '5758']
  condition: selection

This rule builds on Wazuh's own work. Wazuh decoded the log and tagged it with a rule id. Sigma groups those ids into one detection with a MITRE ATT&CK tag. On the archives feed a rule can match on the decoded fields of events that Wazuh had no rule for.

Every match is published to samma.alerts.wazuh as one JSON document. It holds the Sigma rule (id, title, level, tags) and the full event that matched.

Step 4: return the alerts to the Wazuh indexer

This is the part that makes it an extension of Wazuh. A second Vector reads the detections from NATS, reshapes each one into a Wazuh alert, and writes it to the Wazuh indexer.

acknowledgements:
  enabled: true

sources:
  samma_alerts:
    type: nats
    url: ${NATS_URL}
    subject: samma.alerts.>
    jetstream:
      stream: SIEM_ALERTS
      consumer: wazuh-writeback

transforms:
  to_wazuh_alert:
    type: remap
    inputs: [samma_alerts]
    file: /etc/vector/writeback.vrl

sinks:
  wazuh_indexer:
    type: elasticsearch
    inputs: [to_wazuh_alert]
    endpoints: ["https://wazuh-indexer:9200"]
    api_version: v7
    mode: bulk
    bulk:
      action: index
      index: "wazuh-alerts-4.x-sigma-%Y.%m.%d"
    id_key: id
    auth:
      strategy: basic
      user: ${INDEXER_USER}
      password: ${INDEXER_PASSWORD}
    tls:
      ca_file: /etc/vector/certs/root-ca.pem
    buffer:
      type: disk
      when_full: block

Three details do the work here:

  • The index name. Wazuh's index template applies to wazuh-alerts-4.x-*, and the dashboard reads the pattern wazuh-alerts-*. An index called wazuh-alerts-4.x-sigma-2026.11.17 gets the Wazuh field mappings and is picked up by the dashboard, but stays separate from the indices Filebeat writes. You can set its retention on its own, or delete it, without touching a single original Wazuh alert.
  • The document id. id_key: id uses the detection's id as the document _id. The id is a hash of the rule and the event, so if NATS redelivers a message it overwrites the same document. No duplicates.
  • A user with small rights. Create an indexer user that can only write to wazuh-alerts-4.x-sigma-*. The lane never needs admin.

Vector's elasticsearch sink speaks to OpenSearch, which is what the Wazuh indexer is.

The field mapping

writeback.vrl turns a detection into the shape the Wazuh dashboard expects:

alert = object!(parse_json!(string!(.message)))
event = object(alert.event) ?? {}
rule = object!(alert.rule)

levels = {"low": 3, "medium": 7, "high": 12, "critical": 15}
level = get(levels, [string!(rule.level)]) ?? 3

# attack.t1110.001 -> T1110.001
mitre = []
for_each(array(rule.tags) ?? []) -> |_i, tag| {
  m = parse_regex(string(tag) ?? "", r'^attack\.(?P<id>t\d{4}(\.\d{3})?)$') ?? {}
  if exists(m.id) { mitre = push(mitre, upcase(string!(m.id))) }
}

when = parse_timestamp(string(event.event_time) ?? "", "%+") ??
       parse_timestamp(string(alert.alerted_at) ?? "", "%+") ?? now()

. = {
  "id": alert.id,
  "timestamp": when,
  "@timestamp": when,
  "rule": {
    "id": rule.id,
    "level": level,
    "description": rule.title,
    "info": rule.description,
    "groups": ["sigma", "samma", alert.log_source],
    "mitre": {"id": mitre}
  },
  "decoder": {"name": "sigma"},
  "location": join!(["samma", alert.log_source], "/"),
  "agent": object(event.agent) ?? {"id": "000", "name": "samma"},
  "manager": object(event.manager) ?? {"name": "wazuh-manager-master-0"},
  "data": {
    "sigma": {
      "level": rule.level,
      "file": rule.file,
      "tags": rule.tags,
      "source_rule": event.rule
    }
  }
}
if exists(event.cluster) { .cluster = event.cluster }
if exists(event.full_log) { .full_log = event.full_log }

What it does:

  • Sigma level to Wazuh level. low, medium, high and critical become 3, 7, 12 and 15, which land in the matching severity bands of the dashboard.
  • agent, manager and cluster are copied from the original event. The alert shows up under the right agent, and it passes the dashboard's own filter on cluster and manager name. For a source with no Wazuh agent we fall back to agent 000, the manager itself.
  • rule.groups gets sigma. One filter in the dashboard, rule.groups: sigma, shows everything this lane produced. Remove it and you see both lanes together.
  • MITRE tags go to rule.mitre.id, the field the Wazuh MITRE ATT&CK view uses.
  • The original Wazuh rule is kept under data.sigma.source_rule, so you can see which Wazuh rule the detection was built on.

What lands in the indexer

We tested the write-back with a real detection against OpenSearch with the Wazuh 4.14 index template loaded. This is the document, trimmed a little:

{
  "_index": "wazuh-alerts-4.x-sigma-2026.11.17",
  "_id": "det_3f1c9a7e52b0…",
  "_source": {
    "timestamp": "2026-11-17T09:14:01.792Z",
    "agent": { "id": "001", "name": "test-agent", "ip": "10.0.0.12" },
    "manager": { "name": "wazuh-manager-worker-0-0" },
    "rule": {
      "id": "ab336644-2a31-4d06-8625-5d8e42bc29ab",
      "level": 3,
      "description": "Failed Login On A Wazuh Agent",
      "groups": ["sigma", "samma", "wazuh"],
      "mitre": { "id": ["T1110.001"] }
    },
    "decoder": { "name": "sigma" },
    "location": "samma/wazuh",
    "full_log": "Nov 17 09:14:01 base sshd[2211]: Failed password for alice from 10.0.0.99 port 51234 ssh2",
    "data": { "sigma": { "source_rule": { "id": "5716", "description": "sshd: authentication failed." } } }
  }
}

It has the same fields as any Wazuh alert, so the dashboard's tables, filters and visualisations work on it without changes.

Other sources, same dashboard

The write-back reads samma.alerts.>, every lane, not only Wazuh. We also run lanes for osquery, Kubernetes audit events and cloud audit logs. Each one publishes to its own subject, runs its own Sigma rules, and the detections go through the same write-back.

So the Wazuh dashboard becomes the one place to look, also for alerts on data that never passed through a Wazuh agent.

Things to know

  • Sigma rule ids are UUIDs. Wazuh rule ids are numbers. rule.id is a keyword field in the index, so a UUID is stored and searchable, but it will look different in the rule id column.
  • The Wazuh manager does not know these rules. They are not in the ruleset, so the dashboard's rule pages cannot show the rule text. The rule file name is in data.sigma.file.
  • Active response does not fire on them. The alerts are written to the indexer, they do not pass back through the manager.
  • archives.json is large. Only turn on logall_json if you use it, and rotate the files.
  • Watch for loops. The write-back goes to the indexer, not to the manager, so a detection can never come back around as a new event. Keep it that way.

Result

Wazuh keeps doing everything it did before: agents, decoding, rules, vulnerability detection, the indexer and the dashboard. Beside it runs a lane where you can add a log stream, parse it your own way, run your own rules, and bring in sources Wazuh has no agent for. The results come back into the Wazuh indexer and the Wazuh dashboard.

You get the flexibility to extend Wazuh without changing Wazuh.

Filed underwazuh · siem · nats · sigma · vector · opensearch · kubernetes · samma