Skip to main content

​
Schema Overview

Beacon detection rules are YAML documents ending in .rule.yaml. Each rule describes one security condition over Beacon endpoint events and includes enough metadata and tests for the rule to be validated before it runs. The structural schema is the threat-rules/v1 JSON Schema in the Agent Beacon repository. The runtime engine also compiles CEL expressions and checks rule fixtures, because those checks cannot be fully represented by JSON Schema alone.

​
Minimal Rule

A rule must define its identity, maturity, detection logic, emitted reason, and at least one fixture.
Minimal single-event rule
id: suspicious-egress-command
version: 1
title: Suspicious network egress command
severity: high
status: experimental
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" }

​
Top-Level Fields

FieldRequiredMeaning
idYesStable rule identity. Use lowercase letters, numbers, and hyphens.
versionYesInteger rule revision. Increase it when rule logic changes.
titleYesHuman-readable rule name.
descriptionNoLonger explanation for readers. It is not evaluated.
severityYesOne of info, low, medium, high, or critical.
statusYesOne of experimental, stable, or deprecated.
postureYesdetect for observe-only rules or enforce-capable for rules designed to support enforcement.
taxonomyNoExternal references such as OWASP, MITRE ATLAS, or CVEs.
matchOne of match or correlationCEL boolean expression for a single event.
correlationOne of match or correlationOrdered multi-event sequence definition.
emit.reasonYesHuman-readable finding reason.
testsYesEmbedded conformance fixtures.
Exactly one of match or correlation must be present.

​
Match Rules

A match rule evaluates one event at a time. The event is available as e, and field paths mirror the endpoint event JSON shape.
Match expression
match: >
  e.event.action == "file.read" &&
  e.file.path.matches("(\\.env|credentials|id_rsa|\\.aws/)")
Use match when one event is enough to explain the behavior, such as a command, file read, approval decision, or MCP tool call.

​
Correlation Rules

A correlation rule evaluates an ordered sequence of events. In threat-rules/v1, correlations are scoped to a single session and must complete inside a duration window.
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?://")
Use correlation when the risk comes from a sequence, such as a secret-bearing file read followed by network egress in the same agent session.

​
Tests

Each rule carries test fixtures that define expected verdicts. Fixtures use partial Beacon events, so a test only needs the fields that matter for the rule.
Fixture shape
tests:
  - name: read_env_then_curl
    verdict: match
    events:
      - timestamp: "2026-06-13T10:00:00Z"
        event: { action: file.read }
        file: { path: ".env" }
        session: { id: s1 }
      - timestamp: "2026-06-13T10:00:30Z"
        event: { action: command.executed }
        command: { command: "curl https://example.com" }
        session: { id: s1 }
  - name: benign_read_then_local_command
    verdict: no_match
    events:
      - event: { action: file.read }
        file: { path: "README.md" }
        session: { id: s1 }
Fixtures keep rules reviewable. They show what the author intended to detect and what should stay out of scope.

​
Field Paths

CEL expressions use e.<field> paths that match the Beacon event schema. Common paths include:
Field pathCommon use
e.event.actionMatch the normalized event action.
e.command.commandMatch shell or process command text.
e.file.pathMatch file paths.
e.prompt.textMatch prompt text when retained.
e.session.idCorrelate activity within one session.
e.mcp.serverMatch MCP-like server context.
e.approval.decisionMatch approval or policy outcomes.
e.gen_ai.usage.input_tokensMatch GenAI usage fields.
Use beacon rules fields or the generated upstream field reference to confirm available paths.

Detection Standard

Review maturity, conformance, and CEL requirements.

Detection Engine

See how YAML rules are loaded and evaluated.

beacon rules lint

Validate rule files and run embedded fixtures.

Endpoint schema fields

Review the event entities rules can match.