Skip to content

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

docs: address review on the fleet guide and deployment profile

Claudece790a202e74
diff --git a/docs/platforms/fleet-deployment.mdx b/docs/platforms/fleet-deployment.mdx
index ec156c27..cddbc66b 100644
--- a/docs/platforms/fleet-deployment.mdx
+++ b/docs/platforms/fleet-deployment.mdx
@@ -5,6 +5,10 @@ description: "Deploy Beacon to managed Linux, macOS and Windows machines with re
This page puts the fleet settings together for each platform: the package, the settings your fleet tooling writes before installing it, how to pin and roll out versions, and how to check the result. The behavior is the same on Linux, macOS and Windows.
+<Note>
+ Everything on this page needs a release newer than 1.3.57. Version 1.3.57 and earlier ignore these settings and install a shared log, and record OpenTelemetry events on macOS and Windows under the collector's account. Pin a newer version in the examples below.
+</Note>
+
## What a fleet install gives you
| | Result |
@@ -36,7 +40,7 @@ Each is ignored, with a warning in the install output, unless root (SYSTEM or Ad
## Linux with Salt
-The signed apt repository at `https://apt.beacon.sh` carries every release from 1.3.57 on, so a machine can install any of them by version. Pin the repository key by its hash, so a changed key stops the state instead of being trusted:
+The signed apt repository at `https://apt.beacon.sh` keeps every release it has published, so a machine can install any of them by version. Pin the repository key by its hash, so a changed key stops the state instead of being trusted:
```yaml title="beacon.sls"
/etc/default/beacon:
@@ -64,7 +68,7 @@ The signed apt repository at `https://apt.beacon.sh` carries every release from
beacon:
pkg.installed:
- - version: 1.3.57 # the release you approved; raise it to roll forward
+ - version: "<version>" # the release you approved (newer than 1.3.57); raise it to roll forward
- hold: True
- refresh: True
- require:
@@ -122,19 +126,31 @@ Beacon never updates itself. `beacon endpoint update --apply` runs only when som
## Check a machine
-On the machine, as root (an elevated shell on Windows):
+On Linux and macOS, as root:
-```bash title="Status"
+```bash title="Status (Linux, macOS)"
sudo beacon endpoint status --system --json | jq '{log_access, dashboard}'
sudo beacon endpoint doctor --system
```
-Expect `"log_access": "restricted"` (and `"dashboard": "disabled"` if you set it), and `runtime_log_access: ok` from `doctor`. Then confirm that events name the person: as an ordinary account, send one prompt in an agent Beacon configured, and look at the newest events:
+On Windows, in an elevated PowerShell:
+
+```powershell title="Status (Windows)"
+beacon endpoint status --system --json | ConvertFrom-Json | Select-Object log_access, dashboard
+beacon endpoint doctor --system
+```
+
+Expect `log_access` to be `restricted` (and `dashboard` to be `disabled` if you set it), and `runtime_log_access: ok` from `doctor`. Then confirm that events name the person: as an ordinary account, send one prompt in an agent Beacon configured, and look at the newest events:
-```bash title="Who acted"
+```bash title="Who acted (Linux, macOS)"
sudo tail -n 20 /var/log/beacon-agent/runtime.jsonl | jq -c '{action: .event.action, harness: .harness.name, user: .user.name}'
```
+```powershell title="Who acted (Windows, elevated)"
+Get-Content "$env:ProgramData\Beacon\Endpoint\logs\runtime.jsonl" -Tail 20 | ConvertFrom-Json |
+ Select-Object @{n='action';e={$_.event.action}}, @{n='harness';e={$_.harness.name}}, @{n='user';e={$_.user.name}}
+```
+
The person's account should appear, not `root` (or `COMPUTERNAME$` on Windows). An event recorded with an empty `user` came from a sender the collector could not identify, for example one that disconnected before the lookup; it is never attributed to someone else. Events from collectors older than this behavior carry the collector's account until the endpoint is upgraded or repaired. In Microsoft Sentinel the same account is the `UserName` column; see [Microsoft Sentinel](/log-forwarding/microsoft-sentinel).
If a log shipper reads the file as its own account, add that account to `BEACON_LOG_READERS` (or to `beacon-log` directly) and restart it; Beacon's own forwarders run as root or SYSTEM and need nothing. See [Let your log shipper read the log](/security/restricted-log-access#let-your-log-shipper-read-the-log).
diff --git a/docs/platforms/linux-deployment-profile.mdx b/docs/platforms/linux-deployment-profile.mdx
index 702d1052..ed4e1615 100644
--- a/docs/platforms/linux-deployment-profile.mdx
+++ b/docs/platforms/linux-deployment-profile.mdx
@@ -13,11 +13,11 @@ Beacon loads nothing into the kernel and needs nothing beyond a standard POSIX s
|---|---|
| Kernel modules | None loaded, none required |
| eBPF / audit subsystem | Not used |
-| netlink | One `NETLINK_SOCK_DIAG` query per OpenTelemetry export, to look up which account owns the sending loopback connection |
+| netlink | `NETLINK_SOCK_DIAG` per OpenTelemetry export, to look up which account owns the sending loopback connection: one exact query, or two for an IPv4 connection (as IPv4, then as an IPv4-mapped IPv6 address) |
| ptrace, process injection | Not used |
| cgroups, `/sys`, udev | Not read |
| Capabilities, setuid, setcap | None |
-| `/proc` | `/proc/1/comm`, to detect whether systemd is PID 1; `/proc/net/tcp` and `/proc/net/tcp6` only when `NETLINK_SOCK_DIAG` is unavailable, for the same connection lookup |
+| `/proc` | `/proc/1/comm`, to detect whether systemd is PID 1; `/proc/net/tcp` and `/proc/net/tcp6` for the same connection lookup when the `NETLINK_SOCK_DIAG` query fails, and when it finds nothing before it has once found a socket (the kernel answers the same way when the `tcp_diag` module is missing) |
Everything it uses from the kernel:
@@ -25,7 +25,7 @@ Everything it uses from the kernel:
|---|---|---|
| TCP loopback | Three listeners on `127.0.0.1` | Collector cannot start |
| `flock(2)` | Serializing writes to the runtime log | Degrades on some network filesystems; fine on local disk |
-| `fork`/`exec` | One short-lived hook process per agent event | Hook capture stops; OpenTelemetry capture continues |
+| `fork`/`exec` | One short-lived hook process per agent event. The collector also runs `/usr/bin/id -nu <uid>` (500 ms limit) to name a sender whose account is not in `/etc/passwd`, such as an LDAP, SSSD or AD account, at most once per account every 10 minutes | Hook capture stops; OpenTelemetry capture continues. Without `id`, a directory account's events carry its uid without a name |
| Ordinary file I/O | Config and log | None |
| `/proc/1/comm` | systemd detection | Falls back to a supervised collector, which does not restart on exit or start at boot |
| `NETLINK_SOCK_DIAG`, `/proc/net/tcp{,6}` | Recording each OpenTelemetry export under the account that sent it | The export is recorded with no account, never as root or anyone else |
@@ -118,7 +118,7 @@ ss -ltnp | grep beacon-otelcol
- In user mode everything runs as you under `~/.beacon`, with no privileges required.
- The log contains prompt text, command lines, file paths, and tool inputs, after redaction and a
64 KiB per-event limit. Treat it as sensitive data.
-- Account lookup goes through `getent`, so accounts from OpenLDAP, SSSD, or AD resolve normally.
+- The CLI looks accounts up through `getent`, and the collector names a sender from `/etc/passwd` and then `id -nu`, so accounts from OpenLDAP, SSSD, or AD resolve normally.
## Pinning it to housekeeping cores