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
Keep fresh agent authentication triage scoped and non-destructive
pulse-triage[bot]341de1644cba
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex 201e12ef91..717e743b9e 100644--- a/docs/UNIFIED_AGENT.md+++ b/docs/UNIFIED_AGENT.md@@ -979,6 +979,50 @@ private, and report evidence as unavailable if safe collection is not possible.QNAP and Unraid log locations are described in the[space troubleshooting section](#installer-fails-with-not-enough-free-disk-space).+### Agent lookup returns HTTP 401 or 403++At `/api/agents/agent/lookup`, Pulse authenticates the request **before**+searching for the host. **HTTP 401** is an authentication rejection;+**HTTP 403** with `missing_scope` means the authenticated token lacks+`agent:report`. An authenticated lookup can return **HTTP 404** when no matching+host exists. A 401 alone does not identify a mistyped, expired or revoked token,+the wrong Pulse instance, or an upstream authentication layer.++The silent token prompt only keeps the secret out of the copied command and+shell history; it does not change reporting permissions. The normal+**Settings → Infrastructure → Install on a host** flow issues a monitoring+token. It does not use `--enroll`; the separate cluster deployment flow exchanges+a bootstrap token for a runtime token. Do not substitute a bootstrap token or+assume an enrolment-specific correction applies to a normal host installation.++Use the [bounded agent log reader](#collect-agent-logs-safely) on the affected+agent host, or inspect an already retained excerpt privately. Distinguish:++- `remote_config_client` reporting a lookup failure: this concerns configuration+ retrieval and does not establish whether ordinary host reports were accepted.+- **Pulse rejected this agent's API token** from host reporting: keep its HTTP+ status and redacted error, separately from the lookup failure.++A running local service or successful-looking installer output does not prove+that Pulse accepted a fresh report. No host-report error in the selected log+window is inconclusive, not proof of successful reporting. Do not restart,+re-enrol, delete identity or enable debug logging to manufacture that evidence.++In your signed-in administrator session on the **same Pulse instance** the+agent targets, check the intended record under **Settings → Security → API+Tokens** without revealing or copying its secret. Its presence, expiry and+reporting scope help distinguish server-side rejection, but do not prove that+the running service is using that record. Keep service environments, token+files and connection files private; do not paste a credential into a command,+URL or issue. Do not grant administrator scope, change Proxmox permissions or+disable authentication/TLS to test a guess.++If reporting this problem, say whether the existing error is lookup-only or+also affects host reporting, and share only the failure stage, HTTP status and+manually redacted error line. Keep the installation and saved credentials+unchanged until the failing stage is understood; a 401 is not itself a reason+to reinstall or rotate every token.+### pfSense service disabled after a major upgradePulse installs two service files on pfSense: the FreeBSD rc.d service atdiff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex 201e12ef91..717e743b9e 100644--- a/frontend-modern/public/docs/UNIFIED_AGENT.md+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md@@ -979,6 +979,50 @@ private, and report evidence as unavailable if safe collection is not possible.QNAP and Unraid log locations are described in the[space troubleshooting section](#installer-fails-with-not-enough-free-disk-space).+### Agent lookup returns HTTP 401 or 403++At `/api/agents/agent/lookup`, Pulse authenticates the request **before**+searching for the host. **HTTP 401** is an authentication rejection;+**HTTP 403** with `missing_scope` means the authenticated token lacks+`agent:report`. An authenticated lookup can return **HTTP 404** when no matching+host exists. A 401 alone does not identify a mistyped, expired or revoked token,+the wrong Pulse instance, or an upstream authentication layer.++The silent token prompt only keeps the secret out of the copied command and+shell history; it does not change reporting permissions. The normal+**Settings → Infrastructure → Install on a host** flow issues a monitoring+token. It does not use `--enroll`; the separate cluster deployment flow exchanges+a bootstrap token for a runtime token. Do not substitute a bootstrap token or+assume an enrolment-specific correction applies to a normal host installation.++Use the [bounded agent log reader](#collect-agent-logs-safely) on the affected+agent host, or inspect an already retained excerpt privately. Distinguish:++- `remote_config_client` reporting a lookup failure: this concerns configuration+ retrieval and does not establish whether ordinary host reports were accepted.+- **Pulse rejected this agent's API token** from host reporting: keep its HTTP+ status and redacted error, separately from the lookup failure.++A running local service or successful-looking installer output does not prove+that Pulse accepted a fresh report. No host-report error in the selected log+window is inconclusive, not proof of successful reporting. Do not restart,+re-enrol, delete identity or enable debug logging to manufacture that evidence.++In your signed-in administrator session on the **same Pulse instance** the+agent targets, check the intended record under **Settings → Security → API+Tokens** without revealing or copying its secret. Its presence, expiry and+reporting scope help distinguish server-side rejection, but do not prove that+the running service is using that record. Keep service environments, token+files and connection files private; do not paste a credential into a command,+URL or issue. Do not grant administrator scope, change Proxmox permissions or+disable authentication/TLS to test a guess.++If reporting this problem, say whether the existing error is lookup-only or+also affects host reporting, and share only the failure stage, HTTP status and+manually redacted error line. Keep the installation and saved credentials+unchanged until the failing stage is understood; a 401 is not itself a reason+to reinstall or rotate every token.+### pfSense service disabled after a major upgradePulse installs two service files on pfSense: the FreeBSD rc.d service atdiff --git a/scripts/tests/test_agent_auth_docs.py b/scripts/tests/test_agent_auth_docs.pynew file mode 100644index 0000000000..be05010683--- /dev/null+++ b/scripts/tests/test_agent_auth_docs.py@@ -0,0 +1,87 @@+#!/usr/bin/env python3+"""Keep passive agent-authentication triage aligned with the real install flow.++These source/document controls do not authenticate an installed agent or+establish a reporter's cause. No credential, service or target is accessed.+"""++from pathlib import Path+import re+import unittest+++ROOT = Path(__file__).resolve().parents[2]+DOC = ROOT / "docs/UNIFIED_AGENT.md"+++def section():+ text = DOC.read_text(encoding="utf-8")+ marker = "### Agent lookup returns HTTP 401 or 403\n"+ if marker not in text:+ raise AssertionError("missing agent authentication triage")+ return re.split(r"\n#{2,3} ", text.split(marker, 1)[1], 1)[0]+++class AgentAuthDocsTest(unittest.TestCase):+ def test_status_explanations_match_authentication_before_scoped_lookup(self):+ text = " ".join(section().split())+ routes = (ROOT / "internal/api/router_routes_registration.go").read_text()+ self.assertIn(+ '"/api/agents/agent/lookup", RequireAuth(r.config, '+ 'RequireScope(config.ScopeAgentReport, r.unifiedAgentHandlers.HandleLookup)',+ routes,+ )+ auth = (ROOT / "internal/api/auth.go").read_text()+ self.assertIn('http.Error(w, "Invalid API token", http.StatusUnauthorized)', auth)+ scope = (ROOT / "internal/api/apihttp/scope.go").read_text()+ denial = scope.split("func RespondMissingScope(", 1)[1]+ self.assertIn("w.WriteHeader(http.StatusForbidden)", denial)+ self.assertIn('"error":', denial)+ self.assertIn('"missing_scope"', denial)+ for fact in ("authenticates the request **before**", "**HTTP 401** is an authentication rejection",+ "**HTTP 403** with `missing_scope`", "`agent:report`", "**HTTP 404**",+ "upstream authentication layer"):+ self.assertIn(fact, text)++ def test_normal_install_is_not_conflated_with_bootstrap_enrolment(self):+ text = " ".join(section().split())+ install = (ROOT / "frontend-modern/src/components/Settings/useInfrastructureInstallState.tsx").read_text()+ args = install.split("const getInstallerExtraArgs = () => [", 1)[1].split("];", 1)[0]+ self.assertNotIn("--enroll", args)+ scopes = (ROOT / "internal/api/agenttokens/install.go").read_text()+ host = scopes.split("func HostScopes(", 1)[1].split("\n}", 1)[0]+ self.assertIn("config.ScopeAgentReport", host)+ self.assertIn("config.ScopeAgentConfigRead", host)+ self.assertNotIn("ScopeAgentEnroll", host)+ prompt = (ROOT / "frontend-modern/src/utils/agentInstallCommand.ts").read_text()+ self.assertIn('read -r -s -p', prompt)+ self.assertIn('--token-file "$token_file"', prompt)+ for fact in ("silent token prompt", "does not change reporting permissions",+ "It does not use `--enroll`", "bootstrap token for a runtime token",+ "Do not substitute a bootstrap token", "normal host installation"):+ self.assertIn(fact, text)++ def test_triage_preserves_unknowns_state_and_private_credentials(self):+ text = " ".join(section().split())+ host = (ROOT / "internal/hostagent/agent.go").read_text()+ self.assertIn("Pulse rejected this agent's API token", host)+ client = (ROOT / "internal/remoteconfig/client.go").read_text()+ self.assertIn('Str("component", "remote_config_client")', client)+ for fact in ("bounded agent log reader", "affected agent host", "retrieval and does not establish",+ "ordinary host reports were accepted", "successful-looking installer output does not prove",+ "No host-report error", "inconclusive", "Do not restart, re-enrol, delete identity",+ "same Pulse instance", "do not prove that the running service is using that record",+ "service environments, token files and connection files private",+ "Do not grant administrator scope", "disable authentication/TLS",+ "manually redacted error line", "saved credentials unchanged",+ "not itself a reason to reinstall or rotate every token"):+ self.assertIn(fact, text)+ self.assertNotIn("```", section(), "Reuse the bounded reader; do not add live credential probes")++ def test_shipped_help_matches_the_canonical_guide(self):+ self.assertEqual(DOC.read_bytes(),+ (ROOT / "frontend-modern/public/docs/UNIFIED_AGENT.md").read_bytes())+++if __name__ == "__main__":+ unittest.main()