Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Explain the distinct Linux agent privilege profiles
pulse-triage[bot]7ede32f27a77
diff --git a/docs/PRODUCTION_SECURITY.md b/docs/PRODUCTION_SECURITY.mdindex b0d61e87b0..bdd92e4c4f 100644--- a/docs/PRODUCTION_SECURITY.md+++ b/docs/PRODUCTION_SECURITY.md@@ -15,7 +15,7 @@ utilization, storage, guests, and status.| Collection path and coverage | Privilege boundary || --- | --- || **Proxmox API only:** PVE, PBS, and PMG inventory; node and guest state; storage usage; and normal API metrics | No Pulse software runs on the Proxmox host. Use a dedicated read-only or narrowly scoped API token. |-| **Proxmox API plus host agent:** API coverage plus host-local SMART, temperatures, ZFS/Ceph/mdadm detail, arbitrary mount capacity, and full LXC filesystem capacity | The Linux agent runs as `root` by default for the supported full-telemetry profile. |+| **Proxmox API plus host agent:** API coverage plus host-local telemetry; the available readings depend on the chosen agent profile | The full-telemetry Linux agent runs as `root` by default. Compare the [Linux agent profiles](#choose-a-linux-agent-profile) before granting host access. || **Guest-local agent:** Host metrics and optional Docker/Podman inventory inside a VM or LXC | The agent is trusted inside that guest only; it does not grant Pulse access to the hypervisor. |For most Proxmox installations, begin with **Settings → Infrastructure**@@ -66,13 +66,45 @@ unmarked installations remain in a visible `legacy` compatibility state duringthe migration. Agent Doctor reports both local authority and credential scopeso an over-scoped monitoring install is not mistaken for a safe default.-On standard Linux systemd hosts the installer also offers a supported-least-privilege profile: `--least-privilege` runs the service as a dedicated-`pulse-agent` system user, with optional `--grant-smart` and `--grant-pct`-flags that restore SMART and Proxmox LXC filesystem collection through-exact-command sudoers grants. Command execution and `pct exec` guest inventory-stay root-profile features. If API data is sufficient, API-only monitoring-remains the cleanest least-privilege choice of all — it needs no agent.+### Choose a Linux agent profile++If API data is sufficient, keep API-only monitoring: it needs no host agent.+For standard Linux systemd hosts that need local readings, there are **two+different least-privilege profiles**, not one interchangeable set of flags:++- **Typed-helper profile — `--least-privilege --enable-privileged-helper`.**+ The networked collector runs as `pulse-agent`, with root-owned binaries and+ no membership in the rootful Docker group. A separate root helper, isolated+ from the host network, handles bounded SMART, LXC filesystem and container+ summary reads, and signed collector-update transactions. This reduces the+ collector's authority; it does not remove all root code. Do not combine it+ with `--grant-smart` or `--grant-pct`, or remove the helper's `PrivateNetwork`+ isolation to recover a missing reading.+- **Legacy compatibility profile — `--least-privilege` alone.** The collector+ uses a non-root service account, but can join the `docker` group when Docker+ monitoring is enabled. Access to a rootful Docker socket is root-equivalent;+ a non-root username alone does not establish isolation. Optional+ `--grant-smart` and `--grant-pct` use scoped sudo wrappers, not the typed+ helper. An active sudo grant sets `NoNewPrivileges=false`; without those+ grants it stays enabled. These are deliberate privilege trade-offs, not+ fixes to apply automatically when telemetry is missing.++The typed-helper profile is **opt-in, not the default or full-telemetry parity**.+For rootful Docker or Podman it supplies container summaries, not container+stats, image-update checks or lifecycle actions. Full container monitoring+needs a supported collector-owned rootless socket; do not substitute a rootful+socket to fill the gap. The collector cannot enable the combined command+profile. A separately enabled action runner has its own credential and trust+boundary; choosing the helper does not enable it.++Both least-privilege choices are limited to standard Linux systemd hosts, not+NAS appliances or non-systemd platforms; an unsupported-profile refusal is not+a reason to bypass the installer. Check the+[profile details](AGENT_SECURITY.md#least-privilege-agent-profile) and+[support and qualification limits](AGENT_SECURITY.md#safe-profile-support-and-qualification-matrix)+against the version you intend to install. Ordinary `--update` preserves the+installed profile; it does not migrate a root collector to the typed helper.+Changing profile is a separate planned operation, not a diagnostic step.See [Agent Security](AGENT_SECURITY.md) for the precise command, guest-access,update, and service-hardening boundaries.@@ -208,7 +240,9 @@ and measure their own workload.allowlist for a temporary discovery run.- [ ] Confirm inventory, storage, backup, replication, and alert behavior onone cluster before adding the rest.-- [ ] Add root agents only to hosts that need specific local telemetry; keep+- [ ] Add host agents only for needed local telemetry. Compare the+ [agent profiles](#choose-a-linux-agent-profile), including Docker socket+ authority and reduced telemetry, before choosing root or sudo grants. Keepcommands disabled unless there is a reviewed operational need.- [ ] Check existing inventory and provider identity before adding anothercluster; matching node names or VMIDs do not establish the same resource.diff --git a/frontend-modern/public/docs/PRODUCTION_SECURITY.md b/frontend-modern/public/docs/PRODUCTION_SECURITY.mdindex b0d61e87b0..bdd92e4c4f 100644--- a/frontend-modern/public/docs/PRODUCTION_SECURITY.md+++ b/frontend-modern/public/docs/PRODUCTION_SECURITY.md@@ -15,7 +15,7 @@ utilization, storage, guests, and status.| Collection path and coverage | Privilege boundary || --- | --- || **Proxmox API only:** PVE, PBS, and PMG inventory; node and guest state; storage usage; and normal API metrics | No Pulse software runs on the Proxmox host. Use a dedicated read-only or narrowly scoped API token. |-| **Proxmox API plus host agent:** API coverage plus host-local SMART, temperatures, ZFS/Ceph/mdadm detail, arbitrary mount capacity, and full LXC filesystem capacity | The Linux agent runs as `root` by default for the supported full-telemetry profile. |+| **Proxmox API plus host agent:** API coverage plus host-local telemetry; the available readings depend on the chosen agent profile | The full-telemetry Linux agent runs as `root` by default. Compare the [Linux agent profiles](#choose-a-linux-agent-profile) before granting host access. || **Guest-local agent:** Host metrics and optional Docker/Podman inventory inside a VM or LXC | The agent is trusted inside that guest only; it does not grant Pulse access to the hypervisor. |For most Proxmox installations, begin with **Settings → Infrastructure**@@ -66,13 +66,45 @@ unmarked installations remain in a visible `legacy` compatibility state duringthe migration. Agent Doctor reports both local authority and credential scopeso an over-scoped monitoring install is not mistaken for a safe default.-On standard Linux systemd hosts the installer also offers a supported-least-privilege profile: `--least-privilege` runs the service as a dedicated-`pulse-agent` system user, with optional `--grant-smart` and `--grant-pct`-flags that restore SMART and Proxmox LXC filesystem collection through-exact-command sudoers grants. Command execution and `pct exec` guest inventory-stay root-profile features. If API data is sufficient, API-only monitoring-remains the cleanest least-privilege choice of all — it needs no agent.+### Choose a Linux agent profile++If API data is sufficient, keep API-only monitoring: it needs no host agent.+For standard Linux systemd hosts that need local readings, there are **two+different least-privilege profiles**, not one interchangeable set of flags:++- **Typed-helper profile — `--least-privilege --enable-privileged-helper`.**+ The networked collector runs as `pulse-agent`, with root-owned binaries and+ no membership in the rootful Docker group. A separate root helper, isolated+ from the host network, handles bounded SMART, LXC filesystem and container+ summary reads, and signed collector-update transactions. This reduces the+ collector's authority; it does not remove all root code. Do not combine it+ with `--grant-smart` or `--grant-pct`, or remove the helper's `PrivateNetwork`+ isolation to recover a missing reading.+- **Legacy compatibility profile — `--least-privilege` alone.** The collector+ uses a non-root service account, but can join the `docker` group when Docker+ monitoring is enabled. Access to a rootful Docker socket is root-equivalent;+ a non-root username alone does not establish isolation. Optional+ `--grant-smart` and `--grant-pct` use scoped sudo wrappers, not the typed+ helper. An active sudo grant sets `NoNewPrivileges=false`; without those+ grants it stays enabled. These are deliberate privilege trade-offs, not+ fixes to apply automatically when telemetry is missing.++The typed-helper profile is **opt-in, not the default or full-telemetry parity**.+For rootful Docker or Podman it supplies container summaries, not container+stats, image-update checks or lifecycle actions. Full container monitoring+needs a supported collector-owned rootless socket; do not substitute a rootful+socket to fill the gap. The collector cannot enable the combined command+profile. A separately enabled action runner has its own credential and trust+boundary; choosing the helper does not enable it.++Both least-privilege choices are limited to standard Linux systemd hosts, not+NAS appliances or non-systemd platforms; an unsupported-profile refusal is not+a reason to bypass the installer. Check the+[profile details](AGENT_SECURITY.md#least-privilege-agent-profile) and+[support and qualification limits](AGENT_SECURITY.md#safe-profile-support-and-qualification-matrix)+against the version you intend to install. Ordinary `--update` preserves the+installed profile; it does not migrate a root collector to the typed helper.+Changing profile is a separate planned operation, not a diagnostic step.See [Agent Security](AGENT_SECURITY.md) for the precise command, guest-access,update, and service-hardening boundaries.@@ -208,7 +240,9 @@ and measure their own workload.allowlist for a temporary discovery run.- [ ] Confirm inventory, storage, backup, replication, and alert behavior onone cluster before adding the rest.-- [ ] Add root agents only to hosts that need specific local telemetry; keep+- [ ] Add host agents only for needed local telemetry. Compare the+ [agent profiles](#choose-a-linux-agent-profile), including Docker socket+ authority and reduced telemetry, before choosing root or sudo grants. Keepcommands disabled unless there is a reviewed operational need.- [ ] Check existing inventory and provider identity before adding anothercluster; matching node names or VMIDs do not establish the same resource.diff --git a/frontend-modern/src/features/docs/__tests__/productionAgentProfilesGuide.test.ts b/frontend-modern/src/features/docs/__tests__/productionAgentProfilesGuide.test.tsnew file mode 100644index 0000000000..b79409b327--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/productionAgentProfilesGuide.test.ts@@ -0,0 +1,89 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import { renderDocMarkdown } from '../docMarkdown';++const frontendRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');+const readDoc = (name: string) =>+ readFileSync(path.join(frontendRoot, '../docs', `${name}.md`), 'utf8');++function articleFor(name: string) {+ const article = document.createElement('article');+ article.innerHTML = renderDocMarkdown(readDoc(name), name);+ return article;+}++function profileChoice(article: HTMLElement) {+ const heading = article.querySelector('#choose-a-linux-agent-profile');+ expect(heading?.textContent).toBe('Choose a Linux agent profile');+ const section = document.createElement('section');+ for (let node = heading!.nextElementSibling; node && node.tagName !== 'H2';) {+ section.append(node.cloneNode(true));+ node = node.nextElementSibling;+ }+ return section;+}++describe('Production guide agent-profile choice', () => {+ it('distinguishes the two choices in the actual rendered list', () => {+ const choice = profileChoice(articleFor('PRODUCTION_SECURITY'));+ const profiles = [...choice.querySelectorAll('li')];+ expect(profiles).toHaveLength(2);+ expect(profiles[0].querySelector('code')?.textContent).toBe(+ '--least-privilege --enable-privileged-helper',+ );+ expect(profiles[1].querySelector('code')?.textContent).toBe('--least-privilege');+ const typed = profiles[0].textContent!.replace(/\s+/g, ' ');+ expect(typed).toContain('no membership in the rootful Docker group');+ expect(typed).toContain('does not remove all root code');+ expect(typed).toContain('Do not combine it with --grant-smart or --grant-pct');+ const legacy = profiles[1].textContent!.replace(/\s+/g, ' ');+ expect(legacy).toContain('rootful Docker socket is root-equivalent');+ expect(legacy).toContain('NoNewPrivileges=false');+ expect(legacy).toContain('scoped sudo wrappers, not the typed helper');+ });++ it('keeps reduced telemetry, platform limits and migration separate from installation advice', () => {+ const choice = profileChoice(articleFor('PRODUCTION_SECURITY'));+ const text = choice.textContent!.replace(/\s+/g, ' ');+ expect(text).toContain('opt-in, not the default or full-telemetry parity');+ expect(text).toContain('not container stats, image-update checks or lifecycle actions');+ expect(text).toContain('do not substitute a rootful socket');+ expect(text).toContain('separately enabled action runner has its own credential');+ expect(text).toContain('not NAS appliances or non-systemd platforms');+ expect(text).toContain('Ordinary --update preserves the installed profile');+ expect(text).toContain('not a diagnostic step');+ // Profile flags are choices, not a second unsigned installer recipe.+ expect(choice.querySelector('pre')).toBeNull();+ });++ it('routes both the first comparison and rollout checklist to the profile decision', () => {+ const article = articleFor('PRODUCTION_SECURITY');+ const links = article.querySelectorAll('a[href="#choose-a-linux-agent-profile"]');+ expect(links).toHaveLength(2);+ expect(article.querySelector('#choose-a-linux-agent-profile')).not.toBeNull();+ expect(links[0].closest('table')).not.toBeNull();+ expect(links[1].closest('li')?.textContent).toContain(+ 'Docker socket authority and reduced telemetry',+ );+ });++ it('links to real shipped profile and qualification headings, without losing backup safety', () => {+ const article = articleFor('PRODUCTION_SECURITY');+ const security = articleFor('AGENT_SECURITY');+ for (const anchor of [+ 'least-privilege-agent-profile',+ 'safe-profile-support-and-qualification-matrix',+ ]) {+ expect(article.querySelector(`a[href="/docs/AGENT_SECURITY#${anchor}"]`)).not.toBeNull();+ expect(security.querySelector(`#${anchor}`)).not.toBeNull();+ }+ const backup = article.querySelector('a[href="/docs/VM_DISK_MONITORING#backup-safety"]');+ expect(backup).not.toBeNull();+ expect(articleFor('VM_DISK_MONITORING').querySelector('#backup-safety')).not.toBeNull();+ expect(+ readFileSync(path.join(frontendRoot, 'public/docs/PRODUCTION_SECURITY.md'), 'utf8'),+ ).toBe(readDoc('PRODUCTION_SECURITY'));+ });+});diff --git a/scripts/tests/test_production_rollout_docs.py b/scripts/tests/test_production_rollout_docs.pyindex dcb77c546c..bb7e13b2eb 100644--- a/scripts/tests/test_production_rollout_docs.py+++ b/scripts/tests/test_production_rollout_docs.py@@ -113,6 +113,41 @@ class ProductionRolloutDocsTest(unittest.TestCase):self.assertIn(boundary, text)self.assertNotRegex(text, r"(?:--insecure|curl[^\n]*\||--token\s)")+ def test_linux_profile_choice_matches_installer_authority_boundaries(self):+ text = section("### Choose a Linux agent profile")+ for boundary in ("two different least-privilege profiles",+ "--least-privilege --enable-privileged-helper",+ "root-owned binaries", "no membership in the rootful Docker group",+ "does not remove all root code", "Do not combine it",+ "--grant-smart", "--grant-pct", "PrivateNetwork",+ "root-equivalent", "NoNewPrivileges=false",+ "not the default or full-telemetry parity",+ "not container stats, image-update checks or lifecycle actions",+ "collector-owned rootless socket", "separately enabled action runner",+ "not NAS appliances or non-systemd platforms",+ "Ordinary `--update` preserves the installed profile",+ "not a diagnostic step"):+ with self.subTest(boundary=boundary):+ self.assertIn(boundary, text)+ installer = (ROOT / "scripts/install.sh").read_text()+ # The summary must explain distinct real installer paths, not imply+ # that adding every privilege flag produces the stronger profile.+ for refusal in ("--enable-privileged-helper requires --least-privilege",+ "--enable-privileged-helper cannot be combined with legacy --grant-smart/--grant-pct sudo paths",+ "--least-privilege and --enable-commands are mutually exclusive",+ "--enable-action-runner requires the safe --least-privilege --enable-privileged-helper collector profile"):+ self.assertIn(refusal, installer)+ account = installer.split("provision_least_privilege_user() {", 1)[1].split("\n}\n", 1)[0]+ self.assertIn('"$PRIVILEGED_HELPER_ENABLED" != "true" && "$ENABLE_DOCKER" != "false"', account)+ self.assertIn('usermod -aG docker "$LEAST_PRIVILEGE_USER"', account)++ def test_rollout_requires_profile_choice_not_root_as_the_only_host_path(self):+ text = section("## Production rollout checklist")+ self.assertIn("Add host agents only for needed local telemetry", text)+ self.assertIn("#choose-a-linux-agent-profile", text)+ self.assertIn("Docker socket authority and reduced telemetry", text)+ self.assertNotIn("Add root agents only", text)+def test_operational_upgrade_checks_are_observational_not_action_probes(self):text = " ".join(TRUST_DOC.read_text().split("### Read-only checks after upgrading\n", 1)[1].split())for boundary in ("existing authenticated browser session", "ordinary collection",