Files
cairnobs/docs/windows.md
T
jcoffey-dev 77dac1c9c4
ci / check (pull_request) Successful in 5m32s
ci / postgres (pull_request) Successful in 10m31s
Ready to be read: SECURITY.md, the docs site, generic names
SECURITY.md says where to report a problem ([email protected]) and
what's in scope. The README points at docs.cairnobs.org for people
installing Cairn OBS.

The tests, examples and notes named a real fleet: its host names, its
mesh and desk link, a public address, its site and its backups. They're
now node1, node2 and so on, wg-desk, 10.30/10.31, 203.0.113.52 (TEST-NET-3),
Lisbon, wiki-db and photos.

docs/install.md's Windows paragraph said no VMs; the agent now reports
certificate stores, the event log and Hyper-V's VMs, on amd64 and arm64.
2026-11-15 13:24:15 -07:00

10 KiB
Raw Permalink Blame History

Windows agent: design note

Status: decided 2026-11-14 (Decisions, at the end): every question went the recommended way. Built: steps 1–4 under Plan (2026-11-14), and run on a Windows Server 2025 evaluation VM (decision 5) the same day; what that turned up was fixed in #10. Steps 5–8 built 2026-11-15.

John, 2026-11-12: "will need windows agent as well". Plenty of the fleets Cairn OBS is for have Windows servers beside the Linux ones (domain controllers, file servers, SQL Server, the odd vendor appliance), and today they're invisible to it.

What there is now

obs-beacon-agent is Linux only. It reads /proc and statfs for the host, systemd over D-Bus for units, and a root helper on a Unix socket for containers, the map sample, libvirt, the SMBIOS UUID and certificate files. Everything else it does is plain Go and would build anywhere: enrolling and mTLS to obs-beacond, the queue of unsent reports, checks, fetches of status pages, the certificate scan of listening ports, the cluster watcher and the platform readers (Proxmox, vSphere, Nutanix, Pure). GOOS=windows go build stops at the first Linux-only file.

What a Windows agent reports

The same report, so obs-beacond judges a Windows host with the code it has; where Windows has no answer the field stays empty.

report field Windows source
os, kernel product name and build (RtlGetVersion, the registry's ProductName, DisplayVersion)
uptime_s GetTickCount64
cpus, cpu_pct GetSystemTimes, between reports, as on Linux
load none: Windows has no load average. Left at zero, and the UI shows "—" for Windows hosts rather than 0.00
mem GlobalMemoryStatusEx; the page file as swap
disks fixed volumes (GetLogicalDriveStrings, GetDiskFreeSpaceEx); mount points by drive letter or folder
net GetIfTable2 byte counters, loopback and virtual adapters left out as on Linux
machine_uuid SMBIOS from GetSystemFirmwareTable('RSMB'), so a Windows VM links to its VMware, Hyper-V, Proxmox or KubeVirt host as Linux VMs do
units, services Windows services from the Service Control Manager: Running → active, Stopped with start type Automatic → failed (a service that should be running isn't), the rest inactive. expected.yaml names them by service name (units: [W32Time, MSSQLSERVER])
checks, fetches, certs unchanged: plain Go
map listeners and connections with their owning process from GetExtendedTcpTable/GetExtendedUdpTable, addresses from GetAdaptersAddresses; the same shrinking and the same rule that Internet clients' addresses never leave the host (maps.md)
containers, vms, backups, cert_files not at first (see Later)

No cgo: golang.org/x/sys/windows (already in the module) has every call above, so the Windows agent cross-builds on Linux like the rest.

Privileges

On Linux the agent runs unprivileged and a small root helper does the few things that need root. Windows needs no helper for the list above: a service running as its own virtual account (NT SERVICE\obs-beacon-agent, which Windows creates with the service, with no password and no rights beyond a normal user's) can query the Service Control Manager, read the TCP tables with their process IDs, the firmware table and the counters. Two things it can't see without more: the names of a few protected processes in the map (shown as "pid 1234"), and the event log's Security channel (not needed).

Install

A zip per architecture in the release (obs-beacon-agent_<v>_windows_amd64.zip, _windows_arm64.zip: the exe, agent.yaml.example, the licence files), checked against SHA256SUMS as the Linux packages are. The exe installs itself:

obs-beacon-agent.exe service install -config C:\ProgramData\obs-beacon\agent.yaml

registers the service (automatic start, restart on failure, the virtual account), puts the config and state under C:\ProgramData\obs-beacon with access for that account and Administrators only, and starts it. service uninstall takes it away. Join tokens get a PowerShell twin of install.sh: install.ps1 -Join cobsj1_…, copied from the Hosts page as the Linux line is, which downloads the zip, checks its hash, installs and joins. An MSI can come later for people who deploy with Group Policy or Intune (wixl from msitools builds one on Linux).

Signing

Windows warns about unsigned executables (SmartScreen, and some endpoint protection quarantines them), so a public release wants a code-signing certificate. That costs money: Azure Artifact Signing is the cheapest ($9.99 a month; whether a young LLC qualifies is unclear), a classic OV certificate a few hundred dollars a year. While the code is private this doesn't matter: the release's SHA256SUMS (and its minisign signature, once the repo has MINISIGN_SECRET_KEY) say the files are ours.

Testing

Unit tests for the parts that are plain Go run on Linux as now; the Windows calls need Windows. Options, with what each costs:

  • A Windows Server 2025 evaluation VM on a development workstation (free for 180 days, renewable by reinstalling): installs QEMU/libvirt on a development workstation and downloads the ~6 GB ISO from Microsoft. Also gives a real libvirt host for the libvirt reader, which has only been tested against fakes.
  • GitHub Actions Windows runners: free minutes, but the private code goes to GitHub before launch.
  • Cross-build and unit tests only until launch, real Windows at the first user who has one: cheapest, least sure.

Plan

  1. Builds and reports the host. Linux-only code behind build tags; the Windows host collector (table above, less units and map); the Windows service and service install|uninstall; the zip in releases; obs-beacond and the UI show a Windows host properly ("—" for load, "Windows services" for systemd units, the OS).
  2. Services: the SCM as units, and the services list for adopting what's running.
  3. Map sample and certificate scan: TCP/UDP tables and adapters, and the existing scan of listening ports.
  4. install.ps1 and join tokens from the Hosts page.

Then, from John's "work it out make it sexy and relavant" (2026-11-15):

  1. The machine's certificate stores into the certificate inventory (built 2026-11-15): My and WebHosting by default (cert_stores), read-only as the service's own account, places of kind store at Cert:\LocalMachine\My\<thumbprint>. With the port scan, an IIS or RDP binding still serving the old certificate after a renewal shows as "renewed but not reloaded", as on Linux.

  2. arm64 (built 2026-11-15): a windows_arm64 zip beside the amd64 one; install.ps1 picks by the machine's architecture.

  3. The event log (built 2026-11-15): every five minutes the agent reads the errors and criticals of the last day in System and Application through wevtapi (at most 2,000 a log, newest first), grouped by log, source and event ID with the latest one's message as Windows formats it, on the host's page ("Event log"). A critical event in the last hour (Kernel-Power 41, a failing disk) is a warning; errors are listed, never alerted on: Windows logs plenty nobody needs waking for. event_log: false turns it off. The service's own account reads both logs on Server 2025 without extra rights.

  4. Hyper-V VMs (built 2026-11-15), like libvirt's: each report, the agent asks WMI's root\virtualization\v2 (COM through x/sys/windows, no cgo, no new dependency) for every VM's state and health, BIOS GUID, generation, vCPUs, memory and automatic start action. They're the host's VMs on its page and the workloads list, judged as libvirt's are, and an agent inside one links to it by the BIOS GUID (its SMBIOS UUID). Nothing is read or said where Hyper-V isn't installed; hyperv: false turns it off.

    What the agent's account needs. Hyper-V shows its VMs only to Administrators and Hyper-V Administrators; anyone else gets an empty list. Windows has no read-only Hyper-V role, and Hyper-V Administrators can also start, stop and change VMs, so the agent isn't added on its own: on a Hyper-V host without it, the host page and a warning say so ("can't read its VMs"), and an admin chooses either

    Add-LocalGroupMember -Group "Hyper-V Administrators" -Member "NT SERVICE\obs-beacon-agent"
    Restart-Service obs-beacon-agent
    

    or hyperv: false. The agent only ever reads (four WQL SELECTs); the group is what Windows asks for, not what the agent uses. Tested on Windows Server 2025 with Hyper-V nested under KVM: without the group, the warning; with it, every VM.

An MSI waits for the code-signing decision (Signing): unsigned, it adds little over the zip and install.ps1.

Questions

  1. Privileges. (a) The service's own virtual account, no admin, no helper. (b) LocalSystem: everything readable, but the agent then holds the most powerful account on the machine.
  2. What first. (a) Steps 1–4 as above, the rest later. (b) Steps 1–2 only (host and services) until someone runs it.
  3. Install. (a) Zip + service install + install.ps1; an MSI later. (b) An MSI first.
  4. Signing. (a) Unsigned while private; decide on a certificate before launch. (b) Buy Azure Artifact Signing now ($9.99/month).
  5. Testing. (a) A Windows Server 2025 evaluation VM on a development workstation (installs QEMU/libvirt there, ~6 GB download, nothing billed). (b) GitHub Actions Windows runners (private code on GitHub). (c) Cross- build and unit tests only until launch.

IBM i (John, 2026-11-12) is a separate note: no Go agent there; the idea so far is reading it agentlessly through IBM's Mapepire server with a read-only profile.

Decisions

John, 2026-11-14: "go with you recommendations".

  1. The service's own virtual account, no admin, no helper.
  2. Steps 1–4 under Plan; the event log, certificate store, Hyper-V, an MSI and arm64 later.
  3. Zip + service install + install.ps1; an MSI later.
  4. Unsigned while private; a code-signing certificate is decided before launch.
  5. A Windows Server 2025 evaluation VM on a development workstation (QEMU/libvirt there, the ISO from Microsoft; nothing billed).