Skip to main content

​
Engine Overview

The Beacon detection engine runs threat rules over ordered endpoint events. The engine ships in the Beacon CLI, while the rule corpus is external data loaded from a directory, the local rule store, or a small embedded baseline. Local scanning is read-only and does not contact the network.

​
Active Rule Resolution

When beacon scan runs, Beacon resolves the active rules in this order:
  1. If --rules <dir> is provided, load .rule.yaml files from that directory.
  2. Otherwise, load installed rules from the endpoint rule store.
  3. If the store is absent or empty, load the built-in baseline rules embedded in the binary.
The per-user store is under the endpoint base directory, commonly ~/.beacon/endpoint/rules. System-mode installs use the system endpoint base directory.

​
Load-Time Validation

Rules are checked before any event scanning begins. Beacon:
  • decodes rule YAML strictly
  • rejects unknown structural fields
  • enforces required fields and match versus correlation exclusivity
  • validates rule IDs and duplicate IDs in a pack
  • compiles CEL expressions against Beacon event fields
  • ensures expressions evaluate to booleans
  • enforces maturity gates for experimental, stable, and deprecated
  • runs embedded fixtures for linting and install workflows
Invalid rules fail early so scans do not produce ambiguous results.

​
Event Input

beacon scan reads the resolved runtime.jsonl endpoint log unless a different path is supplied with --log-path. Each line is parsed as a Beacon endpoint event. The scan keeps the ordered event stream because correlation rules need event order and timestamps to evaluate windows. Use --session to scan only events whose session.id contains a given value.

​
Single-Event Matching

A single-event rule has a top-level match expression. The engine evaluates that expression independently against each event.
Single-event match
match: >
  e.event.action == "command.executed" &&
  e.command.command.matches("\\b(curl|wget|nc)\\b")
If any event satisfies the expression, the rule produces a finding with that event as evidence.

​
Correlation Matching

A correlation rule describes ordered steps inside a session window.
Ordered session correlation
correlation:
  scope: session
  window: 120s
  steps:
    - id: read_secret
      match: >
        e.event.action == "file.read" &&
        e.file.path.matches("(\\.env|credentials|id_rsa|\\.aws/)")
    - id: egress
      match: >
        e.event.action == "command.executed" &&
        e.command.command.matches("curl\\s+.*https?://")
For threat-rules/v1, correlation scope is session. Beacon groups events by e.session.id, then looks for each step in order. A later step must occur at or after the prior matched step, and the final step must occur within the configured window from the first matched step. Correlation is useful when no single event is suspicious enough on its own, but the sequence is meaningful.

​
Findings

When a rule fires, Beacon emits a finding. Findings include:
  • rule ID and rule title
  • severity
  • emitted reason from emit.reason
  • session ID when available
  • evidence events that matched the rule
  • policy metadata derived from the rule, such as policy.id, policy.name, and policy.reason
Human output summarizes findings by severity, rule, session, reason, and evidence lines. JSON output emits machine-readable finding objects for automation.

​
Filtering And Gates

beacon scan supports two severity controls:
  • --min-severity filters displayed findings.
  • --fail-on exits non-zero if any finding at or above the threshold exists.
The fail gate is evaluated before display filtering, so automation can fail on all matching detections even when output is narrowed for readability.

​
Operational Boundaries

Scanning does not mutate endpoint telemetry, change rule files, or fetch remote content. Rule installation and remote rule pack retrieval are explicit beacon rules workflows. Use the CLI pages for operational details:

beacon scan

Run detections over local endpoint telemetry.

Run local scans

Choose logs, rule directories, sessions, and output formats.

Use scan gates

Fail automation based on severity thresholds.

beacon rules

Manage the active rule store.

Detections

Return to the detections overview.

Detection YAML Schema

Review the rule document fields the engine loads.

Detection Standard

Understand conformance, maturity, and CEL requirements.

Endpoint Event Schema

Review the event stream evaluated by detections.