Detections

How Beacon detections turn agent runtime telemetry into security findings

Overview

Beacon detections are threat rules for AI-agent telemetry. They read normalized endpoint events, evaluate rule conditions over those events, and emit findings that explain which rule fired, why it fired, and which events were involved.

Use detections when you want to review local agent activity for risky commands, sensitive file access, suspicious tool use, policy bypass attempts, prompt-injection patterns, or multi-step behavior such as a secret read followed by outbound network access.

The detection format is open and lives in the Agent Beacon repository. Rules are YAML documents with CEL match expressions, metadata, and embedded test fixtures. The detection engine ships with the Beacon CLI, while rule packs are external data that can be installed, updated, and linted separately from the binary.

Local scanning is read-only and offline. beacon scan does not fetch rule packs, send telemetry to Asymptote, mutate endpoint configuration, or change the runtime log.

Quickstart

Run active detections over the default per-user endpoint log:

Scan local endpoint telemetry

beacon scan

Print machine-readable findings for automation or downstream tooling:

JSON findings

beacon scan --json

Install the full maintained rule pack from a Beacon release:

Install the full threat-rule pack

beacon rules pull https://github.com/asymptote-labs/agent-beacon/releases/download/v0.0.66/threat-rules.tar.gz

List the active rules Beacon will use:

List active detections

beacon rules list

Run a high-severity gate, useful in local validation or CI-like checks:

Fail on high or critical findings

beacon scan --fail-on high

What Detections Look For

Detections focus on risky agent behavior that is hard to understand from one raw log line alone:

• Credential access: reads of .env, SSH keys, cloud credentials, browser session stores, shell history, process tables, Kubernetes kubeconfigs and service-account tokens, GPG private keyrings, or password-manager vaults (KeePass, 1Password, Bitwarden, LastPass, pass).
• Context exfiltration: network commands, paste and transfer services, DNS tunneling, Git bundles, outbound MCP calls, secret-bearing request bodies, SSH reverse-tunnel or SOCKS-proxy invocations, or archive-then-upload pipelines.
• Risky commands: destructive shell operations, persistence installation (crontab, systemd timers, kernel modules), shell escapes, privileged container runs, curl-to-shell patterns, sudoers edits, root-equivalent changes, or history-rewriting git operations (filter-branch, filter-repo, rebase -i, force-push to protected branches).
• Sensitive edits: changes to CI pipelines, dependency manifests, shell startup files, authorization code, autostart units, agent instruction files, SSH authorized_keys or sshd_config, /etc/hosts or hosts.allow/deny, container or IaC files (Dockerfile, Terraform, Kubernetes manifests, Helm values), or other control surfaces.
• Prompt injection: instructions that try to override roles, ignore prior instructions, exfiltrate context, hide with invisible characters, or decode and execute hidden payloads.
• Approval and policy abuse: denied actions that still execute, high-risk approvals without a reason, attempts to spawn around runtime permission controls (agent CLIs launched with permission-elevating env vars, sandbox-escape primitives like nsenter / unshare / chroot / pivot_root), or re-invocations of denied commands through a renamed binary or temp-path shim.
• Agent runtime control: spawns of known agent CLIs (Claude Code, Codex, Cursor Agent, Aider, Goose, OpenCode, Gemini) that arrive with permission-elevating env vars or attempt to hand off credentials or context to a second agent.
• Resource consumption: unusually expensive single calls when token and cost telemetry are available, fork-bomb patterns (:(){ :|:& };:, while true; do ... & done), or disk-fill primitives (dd of /dev/zero to large targets, fallocate, yes-piped-to-file).

Because rules run over the shared Beacon event model, the same rule vocabulary can apply across supported harnesses when those harnesses emit the required fields.

Inventory helps explain which harnesses, local config, MCP servers, and skills are present and observable on an endpoint. Detection coverage depends on the telemetry fields emitted by those supported harnesses and visible local configuration.

Detection Coverage

Beacon ships with a small built-in baseline so beacon scan works before any rule store is installed. The broader rule pack is distributed as a release asset and includes categories like these:

Category	Example behaviors
credential-access	Credential-file reads, browser session store reads, shell history scans, SSH agent enumeration, Kubernetes kubeconfig reads, GPG secret-key exports, password-manager vault reads
context-exfiltration	Secret read then egress, credentials in curl data, upload to paste or transfer sites, SSH tunnel egress, archive-then-upload pipelines
risky-command	Curl piped to shell, recursive root delete, sudoers tampering, persistence installation, crontab modification, kernel-module load
sensitive-edit	CI pipeline edits, dependency manifest edits, shell login file edits, agent control surface edits, SSH authorized_keys edits, /etc/hosts edits, container / IaC file edits
prompt-injection	Role override jailbreaks, hidden payloads, markdown-image exfiltration, instruction override markers
external-access	Cloud metadata endpoint access, link-local target fetches, external MCP tool calls
approval-abuse	Permission-bypass execution or high-risk approvals without reviewer context, denied-command re-invocation through renamed binaries
source-control	Git hook installation, remote tampering, Git config execution injection, history rewriting (filter-branch / filter-repo / rebase -i), force-push to protected branches
agent-control	Agent CLIs spawned with permission-elevating env vars, sandbox-escape primitives, inter-agent credential handoff

Rules only evaluate events that exist in the runtime log. For example, an MCP detection needs MCP-like activity to be emitted by a supported harness, and a prompt-injection rule needs retained prompt or content fields to be present under the endpoint’s local data-retention settings.

Detection Flow

1. A supported agent harness emits runtime telemetry.
2. Beacon normalizes that telemetry into endpoint events and writes runtime.jsonl.
3. beacon scan loads the active rule set from an explicit rules directory, the local rule store, or the built-in baseline.
4. Each rule is decoded, validated, and compiled before it runs.
5. The scan evaluates rules against the ordered event stream.
6. Matching rules produce findings with rule metadata, severity, reason, session context, and evidence events.

You can run the same local detection flow from the command line with beacon scan or inspect it in the loopback-only endpoint dashboard. The dashboard Detections view lists active rules, while the Findings view runs those rules over the configured runtime log on demand.

Rules And Findings

A rule is the durable detection definition. It contains an id, title, severity, CEL logic, and test fixtures that prove the expected behavior.

A finding is the runtime result of a rule firing. Findings include the rule identity, severity, emitted reason, matched session when available, and the event evidence that caused the match.

Finding shape

{
  "rule_id": "secret-read-then-egress",
  "title": "Secret-file read followed by network egress",
  "severity": "high",
  "posture": "detect",
  "reason": "Secret file read then network egress within one session",
  "session_id": "claude-session-123",
  "events": [
    {
      "event": { "action": "file.read" },
      "file": { "path": ".env" }
    },
    {
      "event": { "action": "command.executed" },
      "command": { "command": "curl https://example.com" }
    }
  ]
}

Finding output is intended to be explainable first: analysts should be able to see the rule, the reason, and the evidence events without reconstructing the whole session by hand.

Single-event 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" }

Rule Sources

Beacon can run detections from three sources, resolved in this order:

1. An explicit directory passed to beacon scan --rules.
2. The local endpoint rule store managed by beacon rules.
3. The built-in baseline when no local store is installed or the store is empty.

Use an explicit rule directory when you are developing or testing a rule pack without installing it:

Scan with a local rule directory

beacon scan --rules ./rules --log-path ./runtime.jsonl

Use the rule store when you want Beacon’s normal local scan and dashboard workflows to use the same installed rules:

Install local rules into the store

beacon rules add ./rules

The per-user store is under the endpoint base directory, commonly ~/.beacon/endpoint/rules. System-mode installs use the system endpoint base directory.

Author And Validate Rules

Threat rules are meant to be reviewed and tested like code. A new rule should start as experimental, include a plain-language emit.reason, and carry at least one fixture that proves the expected verdict.

Validate a rule file or directory before installing it:

Lint rule files

beacon rules lint ./rules

Print the event fields available to CEL expressions:

List CEL field paths

beacon rules fields

Use the Detection YAML Schema page for the rule document shape, the Detection Standard page for maturity and conformance requirements, and the Detection Engine page for load-time validation and evaluation behavior.

Operational Notes

• beacon scan --min-severity <level> filters displayed findings.
• beacon scan --fail-on <level> exits non-zero when any finding at or above the threshold exists.
• beacon scan --session <id> narrows evaluation to events whose session ID contains the supplied value.
• beacon scan --log-path <path> scans a copied or archived runtime.jsonl file.
• beacon rules pull is the only rules workflow that reaches the network, and only for the explicit URL you provide.
• The local dashboard mirrors beacon scan rule resolution and finding behavior, but stays loopback-only and read-only.

Managed Detections

The open-source Beacon flow runs detections locally over endpoint JSONL. Asymptote Managed builds on the same telemetry foundation with centralized ingest, retention, search, detections, fleet-wide visibility, policy workflows, identity mapping, SSO/RBAC, and investigation workflows.

Use local Beacon detections when you need offline endpoint checks or customer-controlled forwarding. Use Managed when you need centralized review across a fleet or organization.

Read Next

YAML Schema

Learn the fields used by Beacon threat-rule YAML files.

Detection Standard

Understand the threat-rules/v1 standard, maturity ladder, and conformance model.

Detection Engine

See how rules are loaded, compiled, evaluated, and turned into findings.

beacon scan

Run active rules over local endpoint telemetry.

Endpoint dashboard

Browse active detections and findings in the local dashboard.

Related

Endpoint Event Schema

Review the normalized JSON fields that detections evaluate.

Inventory

Review local harness, MCP server, skill, and configuration visibility.

beacon rules

Manage, install, lint, and inspect local detection rules.