# wazuh-soar

Companion files for the lesson **SOAR with Wazuh: n8n, Shuffle and TheHive**.

Lesson: <https://maheshtata.com/wazuh/wazuh-soar/>

Tested against: Wazuh 5.0 (beta5 documentation, September 2026). Wazuh 5.0 is still in beta, so
treat every field name here as verified against the beta documentation and re-verify at general
availability.

## Files

| File | What it is | Where it goes |
| --- | --- | --- |
| `webhook-payload-contract.json` | The Mustache message template for an alerting trigger action | Explore > Alerting > your monitor > Trigger > Action > Message |
| `payload-contract.schema.json` | JSON Schema for the body the automation platform receives | Your automation platform, as the first validation step of the playbook |

## How to use

1. Create a notification channel of type **Custom webhook** under Explore > Notifications >
   Channels. Put credentials in the channel headers, not in the message.
2. Create a per-document monitor under Explore > Alerting > Create Monitor, targeting
   `wazuh-findings-v5-*` (or a single category data stream).
3. Add a query on `wazuh.rule.level`, then a trigger, then a notification action pointing at the
   channel.
4. Paste `webhook-payload-contract.json` into the action's **Message** field, with the
   `_comment_*` keys removed.
5. Use the channel's test-message button and confirm the body arrives intact on the far side. A
   malformed body produces nothing on the receiver and no error in Wazuh.
6. Validate every inbound request against `payload-contract.schema.json` before the playbook
   branches on it.

## Deliberate omissions

The template carries **scalar fields only**. Two categories are left out on purpose:

- **Array fields** such as `wazuh.agent.groups`. Mustache renders a list through a section block,
  which does not produce clean JSON inside a fixed template.
- **Free text** such as `event.original`. Untrusted log content inside a JSON string template is a
  quoting hazard.

Both are on the finding document. The playbook fetches the document with `finding.doc_id` and
`finding.doc_index` when it needs them, which is also the right pattern for anything larger than a
routing decision.

## Field provenance

Every `_source` path in the template appears on the enriched finding document published in the
official 5.0-beta walkthrough at
<https://documentation.wazuh.com/5.0-beta/user-manual/data-analysis/detection-workflow.html>.

The `ctx.alerts.0.sample_documents.0._source.<field>` addressing form comes from the Wazuh
migration guide at
<https://github.com/wazuh/wazuh/blob/main/docs/guide/migration/integratord-notifications.md>.

The `ctx.monitor.*`, `ctx.trigger.*` and `ctx.period*` variables come from
<https://docs.opensearch.org/latest/observing-your-data/alerting/actions/>.

## Versioning

`contract_version` is the coupling point between Wazuh and your automation. Bump the major version
on any removal or rename, bump the minor on an addition, and have the playbook refuse a major it
was not written for. Silently ignoring an unknown version is how a broken branch survives for
weeks.