# Add Your Own Rules

> Write and deploy your own Sigma rules on a Whisper endpoint: the log-source mapping, where the file goes, how to reload, how to confirm a match.

*Source: https://www.whisper.security/docs/endpoint/operate/rules*

---
Your rules are evaluated by the same engine as the bundled content, on the same event stream, with the same result: a match is held, not contained.

## 1. Pick the event kind the rule reads

The sensor emits four kinds, and Sigma names them differently. Set the log source to match.

| Event kind | Sigma `category` |
|---|---|
| `exec` | `process_creation` |
| `file` | `file_event` |
| `conn` | `network_connection` |
| `dns` | `dns_query` |

A rule matches one event at a time, so write each condition against a single event. A sequence that spans events is what the event-chain family in [what the sensor detects](/docs/endpoint/operate/detections) already correlates.

## 2. Write the rule

```yaml
title: Shell spawned by the backup agent
id: 8f0f4b2e-1d3a-4c77-9b21-2e6d5a0c9f14
status: experimental
logsource:
  category: process_creation
detection:
  parent:
    ParentImage|endswith: '/backup-agent'
  shells:
    Image|endswith:
      - '/bash'
      - '/sh'
  condition: parent and shells
level: high
```

Give every rule its own `id`. A rule whose `id` matches a bundled rule replaces it, which is how you retune shipped content rather than fight it.

## 3. Put it on the host

Rules live in `.whisper/sigma/` as `*.yml` or `*.yaml`, one rule per file, readable by the service account. That directory sits under the project root: the directory you ran `whisper init` in, which is the same one the service runs from.

```bash
sudo install -m 0644 backup-agent-shell.yml "$(pwd)/.whisper/sigma/backup-agent-shell.yml"
```

The directory is optional and usually absent, so create it the first time you add a rule. A file the evaluator cannot parse is skipped on its own and the rest still load, so one bad rule never costs you the set.

## 4. Reload

```bash
sudo -E whisper service restart --sensor
```

## 5. Confirm it fired

Trigger the behaviour, then read the queue:

```bash
whisper alerts list
```

A match arrives as a held finding with the process that caused it attached, and shows up in the console's attention list at the same time. If nothing arrives, check that the log source matches the kind the collectors actually emit for that behaviour, and that the service restarted after you copied the file in.

Keep the rule's own scope tight. The sensor's job is to keep collecting whatever the detectors do, and a rule that matches broadly costs you attention rather than telemetry, so the cheapest place to fix a noisy rule is its condition. [Alerts and incidents](/docs/endpoint/operate/alerts) covers muting one while you do.