# Detection rules and shadow mode

Install the SigmaHQ rule pack, check that each rule can see your data, backtest it, trial it in shadow mode and promote it to production when it is quiet.

A detection rule is a query over your logs and endpoint events that raises an alert when it matches. This page shows how to install the SigmaHQ rules, check which ones can see your data, and trial each rule in shadow mode before it can page anyone.

## How detections run

Each enabled rule runs as a monitor in your workspace, so its alerts flow into **Security › Alerts** and the same problems and cases as the rest of your alerts. A rule moves through three stages:

| Stage          | Runs                | What happens to its alerts                                                                                              |
| -------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Draft**      | No                  | Nothing. The rule is off.                                                                                               |
| **Test**       | Yes, in shadow mode | Recorded in the **Shadow** lane only. Nothing notifies, pages, opens a case, runs a playbook or reaches the SOC agents. |
| **Production** | Yes                 | Routed through your notification policies, pages, cases and the SOC agents.                                             |

> **The switch in the list skips shadow mode**
>
> Turning a **Draft** rule on with the switch in the rule list runs it in **Production**. To trial a rule first, open it and select **Promote to test**.

## Before you begin

* Logs or endpoint events from the systems you want to watch. The **Linux Endpoint Security** integration sends process, network and file events that Sigma's Linux rules read without any mapping; the collector's Linux installer grants what it needs with `--enable-security`. Firewalls, proxies and other devices can send syslog; see [Syslog](https://tracix.io/docs/collect/network-data/syslog).
* An editor or admin role. Editors and admins install, import and promote rules; only admins change the log source mapping.

## Install the SigmaHQ pack

**1. Open the rule library**

Open **Security › Detection rules**.

**2. Install the pack**

On the **Sigma core pack** strip, select the install button. On a new workspace it reads **Install 3,665 rules**: the pack holds 3,665 SigmaHQ rules covering 170 ATT\&CK techniques, from one pinned SigmaHQ release. Every rule keeps its original YAML and author.

**3. Import ATT&CK data**

On the **MITRE ATT\&CK data** strip, select **Import ATT\&CK data**. Tracix downloads the enterprise ATT\&CK bundle, about 40 MB, from MITRE's official repository. Technique names and the coverage map need it.

Pack rules install turned off, and none of them runs or creates a monitor until you enable it. Rules marked experimental or test upstream start at stage **Test**; the rest start as **Draft**. When a newer pack ships, **Update pack rules** updates the rules you haven't edited, and records each update as a new version.

Detection rules come from the [SigmaHQ](https://github.com/SigmaHQ/sigma) project under the Detection Rule License 1.1. Alerts from a SigmaHQ rule show the rule's author and license.

## Check that a rule can see your data

Every Sigma rule names a log source, such as Linux process creation or a firewall. Tracix routes each log source to the data in your workspace that carries it.

* A rule whose log source has no route is saved off, with the reason, and stays off until something routes it.
* Open a rule to see the fields it reads, with unmapped fields flagged, and select **Check log source (24h)** to see whether that source sent data in the last day.
* Admins add routes and field renames for their own sources under **Log source mapping** in the rule library. Saving recompiles the rules it affects.

## Backtest a rule

Open a rule, choose a **Backtest** window of **Last 24 hours**, **Last 7 days** or **Last 30 days**, and select **Run**. The backtest replays the rule over that history, with its exceptions applied, and shows how many events and entities it would have matched. Backtest a pack rule before you enable it, so a noisy rule never reaches the pager.

## Trial a rule in shadow mode

**1. Promote it to test**

Open the rule and select **Promote to test**. The rule starts running, and its matches are recorded without notifying anyone.

**2. Watch its shadow hits**

The rule's **Shadow hits · last 24 hours** panel lists what it matched. **Security › Alerts** shows every shadow alert in the **Shadow** lane, kept out of the other lanes.

**3. Tune it**

Add exceptions in the rule's exceptions editor, or reference a value list, to suppress known-good matches. Test the edited exceptions against the last 24 hours before you save.

**4. Promote it to production**

Select **Promote to production** and confirm. New matches now notify through your notification policies and reach the SOC agents. Alerts the rule recorded during its test stay quiet.

Select **Demote to test** or **Demote to draft** to move a rule back a stage. Every stage move, like every edit, is a new version: the rule's history shows what changed and can restore an earlier version.

## Bring your own rules

Select **Import rules** in the rule library. The import drawer takes:

* **Paste** or **Upload**: Sigma YAML, as `.yml` or `.yaml` files or a `.zip` of them.
* **Git repository**: the YAML files in a GitHub or GitLab repository, public or read with a credential.
* **Splunk SPL** and **Sentinel KQL**: a translation of the supported query shapes into Sigma, with warnings for what it can't translate. Unsupported shapes are refused rather than guessed.
* **YARA**: rulesets for scanning files on hosts.

Every Sigma import goes through the same review first. For each document it shows whether the import creates, updates or skips a rule, whether the rule compiles, which fields are unmapped, whether its log source sent data in the last 24 hours, and an optional backtest. New rules arrive turned off unless you enable them in the review. Select **Import selected** to finish.

To keep rules in Git, an admin can connect a repository branch with **Keep in sync** in the Git repository tab, or move rules into a repository with **Export to git**, which opens a pull request. See [Detections as code](https://tracix.io/docs/api/as-code).

## See your ATT\&CK coverage

Open **Security › ATT\&CK Coverage** to see the enterprise ATT\&CK matrix, with each technique shaded by whether an enabled rule covers it, rules exist but are off, or nothing covers it. Select a technique to open the rule library filtered to it.

MITRE ATT\&CK® technique data © The MITRE Corporation. ATT\&CK® is reproduced and distributed with the permission of The MITRE Corporation.

## Next steps

- [Response actions](https://tracix.io/docs/security/response): Act on what the rules find

- [Problems and cases](https://tracix.io/docs/alerting/problems-and-cases): Work security alerts as cases

- [Detections as code](https://tracix.io/docs/api/as-code): Keep rules in Git and deploy them from CI