Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

2.0 KB
Raw Blame
---
title: "Run Local Scans"
description: "Scan local Beacon endpoint telemetry with active threat-detection rules"
---

## Command overview

Run `beacon scan` after endpoint telemetry is flowing to evaluate the runtime log with active threat-detection rules.

```bash title="Run a local scan"
beacon scan
```

Scanning is read-only. It loads local telemetry from the resolved runtime JSONL log, evaluates rules in memory, and prints findings without contacting the network.

## Rule selection

Beacon chooses rules in this order:

1. Rules in the local rule store.
2. The built-in baseline rules, except any whose id a store rule already defines (the store copy wins). With no store installed, the baseline runs alone.
3. The directory passed with `--rules`, when you want an explicit rule pack for one scan. It replaces both of the above.

```bash title="Scan with an explicit rule directory"
beacon scan --rules ./rules
```

## Runtime log selection

Use per-user endpoint paths by default:

```bash title="Scan user-mode telemetry"
beacon scan --user
```

Scan system-mode telemetry:

```bash title="Scan system-mode telemetry"
sudo beacon scan --system
```

Scan a copied or exported runtime log:

```bash title="Scan a specific runtime log"
beacon scan --log-path ./runtime.jsonl
```

## Session filtering

Filter to one session id substring when you are investigating a known agent run:

```bash title="Scan one session"
beacon scan --session claude-session-123
```

## Output

Human-readable output summarizes each finding, its severity, rule id, reason, session, and matched events.

For JSON output, use:

```bash title="Print JSON findings"
beacon scan --json
```

## Related

<Columns cols={2}>
  <Card title="Use scan gates" icon="circle-exclamation" href="/cli/scan-ci-gates">
    Filter findings and fail automation on severity thresholds.
  </Card>
  <Card title="beacon rules" icon="shield-halved" href="/cli/rules">
    Manage the rules used by local scans.
  </Card>
</Columns>