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
---
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` 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
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.
### Agents in a sandbox
A sandbox launcher such as bubblewrap usually leaves both the socket and the log out of the sandbox. To keep live hook events from such an agent, with the sending account recorded by the operating system, mount the collector's socket directory into the sandbox at the same path:
```bash title="bubblewrap: give sandboxed hooks the collector"
bwrap ... --bind /var/run/beacon-agent /var/run/beacon-agent ...
```
This works for a sandbox without its own user namespace, which is how bubblewrap runs when installed setuid. Such a sandbox builds its root filesystem on a tmpfs owned by the account it runs as, so `/`, `/var` and `/var/run` belong to that account inside it. Hooks accept parent directories owned by root or by their own account. Before sending anything, they also check that the process serving the socket is root. Sandboxes with their own user namespace are not covered.
To also hold events while the collector restarts, mount the account's spool too: `--bind ~/.beacon/endpoint/spool ~/.beacon/endpoint/spool`, with the directory created beforehand (`0700`). The next event that gets through, from inside the sandbox or outside it, delivers what was held.
A hook that can reach neither the socket nor a spool does not record the event. It prints `beacon-hooks: this event was NOT recorded` and the reason to the hook's stderr, and the agent carries on. On Linux, inside a sandbox whose root filesystem is a tmpfs owned by the account (bubblewrap's), a hook never puts the log or the spool on that filesystem; only directories the sandbox mounts take them. That holds even when a project bound under the home makes the home exist inside the sandbox, so events never go to files that disappear with the sandbox.
Runtimes that build their own sandbox, such as DeepSeek Harness or Gemini CLI and Qwen Code in a container, usually leave only the session workspace writable, and you cannot add mounts. There the hook stages the event in the session workspace instead, and Beacon drains it later; see [`beacon endpoint spool`](/cli/endpoint-spool).
## Turn it on
<Note>
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:
```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
```
A first install from a package is restricted already, with no setting, on Linux, macOS and Windows; see [Package installs](#package-installs).
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.
## Package installs
The `.deb` and `.rpm`, the macOS `.pkg` and the Windows MSI follow the same rules.
**A first install is restricted.** A package is installed by an administrator for the whole machine, often by fleet tooling, so it sets up restricted access without a second step. An upgrade, a reinstall over a kept config, or a reinstall over a log kept by `uninstall --keep-logs` keeps whatever mode the endpoint already has, so existing endpoints never change. A first install that fails removes the log it created, so retrying it is still a first install. An install whose collector is not an OS service stays shared, because nothing there restarts the collector: on Linux a host without systemd as PID 1 (a container, WSL without systemd), and on Linux or Windows one installed with `BEACON_SERVICE=none`. `BEACON_LOG_ACCESS=shared` installs a new endpoint shared.
**Who is added to `beacon-log` depends on how the package was installed:**
| Installed by | How the install recognizes it | Added to `beacon-log` |
|---|---|---|
| Fleet tooling, unattended (Salt, Ansible, Jamf, Kandji, Intune, SCCM) | Linux: root with no `SUDO_USER`, or sudo with no terminal or under `DEBIAN_FRONTEND=noninteractive` (Ansible `become`, a Packer sudo provisioner). macOS: `installer` (sets `COMMAND_LINE_INSTALL`). Windows: a silent MSI (`msiexec /qn`) | Nobody |
| A person, as an administrator | Linux: `sudo apt install` or `sudo dpkg -i` at a terminal. macOS: Apple's Installer.app, running as the logged-in user. Windows: the installer's full interface | That person, so the dashboard, `beacon traces` and `beacon share` work for them after they log in again |
| 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`.
**Fleet tooling sets these settings where it already writes settings,** because an MDM or a configuration manager cannot set the environment of a package's install script. The names are the same everywhere: `BEACON_LOG_ACCESS`, `BEACON_LOG_READERS`, `BEACON_ENDPOINT_HARNESSES` and the other documented `BEACON_*` install settings.
| Platform | Where | Written by |
|---|---|---|
| Linux | `/etc/default/beacon` (Debian, Ubuntu) or `/etc/sysconfig/beacon` (Fedora, RHEL), as `KEY=VALUE` lines; see [Settings for configuration-manager installs](/platforms/linux#settings-for-configuration-manager-installs) | Salt, Ansible, Puppet, Chef |
| 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. 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
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 keep their events in their spool, and the collector keeps running and serves the pipe as soon as the name is free. Hooks run by SYSTEM or by an administrator 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
```
A first MSI install is restricted already. An upgrade keeps whatever mode the endpoint has. Fleet tooling sets `BEACON_LOG_ACCESS` and the other install settings as policy values; see [Package installs](#package-installs).
Switching replaces every file in the log directory with a fresh copy and resets the security of everything in it, 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. The log is put back to shared, so hooks keep writing. Close that process (or sign the account out) and run the command again.
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 and Elastic Agent run by default, keep working with no change. The Splunk Universal Forwarder runs as SYSTEM only in releases before 9.1; from 9.1 it installs by default as the virtual account `NT SERVICE\SplunkForwarder`, which must be added and the forwarder restarted:
```powershell title="Splunk Universal Forwarder 9.1 and later"
net localgroup beacon-log "NT SERVICE\SplunkForwarder" /add
Restart-Service SplunkForwarder
```
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 log
Install creates the `beacon-log` group if it is missing and adds only the accounts named by `BEACON_LOG_READERS` or `--log-readers`, or the person who ran a first package install interactively (see [Package installs](#package-installs)). 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
**rsyslog.** When rsyslog [forwards the log to your collector](/log-forwarding/rsyslog), it reads the file as root on RHEL, Debian and most other distributions, so nothing changes there. On Ubuntu it runs as the `syslog` user: run `sudo usermod -aG beacon-log syslog` and restart rsyslog. See [With restricted log access](/log-forwarding/rsyslog#with-restricted-log-access).
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. On Windows, a shipper you write yourself should also open the log with delete sharing, or it holds rotation up while it reads; see [Reading the log on Windows](/log-forwarding/local-jsonl#reading-the-log-on-windows).
## 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 (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` |
| 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 open to every account.** 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, and the browser extension use them. On Linux, macOS and Windows the collector records each such event under the account that owns the connection it arrived on, as the operating system reports it, and ignores any account the sender names itself; an event whose sender had already disconnected when the collector looked carries no `user` at all, so it is never mistaken for root's. That names the sender but does not stop an account sending whatever it likes under its own name. Claude Cowork's events carry no `user`, because they arrive through a relay whose account is not the person's, and keep the cloud account and the relaying account only in their raw attributes. The person is on the same session's hook and plugin events, which share the OTLP events' `session.id` and which restricted mode does attribute; see [Microsoft Sentinel forwarding](/log-forwarding/microsoft-sentinel#who-ran-each-session) for the join.
- **Root is trusted.** An administrator can read and change the log in either mode. On Windows that is SYSTEM and any elevated administrator.
## 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>