# Install the Wazuh integration

> Install the Whisper connector on a Wazuh 4.x manager: bootstrap, tarball, OS package, or the official Wazuh integrations repo, then verify enrichment.

*Source: https://www.whisper.security/docs/integrations/wazuh/installation*
*Published: 2026-08-10*
*Last updated: 2026-09-19*

---
Methods A–C run the same `install.sh`; method D copies the files onto the manager by hand. Pick whichever fits your configuration management or your provenance requirements.

---

## Requirements

- A **Wazuh manager on the 4.x line**, and root on that host. Verified end-to-end on 4.14.5.
- **TLS egress to `graph.whisper.security`** for methods A–C; method D reaches `graph.whisper.online` instead (below).
- An API key **only** if you want the keyed modes — the on-demand CLI or the agent-activity log source. Per-alert enrichment needs none.

---

## Download

From the [releases page](https://github.com/whisper-sec/whisper-wazuh/releases), v1.1.0:

| Asset | For |
|---|---|
| `whisper-wazuh.tar.gz` | the `latest/download` URL used by method B |
| `whisper-wazuh-1.1.0.tar.gz` | the version-pinned tarball |
| `whisper-wazuh_1.1.0_all.deb` | Debian / Ubuntu |
| `whisper-wazuh-1.1.0-1.noarch.rpm` | RHEL family |
| `SHA256SUMS` | checksum verification |

> **Warning:** Method A pipes a script into `sh` as root. `SHA256SUMS` is published for exactly this reason — if that is a step your change process requires, use method B and verify the tarball before you run anything.

---

## Method A — one-line bootstrap

```bash
curl -sSL https://raw.githubusercontent.com/whisper-sec/whisper-wazuh/main/bootstrap.sh \
  | sudo sh -s -- --group sshd --api-key-file /path/to/your-whisper-key.txt
```

Drop `--api-key-file` entirely if you are running keyless.

---

## Method B — the tarball, inspected first

```bash
curl -sSL https://github.com/whisper-sec/whisper-wazuh/releases/latest/download/whisper-wazuh.tar.gz | tar xz
cd whisper-wazuh-*
sudo sh install.sh --group sshd --api-key-file /path/to/your-whisper-key.txt
```

---

## Method C — the .deb or .rpm package

```bash
sudo dpkg -i whisper-wazuh_1.1.0_all.deb        # Debian/Ubuntu
sudo rpm -i whisper-wazuh-1.1.0-1.noarch.rpm    # RHEL family
```

The package stages files to `/usr/share/whisper-wazuh` and adds a `whisper-wazuh-install` command. **It does not auto-activate.** Activation patches `ossec.conf` and restarts the manager, so it is a deliberate, separate admin step:

```bash
sudo whisper-wazuh-install --group sshd --api-key-file /path/to/your-whisper-key.txt
```

**Containerised manager?** Skip `--api-key-file` and inject `WHISPER_API_KEY` as a container-env secret instead.

---

## Method D — from the official Wazuh integrations repository

Wazuh also ships this connector directly in its own repository: [`wazuh/integrations/integrations/whisper`](https://github.com/wazuh/integrations/tree/main/integrations/whisper).

It installs five files — the `custom-whisper` shell wrapper, `custom-whisper.py`, `whisper_client.py`, `whisper_rules.xml` and `whisper-template.json` — copied onto the manager by hand, to the destinations its own README gives. It follows Wazuh's standard integratord pattern (Pattern A) and needs nothing beyond the Python standard library.

This path is **keyless only**. It queries `https://graph.whisper.online` anonymously — no API key — and covers per-alert enrichment; it has no on-demand CLI and no agent-activity log source, since those need a key.

Prefer method D for official Wazuh community provenance and manual control over each file placed on the manager. Prefer methods A–C for the full product: the keyed modes, and an installer that manages the files, the template and the `ossec.conf` patch for you.

---

## What methods A–C do

Pushes the indexer template, drops the files, patches `ossec.conf` **with rollback**, restarts the manager, and verifies.

---

## Verify

```bash
grep whisper: /var/ossec/logs/integrations.log   # expect  invoke → api → emit
```

Then search `data.whisper.ioc:<the IP>` in the dashboard. A new enrichment alert appears next to the original one.

> **Note:** Enrichment starts on the **next** alert in a trigger group that carries a public IP or domain. It does not backfill, so if the group is quiet, nothing is broken — generate an alert with an external indicator in it and look again.

---

## Uninstall

`integrations/whisper/uninstall.sh` in the package removes it cleanly, reverting the `ossec.conf` patch.

---

## Related

- [Wazuh integration — overview](/docs/integrations/wazuh/overview) — the two modes and what Whisper never receives
- [Configure the Wazuh integration](/docs/integrations/wazuh/configuration) — trigger groups, the envelope and the verdict gates