diff --git a/README.md b/README.md index 1832b1920..c7ecc1579 100644 --- a/README.md +++ b/README.md @@ -142,7 +142,7 @@ and Recovery desktop history-table layout are all aligned. - **[AI Features](docs/AI.md)**: Pulse Assistant (Chat) and Pulse Patrol documentation. - **[Multi-Tenant](docs/MULTI_TENANT.md)**: Enterprise multi-tenant setup and configuration. - **[Troubleshooting](docs/TROUBLESHOOTING.md)**: Solutions to common issues. -- **[Agent Security](docs/AGENT_SECURITY.md)**: Details on checksum-verified updates and verification. +- **[Agent Security](docs/AGENT_SECURITY.md)**: Agent privilege model, Proxmox API-only choices, and checksum/signature verification. - **[Docker Monitoring](docs/DOCKER.md)**: Setup and management of Docker agents. - **[Unified Navigation](docs/MIGRATION_UNIFIED_NAV.md)**: Guide to the new task-based navigation. diff --git a/docs/AGENT_SECURITY.md b/docs/AGENT_SECURITY.md index 575671557..8ecc27b8f 100644 --- a/docs/AGENT_SECURITY.md +++ b/docs/AGENT_SECURITY.md @@ -6,10 +6,11 @@ Pulse agents incorporate several security mechanisms to ensure that the code run Pulse's Linux/systemd installer runs the unified agent as `root` by default. That is intentional for full host telemetry: disk SMART data, mdadm/RAID state, -temperature sensors, Docker or Podman socket reads, Proxmox host details, and -some NAS/platform integrations commonly require root or equivalent local -privileges. Running the service as a lower-privilege user may work for a narrow -subset of metrics, but it is not a supported full-telemetry profile today. +temperature sensors, Docker or Podman socket reads, Proxmox host-local details +that are not available through the API, and some NAS/platform integrations +commonly require root or equivalent local privileges. Running the service as a +lower-privilege user may work for a narrow subset of metrics, but it is not a +supported full-telemetry profile today. Treat a host agent like other infrastructure monitoring software with local root read access: @@ -20,6 +21,11 @@ root read access: remediation; - update from signed release assets rather than arbitrary branch snapshots. +The agent is primarily an outbound reporter to your Pulse server. By default it +also exposes local health and Prometheus endpoints on `:9191`; set +`--health-addr 127.0.0.1:9191` to bind that surface to loopback, or +`--health-addr ""` to disable it when you do not scrape agent-local metrics. + Command execution is disabled by default. It can be enabled with `--enable-commands`, `PULSE_ENABLE_COMMANDS=true`, or the centralized agent command setting after enrollment. Leave it disabled for read-only monitoring. @@ -27,6 +33,32 @@ When enabled, commands still flow through Pulse's command policy and approval surfaces instead of silently turning every agent into an unrestricted remote shell. +## Proxmox Deployment Choices + +You do not need a Pulse agent on every Proxmox-related host just to see basic +cluster inventory and utilization. Start with the least-privilege path that +answers your monitoring question: + +| Goal | Recommended path | Root agent needed? | +|---|---|---| +| PVE/PBS/PMG inventory, node status, VM/container status, storage usage, and normal Proxmox API metrics | Add the Proxmox connection with a read-only or narrowly scoped API token | No | +| VM guest disk and memory details through QEMU Guest Agent | Use Proxmox API permissions such as `VM.GuestAgent.Audit` and `VM.GuestAgent.FileRead` where supported | No host agent for the Proxmox node | +| Docker/Podman containers inside a VM or LXC | Install the agent inside that VM/LXC with Docker/Podman monitoring enabled | Usually requires root or Docker socket-equivalent access | +| Host SMART, temperatures, local ZFS/Ceph/mdadm detail, arbitrary mount reads, and full host telemetry | Install the agent on that host | Yes, for the supported full-telemetry profile | +| Kubernetes node/pod monitoring from a cluster | Use the Kubernetes agent/DaemonSet profile | Depends on whether host metrics are enabled | + +If Proxmox API data is enough for your use case, prefer API-only monitoring and +do not install a host agent just because the installer exists. Install agents +where you need data that Proxmox cannot provide through its API, or where the +data lives inside a guest/container rather than at the Proxmox node layer. + +Running `pulse-agent` as a custom non-root systemd user is possible by editing +the service unit, but it is not a supported full-telemetry mode today. Expect +gaps in SMART, temperature, Docker socket, ZFS/Ceph/mdadm, mount, and platform +integration data unless you deliberately grant equivalent capabilities or group +access. If you choose that route, treat it as a local hardening profile and +verify the exact metrics you care about after the change. + ## Supply-Chain Boundary The agent self-update path is not just "download the latest binary and run it". @@ -40,6 +72,12 @@ release-pinned, signature-verified server installer flow documented in [README.md](../README.md) and [INSTALL.md](INSTALL.md), then use the agent install command generated by your own Pulse server. +For the server installer, avoid `latest` when you want a tighter change-control +boundary. Download a specific release tag, verify the `install.sh.sshsig` +signature, and pass that same tag to `bash install.sh --version`. Agent +self-updates still verify checksum headers, and release builds require +signatures when a trusted update key is embedded. + ## Self-Update Security The agent's self-update mechanism is critical for security and stability. To prevent supply chain attacks or compromised update servers from distributing malicious or broken agents, Pulse employs a rigorous verification process. diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 26dae8dc9..99fe4b9b4 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -150,7 +150,13 @@ Pulse is secure by default. On first launch, you must retrieve a **Bootstrap Tok - Set your **Admin Username** and **Password** (or let Pulse generate one). - Pulse generates an **API token** for agents and automations. - Copy the credentials before leaving the page. -4. Open **Settings → Infrastructure → Install on a host** and install the unified agent on each host you want monitored. +4. Open **Settings → Infrastructure → Install on a host** and install the + unified agent only on hosts where you need agent-provided telemetry. For + Proxmox, start with API-only monitoring when inventory, node status, + VM/container status, and storage metrics are enough; use agents for + inside-guest Docker/Podman visibility, host SMART/temperature data, local + ZFS/Ceph/mdadm detail, or other telemetry that requires local host access. + See [Agent Security](AGENT_SECURITY.md). > **Note**: If you configure authentication via environment variables (`PULSE_AUTH_USER`/`PULSE_AUTH_PASS`), the bootstrap token is automatically removed and this step is skipped. diff --git a/docs/README.md b/docs/README.md index b94924854..59c04d43c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -57,7 +57,7 @@ All other documents are supporting references unless explicitly required for evi - **[Privacy](PRIVACY.md)** – What leaves your network (and what doesn’t). - **[OIDC / SSO](OIDC.md)** – OIDC Single Sign-On configuration (Authentik, Keycloak, Azure AD, etc.). - **[Proxy Auth](PROXY_AUTH.md)** – Authentik/Authelia/Cloudflare proxy authentication configuration. -- **[Agent Security](AGENT_SECURITY.md)** – Agent self-update verification and API security. +- **[Agent Security](AGENT_SECURITY.md)** – Agent privilege model, Proxmox API-only choices, and self-update verification. ## 📖 Advanced Topics (Relay / Pro / legacy Pro+ / Cloud) diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md index a4bd35d0b..723b6eeeb 100644 --- a/docs/UNIFIED_AGENT.md +++ b/docs/UNIFIED_AGENT.md @@ -3,6 +3,14 @@ The unified agent (`pulse-agent`) combines host, Docker, and Kubernetes monitoring into a single binary. It replaces older split-agent installs with one deployment and one service for simpler operations. Install it on each host you want Pulse to monitor. This is the primary monitoring path for infrastructure onboarding. +For Proxmox, install the agent only where you need telemetry that the Proxmox +API cannot provide, such as inside-guest Docker/Podman visibility, host SMART +and temperature data, local ZFS/Ceph/mdadm detail, or arbitrary mount reads. +Basic Proxmox inventory and utilization can use a read-only or narrowly scoped +Proxmox API token instead. See [Agent Security](AGENT_SECURITY.md) for the +root-service trade-off, restricted-user expectations, and supply-chain +verification guidance. + > Note: For temperature monitoring, use `pulse-agent --enable-proxmox` (recommended) or SSH-based collection. The legacy sensor proxy has been removed. See `docs/TEMPERATURE_MONITORING.md`. ## Quick Start @@ -92,6 +100,9 @@ curl -fsSL http://:7655/install.sh | \ | `--log-level` | `LOG_LEVEL` | Log verbosity (`debug`, `info`, `warn`, `error`) | `info` | | `--health-addr` | `PULSE_HEALTH_ADDR` | Health/metrics server address | `:9191` | +Use `--health-addr 127.0.0.1:9191` when only local Prometheus scraping needs +the health/metrics endpoint, or `--health-addr ""` to disable that listener. + **Token resolution order**: `--token` → `--token-file` → `PULSE_TOKEN` → `/var/lib/pulse-agent/token`. ### Advanced Flags diff --git a/docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-agent-security-2026-05-04.md b/docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-agent-security-2026-05-04.md new file mode 100644 index 000000000..8f4e9879c --- /dev/null +++ b/docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-agent-security-2026-05-04.md @@ -0,0 +1,34 @@ +# Documentation Currentness Agent Security Follow-Up + +- Date: `2026-05-04` +- Lane: `L9` +- Related discussion: `#1453` + +## Context + +Discussion `#1453` relayed a Proxmox community question about whether Pulse +agents should run as `root`, whether API-only monitoring is enough for +read-only Proxmox use cases, and what supply-chain risk exists when running an +installer as `root`. The existing agent security guide already documented the +Linux/systemd root default and checksum/signature verification, but it did not +clearly separate Proxmox API-only monitoring from host/guest agent installs. + +## Outcome + +The active public docs now make the Proxmox deployment choice explicit: + +- start with Proxmox API-only monitoring when inventory, node status, + VM/container status, storage usage, and normal API metrics are enough; +- install agents only where Pulse needs data that Proxmox cannot provide + through the API, such as inside-guest Docker/Podman visibility, host SMART + and temperature data, local ZFS/Ceph/mdadm detail, arbitrary mount reads, or + Kubernetes node/pod reporting; +- treat custom non-root systemd service users as local hardening profiles, not + supported full-telemetry mode; +- describe the agent-local health/metrics listener and the `--health-addr` + options for loopback binding or disabling; +- keep release-pinned, signature-verified server installer guidance visible + alongside agent checksum/signature update verification. + +This keeps the project response in durable official guidance rather than a +social-thread reply. diff --git a/docs/release-control/v6/internal/status.json b/docs/release-control/v6/internal/status.json index 9706b0d2c..7ef41f9dd 100644 --- a/docs/release-control/v6/internal/status.json +++ b/docs/release-control/v6/internal/status.json @@ -872,6 +872,11 @@ "path": "docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-2026-03-13.md", "kind": "file" }, + { + "repo": "pulse", + "path": "docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-agent-security-2026-05-04.md", + "kind": "file" + }, { "repo": "pulse", "path": "docs/release-control/v6/internal/SOURCE_OF_TRUTH.md", @@ -4322,6 +4327,12 @@ "kind": "file", "evidence_tier": "local-rehearsal" }, + { + "repo": "pulse", + "path": "docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-agent-security-2026-05-04.md", + "kind": "file", + "evidence_tier": "local-rehearsal" + }, { "repo": "pulse", "path": "docs/release-control/v6/internal/records/documentation-currentness-and-legacy-cleanup-contribution-policy-2026-05-01.md",