Skip to main content

Command overview

beacon rules diff compares what two rule packs say about the same events and lists every verdict that changed.
Command syntax
Use it before merging a change to a rule, to a predicate or catalog 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.
Example output

A change to the rules

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

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:
Compare across two builds of Beacon
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

beacon rules lint

Validate rule files and run embedded fixtures.

Rule YAML schema

Predicates and the definitions a pack ships.