The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Package installs: turn the local dashboard off on a first install
Claude4bc7bd9061b7
diff --git a/CLAUDE.md b/CLAUDE.mdindex a8423d61..23362a9b 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -73,7 +73,7 @@ Supported runtime surfaces today:- Beacon Cloud forwarding, the one Beacon-hosted network channel for endpoint telemetry: user-mode `beacon endpoint connect` authorizes device enrollment with the signed-in CLI account; system mode uses browser PKCE at `/cli/enroll`. Both store only the per-device key in `<BaseDir>/asymptote/vector-secrets.json` (0600, 0700 dir), render the selected privacy mode into `vector.toml` (re-rendered in place by install, repair and package upgrades, see above), validate it, and run Vector as `com.beacon.endpoint.asymptote-forwarder` / `beacon-asymptote-forwarder.service` through `service.ForwarderManager` (refused in supervised mode). `enrollment.json` and `config.json`'s `managed_ingest` block carry only non-secret identity and privacy mode; `beacon endpoint status` reports forwarder state and a live credential check (`GET /v1/ingest/health`, 3 s timeout); `disconnect` and `uninstall` remove the forwarder and credentials but never revoke server-side.- Asymptote Observe TypeScript SDK instrumentation for cloud applications, starting from OpenTelemetry/OpenLLMetry patterns and `observe()` wrappers.- Elasticsearch/Filebeat content pack generation for forwarding local Beacon JSONL into customer-managed Elastic deployments or the bundled loopback-only development stack.-- A local-only dashboard served by `beacon endpoint dashboard`, bound to loopback by default and backed by the runtime JSONL log (docs in `docs/cli/dashboard.mdx#access-control`). Loopback binding and `RequireLoopbackHost` keep other machines and DNS-rebinding pages out but not other local accounts, so every run (and `beacon lenses preview`) makes a per-launch secret (`dashboard.NewToken`, 256 bits, kept in memory and printed only inside `LaunchURL`'s `?token=`, never written to a file, log or JSON) and `ListenAndServe` refuses to start without `Options.Token`. `RequireToken` (`dashboard/access.go`) accepts the token once per browser, sets an HttpOnly, SameSite=Strict, Path=/ cookie named for the port (`CookieName`) and 303-redirects without the token; every other request needs the cookie (constant-time compare) or gets 401. Lens frames and `/api/lens-data` ride the cookie as same-site requests; the e2e server takes its secret from `BEACON_E2E_DASHBOARD_TOKEN` and the Playwright config seeds the cookie (`tests/access.spec.ts` covers the launch URL). Cookies are shared across ports of `127.0.0.1`, so never describe the secret as more than keeping out accounts that do not have it. The administrator switch is the system `config.json` `dashboard` (`enabled`, the default when empty, or `disabled`; `install|repair --system --dashboard`, `BEACON_DASHBOARD` in the three install scripts, carried by `buildConfig`, refused in user mode): when disabled, `refuseDisabledDashboard` (`cmd/endpoint_dashboard_access.go`, via `endpointconfig.SystemDashboardDisabled`) stops the dashboard and lens preview for every account, and status reports it as `dashboard`. Any value but empty or `enabled` reads as disabled (`Config.DashboardMode`), and `buildConfig` carries such a value as `disabled` (`carriedDashboard`) so preflight never fails a repair over it. A system config holding a HEC token is root-only, so `endpointconfig.Save` also keeps a world-readable `dashboard-disabled` marker beside the system config while the switch is off (`syncDashboardMarker`; uninstall removes it); `DashboardDisabledAt` reads the config when it can and the marker only when reading the config is refused for permission, a config that does not parse refuses, and `buildConfig` keeps the switch off from the marker (`systemDashboardMarked`) when the config does not load.+- A local-only dashboard served by `beacon endpoint dashboard`, bound to loopback by default and backed by the runtime JSONL log (docs in `docs/cli/dashboard.mdx#access-control`). Loopback binding and `RequireLoopbackHost` keep other machines and DNS-rebinding pages out but not other local accounts, so every run (and `beacon lenses preview`) makes a per-launch secret (`dashboard.NewToken`, 256 bits, kept in memory and printed only inside `LaunchURL`'s `?token=`, never written to a file, log or JSON) and `ListenAndServe` refuses to start without `Options.Token`. `RequireToken` (`dashboard/access.go`) accepts the token once per browser, sets an HttpOnly, SameSite=Strict, Path=/ cookie named for the port (`CookieName`) and 303-redirects without the token; every other request needs the cookie (constant-time compare) or gets 401. Lens frames and `/api/lens-data` ride the cookie as same-site requests; the e2e server takes its secret from `BEACON_E2E_DASHBOARD_TOKEN` and the Playwright config seeds the cookie (`tests/access.spec.ts` covers the launch URL). Cookies are shared across ports of `127.0.0.1`, so never describe the secret as more than keeping out accounts that do not have it. The administrator switch is the system `config.json` `dashboard` (`enabled`, the default when empty, or `disabled`; `install|repair --system --dashboard`, `BEACON_DASHBOARD` in the three install scripts, carried by `buildConfig`, refused in user mode; a first package install, decided by the same no-system-config-and-no-log test as restricted log access, passes `disabled` when `BEACON_DASHBOARD` is unset, on every platform and service mode, and upgrades pass nothing): when disabled, `refuseDisabledDashboard` (`cmd/endpoint_dashboard_access.go`, via `endpointconfig.SystemDashboardDisabled`) stops the dashboard and lens preview for every account, and status reports it as `dashboard`. Any value but empty or `enabled` reads as disabled (`Config.DashboardMode`), and `buildConfig` carries such a value as `disabled` (`carriedDashboard`) so preflight never fails a repair over it. A system config holding a HEC token is root-only, so `endpointconfig.Save` also keeps a world-readable `dashboard-disabled` marker beside the system config while the switch is off (`syncDashboardMarker`; uninstall removes it); `DashboardDisabledAt` reads the config when it can and the marker only when reading the config is refused for permission, a config that does not parse refuses, and `buildConfig` keeps the switch off from the marker (`systemDashboardMarked`) when the config does not load.- Token usage and runtime-reported cost capture across spans, logs, and metric datapoints, normalized into `gen_ai.usage`, with attribution rollups served by the dashboard token view (`/api/tokens`) and the `beacon token-usage` report command for local and CI logs. Every report row carries three costs (`cli/beacon/internal/tokens/cost.go`): `cost_usd` (runtime-reported, unchanged), `estimated_cost_usd` (list price of every priced token, from `internal/pricing`, computed after dedup and cumulative resolution) and `effective_cost_usd` with `cost_source` (per endpoint/harness/session scope, reported cost wins wholesale when the scope has any; otherwise the estimate; session-less events per event), plus `unpriced_events`/`unpriced_tokens` and a report-level `pricing` block (catalog provenance, per-model key, match, base rates, bands applied, fallbacks, unpriced models). Long-context bands apply only to events `requestScoped` classifies as one model request; it defaults to aggregate, so a new capture path is priced at base rates until it is added there with a test. Lens data (`LensDataV1`) carries no estimate.- Local threat detection via `beacon scan`, which runs the open Threat Rules format (`spec/threat-rules`; CEL match conditions over the endpoint event schema, with embedded conformance fixtures) over the runtime JSONL. The engine (`pkg/asymptoteobserve/threatrules`) ships in the binary; the rule corpus is external data loaded from a local store (`~/.beacon/endpoint/rules`) managed by `beacon rules`, so the corpus can grow without enlarging the binary. `scan` is read-only and offline; only the explicit, user-initiated `beacon rules pull <url>` reaches the network, over `https://` only (plain http just for loopback, no redirect off https), size-capped, and verified first when `--sha256` is given. A small frozen baseline is embedded so `scan` works before any rules are installed, and it stays active alongside the store: a store rule replaces a baseline rule only by id (`rulestore.LoadActiveSkipping`), so installing one rule never silently switches the baseline off; only `--rules <dir>` runs a directory alone.- Session handoff via `beacon handoff list|export|resume` (`cli/beacon/internal/handoff`, `cli/beacon/cmd/handoff*.go`; docs in `docs/cli/handoff.mdx` and `docs/concepts/session-handoff.mdx`). Every runtime is one entry in the registry in `cli/beacon/internal/handoff/runtimes.go`: its session source, the names it answers to, and the commands that reopen it or start it from a brief; `TestRegistryIsConsistent` checks the entries. Handoff reads the session stores of Claude Code, Codex CLI, OpenCode, Cline, Pi, Prime Agent, Factory Droid, GitHub Copilot CLI, Hermes Agent, DeepSeek Harness, fx, Grok Build, OpenClaw Gateway and Cursor read-only and never touches the network. Oh My Pi, Gemini CLI, Qwen Code, Kiro, Antigravity CLI, Devin CLI, Muse Code, OpenHands and goose have no store Beacon reads: their sessions come from the runtime log, and they take a brief as the target of `--agent`. `resume` reopens a session natively with its runtime's own command when it can, and otherwise writes a brief to `~/.beacon/endpoint/handoffs` (0700/0600) and starts a new session pointed at it. DeepSeek Harness cannot be started, and Hermes Agent and fx only reopen their own sessions, so their sessions continue in another runtime. fx, Grok Build and Cursor find a session by the directory they run in, so they are reopened natively only in the session's own directory. The brief is passed by absolute path, never inlined on a command line. By default the runtime runs in the calling terminal; `--launch auto|new-terminal|tmux` (`internal/handoff/detached.go`) instead writes a one-time `launch-<id>.json` specification (0600, expires after five minutes) beside the briefs, opens a terminal surface (cmux or Terminal.app, Windows Terminal or PowerShell, a Linux terminal emulator, or a detached tmux session) running the hidden `beacon handoff _launch --spec`, and waits up to 15 s for it to confirm the runtime started, removing the specification on a timeout so a late terminal starts nothing (the trampoline claims it by an atomic rename, so a timeout after the claim reports that the runtime may still start rather than cancelled, and the status is renamed into place so the caller never reads it half-written). Content is never put on the terminal's command line, and only the store-locating path variables in `carriedEnvNames`, never credentials, are carried into the specification. Every launch keeps the runtime's approvals on: Beacon never passes a flag that turns them off, names the approval mode that asks where a CLI takes one (Cline always gets `--auto-approve false`, because Cline defaults to approving every tool call), and removes or overrides environment switches that would approve everything (`COPILOT_ALLOW_ALL`, `COPILOT_PLAN_THEN_AUTOPILOT`, `HERMES_YOLO_MODE`, `GOOSE_MODE`); `--print` shows them under `env`. Briefs run every event through `SanitizeEvent`, and quoted content goes in fences longer than any backtick run it contains, with inline fields reduced to one line, so quoted content cannot forge brief structure. A new session's first prompt ends with the `[beacon-handoff from=<harness> session=<id>]` marker (`pkg/asymptoteobserve/handoff.go`). The hook and plugin prompt paths and the session-store mappers record a `session.handoff` event with `handoff.{source_harness,source_session_id}` when they see it; that is an observed claim, not a verified identity.diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdxindex e5555ae8..5cf428e2 100644--- a/docs/changelog/cli.mdx+++ b/docs/changelog/cli.mdx@@ -11,6 +11,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.## Unreleased+- **Package installs turn the local dashboard off** · A first install of the `.deb` or `.rpm`, the macOS `.pkg` or the Windows MSI now turns the local dashboard off for every account on the machine, root included, as `BEACON_DASHBOARD=disabled` already did: a package is installed for the whole machine, and the people using it should not be able to open a view of its telemetry unless an administrator says so. Upgrades, and reinstalls over a kept config or log, keep the setting an endpoint already has, so set `BEACON_DASHBOARD=disabled` to turn it off on machines installed from an earlier release. `BEACON_DASHBOARD=enabled` keeps it on a new install, and `sudo beacon endpoint repair --system --dashboard enabled` turns it back on. Installs from the `beacon` CLI are unchanged. See [Turning the dashboard off](/cli/dashboard#turning-the-dashboard-off).- **Package installs are restricted from the start, on Linux, macOS and Windows** · A first install of the `.deb` or `.rpm`, the macOS `.pkg` or the Windows MSI now sets up [restricted log access](/security/restricted-log-access) on its own: the `beacon-log` group, a log that only the collector writes, and hooks that send their events over the local socket or named pipe, recorded under the account that sent them. Before, a fleet install (Salt, Ansible, Jamf, Intune) left the log writable by every account until someone ran `beacon endpoint repair --system --log-access restricted`. On Linux, only where systemd runs the collector. Upgrades, and reinstalls over a kept config or log, keep the mode an endpoint already has; `BEACON_LOG_ACCESS=shared` installs a new endpoint shared. A person who installs the package interactively (`sudo apt install`, Installer.app, the MSI's full interface) is added to `beacon-log`, so the dashboard, `beacon traces` and `beacon share` work for them; an unattended fleet install adds nobody. `BEACON_LOG_READERS`, or the new `--log-readers`, names exactly who is added. See [Package installs](/security/restricted-log-access#package-installs).- **Package install settings for fleet tooling** · MDMs and configuration managers install packages without letting you set the install script's environment, so the `BEACON_*` install settings could not reach a fleet install. Each package now also reads them where that platform's tooling writes settings: `/etc/default/beacon` or `/etc/sysconfig/beacon` on Linux (read as shell syntax, never run), managed preferences for `com.beacon.endpoint` on macOS, and `HKLM\SOFTWARE\Policies\Beacon\Endpoint` on Windows. Each is ignored unless root (SYSTEM or Administrators) controls it, and the environment still wins. See [Package installs](/security/restricted-log-access#package-installs).- **OpenTelemetry events name the person who sent them on macOS and Windows too** · The collector on macOS and Windows now records each OpenTelemetry export (Claude Code's and Codex's spans, logs and token usage, the browser extension's chats) under the account that owns the connection it arrived on, as Linux already did, instead of the collector's own account (`root`, or the machine account `COMPUTERNAME$` on Windows). macOS reads the owner of the sending socket from the kernel's TCP table (the one `netstat` reads); Windows finds the process that owns the connection and reads the account from its token. A sender's own claim to an account is ignored, an export whose sender cannot be identified (it disconnected before the collector looked) carries no `user` at all, and Claude Cowork events carry no `user` on every platform, with the cloud account Cowork reports and the relaying account kept in their raw attributes. A user-mode collector on Windows can identify only its own account's exports; others carry no `user`. A Falcon LogScale HEC destination records the same account as `runtime.jsonl`, and Beacon's OTLP forward to another backend is unchanged. Run `beacon endpoint repair --system` (package upgrades do this) to render the new collector config; the collector from the same release is required.diff --git a/docs/cli/dashboard.mdx b/docs/cli/dashboard.mdxindex 110e09b6..51afa752 100644--- a/docs/cli/dashboard.mdx+++ b/docs/cli/dashboard.mdx@@ -177,7 +177,11 @@ package upgrades keep until `--dashboard enabled` turns it back on. While it ismode too, and say that the administrator disabled it. Accounts that cannot read a root-onlysystem config read the switch from a world-readable marker beside it, and a config that does notparse also refuses. `beacon endpoint status` (and `--json`, as `dashboard`) reports the setting.-Package installs take it from `BEACON_DASHBOARD=enabled|disabled`; see+Package installs take it from `BEACON_DASHBOARD=enabled|disabled`, and a first package install+(the `.deb` or `.rpm`, the macOS `.pkg` or the Windows MSI, with no system config or log already on+the machine) turns the dashboard off when `BEACON_DASHBOARD` is not set. Upgrades keep what the+endpoint already has. To keep the dashboard on a new install, set `BEACON_DASHBOARD=enabled`, or+turn it on afterwards with `sudo beacon endpoint repair --system --dashboard enabled`; see[`beacon endpoint install`](/cli/endpoint-install#local-dashboard).## Relateddiff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex 98e654ef..1c61a132 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -349,7 +349,9 @@ file beside it follows.For package installs, set `BEACON_DASHBOARD=enabled` or `BEACON_DASHBOARD=disabled` in theenvironment of the package's install script (`install-endpoint.sh` on macOS and Linux,-`install-endpoint.ps1` on Windows); unset keeps the endpoint's setting. Fleet tooling can set it+`install-endpoint.ps1` on Windows). Unset, a first package install (no system config or log on the+machine) turns the dashboard off, and an upgrade or a reinstall over a kept config or log keeps the+endpoint's setting. Fleet tooling can set itwhere it writes the other install settings (`/etc/default/beacon` or `/etc/sysconfig/beacon`, the`com.beacon.endpoint` managed preferences, or the `HKLM\SOFTWARE\Policies\Beacon\Endpoint` policy key);see [Package installs](/security/restricted-log-access#package-installs).diff --git a/docs/platforms/fleet-deployment.mdx b/docs/platforms/fleet-deployment.mdxindex cddbc66b..9ac86282 100644--- a/docs/platforms/fleet-deployment.mdx+++ b/docs/platforms/fleet-deployment.mdx@@ -16,7 +16,7 @@ This page puts the fleet settings together for each platform: the package, the s| Log access | A first package install is [restricted](/security/restricted-log-access): only the collector writes the runtime log, and only root (SYSTEM and Administrators on Windows) and the `beacon-log` group can read it. No second command || Who can read the log | Nobody is added to `beacon-log` by an unattended install. Name exactly who is with `BEACON_LOG_READERS`, such as a log shipper's account || Who acted | Hook events are recorded under the account the operating system says sent them. OpenTelemetry events (browser chats, Claude Code and Codex spans and token data) are recorded under the account that owns the sending connection. On a shared machine each person's events carry their own account, not `root` |-| The local dashboard | Opens only through the per-launch URL it prints. `BEACON_DASHBOARD=disabled` turns it off for every account |+| The local dashboard | Off for every account on a first install. `BEACON_DASHBOARD=enabled` keeps it, and then it opens only through the per-launch URL it prints || Versions | Nothing updates on its own. You choose the version each machine installs, including holding back one release |## The settings@@ -27,7 +27,7 @@ Fleet tooling cannot set the environment of a package's install script, so each|---|---|---|| `BEACON_LOG_ACCESS` | `restricted` | Explicit restricted log access. A first install is restricted without it; setting it keeps the intent in your configuration || `BEACON_LOG_READERS` | empty, or a list | Exactly the accounts added to `beacon-log`, comma-separated (`DOMAIN\name` on Windows). Empty means nobody is ever added implicitly |-| `BEACON_DASHBOARD` | `disabled` (optional) | Refuse to start the local dashboard and lens preview on the machine |+| `BEACON_DASHBOARD` | `disabled` | Refuse to start the local dashboard and lens preview on the machine. A first install is disabled without it; setting it also turns the dashboard off on machines upgraded from an earlier release || `BEACON_ENDPOINT_HARNESSES` | for example `claude,codex,cursor` | The agent runtimes to configure || Platform | Where the settings live |diff --git a/docs/platforms/linux.mdx b/docs/platforms/linux.mdxindex fe75963b..9a036288 100644--- a/docs/platforms/linux.mdx+++ b/docs/platforms/linux.mdx@@ -172,6 +172,8 @@ beacon scan # run threat detection rules over the logbeacon token-usage # token and cost rollups```+A package install turns the dashboard off unless `BEACON_DASHBOARD=enabled` was set; see [Turning the dashboard off](/cli/dashboard#turning-the-dashboard-off).+See the [event schema](/telemetry-schema/event-schema) for the full field reference.## Forwarding@@ -212,7 +214,7 @@ The `Claude Code hooks installed: /root/...` lines printed before it are root'ssudo beacon endpoint user-config repair-installed --system```-Other users on the same machine run the same command for themselves. They all export to the same collector and the same log. A first package install on a host where systemd runs the collector sets the log to [restricted access](/cli/endpoint-install#restricted-log-access): the collector is the only writer, hooks hand their events to it over a local socket and are recorded under the account the kernel says sent them, and only root and the `beacon-log` group can read the log. That includes the people using the machine: the dashboard, `beacon share` and `beacon traces` cannot read the system log for an account outside `beacon-log`. When you install the package yourself with `sudo`, you are added to `beacon-log` (log in again for it to take effect); a configuration manager's install adds nobody. Add anyone else with `sudo usermod -aG beacon-log <user>`, or name them in `BEACON_LOG_READERS` (see [Package installs](/security/restricted-log-access#package-installs)). Without systemd as PID 1 (a container, WSL without systemd) or with `BEACON_SERVICE=none`, the collector is a process nothing restarts, so those installs stay shared unless you ask for restricted. A package upgrade, or a reinstall over a log kept by `uninstall --keep-logs`, keeps whatever mode the endpoint already has, so an endpoint installed from an earlier package stays shared until you switch it with `sudo beacon endpoint repair --system --log-access restricted`. To install with the older shared log instead, where every account appends to the file directly, set `BEACON_LOG_ACCESS=shared` (see below).+Other users on the same machine run the same command for themselves. They all export to the same collector and the same log. A first package install on a host where systemd runs the collector sets the log to [restricted access](/cli/endpoint-install#restricted-log-access): the collector is the only writer, hooks hand their events to it over a local socket and are recorded under the account the kernel says sent them, and only root and the `beacon-log` group can read the log. That includes the people using the machine: the dashboard, `beacon share` and `beacon traces` cannot read the system log for an account outside `beacon-log`. When you install the package yourself with `sudo`, you are added to `beacon-log` (log in again for it to take effect); a configuration manager's install adds nobody. Add anyone else with `sudo usermod -aG beacon-log <user>`, or name them in `BEACON_LOG_READERS` (see [Package installs](/security/restricted-log-access#package-installs)). Without systemd as PID 1 (a container, WSL without systemd) or with `BEACON_SERVICE=none`, the collector is a process nothing restarts, so those installs stay shared unless you ask for restricted. A package upgrade, or a reinstall over a log kept by `uninstall --keep-logs`, keeps whatever mode the endpoint already has, so an endpoint installed from an earlier package stays shared until you switch it with `sudo beacon endpoint repair --system --log-access restricted`. A first package install also turns the [local dashboard](/cli/dashboard#turning-the-dashboard-off) off for every account, wherever the collector runs; set `BEACON_DASHBOARD=enabled` to keep it, and an upgrade keeps whatever an endpoint already has. To install with the older shared log instead, where every account appends to the file directly, set `BEACON_LOG_ACCESS=shared` (see below).### Settings for configuration-manager installsdiff --git a/docs/platforms/macos.mdx b/docs/platforms/macos.mdxindex e79612f7..22279738 100644--- a/docs/platforms/macos.mdx+++ b/docs/platforms/macos.mdx@@ -34,7 +34,7 @@ For deployment across machines, use the signed, notarized, and stapled `.pkg` atThe package also configures the console user's agent runtime, because a system endpoint runs as root and the collector is useless if nothing is exporting to it.-A first install from the package sets up [restricted log access](/security/restricted-log-access): only the collector writes the log, and only root and the `beacon-log` group can read it. An upgrade keeps the mode the endpoint already has. A person who installs the package in Installer.app is added to `beacon-log`, so the dashboard, `beacon traces` and `beacon share` work for them after they log in again; an MDM install adds nobody. See [Package installs](/security/restricted-log-access#package-installs).+A first install from the package sets up [restricted log access](/security/restricted-log-access): only the collector writes the log, and only root and the `beacon-log` group can read it. An upgrade keeps the mode the endpoint already has. A person who installs the package in Installer.app is added to `beacon-log`, so `beacon traces` and `beacon share` work for them after they log in again; an MDM install adds nobody. A first install also turns the [local dashboard](/cli/dashboard#turning-the-dashboard-off) off; set `BEACON_DASHBOARD=enabled` to keep it. See [Package installs](/security/restricted-log-access#package-installs).### Settings for MDM installsdiff --git a/docs/platforms/windows.mdx b/docs/platforms/windows.mdxindex 32987342..9cd9cbdb 100644--- a/docs/platforms/windows.mdx+++ b/docs/platforms/windows.mdx@@ -23,7 +23,7 @@ msiexec /i BeaconEndpointAgent-<version>-x64.msi /qn /l*v install.logThe install needs administrator rights, because it writes under `%ProgramData%` and registers a service. Elevation is requested for you when you double-click the package. A silent install must already be running elevated, which is the normal case for Intune, SCCM, or a management agent.-A first install sets up [restricted log access](/security/restricted-log-access#on-windows): only the SYSTEM collector writes the log, and only SYSTEM, Administrators and the `beacon-log` local group can read it. An upgrade keeps the mode the endpoint already has. Installing interactively adds the account signed in at the console to `beacon-log`, so the dashboard, `beacon traces` and `beacon share` work for it after signing in again; a silent install (`/qn`) adds nobody. See [Package installs](/security/restricted-log-access#package-installs).+A first install sets up [restricted log access](/security/restricted-log-access#on-windows): only the SYSTEM collector writes the log, and only SYSTEM, Administrators and the `beacon-log` local group can read it. An upgrade keeps the mode the endpoint already has. Installing interactively adds the account signed in at the console to `beacon-log`, so `beacon traces` and `beacon share` work for it after signing in again; a silent install (`/qn`) adds nobody. A first install also turns the [local dashboard](/cli/dashboard#turning-the-dashboard-off) off; set `BEACON_DASHBOARD=enabled` to keep it. See [Package installs](/security/restricted-log-access#package-installs).### Settings for fleet installs@@ -136,6 +136,8 @@ beacon scan # run threat detection rules over the logbeacon token-usage # token and cost rollups```+A package install turns the dashboard off unless `BEACON_DASHBOARD=enabled` was set; see [Turning the dashboard off](/cli/dashboard#turning-the-dashboard-off).+See the [event schema](/telemetry-schema/event-schema) for the full field reference.## What the install doesdiff --git a/docs/security/restricted-log-access.mdx b/docs/security/restricted-log-access.mdxindex 52e95b37..bcb3a431 100644--- a/docs/security/restricted-log-access.mdx+++ b/docs/security/restricted-log-access.mdx@@ -76,7 +76,7 @@ The `.deb` and `.rpm`, the macOS `.pkg` and the Windows MSI follow the same rule| Installed by | How the install recognizes it | Added to `beacon-log` ||---|---|---|| Fleet tooling, unattended (Salt, Ansible, Jamf, Kandji, Intune, SCCM) | Linux: root with no `SUDO_USER`, or sudo with no terminal or under `DEBIAN_FRONTEND=noninteractive` (Ansible `become`, a Packer sudo provisioner). macOS: `installer` (sets `COMMAND_LINE_INSTALL`). Windows: a silent MSI (`msiexec /qn`) | Nobody |-| A person, as an administrator | Linux: `sudo apt install` or `sudo dpkg -i` at a terminal. macOS: Apple's Installer.app, running as the logged-in user. Windows: the installer's full interface | That person, so the dashboard, `beacon traces` and `beacon share` work for them after they log in again |+| A person, as an administrator | Linux: `sudo apt install` or `sudo dpkg -i` at a terminal. macOS: Apple's Installer.app, running as the logged-in user. Windows: the installer's full interface | That person, so `beacon traces`, `beacon share` and, if an administrator enables it, the dashboard work for them after they log in again || Anyone, with `BEACON_LOG_READERS` set | The setting, even an empty one | Exactly the accounts it lists, comma-separated (`DOMAIN\name` on Windows) |Set `BEACON_LOG_READERS` to an empty value in a fleet's settings so that nobody is ever added implicitly, whatever runs the install. Accounts are only ever added, never removed, and one that cannot be added is reported without failing the install. `--log-readers` does the same on `beacon endpoint install|repair --system`.diff --git a/packaging/linux/install-endpoint.sh b/packaging/linux/install-endpoint.shindex db11fde0..f81b3249 100755--- a/packaging/linux/install-endpoint.sh+++ b/packaging/linux/install-endpoint.sh@@ -85,7 +85,7 @@ fi# nothing, it is exactly the list: an unattended fleet install sets BEACON_LOG_READERS= so that nobody# is ever added implicitly. Unset, a first install that a person ran with sudo at a terminal# (`sudo apt install`, `sudo dpkg -i`) adds that person, so whoever installed Beacon on their own-# machine can use the dashboard, `beacon traces` and `beacon share` without a second step. A+# machine can use `beacon traces` and `beacon share` without a second step. A# configuration manager running as root has no SUDO_USER, and one that reaches root through sudo# (Ansible `become`, a Packer sudo provisioner) sets SUDO_USER to its automation login, so SUDO_USER# alone is not a person: the install must also have a controlling terminal and not run under@@ -118,8 +118,15 @@ if [ -z "${BEACON_LOG_READERS+set}" ]; thenfifi# enabled or disabled: whether any account may run `beacon endpoint dashboard`. Empty keeps what the-# endpoint already has, so a package upgrade never changes it.+# endpoint already has, so a package upgrade never changes it. A first install defaults to disabled,+# for the same reason it defaults to a restricted log: a package is installed by root for the whole+# machine, and the people using that machine should not be able to open a view of its telemetry+# unless the administrator says so. BEACON_DASHBOARD=enabled opts a new install out.BEACON_DASHBOARD="${BEACON_DASHBOARD:-}"+BEACON_DASHBOARD="$(printf '%s' "$BEACON_DASHBOARD" | tr -d '[:space:]')"+if [ -z "$BEACON_DASHBOARD" ] && [ "$first_install" = 1 ]; then+ BEACON_DASHBOARD=disabled+fi# 1 turns the scheduled session sync on and 0 turns it off; empty keeps what the endpoint already# has, so a package upgrade never changes it.BEACON_SESSION_SYNC="${BEACON_SESSION_SYNC:-}"diff --git a/packaging/linux/test-endpoint-scripts.sh b/packaging/linux/test-endpoint-scripts.shindex 3b768fe4..b84f4520 100644--- a/packaging/linux/test-endpoint-scripts.sh+++ b/packaging/linux/test-endpoint-scripts.sh@@ -97,6 +97,32 @@ expect_log_access restricted "BEACON_SERVICE=systemd"run_install BEACON_SERVICE=none BEACON_LOG_ACCESS=restrictedexpect_log_access restricted "BEACON_SERVICE=none asking for restricted"+# The dashboard. A first install defaults to disabled, whatever the service manager; an upgrade+# passes nothing, so the endpoint keeps its setting; BEACON_DASHBOARD decides either way.+expect_dashboard() {+ got="$(flag_value --dashboard)"+ [ "$got" = "$1" ] || fail "$2: --dashboard is '$got', want '$1'"+}+run_install+expect_dashboard disabled "first install"+run_install BEACON_SERVICE=none+expect_dashboard disabled "first install with BEACON_SERVICE=none"+run_install BEACON_DASHBOARD=enabled+expect_dashboard enabled "first install with BEACON_DASHBOARD=enabled"+run_install BEACON_DASHBOARD=' '+expect_dashboard disabled "first install with a blank BEACON_DASHBOARD"+echo '{}' >"$TMP_DIR/etc/config.json"+run_install+has_flag --dashboard && fail "upgrade: passed --dashboard $(flag_value --dashboard); the existing setting must be kept"+run_install BEACON_DASHBOARD=disabled+expect_dashboard disabled "upgrade with BEACON_DASHBOARD=disabled"+rm -f "$TMP_DIR/etc/config.json"+mkdir -p "$TMP_DIR/log"+: >"$TMP_DIR/log/runtime.jsonl"+run_install+has_flag --dashboard && fail "reinstall over a kept log: passed --dashboard $(flag_value --dashboard)"+rm -f "$TMP_DIR/log/runtime.jsonl"+# A runtime log left by `uninstall --keep-logs` is a reinstall: the install keeps the mode recorded# beside it, so no mode is passed.mkdir -p "$TMP_DIR/log"diff --git a/packaging/macos/install-endpoint.sh b/packaging/macos/install-endpoint.shindex 5605b986..14794a50 100755--- a/packaging/macos/install-endpoint.sh+++ b/packaging/macos/install-endpoint.sh@@ -73,7 +73,7 @@ fi# Accounts to add to the beacon-log group of a restricted log, comma-separated. Set, even to nothing,# it is exactly the list: an MDM sets BEACON_LOG_READERS to an empty string so that nobody is ever# added implicitly. Unset, a first install that a person ran in Installer.app adds that person, so-# whoever installed Beacon on their own Mac can use the dashboard, `beacon traces` and `beacon share`+# whoever installed Beacon on their own Mac can use `beacon traces` and `beacon share`# without a second step. Members are only ever added, never removed.if [ -z "${BEACON_LOG_READERS+set}" ]; thenBEACON_LOG_READERS=@@ -82,8 +82,15 @@ if [ -z "${BEACON_LOG_READERS+set}" ]; thenfifi# enabled or disabled: whether any account may run `beacon endpoint dashboard`. Empty keeps what the-# endpoint already has, so a package upgrade never changes it.+# endpoint already has, so a package upgrade never changes it. A first install defaults to disabled,+# for the same reason it defaults to a restricted log: a package is installed by root for the whole+# machine, and the people using that machine should not be able to open a view of its telemetry+# unless the administrator says so. BEACON_DASHBOARD=enabled opts a new install out.BEACON_DASHBOARD="${BEACON_DASHBOARD:-}"+BEACON_DASHBOARD="$(printf '%s' "$BEACON_DASHBOARD" | tr -d '[:space:]')"+if [ -z "$BEACON_DASHBOARD" ] && [ "$first_install" = 1 ]; then+ BEACON_DASHBOARD=disabled+fi# 1 turns the scheduled session sync on and 0 turns it off; empty keeps what the endpoint already# has, so a package upgrade never changes it.BEACON_SESSION_SYNC="${BEACON_SESSION_SYNC:-}"diff --git a/packaging/macos/test-install-settings.sh b/packaging/macos/test-install-settings.shindex ea79d93e..117c1023 100644--- a/packaging/macos/test-install-settings.sh+++ b/packaging/macos/test-install-settings.sh@@ -84,6 +84,28 @@ rm -f "$TMP_DIR/system/runtime.jsonl"run_install BEACON_LOG_ACCESS=sharedexpect --log-access shared "first install with BEACON_LOG_ACCESS=shared"+# The dashboard follows the same rule: disabled on a first install, nothing passed on an upgrade or a+# reinstall over a kept log, and BEACON_DASHBOARD (environment or preferences) decides either way.+run_install+expect --dashboard disabled "first install dashboard"+run_install BEACON_DASHBOARD=enabled+expect --dashboard enabled "first install with BEACON_DASHBOARD=enabled"+echo '{}' >"$TMP_DIR/system/config.json"+run_install+has_flag --dashboard && fail "upgrade passed --dashboard $(flag_value --dashboard)"+run_install BEACON_DASHBOARD=disabled+expect --dashboard disabled "upgrade with BEACON_DASHBOARD=disabled"+rm -f "$TMP_DIR/system/config.json"+: >"$TMP_DIR/system/runtime.jsonl"+run_install+has_flag --dashboard && fail "reinstall over a kept log passed --dashboard $(flag_value --dashboard)"+rm -f "$TMP_DIR/system/runtime.jsonl"+printf 'BEACON_DASHBOARD=enabled\n' >"$MANAGED.plist"+chmod 644 "$MANAGED.plist"+run_install+expect --dashboard enabled "managed BEACON_DASHBOARD=enabled on a first install"+rm -f "$MANAGED.plist"+# Managed preferences are read, win over local ones, and lose to the environment and to arguments.printf 'BEACON_LOG_ACCESS=shared\nBEACON_ENDPOINT_HARNESSES=claude,cursor\nBEACON_SESSION_SYNC=1\n' >"$MANAGED.plist"printf 'BEACON_LOG_ACCESS=restricted\nBEACON_OTLP_GRPC_PORT=6317\n' >"$LOCAL.plist"diff --git a/packaging/windows/install-endpoint.ps1 b/packaging/windows/install-endpoint.ps1index 364792e3..a3fc107e 100644--- a/packaging/windows/install-endpoint.ps1+++ b/packaging/windows/install-endpoint.ps1@@ -110,8 +110,8 @@ if ([string]::IsNullOrWhiteSpace($logAccess) -and $firstInstall -and $windowsSer# Set -- in the environment, or as a policy value, even an empty one -- it is exactly the list: a# fleet sets an empty BEACON_LOG_READERS policy value so that nobody is ever added implicitly. Unset,# a first install that a person ran from the installer's full interface adds the person signed in at-# the console, so whoever installed Beacon on their own machine can use the dashboard, beacon traces-# and beacon share without a second step. A silent install (msiexec /qn, which Intune and SCCM run)+# the console, so whoever installed Beacon on their own machine can use beacon traces and beacon+# share without a second step. A silent install (msiexec /qn, which Intune and SCCM run)# adds nobody. Members are only ever added, never removed.$logReaders = [Environment]::GetEnvironmentVariable('BEACON_LOG_READERS')if ([string]::IsNullOrWhiteSpace($logReaders)) {@@ -132,8 +132,11 @@ if ([string]::IsNullOrWhiteSpace($logReaders)) {}# enabled or disabled: whether any account may run `beacon endpoint dashboard`. Empty keeps what the# endpoint already has, so an upgrade never changes it. The same variable the Linux and macOS install-# scripts read.+# scripts read. A first install defaults to disabled, as it defaults to a restricted log: the MSI is+# installed for the whole machine, and its users should not be able to open a view of its telemetry+# unless the administrator says so. BEACON_DASHBOARD=enabled opts a new install out.$dashboard = Get-BeaconSetting 'BEACON_DASHBOARD' ''+if ([string]::IsNullOrWhiteSpace($dashboard) -and $firstInstall) { $dashboard = 'disabled' }# Auto-detected rather than required, so a manual invocation without BEACON_COLLECTOR still works.# DiscoverBinary would find this on its own -- it is passed explicitly so that a failure says whichdiff --git a/packaging/windows/test-endpoint-scripts.ps1 b/packaging/windows/test-endpoint-scripts.ps1index f4627a84..05ecdf01 100644--- a/packaging/windows/test-endpoint-scripts.ps1+++ b/packaging/windows/test-endpoint-scripts.ps1@@ -79,6 +79,10 @@ if ($wxs -notmatch [regex]::Escape('-UiLevel "[UILevel]"')) {if ($install -notmatch "BEACON_DASHBOARD" -or $install -notmatch [regex]::Escape("'--dashboard'")) {Fail "install-endpoint.ps1 no longer passes BEACON_DASHBOARD on as --dashboard"}+# A first install defaults the dashboard to disabled, whatever the service mode, as on Linux and macOS.+if ($install -notmatch [regex]::Escape("[string]::IsNullOrWhiteSpace(`$dashboard) -and `$firstInstall) { `$dashboard = 'disabled' }")) {+ Fail "install-endpoint.ps1 must default a first install's dashboard to disabled"+}# The step whose absence made the Linux package produce a healthy collector that captured nothing.if ($install -notmatch 'repair-installed') {Fail "install-endpoint.ps1 must configure the interactive user's runtime, or the endpoint captures nothing"