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
docs: restricted log access on Windows
Claude0ea97ba6c3ce
diff --git a/CLAUDE.md b/CLAUDE.mdindex 8c8d8561..4177c494 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 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 and 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); 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: any local process can still send OTLP, unattributed, so never claim more than the hook channel guarantees. 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. Windows is shared only. 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 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 and 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); 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: any local process can still send OTLP, unattributed, so never claim more than the hook channel guarantees. 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 or fails to start, 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 elevated administrators. 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 each log file under the lock 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 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 restarts the forwarder only when the content changed and the forwarder is running (a stopped one reads the new config when it next starts). 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/changelog/cli.mdx b/docs/changelog/cli.mdxindex acde9fa7..6c7032a3 100644--- a/docs/changelog/cli.mdx+++ b/docs/changelog/cli.mdx@@ -11,7 +11,7 @@ Stay up to date with the latest changes to the Agent Beacon CLI.## Unreleased-- **Restricted log access for system installs** · `beacon endpoint install --system --log-access restricted` makes the collector the only writer of `/var/log/beacon-agent/runtime.jsonl`. Hooks send their events to it over a local Unix socket, each event is recorded under the account the operating system says sent it, and the log becomes `0640 root:beacon-log`, so local accounts can no longer rewrite the log or read other users' sessions. Events are spooled privately and delivered later while the collector restarts. Opt in per endpoint, or with `BEACON_LOG_ACCESS=restricted` for package installs; repair and upgrades keep the mode, and `beacon endpoint doctor` reports a collector that is not serving the socket. Log shippers that do not run as root need to join the `beacon-log` group. The default stays shared, and Windows is not supported yet. See [Restricted log access](/security/restricted-log-access).+- **Restricted log access for system installs** · `beacon endpoint install --system --log-access restricted` makes the collector the only writer of the system runtime log, on macOS, Linux and Windows. Hooks send their events to it over a local Unix socket (a named pipe on Windows), each event is recorded under the account the operating system says sent it, and the log becomes `0640 root:beacon-log` (on Windows, an ACL with SYSTEM, Administrators and read for the `beacon-log` local group only), so local accounts can no longer rewrite the log or read other users' sessions. Events are spooled privately and delivered later while the collector restarts. Opt in per endpoint, or with `BEACON_LOG_ACCESS=restricted` for package installs, the MSI included; repair and upgrades keep the mode, and `beacon endpoint doctor` reports a collector that is not serving the socket. Log shippers that do not run as root (or SYSTEM) need to join the `beacon-log` group. The default stays shared. See [Restricted log access](/security/restricted-log-access).- **Threat rules can match parsed shell commands** · Rules on spec `threat-rules/v1.2` can read `e.command.parsed_commands`: each command's name, arguments, environment prefixes, pipeline stage and the files it writes or deletes. `curl-pipe-to-shell`, `recursive-root-delete` and `base64-decode-piped-to-shell` use it, so they now catch `curl … | sudo -u root bash`, `| /usr/bin/env bash`, `{ curl …; } | sh`, `rm -rf "$HOME"` and `bash -lc '…'` scripts, and no longer fire on the same text inside a quoted string, a commit message or a here-document, or on `rm -rf ~/project/build`. An older Beacon skips v1.2 rules with a warning.- **Shared sessions stay current after more kinds of `beacon share` call** · The dashboard now recognises `beacon share` run under `sudo`, `nohup`, environment assignments or backticks, or cut off when a long command was captured, so a session that shared itself is no longer marked stale.- **Hook events keep a command's closing quote** · A command ending in a quoted word, such as `git commit -m "fix: thing"`, was recorded without its final `"`.diff --git a/docs/cli/endpoint-doctor.mdx b/docs/cli/endpoint-doctor.mdxindex d64328b8..a5d36512 100644--- a/docs/cli/endpoint-doctor.mdx+++ b/docs/cli/endpoint-doctor.mdx@@ -50,7 +50,7 @@ System mode only. Reports whether the system log is shared or [restricted](/cli/| `log_access_mismatch` | warn | The log is marked restricted but `config.json` says shared, so hooks cannot append || `ingest_spool_pending` | warn | Events from the account running doctor are waiting in its spool; they go to the collector with its next event |-In the restricted mode, `runtime_log_permissions` checks that the log and its directory are closed to other accounts instead of checking that hooks can append. Run without `sudo`, doctor cannot open a restricted log, and says so rather than reporting a failure.+In the restricted mode, `runtime_log_permissions` checks that the log and its directory are closed to other accounts instead of checking that hooks can append. On Windows it reads the ACL of the log directory and of everything directly in it, and reports `restricted_acl` when only SYSTEM, Administrators and the `beacon-log` group (read only) can reach them, or `restricted_log_too_open` naming each grant to anyone else. Run without `sudo` (or, on Windows, unelevated), doctor cannot open a restricted log, and says so rather than reporting a failure. On Windows the suggested repair is `beacon endpoint repair --system` from an elevated shell.### `console_user_configured`diff --git a/docs/cli/endpoint-install.mdx b/docs/cli/endpoint-install.mdxindex 5c16b2d0..6bcfbb43 100644--- a/docs/cli/endpoint-install.mdx+++ b/docs/cli/endpoint-install.mdx@@ -278,7 +278,7 @@ What this does and does not change:- Every event that arrives over the socket records the account that sent it, as the operating system reports it. A user still controls their own agent, so they can still send events of their own choosing, including ones that name another session's id, but always under their own account.- The collector's OTLP ports on `127.0.0.1` still accept telemetry from any local process, as they do in the shared mode. Agents that export over OTLP, such as Claude Code and Codex, use them. Events that arrive that way are not attributed by the operating system.-While the endpoint is restricted, commands that read the system log as the person running them (`beacon endpoint dashboard`, `beacon scan`, `beacon traces`, and the session lookups in `beacon share`, `beacon handoff` and `beacon git` commit linking) see it only when run as root or by a `beacon-log` member. [`beacon endpoint doctor`](/cli/endpoint-doctor#runtime_log_access) connects to the socket and reports a collector that is not answering on it, including one that was killed and left its socket behind, and any events waiting in the caller's spool. Restricted log access is not available on Windows yet. For how the mode fits with log shippers such as Microsoft Sentinel, and what it does and does not protect, see [Restricted log access](/security/restricted-log-access).+While the endpoint is restricted, commands that read the system log as the person running them (`beacon endpoint dashboard`, `beacon scan`, `beacon traces`, and the session lookups in `beacon share`, `beacon handoff` and `beacon git` commit linking) see it only when run as root or by a `beacon-log` member. [`beacon endpoint doctor`](/cli/endpoint-doctor#runtime_log_access) connects to the socket and reports a collector that is not answering on it, including one that was killed and left its socket behind, and any events waiting in the caller's spool. On Windows the mode works the same way with Windows mechanisms: hooks send to the named pipe `\\.\pipe\beacon-agent-ingest`, the log directory's ACL gives SYSTEM and Administrators full control, the `beacon-log` local group read and nobody else anything, events record the sender's SID and account name, and the commands run from an elevated shell (see [On Windows](/security/restricted-log-access#on-windows)). For how the mode fits with log shippers such as Microsoft Sentinel, and what it does and does not protect, see [Restricted log access](/security/restricted-log-access).## Running user and system mode togetherdiff --git a/docs/log-forwarding/microsoft-sentinel.mdx b/docs/log-forwarding/microsoft-sentinel.mdxindex 1441bdb5..73f15f21 100644--- a/docs/log-forwarding/microsoft-sentinel.mdx+++ b/docs/log-forwarding/microsoft-sentinel.mdx@@ -143,7 +143,7 @@ The DCR uses Custom Text Logs because Beacon writes newline-delimited JSON. TheAzure Monitor Agent does not run on macOS, so Macs use the [Vector path](#vector-and-the-logs-ingestion-api). The signed macOS package installs Vector at `/opt/beacon/bin/vector`, just like the Linux packages.-For Azure Monitor Agent on Windows or Linux, install AMA on the machine, add a custom text log source pointing at the Beacon runtime log (usually `/var/log/beacon-agent/runtime.jsonl`), apply the Beacon DCR transform, route output to `BeaconRuntime_CL`, and associate the DCR with the machine. On an endpoint with [restricted log access](/security/restricted-log-access), AMA can read the log only if it runs as root or its account is in the `beacon-log` group.+For Azure Monitor Agent on Windows or Linux, install AMA on the machine, add a custom text log source pointing at the Beacon runtime log (usually `/var/log/beacon-agent/runtime.jsonl`), apply the Beacon DCR transform, route output to `BeaconRuntime_CL`, and associate the DCR with the machine. On an endpoint with [restricted log access](/security/restricted-log-access), AMA can read the log only if it runs as root (SYSTEM on Windows, its default) or its account is in the `beacon-log` group.### Azure Monitor Agent outside Azurediff --git a/docs/security/restricted-log-access.mdx b/docs/security/restricted-log-access.mdxindex e04b5a25..f5de87f8 100644--- a/docs/security/restricted-log-access.mdx+++ b/docs/security/restricted-log-access.mdx@@ -3,7 +3,7 @@ title: "Restricted Log Access"description: "Make the collector the only writer of the system runtime log, so local accounts cannot rewrite it or read other users' sessions, and let a log shipper keep reading it"----A system-mode endpoint keeps one runtime log for every user on the machine, `/var/log/beacon-agent/runtime.jsonl`. Your SIEM shipper reads that file. Restricted log access is the mode to use when no ordinary account on the machine should be able to change that file or read it.+A system-mode endpoint keeps one runtime log for every user on the machine: `/var/log/beacon-agent/runtime.jsonl` on macOS and Linux, `%ProgramData%\Beacon\Endpoint\logs\runtime.jsonl` on Windows. Your SIEM shipper reads that file. Restricted log access is the mode to use when no ordinary account on the machine should be able to change that file or read it.## Why the default log is shared@@ -44,7 +44,7 @@ If the collector is stopped or restarting, a hook writes its events to a spool i## Turn it on<Note>- Restricted log access applies to system-mode installs on macOS and Linux. It is not available on Windows yet, and a per-user log in `~/.beacon` is already private to its owner.+ Restricted log access applies to system-mode installs on macOS, Linux and Windows. A per-user log in `~/.beacon` is already private to its owner. On Windows, hooks use a named pipe instead of a socket and the log is closed off by its ACL instead of file modes; see [On Windows](#on-windows).</Note>On a new system install:@@ -65,6 +65,47 @@ Switching replaces the log and its archives with fresh copies, so a file handleThe mode is recorded in `config.json` as `log_access` and in a root-owned `.beacon-log-access` marker beside the log. `beacon endpoint repair`, package upgrades, the Jamf `repair-hooks.sh` policy, and a reinstall after `uninstall --keep-logs` all keep it, so you set it once per endpoint.+## On Windows++Restricted mode works the same way on a Windows system install, with Windows mechanisms in place of the Unix ones.++| | Shared (default) | Restricted |+|---|---|---|+| Who writes `runtime.jsonl` | The collector (`BeaconCollector`, running as SYSTEM) and every user's hooks | The collector only |+| How hooks deliver events | Append to the file | Send to the named pipe `\\.\pipe\beacon-agent-ingest` |+| Log directory and everything in it | Users read; interactive users read and write the log files | SYSTEM and Administrators full control, read for the `beacon-log` local group, nothing for anyone else |+| Lock (`runtime.jsonl.lock`) | As the log | SYSTEM and Administrators only |+| User recorded on hook events | What the hook reports | The account Windows says sent the event: its SID in `user.uid` and `DOMAIN\name` in `user.name` |+| Collector down or restarting | Hooks keep appending | Hooks hold events in a private spool in their profile and send them later |++The pipe is created by the SYSTEM collector, refuses connections from other machines and denies network logons, and does not let ordinary accounts add an instance of their own. Hooks send only to a pipe that SYSTEM or Administrators created, so an account that takes the name first gets nothing. Hooks run by SYSTEM or from an elevated shell write the log directly, as root does on Unix.++Run the commands from an elevated shell:++```powershell title="Switch a Windows endpoint to restricted"+beacon endpoint repair --system --log-access restricted+```++For the MSI and `install-endpoint.ps1`, set `BEACON_LOG_ACCESS=restricted` in the machine environment before installing. An upgrade with the variable unset keeps whatever mode the endpoint has.++Switching replaces every file of the log with a fresh copy and resets the security of everything in the log directory, so a handle another account opened while the log was shared stops reaching it. Windows cannot replace a file that another process holds open without allowing deletes. If one does, the switch waits a few seconds, then fails and names the file. Close that process (or sign the account out) and run the command again; until then the endpoint keeps the shared mode.++Add a shipper's account to the readers group from an elevated shell, then restart the shipper:++```powershell title="Add a shipper's account to beacon-log"+net localgroup beacon-log <account> /add+```++Shippers that run as SYSTEM, which is how Azure Monitor Agent, the Splunk Universal Forwarder and Elastic Agent run by default, keep working with no change.++To verify, run `beacon endpoint doctor --system` from an elevated shell and expect `runtime_log_access: ok` and `runtime_log_permissions: ok` (`restricted_acl`), then check the directory:++```powershell title="Check the log directory's access"+icacls "$env:ProgramData\Beacon\Endpoint\logs"+```++It lists `NT AUTHORITY\SYSTEM`, `BUILTIN\Administrators` and `beacon-log` and nothing else.+## Let your log shipper read the logInstall creates the `beacon-log` group if it is missing and adds nobody to it. A shipper that runs as root keeps working with no change, and so does the Beacon Cloud forwarder. A shipper that runs as its own account needs to join the group, and then be restarted so it picks up the new membership:@@ -115,7 +156,7 @@ The same rule applies to Splunk Universal Forwarder, Filebeat or Elastic Agent,| Action | Who can do it ||---|---|-| Install, repair, uninstall, connect or disconnect the system endpoint, or change its log access mode | Root only. These commands change root-owned files and services, and refuse or fail without `sudo` |+| Install, repair, uninstall, connect or disconnect the system endpoint, or change its log access mode | Root only (an elevated administrator on Windows). These commands change root-owned files and services, and refuse or fail without `sudo` or elevation || Append events to the log | Only the collector. Users' hooks deliver through the socket, stamped with the sending account || Rewrite, truncate or delete events already in the log | Root only || Read the log, including with `beacon endpoint dashboard`, `beacon scan`, `beacon traces`, and the session lookups in `beacon share`, `beacon handoff` and `beacon git` | Root and members of `beacon-log` |@@ -130,7 +171,7 @@ Restricted mode protects the **log**: what has been recorded cannot be altered o- **A user still controls their own agent.** They can still send events of their own choosing through the socket, including ones that name another session's id, but every event is recorded under their own account, as the operating system reports it. They cannot write an event that claims to be someone else's.- **A user can still change their own agent settings.** The hooks and OpenTelemetry settings that send an agent's activity to Beacon live in each user's home (for example `~/.claude/settings.json`), and that user can edit them, which stops capture of their future sessions. Restricted mode does not change this. Run [`beacon endpoint doctor --system`](/cli/endpoint-doctor#console_user_configured) from your MDM to catch it: `console_user_configured` fails when the logged-in user's agents no longer point at the collector, and `sudo beacon endpoint user-config repair-installed --system` puts the settings back.- **The OTLP ports are not attributed.** The collector's OTLP receivers on `127.0.0.1:4317` and `4318` still accept telemetry from any local process, as in the shared mode. Agents that export over OTLP, such as Claude Code and Codex, use them, and events that arrive that way carry the user the agent reports rather than one the operating system confirmed.-- **Root is trusted.** An administrator can read and change the log in either mode.+- **Root is trusted.** An administrator can read and change the log in either mode. On Windows that is SYSTEM and any elevated administrator.## Verify