From b85e70344b23c98b3881bd8763713cc939e2d0c7 Mon Sep 17 00:00:00 2001 From: Bobban Rydh Date: Tue, 6 Oct 2026 22:05:19 +0200 Subject: [PATCH] Document the agent and outgoing-connection protections Co-Authored-By: Claude Sonnet 5.5 --- README.md | 13 +++++++++++++ agent/windows/README.md | 2 ++ 2 files changed, 15 insertions(+) diff --git a/README.md b/README.md index 344d1f7..a448fae 100644 --- a/README.md +++ b/README.md @@ -218,6 +218,19 @@ changes a list once you add it and save. (Statistics Sweden used to publish this stopped after 2023.) Names are kept to letters, digits and hyphens so they work as hostnames; å, ä and ö become a, a and o. +**Agents and what the server connects to** — the agents only push: the server replies "received" and nothing more, so it has no way to +make a server run anything. Each server has its own token (kept only as a hash), which can do one thing: replace that server's own report. +The Linux agent hands its token to curl on standard input and keeps its payload in a private temporary directory, so neither is visible +to other users on the machine, and its systemd unit runs with the usual restrictions (no new privileges, read-only system, private /tmp). +On Windows the agent's folder is limited to SYSTEM and Administrators. The agent endpoint checks the token before it reads a report, takes +reports of several MB, and trims overlong text rather than rejecting the whole report. **After upgrading, re-run the install one-liner on +each server** to pick this up — an installed agent keeps its own copy of the script and doesn't update itself. +A few features connect to a host somebody typed in: the certificate check on a secret, the WHOIS server a registry names, and the port +scanner. These refuse this server itself (loopback), link-local addresses and the cloud metadata addresses (169.254.169.254 and its +relatives), and connect to the address they checked rather than looking the name up a second time. LAN hosts are fine for certificate +checks and scans; a WHOIS server must be public. IDs in a request (a device, a node, a DNS record) are checked against what a real ID +looks like before they go into a call to a connected system. `npm test --workspace server` covers all of this. + **Privacy** — a page every signed-in user can open that says what this installation stores (accounts, sign-in sessions with their IP and browser, the audit and diagnostic logs, server reports, the secrets tracker, credentials), where data diff --git a/agent/windows/README.md b/agent/windows/README.md index 62d6cd5..296aa46 100644 --- a/agent/windows/README.md +++ b/agent/windows/README.md @@ -5,6 +5,8 @@ scheduled tasks, plus hostname, IP addresses, CPU / memory / disk usage and list runs as a scheduled task (as SYSTEM, every 15 minutes) and pushes to `POST /api/agent/report`, so the machine never needs to be reachable from Homelab Manager. + +The installer limits `%ProgramData%\HomelabManager` to SYSTEM and Administrators. The agent runs as SYSTEM, so anyone who could change its script could run code as SYSTEM; the folder is not left to inherit ProgramData's default permissions. Re-running the install one-liner applies this to an existing install. ## Install 1. In Homelab Manager, **Servers → Manage servers → Add a server**, choose **Windows** as the