# wazuh-active-response

Companion files for the lesson **Wazuh Active Response: How It Works and When to Leave It Off**.

Lesson: https://maheshtata.com/wazuh/wazuh-active-response/

Tested against: Wazuh 5.0 (beta5 documentation, September 2026). `verified: false` until the lab pass.

## Files

| File | Purpose |
| --- | --- |
| `custom-ar-skeleton.py` | A custom active response script skeleton following the documented Wazuh 5.0 message contract, with a dry-run mode and a never-touch list added on top. |
| `gating-checklist.md` | The checklist to pass, per environment, before any response is allowed to act. Includes a failure-mode table. |

## Using them

1. Read `gating-checklist.md` first. If you cannot tick section 2, stop.
2. Copy the skeleton to the agent:

```bash
sudo cp custom-ar-skeleton.py /var/ossec/active-response/bin/custom-ar
sudo chmod 750 /var/ossec/active-response/bin/custom-ar
sudo chown root:wazuh /var/ossec/active-response/bin/custom-ar
```

3. Create the active response configuration under **Explore > Active Responses** with the
   executable name `custom-ar`, location `Local`, and the type you chose.
4. Create a monitor of type **Active response** on a single `wazuh-findings-v5-<category>` data
   stream, add a trigger on one `wazuh.rule.id`, and attach the active response as the action.
5. Leave `DRY_RUN = True` until the log lines in the agent's `active-responses.log` are exactly
   what you expect.

## Caveats

- The script defaults to dry run. It does nothing until you set `DRY_RUN = False` and fill in
  the two TODO branches.
- `NEVER_TOUCH` and `NEVER_TOUCH_NETWORKS` ship empty. Populate them before the first real run.
- Windows agents run executables. Convert the script with PyInstaller or wrap it in a batch
  launcher, as the Wazuh documentation describes.
- Active response monitors must target `wazuh-findings-v5-*` indices, run at an interval of at
  most 1 minute, and use a document-level trigger.
- Execution results are written to `wazuh-active-responses*` and retained for 3 days by the
  default ISM policy.

## Sources

- https://documentation.wazuh.com/5.0-beta/user-manual/capabilities/active-response/how-it-works.html
- https://documentation.wazuh.com/5.0-beta/user-manual/capabilities/active-response/custom-active-response-scripts.html
- https://documentation.wazuh.com/5.0-beta/user-manual/capabilities/active-response/python-active-response-script-sample.html
- https://documentation.wazuh.com/5.0-beta/user-manual/capabilities/active-response/migrating-active-response-scripts.html
- https://documentation.wazuh.com/5.0-beta/user-manual/wazuh-indexer/modules/alerting.html
- https://documentation.wazuh.com/5.0-beta/user-manual/reference/ossec-conf/active-response.html