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.

• Machine questions (Linux: observe:folders, observe:journal, observe:logins, observe:cert). What a host would otherwise ask the person to run a command for, answered here. Each value is checked against its written rule before anything is read or run, and a refusal says which rule it broke.

  • observe:folders <absolute path> [depth 1-3, default 2]: the 25 largest folders under the path, down to the depth, and the total, on the path's own filesystem only, counted as du -x counts (disk blocks, a file with several links once). Only folders are named, never files. What could not be read, and filesystems mounted under the path, are listed against the folder that holds them, with a reason and a count. A relative path, one containing .., and /proc, /sys and /dev (or a link leading into them) are refused. The walk shares the 20-second op budget; one that runs out answers with what it measured, marked incomplete. It follows no link, and a folder swapped for one while it reads is listed as changed. While four earlier walks are still inside a read that has not returned, no new walk starts.
  • observe:journal <unit> [minutes 1-60, default 15]: one systemd unit's journal over the window, up to 5000 lines and 200 KB, newest kept. A name with no type is a service. The unit must be in systemd's unit-name alphabet and one this machine has, loaded or installed; otherwise it is refused, with the units whose names come close.
  • observe:logins [hours 1-168, default 24]: sshd's failed logins counted and ranked by source address and by user name (20 each), and the last 20 accepted logins with user, source, method and time. A user name the other side sent is cut to 32 characters, and anything outside the characters account names use reads ?. No raw line, key fingerprint or password is returned. Only lines sshd wrote as root are read (_UID=0), so another account cannot add login lines or bury the real ones.
  • observe:cert <port> [server name]: the certificate this machine's own TCP listener on the port serves: subject, names, issuer, dates, days left, and whether the chain verifies against this machine's roots for that name. The port must be one ss shows listening here.

  observe:journal and observe:logins first check that the bastion can read the system journal (root, as the networked install runs it, or a member of systemd-journal). An account that cannot is shown only its own lines by journalctl, which would read as a quiet machine, so they answer with the reason instead, and observe:logins reports its counts as -1.

The observe ops that send traffic are observe:net, observe:k8s (a read-only query of a cluster API), 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) and observe:cert, which connects only to this machine: loopback first, then an address of this machine the listener is bound to. 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.