Skip to content

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

Address review: Fleet wrapper settings, automation sudo, Installer.app check

Clauded7822b067d59
diff --git a/CLAUDE.md b/CLAUDE.md
index 64ba87bd..b66659b5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@ Do not recreate or depend on removed `asymptote` mirror trees. Keep new work foc
- Beacon is visibility-first endpoint telemetry for local AI agent runtimes, not a hosted policy service or general endpoint protection product.
- Preserve the local-only default. The public Beacon build must not require a hosted account, remote policy fetch, hosted dashboard, or external network dependency during normal hook execution, and hooks themselves never touch the network.
- `beacon login` is the account-identity channel for interactive users and is required by the interactive `beacon endpoint install` wizard. It uses browser PKCE against beacon.sh and stores the scoped CLI token only in `~/.beacon/auth/session.json` (0600 under a 0700 directory). Signing in alone never starts forwarding. User-mode `beacon endpoint connect` may send that token once to `POST /api/cli/enroll/account` to authorize minting a separate device ingest key, and `beacon mcp token create` may send it to `POST /api/cli/mcp/tokens` (scope `mcp:token:create`, listed on the sign-in page) to mint a personal MCP token that is printed once to stdout and never written to a file, and `beacon share` may send it (scope `traces:write`, also on the sign-in page) to `PUT /v1/traces/{external_id}`, `POST /v1/traces/{external_id}/events/batch` and `GET /v1/traces/{external_id}` on the Beacon API host (`https://api.beacon.sh` for a beacon.sh sign-in, other hosts unchanged, `BEACON_API_URL` overrides) to upload a shared trace the person chose to publish, as a `beacon.trace.v1` summary and its events (`cli/beacon/internal/account/share.go`; a `bcn_api_` API key from `--key` or `BEACON_API_KEY` may stand in for it, precedence `--key`, then a current sign-in carrying the scope, then the environment). These are explicit, user-initiated requests with redirects refused. Hooks, plugins and background jobs never make them, with one exception: the git pre-push hook, only when the person opted in with `beacon git setup --share-sessions` (public needs confirmation), may make the three share requests during a push the person started, within the hook's budget and never failing the push. Never copy the account token into endpoint config, Vector, hook environments, logs, or command output. System/root/package/MDM/CI/piped-stdin/dry-run installs stay noninteractive and account-free.
-- System log access (`beacon endpoint install|repair --system --log-access shared|restricted`; docs in `docs/cli/endpoint-install.mdx#restricted-log-access`). Shared, the CLI default, is the system log as it always was: hooks append to `/var/log/beacon-agent/runtime.jsonl` directly, so it is `0666`. Restricted is opt-in for the CLI and the default for a first package install on every platform (see below; on Linux `packaging/linux/install-endpoint.sh` passes `--log-access restricted` only when neither the system `config.json` nor the runtime log exists, `/proc/1/comm` is systemd and `BEACON_SERVICE` is unset, `auto` or `systemd`; otherwise it passes nothing and the endpoint keeps its mode; `packaging/linux/beacon-settings.sh`, sourced by that script and by the postinstall (which takes only `BEACON_ENDPOINT_HARNESSES`, through `beacon_settings_harnesses` in a subshell, because its user-config step re-runs the CLI as each logged-in user with its environment and must not hand them a Splunk HEC token from the file), reads the `BEACON_*` install settings, never sourcing the file, from a root-owned, not group/other-writable `/etc/default/beacon` or `/etc/sysconfig/beacon` in shell syntax with trailing comments, skipping a malformed value with a warning naming only the key, the last assignment of a key winning within the file, the environment and `install-endpoint.sh`'s positional arguments winning over it; the postinstall prints the `usermod -aG beacon-log` hint for a restricted log; `packaging/linux/test-endpoint-scripts.sh` checks all of it). Restricted makes the root collector the only writer: its `beacon_ingest` extension (`collector-builder/exporter/beaconjsonexporter/beaconingestextension`, appending through the exporter's own `internal/runtimelog`) serves `/var/run/beacon-agent/ingest.sock`, and the hook adapter and the CLI writer, as any account but root writing the system log, hand finished lines to it through `pkg/asymptoteobserve/localingest` (`Deliverer`). The protocol is one batch per connection (`BEACON-INGEST/1`, a header naming the log, one event per line, one JSON reply saying how far it got); the server refuses a batch for any log but its own, identifies the sender only by kernel peer credentials (`SO_PEERCRED`, `LOCAL_PEERCRED`), overwrites the event's `user` with that uid and its resolved name and always derives `event.id` itself (`StampLine` re-encodes, so a sender cannot split or forge lines or reuse another event's id), and bounds connections overall and per uid, batch size, each account's bytes per second, and its own time per connection (shorter than the client's, so it reports how far it got instead of being resent). The client sends only to a socket that root owns in a directory nobody else can write (group-writable ancestors only for gid 0/1, which macOS's `/private/var/run` needs). `Deliverer.Write` sends through the socket when it answers and otherwise appends directly as before; only a direct append refused for permission (a restricted log whose collector is down) spools the line, to the account's private spool for that log (`~/.beacon/endpoint/spool/<log digest>`, 0600 under 0700), and the next line that gets through either way drains it. Root writers and per-user logs always write directly. The mode is `config.json` `log_access`, carried through repair and package upgrades (`BEACON_LOG_ACCESS` in the install scripts). A first install from any package (`.deb`/`.rpm` on systemd hosts, the macOS `.pkg`, the MSI unless `BEACON_SERVICE` names the supervised collector; no system config and no kept log) defaults to restricted in its install script, and adds to `beacon-log` (`--log-readers`, `loggroup.AddMember`: gpasswd/addgroup, dseditgroup, net.exe; add-only, failures reported not fatal; `validAccount` also admits spaces, an apostrophe and non-ASCII letters on Windows, because OOBE names local accounts from what the person typed) exactly `BEACON_LOG_READERS` when set, even empty, else only a person who installed interactively (Linux `SUDO_USER`; macOS Installer.app without `COMMAND_LINE_INSTALL`; Windows MSI `UILevel` >= 4 via the custom action's `-UiLevel`), never an unattended fleet install. Fleet tooling sets the `BEACON_*` install settings where it writes settings: `/etc/default/beacon`/`/etc/sysconfig/beacon` (`packaging/linux/beacon-settings.sh`), managed or local preferences for `com.beacon.endpoint` (`packaging/macos/beacon-settings.sh`), `HKLM\SOFTWARE\Policies\Beacon\Endpoint` (`install-endpoint.ps1`); each read only when root/admin-controlled, environment wins; docs in `docs/security/restricted-log-access.mdx#package-installs`. Install creates the `beacon-log` group (`internal/endpoint/loggroup`, getent/groupadd, dscl/dseditgroup) and `writer.RestrictSystemLog` makes the directory `root:beacon-log 02750`, the log and archives `0640` and the lock root-only `0600`, after writing the root-owned `.beacon-log-access` marker beside the log; a shared log is not narrowed in place but copied to fresh root-created files and renamed over, under its lock (bounded wait), because a descriptor opened while it was 0666 survives any chmod. A failed install restores the previous mode in its rollback, and a shared install removes a dead socket. The marker is what tells every root writer (`asymptoteobserve.RuntimeLogModes`) to keep the restricted modes. The OTLP receivers on loopback are not covered by the socket: any local process can still send OTLP. On Linux those events are attributed to the account that owns the sending socket (peer attribution, below), which names the sender but does not stop an account sending what it likes under its own name; elsewhere they are unattributed, so never claim more than that. Doctor's `runtime_log_access` covers the marker, the socket and pending spool. Unix sockets are local IPC, not a network channel, so the hooks-never-touch-the-network rule holds. On Windows the same mode runs over the named pipe `\\.\pipe\beacon-agent-ingest` (`localingest` `transport_windows.go`, go-winio): the collector creates it as the first instance, and when the name is taken (any account may create one) it reports a recoverable error and retries every few seconds rather than failing, so the rest of the collector stays up; it rejects remote clients and its DACL denies NETWORK and withholds `FILE_CREATE_PIPE_INSTANCE` from ordinary accounts, so it is not a network channel either; a client connects at identification level and sends only to a pipe owned by SYSTEM or Administrators; the server counts a connection against its account from the client process's token before reading and stamps the SID it reads by `ImpersonateNamedPipeClient` after the preamble (they must agree), with `Peer.UID` a string (decimal uid on Unix, SID on Windows) and the name from `LookupAccountSid`, bounded. Privileged writers there are SYSTEM and tokens with Administrators enabled (`CheckTokenMembership`; elevation for another group is not enough). The directory gets `sysacl.RestrictedLogDirDACL` (protected: SYSTEM and Administrators full, `beacon-log` local group read, nothing else; the lock SYSTEM and Administrators only) and everything below it is reset, because every account may bypass traverse checking; `writer.RestrictSystemLog` replaces every file directly in the directory (the log family under the lock; files outside it with another hard link are skipped) with a copy created with its final owner and DACL (`sysacl.CreateRestrictedFile`) and a POSIX-semantics rename, fails naming any file held open without sharing delete and then puts a log that was shared back to shared, and writes the marker last (on Windows it decides nothing for root writers, so a failed or killed run is not mistaken for a finished one). The marker counts there when SYSTEM or Administrators own it and no other account can write it. `loggroup` creates the local group with `net.exe` and looks it up qualified with the computer name. Doctor reads the restricted ACL (`writer.CheckRestrictedSystemLogACL`). `packaging/windows/smoke-restricted-log.ps1` runs in `windows-package-smoke` against the installed MSI with a real ordinary account. Hook and writer tests point `logging.EndpointIngest`/`writer.Ingest` at sockets of their own.
+- System log access (`beacon endpoint install|repair --system --log-access shared|restricted`; docs in `docs/cli/endpoint-install.mdx#restricted-log-access`). Shared, the CLI default, is the system log as it always was: hooks append to `/var/log/beacon-agent/runtime.jsonl` directly, so it is `0666`. Restricted is opt-in for the CLI and the default for a first package install on every platform (see below; on Linux `packaging/linux/install-endpoint.sh` passes `--log-access restricted` only when neither the system `config.json` nor the runtime log exists, `/proc/1/comm` is systemd and `BEACON_SERVICE` is unset, `auto` or `systemd`; otherwise it passes nothing and the endpoint keeps its mode; `packaging/linux/beacon-settings.sh`, sourced by that script and by the postinstall (which takes only `BEACON_ENDPOINT_HARNESSES`, through `beacon_settings_harnesses` in a subshell, because its user-config step re-runs the CLI as each logged-in user with its environment and must not hand them a Splunk HEC token from the file), reads the `BEACON_*` install settings, never sourcing the file, from a root-owned, not group/other-writable `/etc/default/beacon` or `/etc/sysconfig/beacon` in shell syntax with trailing comments, skipping a malformed value with a warning naming only the key, the last assignment of a key winning within the file, the environment and `install-endpoint.sh`'s positional arguments winning over it; the postinstall prints the `usermod -aG beacon-log` hint for a restricted log; `packaging/linux/test-endpoint-scripts.sh` checks all of it). Restricted makes the root collector the only writer: its `beacon_ingest` extension (`collector-builder/exporter/beaconjsonexporter/beaconingestextension`, appending through the exporter's own `internal/runtimelog`) serves `/var/run/beacon-agent/ingest.sock`, and the hook adapter and the CLI writer, as any account but root writing the system log, hand finished lines to it through `pkg/asymptoteobserve/localingest` (`Deliverer`). The protocol is one batch per connection (`BEACON-INGEST/1`, a header naming the log, one event per line, one JSON reply saying how far it got); the server refuses a batch for any log but its own, identifies the sender only by kernel peer credentials (`SO_PEERCRED`, `LOCAL_PEERCRED`), overwrites the event's `user` with that uid and its resolved name and always derives `event.id` itself (`StampLine` re-encodes, so a sender cannot split or forge lines or reuse another event's id), and bounds connections overall and per uid, batch size, each account's bytes per second, and its own time per connection (shorter than the client's, so it reports how far it got instead of being resent). The client sends only to a socket that root owns in a directory nobody else can write (group-writable ancestors only for gid 0/1, which macOS's `/private/var/run` needs). `Deliverer.Write` sends through the socket when it answers and otherwise appends directly as before; only a direct append refused for permission (a restricted log whose collector is down) spools the line, to the account's private spool for that log (`~/.beacon/endpoint/spool/<log digest>`, 0600 under 0700), and the next line that gets through either way drains it. Root writers and per-user logs always write directly. The mode is `config.json` `log_access`, carried through repair and package upgrades (`BEACON_LOG_ACCESS` in the install scripts). A first install from any package (`.deb`/`.rpm` on systemd hosts, the macOS `.pkg`, the MSI unless `BEACON_SERVICE` names the supervised collector; no system config and no kept log) defaults to restricted in its install script, and adds to `beacon-log` (`--log-readers`, `loggroup.AddMember`: gpasswd/addgroup, dseditgroup, net.exe; add-only, failures reported not fatal; `validAccount` also admits spaces, an apostrophe and non-ASCII letters on Windows, because OOBE names local accounts from what the person typed) exactly `BEACON_LOG_READERS` when set, even empty, else only a person who installed interactively (Linux `SUDO_USER` with a terminal on stdin and not `DEBIAN_FRONTEND=noninteractive`, because Ansible `become` and Packer sudo set `SUDO_USER` too; macOS without `COMMAND_LINE_INSTALL` and with an `Installer` process of the console user whose lsof `txt` executable is Apple's `/System/Library/CoreServices/Installer.app`, never a bare process name; Windows MSI `UILevel` >= 4 via the custom action's `-UiLevel`), never an unattended fleet install. In both shell settings parsers an environment variable set to an empty string counts as unset (except `BEACON_LOG_READERS`, where empty means nobody), and the macOS Fleet wrapper (`packaging/macos/fleet/scripts/install.sh`) passes only arguments it was given, so neither hides the settings file or managed preferences. Fleet tooling sets the `BEACON_*` install settings where it writes settings: `/etc/default/beacon`/`/etc/sysconfig/beacon` (`packaging/linux/beacon-settings.sh`), managed or local preferences for `com.beacon.endpoint` (`packaging/macos/beacon-settings.sh`), `HKLM\SOFTWARE\Policies\Beacon\Endpoint` (`install-endpoint.ps1`); each read only when root/admin-controlled, environment wins; docs in `docs/security/restricted-log-access.mdx#package-installs`. Install creates the `beacon-log` group (`internal/endpoint/loggroup`, getent/groupadd, dscl/dseditgroup) and `writer.RestrictSystemLog` makes the directory `root:beacon-log 02750`, the log and archives `0640` and the lock root-only `0600`, after writing the root-owned `.beacon-log-access` marker beside the log; a shared log is not narrowed in place but copied to fresh root-created files and renamed over, under its lock (bounded wait), because a descriptor opened while it was 0666 survives any chmod. A failed install restores the previous mode in its rollback, and a shared install removes a dead socket. The marker is what tells every root writer (`asymptoteobserve.RuntimeLogModes`) to keep the restricted modes. The OTLP receivers on loopback are not covered by the socket: any local process can still send OTLP. On Linux those events are attributed to the account that owns the sending socket (peer attribution, below), which names the sender but does not stop an account sending what it likes under its own name; elsewhere they are unattributed, so never claim more than that. Doctor's `runtime_log_access` covers the marker, the socket and pending spool. Unix sockets are local IPC, not a network channel, so the hooks-never-touch-the-network rule holds. On Windows the same mode runs over the named pipe `\\.\pipe\beacon-agent-ingest` (`localingest` `transport_windows.go`, go-winio): the collector creates it as the first instance, and when the name is taken (any account may create one) it reports a recoverable error and retries every few seconds rather than failing, so the rest of the collector stays up; it rejects remote clients and its DACL denies NETWORK and withholds `FILE_CREATE_PIPE_INSTANCE` from ordinary accounts, so it is not a network channel either; a client connects at identification level and sends only to a pipe owned by SYSTEM or Administrators; the server counts a connection against its account from the client process's token before reading and stamps the SID it reads by `ImpersonateNamedPipeClient` after the preamble (they must agree), with `Peer.UID` a string (decimal uid on Unix, SID on Windows) and the name from `LookupAccountSid`, bounded. Privileged writers there are SYSTEM and tokens with Administrators enabled (`CheckTokenMembership`; elevation for another group is not enough). The directory gets `sysacl.RestrictedLogDirDACL` (protected: SYSTEM and Administrators full, `beacon-log` local group read, nothing else; the lock SYSTEM and Administrators only) and everything below it is reset, because every account may bypass traverse checking; `writer.RestrictSystemLog` replaces every file directly in the directory (the log family under the lock; files outside it with another hard link are skipped) with a copy created with its final owner and DACL (`sysacl.CreateRestrictedFile`) and a POSIX-semantics rename, fails naming any file held open without sharing delete and then puts a log that was shared back to shared, and writes the marker last (on Windows it decides nothing for root writers, so a failed or killed run is not mistaken for a finished one). The marker counts there when SYSTEM or Administrators own it and no other account can write it. `loggroup` creates the local group with `net.exe` and looks it up qualified with the computer name. Doctor reads the restricted ACL (`writer.CheckRestrictedSystemLogACL`). `packaging/windows/smoke-restricted-log.ps1` runs in `windows-package-smoke` against the installed MSI with a real ordinary account. Hook and writer tests point `logging.EndpointIngest`/`writer.Ingest` at sockets of their own.
- Beacon Cloud forwarding (`cli/beacon/internal/endpoint/asymptote`, `beacon endpoint connect`, `beacon endpoint asymptote`) is Vector-shaped: Beacon writes local JSONL, Vector ships runtime lines only from the connection point forward and reads inventory from the beginning to establish the endpoint's current baseline, plus the one bounded exception of the session backfill (below), and the `bcn_device_*` key stays only in `<BaseDir>/asymptote/vector-secrets.json` via Vector's secret backend. The onboarding wizard preselects Beacon Cloud, and confirming it connects this endpoint in the same command once the local install has succeeded; an endpoint that is already enrolled is never re-enrolled, because enrollment rotates the device key. Standard mode ships locally sanitized retained content; metadata-only uses local Vector transforms to remove prompts, responses, reasoning, tool arguments/results, tool descriptions/definitions, retrieval queries/documents, evaluation explanations, agent descriptions, stop sequences, approval/policy reasons, command output, raw fields, diffs, inventory content, and MCP definitions before buffering/upload. Every text-shaped event field must be classified in `metadata_fields_test.go` (`metadataOnlyRemoved`, each with its own `del()` in `pack/metadata-transforms.toml`, or `metadataOnlyKept`); a new field fails that test until it is, and `BEACON_TEST_VECTOR_BIN` runs the transform on an event with every field set. `vector.toml` is not rendered only at connect: `asymptote.ReconcileForwarder` re-renders it in place for a connected endpoint from the current pack with the enrollment's ingest URL and recorded privacy mode, validates it with the forwarder's own Vector exactly as connect does, atomically replaces it, and, when run from install, repair, the package upgrade or the hidden reconcile the macOS postinstall runs (`ReconcileOptions.Restart`), restarts a running forwarder even when nothing changed (after `vector validate` of the current config with the forwarder's own Vector, and never after a warning, so a refused config or a missing Vector leaves the running forwarder alone), as the Sentinel reconcile does: switching to restricted log access replaces the runtime log with a copy, and Vector, which recognizes a file by its first line, keeps tailing the replaced one until it restarts; an upgrade may also have installed a new Vector. A stopped one is never started and reads the new config when it next starts. The `beacon_runtime` source reads `runtime.jsonl.1` too, as the Sentinel pack does, so lines written to a replaced log before a restart are found again at the next rotation instead of lost. It never enrolls, reads or rewrites the secrets file, makes a network request, or touches `vector-data/` (checkpoints stay, so pack changes must keep source ids and fingerprinting stable), and a rejected config is a warning that keeps the old one; it is a no-op when not connected, after an incomplete connect, without an installed unit, or where `ForwarderManager` is unsupported (supervised mode). `lifecycle.Install` runs it last when services are started (so install, repair and the Linux package upgrade), repair's teardown keeps the forwarder (`UninstallOptions.KeepManagedIngest`) instead of disconnecting it, and the macOS postinstall, which installs with `--no-start`, runs the hidden `beacon endpoint asymptote reconcile --system`. Keep the ingest URL `https://`, the wire contract aligned with `beacon-ingest` (`/v1/ingest/{runtime,inventory}` and `/v1/ingest/health`), and do not add another endpoint network channel. The cloud-sandbox shuttle is the bounded exception: only with `BEACON_ORIGIN=cloud`, it can upload new runtime lines to GCS, S3, or the same Beacon ingest contract because no Vector/service manager/browser/persistent disk exists there.
- Session backfill (`cli/beacon/cmd/endpoint_backfill.go`; docs in `docs/cli/endpoint-install.mdx#session-backfill` and `docs/cli/endpoint-connect.mdx#session-backfill`): after every successful install (user or system mode), every session-store collector runs once with `CollectOptions.Since` (30 days; `sessionwindow.Recent` keeps those sessions, newest first, and never touches the cursors of the rest) and a shared `writer.Budget` (24 MiB, at most 12 MiB per runtime through `Budget.Sub`; a refused append returns `writer.ErrBudgetSpent`, the collector stops with cursors past only what was written, and a manual sync reads the rest). A new session-store collector takes both fields, reads its store only through `internal/sessionfs` (a test parses every collector package to enforce it), and joins `endpointBackfillRunners` and that test's list. Every connect, first or re-connect, user or system, runs the same sweep before enrollment (skipped when install just ran it) and, before the forwarder starts, `asymptote.StageBackfill` copies the window's `harness.collection_method=poll` lines into `cloud-backfill.jsonl` beside the runtime log, which the `beacon_backfill` Vector source (fingerprinted `device_and_inode`, so each atomically restaged copy is a new file) reads from the beginning into the runtime sink through the same privacy transform. Live hook/OTLP/plugin history before the connection point stays local. Re-connects restage, so a resend of already-shipped lines is expected and rests on the deterministic `event.id`; a privacy-mode change clears the checkpoints and the restage renames the new-mode copy over the old one (kept until then so the copy is always a new inode; deleted instead when nothing restages), and `disconnect` removes it. System mode runs the collectors under `withUserHome` for the active console user (`activeConsoleUser`), with cursors under the system base directory, and reports a skip when nobody is logged in; root is reading a home the console user controls, so the sweep runs under `sessionfs.Confine` (an `os.Root` on that home, files owned by the home's owner only, non-blocking opens that refuse FIFOs/devices, SQLite read from a private snapshot under `<SystemBaseDir>/state/backfill-snapshots`, retried until the database size/change counter and WAL header are unchanged across the copy, and refused past `sessionfs.MaxSnapshotBytes` (512 MiB with its WAL) with the runtime's sync command named in the report), and refused paths read as absent and are listed in the report. User-mode sync and backfill stay unconfined. The wizard's confirm screen names the upload (`WizardOptions.BackfillDays`). Dry-run, `--no-backfill` and `BEACON_BACKFILL=0` skip all of it; the cmd tests run with `BEACON_BACKFILL=0` set in `TestMain`.
- `beacon endpoint install` has a full-screen onboarding wizard on interactive user TTYs. It signs in, preselects Beacon Cloud, requires an explicit choice to opt out to Local, and asks Managed users to choose Standard or Metadata-only privacy. Signing in alone still moves no telemetry. Confirming Beacon Cloud does: the confirm screen states that it installs Beacon and starts forwarding, and names what the selected privacy mode sends, so that screen is the consent point. The managed destination is recorded only after enrollment succeeds, so a failed enrollment leaves a working local install, prints `beacon endpoint connect` as the retry, and re-offers the question on the next install. The onboarding record is written only after `lifecycle.Install` returns, because a profile written first left a failed install looking onboarded and silently skipped the wizard on the retry. Explicit `install --connect` is unchanged. The wizard is skipped for system/root/CI/piped-stdin/dry-run or `BEACON_ONBOARDING=0`; those unattended paths must never gain an account or browser dependency. Legacy `BEACON_ONBOARDING_EMAIL`/`USAGE` submissions remain only for fleet compatibility. After the destination, the wizard shows an agent tools screen; every row is preselected (opt-out, space toggles). Beacon Cloud MCP is offered only with Beacon Cloud and runs the `beacon mcp connect` flow (`connectCloudMCP` with `yes`, OAuth, detected harnesses) only after the endpoint is connected (or already was), via `finishCloudSetup`; a failed enrollment skips it and names the retry. The Beacon Agent Skills are offered for either destination and installed user-wide into `~/.agents/skills` and, when Claude Code is set up, `~/.claude/skills` (`cli/beacon/internal/agentskills`, `beacon skills install|uninstall`; a `.beacon-managed` marker decides what Beacon may replace or remove; install and repair refresh only copies Beacon already wrote). Both run after `lifecycle.Install` returns and warn rather than fail. The answers are recorded as `onboarding.cloud_mcp`/`agent_skills`. Implementation lives in `cli/beacon/internal/onboarding`, `cli/beacon/cmd/endpoint_onboarding.go`, `cli/beacon/cmd/endpoint_install.go` and `cli/beacon/cmd/agent_tools.go`; keep `docs/cli/endpoint-onboarding.mdx` and `docs/cli/skills.mdx` in sync.
diff --git a/docs/security/restricted-log-access.mdx b/docs/security/restricted-log-access.mdx
index d149c0a0..d1ab38ec 100644
--- a/docs/security/restricted-log-access.mdx
+++ b/docs/security/restricted-log-access.mdx
@@ -75,8 +75,8 @@ 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`. 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`. macOS: Installer.app. Windows: the installer's full interface | That person, so the dashboard, `beacon traces` and `beacon share` work for them after they log in again |
+| 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 |
| 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`.
@@ -89,7 +89,7 @@ Set `BEACON_LOG_READERS` to an empty value in a fleet's settings so that nobody
| macOS | Managed preferences for the domain `com.beacon.endpoint` (a configuration profile), or `/Library/Preferences/com.beacon.endpoint`; see [Settings for MDM installs](/platforms/macos#settings-for-mdm-installs) | Jamf, Kandji, Intune, or `sudo defaults write` |
| Windows | String values under `HKLM\SOFTWARE\Policies\Beacon\Endpoint`; see [Settings for fleet installs](/platforms/windows#settings-for-fleet-installs) | Intune, Group Policy, SCCM |
-Each is read only when root (SYSTEM or Administrators on Windows) controls it, and a value set in the install script's environment wins over it.
+Each is read only when root (SYSTEM or Administrators on Windows) controls it, and a value set in the install script's environment wins over it. On Linux and macOS a variable set to an empty value counts as not set, so a wrapper that passes every variable, such as the Fleet install script, does not hide the settings file or profile; `BEACON_LOG_READERS` is the exception, where empty means nobody.
## On Windows
diff --git a/packaging/linux/beacon-settings.sh b/packaging/linux/beacon-settings.sh
index 0c1be889..e9e45c7e 100644
--- a/packaging/linux/beacon-settings.sh
+++ b/packaging/linux/beacon-settings.sh
@@ -15,9 +15,10 @@
# single or double quotes, whole-line and trailing `# comments`), so nothing in it runs. A value with
# anything else left over (an unquoted space, an unterminated quote) is skipped with a warning rather
# than passed on. The file is ignored unless root owns it and no one else can write it, because the
-# package scripts run as root. A variable already set in the environment wins over the file; within
-# the file, a later assignment of a key replaces an earlier one, as it would for a shell, because a
-# configuration manager often overrides a setting by appending a line.
+# package scripts run as root. A variable already set in the environment to a non-empty value (or
+# BEACON_LOG_READERS set at all, even empty) wins over the file; within the file, a later assignment
+# of a key replaces an earlier one, as it would for a shell, because a configuration manager often
+# overrides a setting by appending a line.
# The documented install settings, the only keys taken from the file.
BEACON_SETTINGS_KEYS='BEACON_ENDPOINT_HARNESSES BEACON_OTLP_GRPC_PORT BEACON_OTLP_HTTP_PORT
@@ -112,7 +113,14 @@ beacon_load_settings() {
for _beacon_key in $BEACON_SETTINGS_KEYS; do
_beacon_known="$_beacon_known$_beacon_key "
# $_beacon_key is one of the fixed names above, so the indirection cannot evaluate anything else.
- eval "_beacon_set=\${$_beacon_key+set}"
+ # A variable set to an empty string counts as unset, as on macOS, so a wrapper that passes every
+ # variable never shadows the file with empty ones; BEACON_LOG_READERS is the exception, because
+ # empty there is a value of its own (nobody is added).
+ if [ "$_beacon_key" = BEACON_LOG_READERS ]; then
+ eval "_beacon_set=\${$_beacon_key+set}"
+ else
+ eval "_beacon_set=\${$_beacon_key:+set}"
+ fi
if [ -n "$_beacon_set" ]; then
_beacon_preset="$_beacon_preset$_beacon_key "
fi
diff --git a/packaging/linux/install-endpoint.sh b/packaging/linux/install-endpoint.sh
index 7cb291b6..bcdcc1ed 100755
--- a/packaging/linux/install-endpoint.sh
+++ b/packaging/linux/install-endpoint.sh
@@ -80,16 +80,31 @@ if [ -z "$BEACON_LOG_ACCESS" ] && [ "$first_install" = 1 ]; then
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 unattended fleet install sets BEACON_LOG_READERS= so that nobody
-# is ever added implicitly. Unset, a first install that a person ran with sudo (`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 configuration manager runs
-# as root with no SUDO_USER, so its installs add nobody. Members are only ever added, never removed.
+# 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
+# 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 terminal on standard input and not run under
+# DEBIAN_FRONTEND=noninteractive, which Ansible's apt module sets. Otherwise nobody is added, and the
+# postinstall prints how to add someone. Members are only ever added, never removed.
+#
+# beacon_person_at_terminal succeeds when a person is running this install interactively.
+# BEACON_INSTALL_TTY=1|0 lets the packaging tests, which run without a terminal, say either way.
+beacon_person_at_terminal() {
+ [ "${DEBIAN_FRONTEND:-}" != noninteractive ] || return 1
+ case "${BEACON_INSTALL_TTY:-}" in
+ 1) return 0 ;;
+ 0) return 1 ;;
+ esac
+ [ -t 0 ]
+}
if [ -z "${BEACON_LOG_READERS+set}" ]; then
BEACON_LOG_READERS=
if [ "$first_install" = 1 ] && [ "$BEACON_LOG_ACCESS" = restricted ]; then
case "${SUDO_USER:-}" in
''|root) ;;
- *) BEACON_LOG_READERS="$SUDO_USER" ;;
+ *) beacon_person_at_terminal && BEACON_LOG_READERS="$SUDO_USER" ;;
esac
fi
fi
diff --git a/packaging/linux/test-endpoint-scripts.sh b/packaging/linux/test-endpoint-scripts.sh
index bb8823de..29caa13c 100644
--- a/packaging/linux/test-endpoint-scripts.sh
+++ b/packaging/linux/test-endpoint-scripts.sh
@@ -210,6 +210,11 @@ INSTALL_ARGS='claude,codex,cursor'
run_install BEACON_DEFAULTS_FILE="$DEFAULTS" BEACON_ENDPOINT_HARNESSES=codex
INSTALL_ARGS=''
[ "$(flag_value --harness)" = "codex" ] || fail "environment over positional: --harness is '$(flag_value --harness)'"
+# A variable set to an empty string is unset as far as the file is concerned: a wrapper that passes
+# every variable must not shadow the file with empty ones.
+run_install BEACON_DEFAULTS_FILE="$DEFAULTS" BEACON_ENDPOINT_HARNESSES= BEACON_OTLP_HTTP_PORT=
+[ "$(flag_value --harness)" = "claude" ] || fail "empty environment variable shadowed the file: --harness is '$(flag_value --harness)'"
+[ "$(flag_value --otlp-http-port)" = "5318" ] || fail "empty environment variable shadowed the file: --otlp-http-port is '$(flag_value --otlp-http-port)'"
# A key assigned twice takes its last value, as a shell would: configuration managers override a
# setting by appending a line. The environment still wins over every one of them.
@@ -259,18 +264,28 @@ expect_readers() {
rm -f "$DEFAULTS"
run_install
has_flag --log-readers && fail "configuration-manager install (no SUDO_USER) passed --log-readers $(flag_value --log-readers)"
-run_install SUDO_USER=alice
+run_install SUDO_USER=alice BEACON_INSTALL_TTY=1
expect_readers alice "first install by sudo"
-run_install SUDO_USER=root
+# sudo also sets SUDO_USER for automation (Ansible become, a Packer sudo provisioner), which has no
+# terminal: its login account must not be added.
+run_install SUDO_USER=deploy BEACON_INSTALL_TTY=0
+has_flag --log-readers && fail "sudo install without a terminal added $(flag_value --log-readers)"
+run_install SUDO_USER=deploy
+has_flag --log-readers && fail "sudo install with no terminal on stdin added $(flag_value --log-readers)"
+run_install SUDO_USER=deploy BEACON_INSTALL_TTY=1 DEBIAN_FRONTEND=noninteractive
+has_flag --log-readers && fail "DEBIAN_FRONTEND=noninteractive install added $(flag_value --log-readers)"
+run_install SUDO_USER=deploy BEACON_INSTALL_TTY=0 BEACON_LOG_READERS=svc_splunk
+expect_readers svc_splunk "explicit BEACON_LOG_READERS without a terminal"
+run_install SUDO_USER=root BEACON_INSTALL_TTY=1
has_flag --log-readers && fail "SUDO_USER=root added root as a reader"
-run_install SUDO_USER=alice BEACON_LOG_ACCESS=shared
+run_install SUDO_USER=alice BEACON_INSTALL_TTY=1 BEACON_LOG_ACCESS=shared
has_flag --log-readers && fail "shared first install by sudo passed --log-readers"
-run_install SUDO_USER=alice BEACON_LOG_READERS=
+run_install SUDO_USER=alice BEACON_INSTALL_TTY=1 BEACON_LOG_READERS=
has_flag --log-readers && fail "BEACON_LOG_READERS= (nobody) still added the sudo user"
run_install SUDO_USER=alice BEACON_LOG_READERS=svc_splunk,bob
expect_readers svc_splunk,bob "BEACON_LOG_READERS over the sudo user"
printf 'BEACON_LOG_READERS= # fleet: nobody implicitly\n' >"$DEFAULTS"
-run_install BEACON_DEFAULTS_FILE="$DEFAULTS" SUDO_USER=alice
+run_install BEACON_DEFAULTS_FILE="$DEFAULTS" SUDO_USER=alice BEACON_INSTALL_TTY=1
has_flag --log-readers && fail "defaults file BEACON_LOG_READERS= still added the sudo user"
printf 'BEACON_LOG_READERS=svc_splunk\n' >"$DEFAULTS"
run_install BEACON_DEFAULTS_FILE="$DEFAULTS"
@@ -278,7 +293,7 @@ expect_readers svc_splunk "defaults file BEACON_LOG_READERS"
rm -f "$DEFAULTS"
mkdir -p "$TMP_DIR/etc"
echo '{}' >"$TMP_DIR/etc/config.json"
-run_install SUDO_USER=alice
+run_install SUDO_USER=alice BEACON_INSTALL_TTY=1
has_flag --log-readers && fail "upgrade by sudo added the sudo user implicitly"
run_install SUDO_USER=alice BEACON_LOG_READERS=svc_splunk
expect_readers svc_splunk "upgrade with explicit BEACON_LOG_READERS"
diff --git a/packaging/macos/beacon-settings.sh b/packaging/macos/beacon-settings.sh
index e7b7f921..302534f8 100644
--- a/packaging/macos/beacon-settings.sh
+++ b/packaging/macos/beacon-settings.sh
@@ -15,7 +15,7 @@
# sudo defaults write /Library/Preferences/com.beacon.endpoint BEACON_LOG_ACCESS restricted
#
# Managed preferences win over local ones, and a variable already set in the environment wins over
-# both. Only the documented install settings are read, one key at a time with `defaults read`, so
+# both (a variable set to an empty string counts as unset, except BEACON_LOG_READERS). Only the documented install settings are read, one key at a time with `defaults read`, so
# nothing in the files runs. A file is ignored unless root owns it and no one else can write it,
# because the package scripts run as root. A value that is not a single line (an array or a
# dictionary) is skipped with a warning naming only its key.
@@ -46,13 +46,22 @@ beacon_prefs_trusted() {
beacon_load_settings() {
_beacon_defaults="${BEACON_DEFAULTS_BIN:-/usr/bin/defaults}"
[ -x "$_beacon_defaults" ] || return 0
- # Which settings are already set is decided once, before any file is read.
+ # Which settings are already set is decided once, before any file is read. A variable set to an
+ # empty string counts as unset, because wrappers (the Fleet install script, a Jamf policy with an
+ # empty parameter) pass every variable whether or not they were given a value, and an empty one
+ # must not shadow the profile. The exception is BEACON_LOG_READERS, where empty is a value of its
+ # own: nobody is added.
_beacon_preset=' '
for _beacon_key in $BEACON_SETTINGS_KEYS; do
# $_beacon_key is one of the fixed names above, so the indirection cannot evaluate anything else.
- eval "_beacon_set=\${$_beacon_key+set}"
+ if [ "$_beacon_key" = BEACON_LOG_READERS ]; then
+ eval "_beacon_set=\${$_beacon_key+set}"
+ else
+ eval "_beacon_set=\${$_beacon_key:+set}"
+ fi
[ -n "$_beacon_set" ] && _beacon_preset="$_beacon_preset$_beacon_key "
done
+ _beacon_taken=' '
for _beacon_prefs in "${BEACON_MANAGED_PREFS:-/Library/Managed Preferences/com.beacon.endpoint}" \
"${BEACON_LOCAL_PREFS:-/Library/Preferences/com.beacon.endpoint}"; do
[ -f "$_beacon_prefs.plist" ] || continue
@@ -65,8 +74,9 @@ beacon_load_settings() {
*" $_beacon_key "*) continue ;;
esac
# Taken from the first file that has it: managed preferences shadow local ones.
- eval "_beacon_set=\${$_beacon_key+set}"
- [ -n "$_beacon_set" ] && continue
+ case "$_beacon_taken" in
+ *" $_beacon_key "*) continue ;;
+ esac
_beacon_value="$("$_beacon_defaults" read "$_beacon_prefs" "$_beacon_key" 2>/dev/null)" || continue
case "$_beacon_value" in
*"
@@ -77,6 +87,7 @@ beacon_load_settings() {
;;
esac
export "$_beacon_key=$_beacon_value"
+ _beacon_taken="$_beacon_taken$_beacon_key "
done
done
}
@@ -91,21 +102,45 @@ beacon_settings_harnesses() {
)
}
+# beacon_installer_app_running CONSOLE succeeds when Apple's Installer.app is running as CONSOLE.
+#
+# A process name proves nothing: any account can start a program called Installer. So each Installer
+# process the console user owns is checked by the executable the kernel says it runs (its `txt`
+# mapping in lsof, which comes from the vnode, not from anything the process chose), and only Apple's
+# /System/Library/CoreServices/Installer.app on the sealed system volume counts.
+beacon_installer_app_running() {
+ _beacon_pgrep="${BEACON_PGREP_BIN:-/usr/bin/pgrep}"
+ _beacon_lsof="${BEACON_LSOF_BIN:-/usr/sbin/lsof}"
+ [ -x "$_beacon_pgrep" ] && [ -x "$_beacon_lsof" ] || return 1
+ for _beacon_pid in $("$_beacon_pgrep" -x -u "$1" Installer 2>/dev/null); do
+ case "$_beacon_pid" in
+ ''|*[!0-9]*) continue ;;
+ esac
+ # -Fn prints one `n<path>` line per file; the first txt file is the program itself.
+ _beacon_exe="$("$_beacon_lsof" -a -p "$_beacon_pid" -d txt -Fn 2>/dev/null | sed -n 's/^n//p' | head -n 1)"
+ [ "$_beacon_exe" = /System/Library/CoreServices/Installer.app/Contents/MacOS/Installer ] && return 0
+ done
+ return 1
+}
+
# beacon_installing_person prints the account of the person who ran this install in Installer.app,
# or nothing for an unattended install. `installer` (which MDM agents and scripts run) sets
# COMMAND_LINE_INSTALL; a person double-clicking the package does it in Installer.app, the console
-# user's own session. Both must hold, so an MDM install that happens while someone is logged in adds
-# nobody.
+# user's own session, which beacon_installer_app_running checks by the executable rather than by a
+# process name. Both must hold, so an MDM install that happens while someone is logged in adds
+# nobody. MDM InstallApplication never sets COMMAND_LINE_INSTALL, so a fleet that does not want even
+# that check deciding sets BEACON_LOG_READERS to an empty string in its profile.
beacon_installing_person() {
[ -z "${COMMAND_LINE_INSTALL:-}" ] || return 0
+ _beacon_console="${BEACON_CONSOLE_USER:-$(stat -f '%Su' /dev/console 2>/dev/null || true)}"
+ case "$_beacon_console" in
+ ''|root|loginwindow|_mbsetupuser|-*) return 0 ;;
+ esac
+ # BEACON_INSTALLER_GUI=1|0 lets the packaging tests, which have no Installer.app, say either way.
_beacon_gui="${BEACON_INSTALLER_GUI:-}"
if [ -z "$_beacon_gui" ]; then
- if /usr/bin/pgrep -x Installer >/dev/null 2>&1; then _beacon_gui=1; else _beacon_gui=0; fi
+ if beacon_installer_app_running "$_beacon_console"; then _beacon_gui=1; else _beacon_gui=0; fi
fi
[ "$_beacon_gui" = 1 ] || return 0
- _beacon_console="${BEACON_CONSOLE_USER:-$(stat -f '%Su' /dev/console 2>/dev/null || true)}"
- case "$_beacon_console" in
- ''|root|loginwindow|_mbsetupuser) return 0 ;;
- esac
printf '%s' "$_beacon_console"
}
diff --git a/packaging/macos/fleet/scripts/install.sh b/packaging/macos/fleet/scripts/install.sh
index 70c65db3..fcab88b6 100755
--- a/packaging/macos/fleet/scripts/install.sh
+++ b/packaging/macos/fleet/scripts/install.sh
@@ -1,28 +1,37 @@
#!/bin/sh
set -eu
+# Fleet's install wrapper: positional arguments ($1 harnesses, $2/$3 OTLP gRPC/HTTP ports, $4
+# collector, $5 no-start, $6-$12 Splunk HEC endpoint, token, index, source, sourcetype,
+# insecure-skip-verify, CA file) become the BEACON_* variables install-endpoint.sh reads.
+#
+# Only values this wrapper was actually given are passed on. install-endpoint.sh applies the defaults
+# itself, after the com.beacon.endpoint managed preferences an MDM profile sets; a default filled in
+# here would shadow the profile's harnesses, ports and forwarder settings.
BEACON_BIN="${BEACON_BIN:-/opt/beacon/bin/beacon}"
-BEACON_COLLECTOR="${BEACON_COLLECTOR:-${4:-/opt/beacon/bin/beacon-otelcol}}"
BEACON_INSTALL_SCRIPT="${BEACON_INSTALL_SCRIPT:-/opt/beacon/scripts/install-endpoint.sh}"
+export BEACON_BIN
-BEACON_BIN="$BEACON_BIN" \
-BEACON_ENDPOINT_HARNESSES="${BEACON_ENDPOINT_HARNESSES:-${1:-claude,codex}}" \
-BEACON_OTLP_GRPC_PORT="${BEACON_OTLP_GRPC_PORT:-${2:-4317}}" \
-BEACON_OTLP_HTTP_PORT="${BEACON_OTLP_HTTP_PORT:-${3:-4318}}" \
-BEACON_COLLECTOR="$BEACON_COLLECTOR" \
-BEACON_NO_START="${BEACON_NO_START:-${5:-0}}" \
-BEACON_SPLUNK_HEC_ENDPOINT="${BEACON_SPLUNK_HEC_ENDPOINT:-${6:-}}" \
-BEACON_SPLUNK_HEC_TOKEN="${BEACON_SPLUNK_HEC_TOKEN:-${7:-}}" \
-BEACON_SPLUNK_INDEX="${BEACON_SPLUNK_INDEX:-${8:-}}" \
-BEACON_SPLUNK_SOURCE="${BEACON_SPLUNK_SOURCE:-${9:-}}" \
-BEACON_SPLUNK_SOURCETYPE="${BEACON_SPLUNK_SOURCETYPE:-${10:-}}" \
-BEACON_SPLUNK_INSECURE_SKIP_VERIFY="${BEACON_SPLUNK_INSECURE_SKIP_VERIFY:-${11:-0}}" \
-BEACON_SPLUNK_CA_FILE="${BEACON_SPLUNK_CA_FILE:-${12:-}}" \
-BEACON_FALCON_HEC_ENDPOINT="${BEACON_FALCON_HEC_ENDPOINT:-}" \
-BEACON_FALCON_HEC_TOKEN="${BEACON_FALCON_HEC_TOKEN:-}" \
-BEACON_FALCON_INDEX="${BEACON_FALCON_INDEX:-}" \
-BEACON_FALCON_SOURCE="${BEACON_FALCON_SOURCE:-}" \
-BEACON_FALCON_SOURCETYPE="${BEACON_FALCON_SOURCETYPE:-}" \
-BEACON_FALCON_INSECURE_SKIP_VERIFY="${BEACON_FALCON_INSECURE_SKIP_VERIFY:-0}" \
-BEACON_FALCON_CA_FILE="${BEACON_FALCON_CA_FILE:-}" \
- "$BEACON_INSTALL_SCRIPT"
+# beacon_fleet_arg NAME VALUE exports NAME=VALUE when VALUE is non-empty and the environment has not
+# already set NAME.
+beacon_fleet_arg() {
+ [ -n "$2" ] || return 0
+ eval "_beacon_current=\${$1:-}"
+ [ -z "$_beacon_current" ] || return 0
+ export "$1=$2"
+}
+
+beacon_fleet_arg BEACON_ENDPOINT_HARNESSES "${1:-}"
+beacon_fleet_arg BEACON_OTLP_GRPC_PORT "${2:-}"
+beacon_fleet_arg BEACON_OTLP_HTTP_PORT "${3:-}"
+beacon_fleet_arg BEACON_COLLECTOR "${4:-}"
+beacon_fleet_arg BEACON_NO_START "${5:-}"
+beacon_fleet_arg BEACON_SPLUNK_HEC_ENDPOINT "${6:-}"
+beacon_fleet_arg BEACON_SPLUNK_HEC_TOKEN "${7:-}"
+beacon_fleet_arg BEACON_SPLUNK_INDEX "${8:-}"
+beacon_fleet_arg BEACON_SPLUNK_SOURCE "${9:-}"
+beacon_fleet_arg BEACON_SPLUNK_SOURCETYPE "${10:-}"
+beacon_fleet_arg BEACON_SPLUNK_INSECURE_SKIP_VERIFY "${11:-}"
+beacon_fleet_arg BEACON_SPLUNK_CA_FILE "${12:-}"
+
+exec "$BEACON_INSTALL_SCRIPT"
diff --git a/packaging/macos/test-install-settings.sh b/packaging/macos/test-install-settings.sh
index 5c6f15d0..8005a976 100644
--- a/packaging/macos/test-install-settings.sh
+++ b/packaging/macos/test-install-settings.sh
@@ -146,6 +146,67 @@ run_install BEACON_INSTALLER_GUI=1 BEACON_CONSOLE_USER=alice
has_flag --log-readers && fail "upgrade in Installer.app added the person implicitly"
rm -f "$TMP_DIR/system/config.json"
+# Without the test override, Installer.app is recognized by the executable the kernel reports for an
+# Installer process the console user owns, never by the process name alone, which any account can use.
+PGREP_STUB="$TMP_DIR/pgrep"
+LSOF_STUB="$TMP_DIR/lsof"
+cat >"$PGREP_STUB" <<'STUB'
+#!/bin/sh
+# pgrep -x -u USER Installer: one pid when the test says an Installer process runs as USER.
+[ "$3" = "$BEACON_TEST_INSTALLER_USER" ] && echo 4242
+exit 0
+STUB
+cat >"$LSOF_STUB" <<'STUB'
+#!/bin/sh
+printf 'p4242\nftxt\nn%s\nftxt\nn/usr/lib/dyld\n' "$BEACON_TEST_INSTALLER_EXE"
+STUB
+chmod 755 "$PGREP_STUB" "$LSOF_STUB"
+APPLE_INSTALLER=/System/Library/CoreServices/Installer.app/Contents/MacOS/Installer
+run_install BEACON_INSTALLER_GUI= BEACON_PGREP_BIN="$PGREP_STUB" BEACON_LSOF_BIN="$LSOF_STUB" \
+ BEACON_CONSOLE_USER=alice BEACON_TEST_INSTALLER_USER=alice BEACON_TEST_INSTALLER_EXE="$APPLE_INSTALLER"
+expect --log-readers alice "Apple's Installer.app running as the console user"
+run_install BEACON_INSTALLER_GUI= BEACON_PGREP_BIN="$PGREP_STUB" BEACON_LSOF_BIN="$LSOF_STUB" \
+ BEACON_CONSOLE_USER=alice BEACON_TEST_INSTALLER_USER=alice BEACON_TEST_INSTALLER_EXE=/Users/alice/bin/Installer
+has_flag --log-readers && fail "a program named Installer that is not Apple's added $(flag_value --log-readers)"
+run_install BEACON_INSTALLER_GUI= BEACON_PGREP_BIN="$PGREP_STUB" BEACON_LSOF_BIN="$LSOF_STUB" \
+ BEACON_CONSOLE_USER=alice BEACON_TEST_INSTALLER_USER=bob BEACON_TEST_INSTALLER_EXE="$APPLE_INSTALLER"
+has_flag --log-readers && fail "Installer.app running as another account added $(flag_value --log-readers)"
+run_install BEACON_INSTALLER_GUI= BEACON_PGREP_BIN="$TMP_DIR/missing" BEACON_LSOF_BIN="$LSOF_STUB" \
+ BEACON_CONSOLE_USER=alice BEACON_TEST_INSTALLER_USER=alice BEACON_TEST_INSTALLER_EXE="$APPLE_INSTALLER"
+has_flag --log-readers && fail "no pgrep: treated as Installer.app and added $(flag_value --log-readers)"
+
+# The Fleet wrapper passes only the arguments it was given, so the managed preferences fill the rest
+# instead of being shadowed by its defaults.
+printf 'BEACON_ENDPOINT_HARNESSES=claude,codex,cursor\nBEACON_OTLP_HTTP_PORT=6318\nBEACON_SPLUNK_INDEX=fleet\n' >"$MANAGED.plist"
+chmod 644 "$MANAGED.plist"
+# run_fleet [ARG ...] runs the Fleet wrapper the way run_install runs the install script.
+run_fleet() {
+ rm -f "$ARGS"
+ env -i PATH="$PATH" HOME="$TMP_DIR" BEACON_BIN="$STUB" BEACON_TEST_ARGS="$ARGS" \
+ BEACON_INSTALL_SCRIPT="$INSTALL_SCRIPT" \
+ BEACON_SYSTEM_CONFIG="$TMP_DIR/system/config.json" \
+ BEACON_SYSTEM_LOG="$TMP_DIR/system/runtime.jsonl" \
+ BEACON_DEFAULTS_BIN="$DEFAULTS_STUB" \
+ BEACON_MANAGED_PREFS="$MANAGED" \
+ BEACON_LOCAL_PREFS="$LOCAL" \
+ BEACON_SETTINGS_OWNER="$(id -u)" \
+ BEACON_INSTALLER_GUI=0 \
+ sh "$ROOT_DIR/packaging/macos/fleet/scripts/install.sh" "$@" >"$TMP_DIR/out" 2>&1 || { cat "$TMP_DIR/out" >&2; return 1; }
+}
+run_fleet
+expect --harness claude,codex,cursor "Fleet wrapper with no arguments: managed harnesses"
+expect --otlp-http-port 6318 "Fleet wrapper with no arguments: managed HTTP port"
+expect --otlp-grpc-port 4317 "Fleet wrapper with no arguments: default gRPC port"
+expect --splunk-index fleet "Fleet wrapper with no arguments: managed Splunk index"
+run_fleet codex
+expect --harness codex "Fleet wrapper argument over managed preferences"
+# An empty variable, as a wrapper or an MDM parameter left blank passes it, does not shadow the
+# preferences either; an empty BEACON_LOG_READERS still means nobody.
+run_install BEACON_ENDPOINT_HARNESSES= BEACON_SPLUNK_INDEX=
+expect --harness claude,codex,cursor "empty BEACON_ENDPOINT_HARNESSES shadowed managed preferences"
+expect --splunk-index fleet "empty BEACON_SPLUNK_INDEX shadowed managed preferences"
+rm -f "$MANAGED.plist"
+
if [ "$failures" -ne 0 ]; then
echo "$failures check(s) failed" >&2
exit 1