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 fresh agent authentication triage scoped and non-destructive

pulse-triage[bot]341de1644cba
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index 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 upgrade
Pulse installs two service files on pfSense: the FreeBSD rc.d service at
diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.md
index 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 upgrade
Pulse installs two service files on pfSense: the FreeBSD rc.d service at
diff --git a/scripts/tests/test_agent_auth_docs.py b/scripts/tests/test_agent_auth_docs.py
new file mode 100644
index 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()