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
Separate optional guest file access from filesystem auditing
pulse-triage[bot]1a672bf2db1b
diff --git a/docs/AGENT_SECURITY.md b/docs/AGENT_SECURITY.mdindex ffc3302179..24146f0869 100644--- a/docs/AGENT_SECURITY.md+++ b/docs/AGENT_SECURITY.md@@ -100,13 +100,24 @@ manual probes during a freeze or thaw.| Goal | Recommended path | Host privilege 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 |+| VM filesystem usage and guest information through QEMU Guest Agent | On PVE 9+, use `VM.GuestAgent.Audit` for intended guests; PVE 8 uses the legacy `VM.Monitor` privilege | No host agent for the Proxmox node |+| Linux guest-memory detail by reading `/proc/meminfo` through QEMU Guest Agent | On PVE 9+, this separate read also needs `VM.GuestAgent.FileRead`; PVE 8 uses `VM.Monitor`. Leave file reads denied if they are not intended | No host agent for the Proxmox node || Configured LXC filesystem capacities and usage | Install the Unified Agent on the owning PVE node; the safe profile uses [socket-free discovery and bounded mount probes](#proxmox-lxc-filesystem-readings-with-the-typed-helper) | Yes, but the safe profile confines it to the root helper rather than a root collector || Docker/Podman containers inside a VM or LXC through guest-local reporting | Install the agent inside that VM/LXC with Docker/Podman monitoring enabled, or use another explicit guest access/reporting path | Requires runtime-socket access: root-equivalent for a rootful daemon, or a collector-owned rootless socket || Docker containers inside an LXC from a Proxmox host agent | Turn on **Discover Docker in LXC guests** in Settings → System → General (admin only), or start Pulse with `PULSE_ENABLE_PROXMOX_GUEST_DOCKER_INVENTORY=true` to lock it on; optionally limit guests with `PULSE_PROXMOX_GUEST_DOCKER_INVENTORY_VMIDS=101,102` | Requires a root/equivalent Pulse agent on the Proxmox node and explicit server opt-in || Host SMART, temperatures, local ZFS/Ceph/mdadm detail, arbitrary mount reads, and full host telemetry | Install the agent on that host | Varies: the safe typed helper covers SMART; capabilities outside the matrix still require the explicit root/full-telemetry profile || Kubernetes node/pod monitoring from a cluster | Use the Kubernetes agent/DaemonSet profile | Depends on whether host metrics are enabled |+**Filesystem auditing does not require Linux memory-file access on PVE 9+.**+Windows has no `/proc/meminfo`; a failed read of that path is not evidence+that Windows disk collection needs `VM.GuestAgent.FileRead`. A permitted read+does not by itself prove fresh readings, workload health or backup safety.+Review the [guest-read permission boundaries](TROUBLESHOOTING.md#check-permissions-proxmox)+for the intended target, keeping privilege separation enabled. Repeated optional+403s are not a reason to widen access, install another agent or rerun setup;+use the [optional-read explanation](TROUBLESHOOTING.md#optional-proxmox-checks-return-403-repeatedly)+and existing observations instead of manual guest-agent probes.+Inside-guest runtime visibility is explicit. Installing the agent inside a VM orLXC authorizes that guest-local agent to report Docker/Podman monitoring dataaccording to its local module flags. A Proxmox node agent does not look insidediff --git a/frontend-modern/public/docs/AGENT_SECURITY.md b/frontend-modern/public/docs/AGENT_SECURITY.mdindex ffc3302179..24146f0869 100644--- a/frontend-modern/public/docs/AGENT_SECURITY.md+++ b/frontend-modern/public/docs/AGENT_SECURITY.md@@ -100,13 +100,24 @@ manual probes during a freeze or thaw.| Goal | Recommended path | Host privilege 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 |+| VM filesystem usage and guest information through QEMU Guest Agent | On PVE 9+, use `VM.GuestAgent.Audit` for intended guests; PVE 8 uses the legacy `VM.Monitor` privilege | No host agent for the Proxmox node |+| Linux guest-memory detail by reading `/proc/meminfo` through QEMU Guest Agent | On PVE 9+, this separate read also needs `VM.GuestAgent.FileRead`; PVE 8 uses `VM.Monitor`. Leave file reads denied if they are not intended | No host agent for the Proxmox node || Configured LXC filesystem capacities and usage | Install the Unified Agent on the owning PVE node; the safe profile uses [socket-free discovery and bounded mount probes](#proxmox-lxc-filesystem-readings-with-the-typed-helper) | Yes, but the safe profile confines it to the root helper rather than a root collector || Docker/Podman containers inside a VM or LXC through guest-local reporting | Install the agent inside that VM/LXC with Docker/Podman monitoring enabled, or use another explicit guest access/reporting path | Requires runtime-socket access: root-equivalent for a rootful daemon, or a collector-owned rootless socket || Docker containers inside an LXC from a Proxmox host agent | Turn on **Discover Docker in LXC guests** in Settings → System → General (admin only), or start Pulse with `PULSE_ENABLE_PROXMOX_GUEST_DOCKER_INVENTORY=true` to lock it on; optionally limit guests with `PULSE_PROXMOX_GUEST_DOCKER_INVENTORY_VMIDS=101,102` | Requires a root/equivalent Pulse agent on the Proxmox node and explicit server opt-in || Host SMART, temperatures, local ZFS/Ceph/mdadm detail, arbitrary mount reads, and full host telemetry | Install the agent on that host | Varies: the safe typed helper covers SMART; capabilities outside the matrix still require the explicit root/full-telemetry profile || Kubernetes node/pod monitoring from a cluster | Use the Kubernetes agent/DaemonSet profile | Depends on whether host metrics are enabled |+**Filesystem auditing does not require Linux memory-file access on PVE 9+.**+Windows has no `/proc/meminfo`; a failed read of that path is not evidence+that Windows disk collection needs `VM.GuestAgent.FileRead`. A permitted read+does not by itself prove fresh readings, workload health or backup safety.+Review the [guest-read permission boundaries](TROUBLESHOOTING.md#check-permissions-proxmox)+for the intended target, keeping privilege separation enabled. Repeated optional+403s are not a reason to widen access, install another agent or rerun setup;+use the [optional-read explanation](TROUBLESHOOTING.md#optional-proxmox-checks-return-403-repeatedly)+and existing observations instead of manual guest-agent probes.+Inside-guest runtime visibility is explicit. Installing the agent inside a VM orLXC authorizes that guest-local agent to report Docker/Podman monitoring dataaccording to its local module flags. A Proxmox node agent does not look insidediff --git a/frontend-modern/src/features/docs/__tests__/pveHelperGuidance.test.ts b/frontend-modern/src/features/docs/__tests__/pveHelperGuidance.test.tsindex 4fc1a6f8c5..61073b6629 100644--- a/frontend-modern/src/features/docs/__tests__/pveHelperGuidance.test.ts+++ b/frontend-modern/src/features/docs/__tests__/pveHelperGuidance.test.ts@@ -38,3 +38,62 @@ describe('confined PVE helper reading guidance', () => {);});});++describe('least-privilege PVE guest reading choices', () => {+ const choice = (label: string): HTMLTableRowElement => {+ const row = [...article('AGENT_SECURITY').querySelectorAll('tbody tr')].find(+ (element) => element.querySelector('td')?.textContent === label,+ );+ expect(row, `separate deployment choice for ${label}`).toBeDefined();+ return row as HTMLTableRowElement;+ };++ it('does not prescribe optional Linux file access for filesystem auditing', () => {+ const row = choice('VM filesystem usage and guest information through QEMU Guest Agent');+ const permissions = row.querySelectorAll('td')[1];+ expect([...permissions.querySelectorAll('code')].map((element) => element.textContent)).toEqual([+ 'VM.GuestAgent.Audit',+ 'VM.Monitor',+ ]);+ expect(permissions.textContent).toContain('PVE 9+');+ expect(permissions.textContent).toContain('PVE 8 uses the legacy');+ expect(permissions.textContent).toContain('intended guests');+ expect(row.querySelectorAll('td')[2].textContent).toBe('No host agent for the Proxmox node');+ });++ it('keeps Linux memory-file access a separate, optional choice', () => {+ const row = choice(+ 'Linux guest-memory detail by reading /proc/meminfo through QEMU Guest Agent',+ );+ const permissions = row.querySelectorAll('td')[1];+ expect([...permissions.querySelectorAll('code')].map((element) => element.textContent)).toEqual([+ 'VM.GuestAgent.FileRead',+ 'VM.Monitor',+ ]);+ expect(permissions.textContent).toContain('On PVE 9+, this separate read also needs');+ expect(permissions.textContent).toContain('PVE 8 uses');+ expect(permissions.textContent).toContain('Leave file reads denied if they are not intended');+ });++ it('routes denials to existing scoped guidance, not another setup or probe', () => {+ const guide = article('AGENT_SECURITY');+ const section = guide.textContent?.split('Filesystem auditing does not require')[1]?.split(+ 'Inside-guest runtime visibility',+ )[0]?.replace(/\s+/g, ' ');+ expect(section).toContain('Windows has no /proc/meminfo');+ expect(section).toContain('not evidence that Windows disk collection needs VM.GuestAgent.FileRead');+ expect(section).toContain('does not by itself prove fresh readings, workload health or backup safety');+ expect(section).toContain('keeping privilege separation enabled');+ expect(section).toContain('not a reason to widen access, install another agent or rerun setup');+ expect(section).toContain('existing observations instead of manual guest-agent probes');+ const trouble = article('TROUBLESHOOTING');+ for (const fragment of [+ 'check-permissions-proxmox',+ 'optional-proxmox-checks-return-403-repeatedly',+ ]) {+ expect(guide.querySelector(`a[href="/docs/TROUBLESHOOTING#${fragment}"]`)).not.toBeNull();+ expect(trouble.querySelector(`#${fragment}`)).not.toBeNull();+ }+ expect(guide.querySelector('a[href="/docs/VM_DISK_MONITORING#backup-safety"]')).not.toBeNull();+ });+});