Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Explain the distinct Linux agent privilege profiles

pulse-triage[bot]7ede32f27a77
diff --git a/docs/PRODUCTION_SECURITY.md b/docs/PRODUCTION_SECURITY.md
index 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 during
the migration. Agent Doctor reports both local authority and credential scope
so 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 on
one 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. Keep
commands disabled unless there is a reviewed operational need.
- [ ] Check existing inventory and provider identity before adding another
cluster; 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.md
index 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 during
the migration. Agent Doctor reports both local authority and credential scope
so 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 on
one 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. Keep
commands disabled unless there is a reviewed operational need.
- [ ] Check existing inventory and provider identity before adding another
cluster; 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.ts
new file mode 100644
index 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.py
index 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",