privatae-bastion/docs/observe.md

Observe: what is running on this machine

Read-only, and reported so the host can show why rather than a verdict.

• Agent observe. Watches for AI-agent activity two ways and correlates by process: a process signal (known agent binaries, interpreter-wrapped ones by command line) and a network signal (connections to inference endpoints, both cloud APIs and local model servers). Each observation carries an origin (interactive, remote, scheduler, service, agent) and a typed evidence list with a confidence tier. Tools that drive the machine with no model of their own are inventoried as automation and promoted to agent only when model traffic joins them. Each also says who owns the account it runs as: owner_class (domain_user, local_user, service, system), owner_admin and owner_interactive (each yes, no or unknown; a group list or token that could not be read is unknown, never no).
• Declared tool servers. The files where Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Codex and Zed declare their MCP servers, per account and for the projects Claude Code lists, read and never written or connected to. Per server: client, scope, path, name, transport, whether it is a local process or a URL (and the URL's host), the launch command truncated like an agent's, the package and whether it is pinned, the names of the environment variables it gets, whether a value looked like a secret (the value is dropped where it is read), whether a remote server has authentication configured, and whether it is running, declared but not running, or running with no declaration. A command line keeps a URL's scheme and host only, and every flag, header or NAME=value that names a secret is replaced. A file is opened only once it is known to be a regular file (on Windows: a reparse point, directory or device at the path is refused, checked on the open handle), and in an account's home or project only when that account or root owns it (on Windows: the account whose profile it is, SYSTEM or the Administrators group; files_foreign_owner counts the rest). The files are read at most every ten minutes, and a read that does not finish holds the beats for at most 20 seconds in total (timed_out says it did not finish; until one read has finished, no server is reported).
• Scheduler inventory. Crontabs, systemd timers, launchd jobs and Windows scheduled tasks whose command would run an agent or automation.
• Baseline and delta. observe:baseline records what is normal on this machine: every automated program, its user, and a digest of the file it runs from. observe:delta reports what the baseline does not hold, with ordinary noise filtered out. Administrator only.
• Computer observe. The machine map the host plans from instead of a screenshot: installed applications with their scripting doors, the windows open now, and one app's accessibility tree as exact text. Read-only. No input injection lives in the bastion.
• Host observe (Linux). Sockets, firewall, failed units and timers, disk, kernel log, and a read-only Kubernetes view where the control-plane installer has placed a view-bound kubeconfig. Every argv is fixed. Off Linux each of these answers unsupported. The one exception is observe:net, which is pure Go and works on every platform: given a host[:port] it makes an outbound probe from this machine (TCP connect, TLS expiry and chain, HTTP status).
• Monitoring observe (observe:alerts, observe:metrics, observe:logs). The pull half of the same family: read-only HTTP against an Alertmanager, Prometheus and Loki running on the box's own network, named once at install in a local config file. Only private addresses are accepted — the reverse of observe:net's public-only rule, since these read the box's own neighbourhood. observe:alerts reports the active Alertmanager set; observe:metrics and observe:logs each take one name from a fixed list and the box owns the query — no PromQL or LogQL ever crosses the wire from the host. Alert counts also ride the heartbeat, refreshed on their own interval, and are absent — not zero — whenever no Alertmanager is configured.

The observe ops that send traffic are observe:net, observe:k8s (a read-only query of a cluster API) and the three monitoring ops above (private addresses only, refused at the socket if a redirect or a DNS answer would move the destination after validation). A build with no enumerator for its platform withholds the capability, so the host can tell a machine that is quiet apart from one that is blind.