Skip to main content

​
Command Overview

beacon rules manages the local threat-rule store used by beacon scan and provides authoring helpers for validating rule packs.
Command syntax
beacon rules [command]
The detection engine ships in the Beacon binary, but rules are external data loaded from the local store. A small baseline is built in and used until you install your own rules.
Beacon never fetches rules on its own. beacon rules pull is the only rules command that reaches the network, and only for the explicit URL you provide.

​
Commands

list

List the active threat-detection rules.

add

Install local rule files into the store.

remove

Remove a rule from the store by id.

pull

Fetch an explicit rule pack URL into the store.

lint

Validate rule files and run embedded fixtures.

fields

Print event fields available to CEL match expressions.

​
Rule format

Threat rules are YAML documents whose match conditions are CEL expressions over Beacon endpoint events. A single-event rule uses a top-level match; a correlated rule uses ordered correlation.steps scoped to a session window. Rules include severity, maturity status, posture, an emitted reason, and embedded conformance fixtures. Stable rules must include at least one matching and one non-matching fixture.
Example rule shape
id: suspicious-egress-command
version: 1
title: Suspicious network egress command
severity: high
status: stable
posture: detect
match: >
  e.event.action == "command.executed" &&
  e.command.command.matches("\\b(curl|wget|nc)\\b")
emit:
  reason: "Agent executed a command commonly used for network egress"
tests:
  - name: positive_basic
    verdict: match
    events:
      - event: { action: command.executed }
        command: { command: "curl https://example.com" }
  - name: unrelated
    verdict: no_match
    events:
      - event: { action: command.executed }
        command: { command: "ls -la" }

​
beacon rules list

List the active rules and show whether each rule came from the store or the built-in baseline.
List active rules
beacon rules list
Use --system to inspect the system-mode rule store.

​
beacon rules add

Install a local .rule.yaml file or a directory of rule files into the store. Rules are validated before install.
Install local rules
beacon rules add ./rules
Overwrite an existing rule with the same id:
Overwrite an existing rule
beacon rules add ./rules --force

​
beacon rules remove

Remove one rule from the store by id.
Remove a rule
beacon rules remove suspicious-egress-command

​
beacon rules pull

Fetch a .rule.yaml, .tar.gz, or .tgz rule pack from an explicit URL and install valid rules into the store.
Pull a rule pack
beacon rules pull https://example.com/beacon-rules.tar.gz
Downloaded tarballs only install .rule.yaml entries. Archive entries containing path traversal elements are rejected before install.

​
beacon rules lint

Validate a rule file or directory, compile CEL expressions against the endpoint event schema, enforce maturity gates, and run embedded conformance fixtures.
Lint a rule directory
beacon rules lint ./rules
With no path, Beacon lints ./rules.

​
beacon rules fields

Print the event fields a rule can reference from CEL expressions.
List rule fields
beacon rules fields
Render a markdown field reference:
Render fields as markdown
beacon rules fields --markdown

​
Shared Store Flags

beacon rules list, add, remove, and pull accept endpoint mode flags:
FlagDescription
--userUse per-user endpoint paths. Enabled by default
--systemUse system endpoint paths
--forceOverwrite an existing rule with the same id. Available on add and pull

beacon scan

Run active rules over local endpoint telemetry.

Detections

Understand the detection model behind Beacon threat rules.

Endpoint Event Schema

Review normalized event fields available to rules.