Skip to content

Self-hosted monitoring for homelabs: host and container metrics and uptime checks from all your machines in one dashboard, with an optional AI agent that diagnoses incidents and suggests fixes.

docs: say which host files the root collector can read (#220)

Karlo Kajba Šimanić8e5d0773d044
diff --git a/SECURITY.md b/SECURITY.md
index 0d89e90..f02d31d 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -516,7 +516,7 @@ development stack's `https` profile, which uses the official image's defaults.
| frontend | `nginx` (port 8080 inside the container, so it needs no capability to listen) | none | read-only; cache, pid file and the `TRUSTED_PROXIES` file in memory |
| redis | `redis` | none while running | read-only, data in its volume |
| postgres | `postgres` | none while running | read-only, data in its volume, socket and `/tmp` in memory |
-| collector | root | none, so it can't read other users' files (see below) | read-only |
+| collector | root | none, so it reads only what root owns or everyone may read, not other users' private files (see below) | read-only |
| collector-gate | root, workers as `nginx` | `CHOWN`, `SETUID`, `SETGID` | read-only, cache and pid in memory |
| docker-proxy | root (to open the Docker socket) | none | read-only, no network |
| system-helper, port-owners (optional) | root | `SYSLOG`; `SYS_PTRACE` and `DAC_READ_SEARCH` (see their sections above) | read-only, no network |
@@ -533,8 +533,13 @@ ran as root) would no longer be writable.
- The collector mounts the host filesystem read-only at `/hostfs` to read disk usage and a few
files such as `/etc/os-release`.
- The collector runs with all capabilities dropped, a read-only filesystem and `no-new-privileges`.
- Without `CAP_DAC_OVERRIDE`, even as root it can't read other users' private files (SSH keys,
- `.env`) through the `/hostfs` mount; only files readable by "other" or owned by root are visible.
+ Without `CAP_DAC_OVERRIDE`, root is treated like any other user: through the `/hostfs` mount it can
+ read files that everyone may read and files that **root itself owns**, and nothing else. So another
+ user's private files (their SSH keys, a `.env` with mode `0600` in their home) are out of reach, but
+ root-owned files are not: `/etc/shadow`, `/root/.ssh`, and any `.env` or key file that belongs to root,
+ which includes the dashboard's own `.env` when the stack was installed as root. The collector reads none
+ of these (it opens a fixed list of files); this is what an attacker who took over the collector could
+ read. To narrow it, keep secrets in files owned by a user other than root with mode `0600`.
Its one kernel-level allowance is a namespaced `net.ipv4.ping_group_range` sysctl, so availability
ping checks can use an unprivileged ICMP socket; it is not a capability and grants no raw-socket access.
- The Docker proxy is reached through a Unix socket in a volume shared only with the collector. It
diff --git a/collector-compose.yml b/collector-compose.yml
index 84dc2a3..92a1800 100644
--- a/collector-compose.yml
+++ b/collector-compose.yml
@@ -28,8 +28,9 @@ services:
# Summary from the optional system helper (read-only; empty unless that profile runs).
- system_events:/helper:ro
- docker_proxy_socket:/run/docker-proxy:ro
- # Read-only host view, no capabilities: as root it then can't read other users' private
- # files (SSH keys, .env) even though / is mounted.
+ # Read-only host view, no capabilities: as root it then reads only what root owns or everyone may
+ # read, not other users' private files, even though / is mounted. Root-owned files (/etc/shadow,
+ # /root/.ssh, a root-owned .env) stay readable; see SECURITY.md.
cap_drop: [ALL]
read_only: true
security_opt:
diff --git a/compose.yml b/compose.yml
index 8a704c8..b5de439 100644
--- a/compose.yml
+++ b/compose.yml
@@ -180,8 +180,9 @@ services:
# Summary from the optional system helper (read-only; empty unless that profile runs).
- system_events:/helper:ro
- docker_proxy_socket:/run/docker-proxy:ro
- # Read-only host view, no capabilities: as root it then can't read other users' private
- # files (SSH keys, .env) even though / is mounted.
+ # Read-only host view, no capabilities: as root it then reads only what root owns or everyone may
+ # read, not other users' private files, even though / is mounted. Root-owned files (/etc/shadow,
+ # /root/.ssh, a root-owned .env) stay readable; see SECURITY.md.
cap_drop: [ALL]
read_only: true
security_opt:
@@ -317,7 +318,8 @@ services:
- frontend
networks:
- # Redis and PostgreSQL are reachable only by the backend; the collector can reach the backend and nothing else.
+ # Redis and PostgreSQL are reachable only by the backend and the agent worker; the collector can reach the backend
+ # and nothing else.
data:
internal: true
front:
diff --git a/docker-compose.server.yml b/docker-compose.server.yml
index 0e6b2bf..7f5ff29 100644
--- a/docker-compose.server.yml
+++ b/docker-compose.server.yml
@@ -192,8 +192,9 @@ services:
# Summary from the optional system helper (read-only; empty unless that profile runs).
- system_events:/helper:ro
- docker_proxy_socket:/run/docker-proxy:ro
- # Read-only host view, no capabilities: as root it then can't read other users' private
- # files (SSH keys, .env) even though / is mounted.
+ # Read-only host view, no capabilities: as root it then reads only what root owns or everyone may
+ # read, not other users' private files, even though / is mounted. Root-owned files (/etc/shadow,
+ # /root/.ssh, a root-owned .env) stay readable; see SECURITY.md.
cap_drop: [ALL]
read_only: true
security_opt:
diff --git a/docs/adding-servers.md b/docs/adding-servers.md
index dac17cc..418af86 100644
--- a/docs/adding-servers.md
+++ b/docs/adding-servers.md
@@ -68,7 +68,7 @@ EOF
| `/proc:/host/proc:ro` | Host CPU, memory, load, network, uptime, boot ID, OOM counter and kernel flags. |
| `/:/hostfs:ro` | Disk usage of every mounted filesystem, hostname, OS name and `/etc/machine-id`. |
| `docker-proxy` | The only container with the Docker socket. It answers container list, inspect (without environment variables) and stats, and nothing else. |
-| `cap_drop: [ALL]`, `read_only: true` | The collector can't read other users' private files through `/hostfs`, or write outside its state volume. |
+| `cap_drop: [ALL]`, `read_only: true` | Through `/hostfs` the collector reads only what root owns or everyone may read, not other users' private files, and it can't write outside its state volume. |
| `collector_state` volume | Keeps the token after approval, so restarts don't need approval again. |
To remove a collector completely:
diff --git a/docs/containers.md b/docs/containers.md
index f13c143..f1d3566 100644
--- a/docs/containers.md
+++ b/docs/containers.md
@@ -243,8 +243,9 @@ health, restarts, CPU, memory, swap and volumes. Each figure is explained in [Me
- It is one Python file using only the standard library: no third-party packages to audit or keep updated.
- It reads the host's `/proc` and its filesystem through **read-only** mounts (`/proc:/host/proc:ro`,
`/:/hostfs:ro`). It runs with **all capabilities dropped**, a read-only root filesystem and
- `no-new-privileges`, so although it runs as root it can't read other users' private files (SSH keys,
- `.env` files) on the host.
+ `no-new-privileges`, so although it runs as root it can't read other users' private files (their SSH
+ keys, their `.env` files) on the host. Files that root itself owns stay readable; see
+ [SECURITY.md](../SECURITY.md#other-exposure-to-be-aware-of).
- Container data comes from the Docker proxy through a Unix socket, not from Docker directly; the
collector has no Docker socket.
- If the optional helpers run, it also reads their summary files from the shared `system_events` volume.