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.

Keep guest disk permission guidance inside the intended access scope

pulse-triage[bot]eb4f3c8e3789
diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.md
index 033e3868a8..0310ad379f 100644
--- a/docs/VM_DISK_MONITORING.md
+++ b/docs/VM_DISK_MONITORING.md
@@ -293,6 +293,13 @@ privilege separation or recreate the token to diagnose a missing reading. See
inspection and repair boundary. A permitted read does not prove disk freshness,
responsiveness or thaw.
+First check whether the VM is an intended monitoring target. Keep intentionally
+restricted access unchanged; do not widen the token's scope just to clear a
+permission error on an excluded guest. A denied filesystem read is unavailable,
+not evidence that the guest or filesystem is unhealthy. Review or change access
+only for intended targets, through normal administration outside backups or
+guest incidents. Table filters and alert suppression do not stop API polling.
+
| Collection | Proxmox VE 9+ | Proxmox VE 8 |
| --- | --- | --- |
| Filesystem usage and guest information | `VM.GuestAgent.Audit` | `VM.Monitor` |
@@ -354,7 +361,7 @@ pass; do not clear or bypass a guest-read pause to test recovery.
| Observation | Useful next check |
| --- | --- |
| **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. |
-| **Permission denied** | Review the token and account's effective read privileges on that VM, including privilege-separated token ACLs. A successful root command would not disprove this error. |
+| **Permission denied** | First check whether this VM is an intended monitoring target. Preserve intentionally restricted access. For intended targets only, review the token and account's effective read privileges, including privilege-separated token ACLs, outside backups or guest incidents. A successful root command would not disprove this error; a denied read does not establish guest or filesystem health. |
| **Timeout or backup lock** | Check the existing backup/task timeline and guest workload locally. Defer active guest-agent probes; increasing a timeout is not a contention or thaw repair. |
| **Rocky Linux / RHEL memory missing** | Review `/etc/sysconfig/qemu-ga` inside the guest. File-read restrictions can explain memory collection failure; they do not by themselves prove why filesystem usage is absent. Change the guest's allowlist or restart its agent only through your normal maintenance procedure, outside backups. |
| **Windows service stopped** | Check the QEMU Guest Agent service inside Windows. Schedule any restart outside backups. |
diff --git a/frontend-modern/browser-verification/1c48d6ea9d6a4ed3.json b/frontend-modern/browser-verification/1c48d6ea9d6a4ed3.json
new file mode 100644
index 0000000000..0d0e471a8b
--- /dev/null
+++ b/frontend-modern/browser-verification/1c48d6ea9d6a4ed3.json
@@ -0,0 +1,40 @@
+{
+ "version": 1,
+ "result": "passed",
+ "base_sha": "1fe65245e823a62b84f84f09997744ca1e61953b",
+ "changed_paths": ["frontend-modern/src/utils/workloadGuestPresentation.ts"],
+ "content_sha256": {
+ "frontend-modern/src/utils/workloadGuestPresentation.ts": "ad087616ec03f0d5f18471f5eaedf5c6493fd1c008aae2362b97637dd7045cbb"
+ },
+ "routes": [
+ "/browser-tests/guest-reading-help.html — production workload row and full GuestDrawer on synthetic readings",
+ "/docs/VM_DISK_MONITORING#a-missing-reading-is-not-an-installation-diagnosis — actual shipped markdown renderer and asset"
+ ],
+ "states": [
+ "Permission-denied filesystem reads with no current usage; retained prev-permission-denied values remain last known and lack measured utilization bars",
+ "New synthetic same-guest reading removes denial guidance and restores its measured bar; unrelated missing-agent guidance unchanged",
+ "Intentionally scoped access, effective account/token rights, unavailable versus unhealthy and backup precautions in shipped help"
+ ],
+ "interactions": [
+ "Desktop keyboard Enter and phone touch open the same guest details",
+ "Read wrapped error guidance and accessible row status without live diagnostics, access changes or external requests",
+ "Follow existing reading-help link with keyboard or touch and view the Permissions section",
+ "Inspect seven desktop/phone/narrow captures; no drawer or document horizontal overflow in checked guest states"
+ ],
+ "viewports": [
+ {
+ "width": 1365,
+ "height": 900
+ },
+ {
+ "width": 390,
+ "height": 844
+ },
+ {
+ "width": 320,
+ "height": 844
+ }
+ ],
+ "verified_at": "2026-10-09T10:50:45.951Z",
+ "browser_evidence": "pulse-worker-browser tmp/guest-permission-proof/run.cjs; saved browser-command exit 0, matching final hashes/result and completed browser/server close; Playwright 1.56.1, Chromium 141.0.7390.37 and WebKit 26.0; seven final captures inspected. Outer exec session separately returned 143, initiator unknown; retained, not diagnosed or hidden. Component/help-browser acceptance only, not independent host cleanup, full-app/native collection or release acceptance."
+}
diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.md
index 033e3868a8..0310ad379f 100644
--- a/frontend-modern/public/docs/VM_DISK_MONITORING.md
+++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md
@@ -293,6 +293,13 @@ privilege separation or recreate the token to diagnose a missing reading. See
inspection and repair boundary. A permitted read does not prove disk freshness,
responsiveness or thaw.
+First check whether the VM is an intended monitoring target. Keep intentionally
+restricted access unchanged; do not widen the token's scope just to clear a
+permission error on an excluded guest. A denied filesystem read is unavailable,
+not evidence that the guest or filesystem is unhealthy. Review or change access
+only for intended targets, through normal administration outside backups or
+guest incidents. Table filters and alert suppression do not stop API polling.
+
| Collection | Proxmox VE 9+ | Proxmox VE 8 |
| --- | --- | --- |
| Filesystem usage and guest information | `VM.GuestAgent.Audit` | `VM.Monitor` |
@@ -354,7 +361,7 @@ pass; do not clear or bypass a guest-read pause to test recovery.
| Observation | Useful next check |
| --- | --- |
| **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. |
-| **Permission denied** | Review the token and account's effective read privileges on that VM, including privilege-separated token ACLs. A successful root command would not disprove this error. |
+| **Permission denied** | First check whether this VM is an intended monitoring target. Preserve intentionally restricted access. For intended targets only, review the token and account's effective read privileges, including privilege-separated token ACLs, outside backups or guest incidents. A successful root command would not disprove this error; a denied read does not establish guest or filesystem health. |
| **Timeout or backup lock** | Check the existing backup/task timeline and guest workload locally. Defer active guest-agent probes; increasing a timeout is not a contention or thaw repair. |
| **Rocky Linux / RHEL memory missing** | Review `/etc/sysconfig/qemu-ga` inside the guest. File-read restrictions can explain memory collection failure; they do not by themselves prove why filesystem usage is absent. Change the guest's allowlist or restart its agent only through your normal maintenance procedure, outside backups. |
| **Windows service stopped** | Check the QEMU Guest Agent service inside Windows. Schedule any restart outside backups. |
diff --git a/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx b/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
index 6289ebd98b..6700c5ca0d 100644
--- a/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx
@@ -86,7 +86,7 @@ describe('DiskList', () => {
],
[
'permission-denied',
- 'Permission denied. Check that your Pulse user/token has VM.Monitor permission (PVE 8) or VM.GuestAgent.Audit permission (PVE 9).',
+ "Permission denied. If this VM is an intended monitoring target, review the configured account and token's effective read permissions: VM.Monitor (PVE 8) or VM.GuestAgent.Audit (PVE 9+). Do not widen intentionally scoped access just to clear this error. A denied read does not establish guest or filesystem health. Defer access changes and live probes during backups or a guest incident.",
],
[
'agent-disabled',
diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystem-provenance.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystem-provenance.test.tsx
index c4c7e49baa..9c3156a8ea 100644
--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystem-provenance.test.tsx
+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystem-provenance.test.tsx
@@ -71,6 +71,40 @@ const filesystemRow = () => screen.getByText(path).closest('tr')!;
afterEach(cleanup);
describe('filesystem details do not promote retained usage to current health', () => {
+ it.each(['permission-denied', 'prev-permission-denied'])(
+ 'shows scoped-access guidance for %s and clears it only on a new reading',
+ (reason) => {
+ const [value, setValue] = createSignal(guest({ diskStatusReason: reason }));
+ render(() => <GuestDrawerOverview {...props(value())} />);
+ const message = screen.getByText(/Do not widen intentionally scoped access/);
+ expect(message).toBeVisible();
+ expect(message).toHaveTextContent('If this VM is an intended monitoring target');
+ expect(message).toHaveTextContent('does not establish guest or filesystem health');
+ expect(message).toHaveTextContent('Defer access changes and live probes during backups');
+ const row = within(filesystemRow());
+ expect(row.queryByRole('progressbar')).not.toBeInTheDocument();
+ expect(
+ row.getByText(
+ reason.startsWith('prev-')
+ ? 'Last known 90% · 9.00 GB/10.0 GB · EXT4'
+ : 'Usage unavailable · ?/10.0 GB · EXT4',
+ ),
+ ).toBeVisible();
+ expect(screen.getByRole('link', { name: 'Filesystem reading guidance' })).toHaveAttribute(
+ 'href',
+ '/docs/VM_DISK_MONITORING#a-missing-reading-is-not-an-installation-diagnosis',
+ );
+ setValue(guest({ diskStatusReason: '' }));
+ expect(
+ screen.queryByText(/Do not widen intentionally scoped access/),
+ ).not.toBeInTheDocument();
+ expect(within(filesystemRow()).getByRole('progressbar')).toHaveAttribute(
+ 'aria-valuenow',
+ '90',
+ );
+ },
+ );
+
it.each(guestDiskDeferrals)(
'keeps prev-%s values labelled, without a current utilization bar',
(reason) => {
diff --git a/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts b/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
index 26ec9ec6dc..50c82d9bbc 100644
--- a/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
+++ b/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts
@@ -10,6 +10,25 @@ import {
} from '@/utils/workloadGuestPresentation';
describe('workloadGuestPresentation', () => {
+ it.each(['permission-denied', 'prev-permission-denied'])(
+ 'keeps %s separate from permission expansion and guest health',
+ (reason) => {
+ const message = getWorkloadGuestDiskStatusMessage(reason);
+ expect(message).toContain('If this VM is an intended monitoring target');
+ expect(message).toContain("configured account and token's effective read permissions");
+ expect(message).toContain('VM.Monitor (PVE 8) or VM.GuestAgent.Audit (PVE 9+)');
+ expect(message).toContain(
+ 'Do not widen intentionally scoped access just to clear this error',
+ );
+ expect(message).toContain('A denied read does not establish guest or filesystem health');
+ expect(message).toContain(
+ 'Defer access changes and live probes during backups or a guest incident',
+ );
+ expect(message.startsWith('Using last known disk stats.')).toBe(reason.startsWith('prev-'));
+ expect(message).not.toMatch(/Administrator|VM\.GuestAgent\.(Exec|FileWrite)|curl|qm agent/);
+ },
+ );
+
it.each(guestDiskDeferrals)(
'explains %s with and without retained disk evidence',
(reason, message) => {
diff --git a/frontend-modern/src/utils/workloadGuestPresentation.ts b/frontend-modern/src/utils/workloadGuestPresentation.ts
index 4e919ae6ea..00272282c5 100644
--- a/frontend-modern/src/utils/workloadGuestPresentation.ts
+++ b/frontend-modern/src/utils/workloadGuestPresentation.ts
@@ -124,7 +124,7 @@ export function getWorkloadGuestDiskStatusMessage(reason?: string): string {
case 'invalid-guest-key':
return 'Guest reads unavailable because the VM identity is invalid.';
case 'permission-denied':
- return 'Permission denied. Check that your Pulse user/token has VM.Monitor permission (PVE 8) or VM.GuestAgent.Audit permission (PVE 9).';
+ return "Permission denied. If this VM is an intended monitoring target, review the configured account and token's effective read permissions: VM.Monitor (PVE 8) or VM.GuestAgent.Audit (PVE 9+). Do not widen intentionally scoped access just to clear this error. A denied read does not establish guest or filesystem health. Defer access changes and live probes during backups or a guest incident.";
case 'agent-disabled':
return 'Proxmox reports the guest agent disabled in VM configuration. Review guest-OS-specific setup outside backups or guest incidents.';
case 'no-filesystems':
diff --git a/scripts/tests/test_pve_backup_troubleshooting_docs.py b/scripts/tests/test_pve_backup_troubleshooting_docs.py
index c71856c7d6..1b4c5cecef 100644
--- a/scripts/tests/test_pve_backup_troubleshooting_docs.py
+++ b/scripts/tests/test_pve_backup_troubleshooting_docs.py
@@ -81,6 +81,21 @@ class BackupAgeEvaluationDocsTest(unittest.TestCase):
class PVEBackupTroubleshootingDocsTest(unittest.TestCase):
+ def test_guest_disk_permission_help_preserves_intended_access_and_backup_safety(self):
+ guide = (ROOT / "docs/VM_DISK_MONITORING.md").read_text()
+ section = guide.split("## ⚙️ Permissions\n", 1)[1].split("\n## ", 1)[0]
+ text = " ".join(section.split())
+ for distinction in ("VM is an intended monitoring target",
+ "Keep intentionally restricted access unchanged",
+ "do not widen the token's scope",
+ "not evidence that the guest or filesystem is unhealthy",
+ "only for intended targets", "outside backups or guest incidents",
+ "Table filters and alert suppression do not stop API polling"):
+ self.assertIn(distinction, text)
+ self.assertNotIn("```", section, "no copied grant or live guest probe")
+ self.assertEqual((ROOT / "docs/VM_DISK_MONITORING.md").read_bytes(),
+ (ROOT / "frontend-modern/public/docs/VM_DISK_MONITORING.md").read_bytes())
+
def test_intentionally_restricted_cluster_is_not_an_access_repair_recipe(self):
trouble = (ROOT / "docs/TROUBLESHOOTING.md").read_text()
section = trouble.split("### Check Permissions (Proxmox)\n", 1)[1].split("\n### ", 1)[0]