Skip to content

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

docs: restricted log access page, and how it fits with log shippers

Justin D'Souza86894febdc25
diff --git a/docs/changelog/cli.mdx b/docs/changelog/cli.mdx
index df7afea6..acde9fa7 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](/cli/endpoint-install#restricted-log-access).
+- **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).
- **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-install.mdx b/docs/cli/endpoint-install.mdx
index 376d8b3d..5c16b2d0 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.
+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).
## Running user and system mode together
diff --git a/docs/docs.json b/docs/docs.json
index e85015dd..2a8cae1f 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -238,6 +238,7 @@
"security/data-inventory",
"security/retention-redaction",
"security/endpoint-operations",
+ "security/restricted-log-access",
"security/policy"
]
},
diff --git a/docs/log-forwarding/microsoft-sentinel.mdx b/docs/log-forwarding/microsoft-sentinel.mdx
index 15642bc1..1441bdb5 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. The
Azure 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.
+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.
### Azure Monitor Agent outside Azure
@@ -203,7 +203,7 @@ sudo systemctl daemon-reload
sudo systemctl enable --now beacon-sentinel
```
-`DynamicUser` runs Vector as an unprivileged user. It can read the runtime log because Beacon writes it world-readable, and systemd reads `azure.env` as root before dropping privileges. `StateDirectory` creates `/var/lib/vector/beacon-sentinel`, where Vector keeps its read position.
+`DynamicUser` runs Vector as an unprivileged user. It can read the runtime log because the default shared log is world-readable, and systemd reads `azure.env` as root before dropping privileges. If the endpoint uses [restricted log access](/security/restricted-log-access), add `SupplementaryGroups=beacon-log` under `[Service]` so Vector can still read it. `StateDirectory` creates `/var/lib/vector/beacon-sentinel`, where Vector keeps its read position.
The pack ships a client secret config. Vector also supports a certificate (`azure_credential_kind = "client_certificate_credential"` with `certificate_path`); see the [`azure_logs_ingestion` sink](https://vector.dev/docs/reference/configuration/sinks/azure_logs_ingestion/).
diff --git a/docs/security/data-flow-threat-model.mdx b/docs/security/data-flow-threat-model.mdx
index 5a8e247c..b4b9ae07 100644
--- a/docs/security/data-flow-threat-model.mdx
+++ b/docs/security/data-flow-threat-model.mdx
@@ -39,6 +39,7 @@ flowchart LR
| Over-collection of prompt or diff content | Standard applies local sanitization and size controls. Metadata-only additionally strips retained prompts, responses, reasoning, tool arguments/results, tool descriptions and definitions, retrieval queries and documents, approval and policy reasons, command output, raw fields, diffs, inventory content, and MCP definitions in Vector before buffering or upload |
| Secret leakage in retained content | Beacon applies redaction, sanitization, truncation, and event-size limits before writing supported content fields |
| Destination credential exposure | Persistent endpoint file-based destinations tail local JSONL, so Beacon endpoint configuration does not store Elastic, Datadog, Sumo Logic, Rapid7, Microsoft Sentinel, AWS, or Google Cloud credentials. Optional Splunk and Falcon tokens live in collector configuration. The CLI account token authorizes user-mode enrollment once and is never copied into endpoint state or Vector. The resulting per-machine device key is stored in a `0600` secrets file read through Vector's secret backend, never in `config.json`, `vector.toml`, or the process environment; it grants only per-device ingest and is revocable. Self-serve cloud-agent uploads are a separate proof-of-concept path: scoped GCS or AWS credentials are injected into the provider-managed sandbox as runtime secrets and must be rotated and access-reviewed. |
+| Local tampering with or reading of the system log | In the default shared mode any local account can append to, rewrite and read the system log. [Restricted log access](/security/restricted-log-access) makes the root collector the only writer, delivers hook events over a local Unix socket stamped with the sending account as the operating system reports it, and limits reading to root and the `beacon-log` group |
| Removal uncertainty | Endpoint uninstall removes managed service and configuration state, with explicit `--keep-logs` and `--keep-config` exceptions |
## Current boundaries
diff --git a/docs/security/endpoint-operations.mdx b/docs/security/endpoint-operations.mdx
index f313df60..c07a6637 100644
--- a/docs/security/endpoint-operations.mdx
+++ b/docs/security/endpoint-operations.mdx
@@ -64,6 +64,8 @@ User mode is the default for local evaluation and writes under the current user'
The system package is designed for Jamf Pro, Fleet, or another macOS MDM. It installs a signed and notarized `.pkg`, creates system endpoint configuration, loads the local collector LaunchDaemon, and writes endpoint events to `/var/log/beacon-agent/runtime.jsonl`.
+By default the system runtime log is shared: hooks run as each logged-in user and append to it directly, so it is mode `0666`. With [restricted log access](/security/restricted-log-access) the collector is the only writer, hooks send their events over the local socket `/var/run/beacon-agent/ingest.sock`, and the log is `0640 root:beacon-log`, readable only by root and members of the `beacon-log` group.
+
The active runtime log rotates when the next write would exceed 10 MiB. Beacon keeps up to five numbered local archives next to the active file, preserving the active path as the handoff point for local inspection and customer-managed shippers.
## Network behavior
diff --git a/docs/security/restricted-log-access.mdx b/docs/security/restricted-log-access.mdx
new file mode 100644
index 00000000..e04b5a25
--- /dev/null
+++ b/docs/security/restricted-log-access.mdx
@@ -0,0 +1,176 @@
+---
+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.
+
+## Why the default log is shared
+
+Agent hooks run as the person using the agent, not as root. In the default **shared** mode they append to the system log directly, so the file has to be writable by every account (`0666`). That has two consequences on a machine with more than one account, or one where a user should not be trusted with the evidence:
+
+- Any local account can truncate, rewrite or delete events already in the log, including before your shipper has read them.
+- Any local account can read every other user's prompts, command output and diffs.
+
+## What restricted mode changes
+
+In the **restricted** mode the root collector is the only process that writes the log. Hooks hand their events to it over a local Unix socket instead of opening the file.
+
+```mermaid
+flowchart LR
+ hooks["Agent hooks (run as each user)"] -->|"Unix socket /var/run/beacon-agent/ingest.sock"| collector["Beacon collector (root)"]
+ otlp["Agents exporting OTLP"] -->|"127.0.0.1:4317 / 4318"| collector
+ collector -->|"only writer"| log["runtime.jsonl (0640 root:beacon-log)"]
+ log -->|"reads as a beacon-log member or root"| shipper["Log shipper (Sentinel, Splunk, Wazuh, ...)"]
+```
+
+| | Shared (default) | Restricted |
+|---|---|---|
+| Who writes `runtime.jsonl` | The collector and every user's hooks | The collector only |
+| How hooks deliver events | Append to the file | Send to `/var/run/beacon-agent/ingest.sock` |
+| Log and archives | `0666` | `0640`, owner `root`, group `beacon-log` |
+| Log directory | Readable by everyone | `2750`, owner `root`, group `beacon-log` |
+| Who can read the log | Every account | Root and members of `beacon-log` |
+| Who can modify the log | Every account | Root only |
+| User recorded on hook events | What the hook reports | The account the operating system says sent the event (`user.uid`, `user.name`) |
+| Collector down or restarting | Hooks keep appending | Hooks hold events in a private spool and send them later |
+
+The event format and every field stay the same, so a parser, DCR transform or SIEM rule built for the shared log needs no change. Nothing leaves the machine: the socket is a local file, and hooks still never touch the network.
+
+### Delivery while the collector is down
+
+If the collector is stopped or restarting, a hook writes its events to a spool in that user's home, `~/.beacon/endpoint/spool` (`0700` directory, `0600` files), and returns at once, so the agent is never held up. The next event that user's hooks send delivers the spooled ones first. Each spool is capped at 8 MiB; events past that are dropped and counted rather than filling the disk. [`beacon endpoint doctor`](/cli/endpoint-doctor#runtime_log_access) reports a collector that is not answering on the socket and any events waiting in the caller's spool.
+
+## 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.
+</Note>
+
+On a new system install:
+
+```bash title="Install with restricted log access"
+sudo beacon endpoint install --system --log-access restricted
+```
+
+On an endpoint that is already installed, including one installed from the signed package, switch it in place. This is also the command to put in an MDM script policy (Jamf, Fleet) that runs after the package:
+
+```bash title="Switch an existing endpoint to restricted"
+sudo beacon endpoint repair --system --log-access restricted
+```
+
+For package installs you can instead set `BEACON_LOG_ACCESS=restricted` in the environment of the package's install script.
+
+Switching replaces the log and its archives with fresh copies, so a file handle another account opened while the log was shared stops reaching it. Existing events are kept.
+
+The 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.
+
+## Let your log shipper read the log
+
+Install 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:
+
+```bash title="Add a shipper's account to beacon-log"
+# Linux
+sudo usermod -aG beacon-log <account>
+# macOS
+sudo dseditgroup -o edit -a <account> -t user beacon-log
+```
+
+If you are not sure which account a shipper runs as, look at its process:
+
+```bash title="Find the account a shipper runs as"
+ps -eo user,comm | grep -i -E '<shipper process name>'
+```
+
+Then confirm that account can read the log:
+
+```bash title="Check the shipper can read the log"
+sudo -u <account> test -r /var/log/beacon-agent/runtime.jsonl && echo readable
+```
+
+### Microsoft Sentinel
+
+**Azure Monitor Agent.** AMA tails the file as the account its agent runs under. If that is not root, add it to `beacon-log` as above and restart AMA. The DCR, transform and `BeaconRuntime_CL` table are unchanged.
+
+**Vector and the Logs Ingestion API.** The [`beacon-sentinel` service](/log-forwarding/microsoft-sentinel#vector-and-the-logs-ingestion-api) runs Vector as a `DynamicUser`, which has no fixed account to add to a group. Give the unit the group instead:
+
+```ini title="/etc/systemd/system/beacon-sentinel.service"
+[Service]
+DynamicUser=yes
+SupplementaryGroups=beacon-log
+```
+
+```bash title="Apply it"
+sudo systemctl daemon-reload
+sudo systemctl restart beacon-sentinel
+```
+
+Vector keeps its read position in `/var/lib/vector/beacon-sentinel`, so it resumes where it stopped and does not resend the log.
+
+### Other shippers
+
+The same rule applies to Splunk Universal Forwarder, Filebeat or Elastic Agent, the Datadog Agent, Wazuh, Rapid7, Sumo Logic and any customer-managed shipper reading the [local JSONL log](/log-forwarding/local-jsonl): running as root, nothing changes; running as its own account, add that account to `beacon-log` and restart it. Splunk HEC and Falcon LogScale HEC are sent by the collector itself and are not affected.
+
+## Who can do what on a restricted endpoint
+
+| 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` |
+| 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` |
+| See whether the endpoint is restricted | Anyone, with `beacon endpoint status --system`. Without `sudo`, status says it cannot read the log rather than reporting it empty |
+
+Add people to `beacon-log` only when they should see every user's sessions on that machine, the same as you would for a shipper.
+
+## What restricted mode does and does not protect
+
+Restricted mode protects the **log**: what has been recorded cannot be altered or read by other local accounts. It does not take control of each person's agent away from them.
+
+- **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.
+
+## Verify
+
+```bash title="Check the mode and the socket"
+sudo beacon endpoint doctor --system
+ls -ld /var/log/beacon-agent
+ls -l /var/log/beacon-agent/runtime.jsonl
+```
+
+Expect `runtime_log_access: ok` with `log_access_restricted`, the directory as `drwxr-s--- root beacon-log`, and the log as `-rw-r----- root beacon-log`. Then confirm events still arrive from an ordinary account: as that user, send one prompt in an agent that uses hooks, such as Cursor or Claude Code, and look for it:
+
+```bash title="See which accounts recent events came from"
+sudo tail -n 20 /var/log/beacon-agent/runtime.jsonl | jq -c '{action: .event.action, user: .user.name}'
+```
+
+Hook events carry the user's own account name, stamped by the collector.
+
+If doctor reports `ingest_socket_missing` or `ingest_socket_unresponsive`, the collector is not serving the socket and hooks are spooling: restart or repair the collector. The full list of results is under [`runtime_log_access`](/cli/endpoint-doctor#runtime_log_access).
+
+## Switch back
+
+```bash title="Return to the shared log"
+sudo beacon endpoint repair --system --log-access shared
+```
+
+The log becomes writable by every account again at once, and hooks go back to appending to it directly. Shippers that read it as `beacon-log` members keep working.
+
+## Related
+
+<Columns cols={2}>
+ <Card title="Endpoint install" icon="download" href="/cli/endpoint-install#restricted-log-access">
+ The `--log-access` flag and install behavior.
+ </Card>
+ <Card title="Microsoft Sentinel" icon="shield" href="/log-forwarding/microsoft-sentinel">
+ Forward the runtime log with Azure Monitor Agent or Vector.
+ </Card>
+ <Card title="Endpoint operations" icon="gear" href="/security/endpoint-operations">
+ Paths, permissions, and daemon behavior.
+ </Card>
+ <Card title="Data flow and threat model" icon="diagram-project" href="/security/data-flow-threat-model">
+ Trust boundaries from collection to forwarding.
+ </Card>
+</Columns>