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.

Point agent authentication help at the real token inventory

pulse-triage[bot]a9b4015872b7
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index a697f3f467..59eab8aec2 100644
--- a/docs/UNIFIED_AGENT.md
+++ b/docs/UNIFIED_AGENT.md
@@ -1068,19 +1068,30 @@ agent host, or inspect an already retained excerpt privately. Distinguish:
- **Pulse rejected this agent's API token** from host reporting: keep its HTTP
status and redacted error, separately from the lookup failure.
+If both lookup and host reporting return 401, this is not a lookup-only failure.
+The host log's restore/upgrade explanation is generic, not an established cause
+for that installation. If you already tried reinstalling, do not repeat it to
+collect evidence; check the intended token record below first.
+
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.
+agent targets, open **Settings → API Access** in the Security group. Check
+whether the intended token is listed, its **Created** time, **Last used** value
+and **Scopes**, without revealing or copying its secret. A missing record and a
+listed record with `Never` are different observations; neither proves that the
+service is presenting the same token. Last-used metadata is not a token-use
+audit and does not identify which consumer authenticated. These observations
+do not prove that the running service is using that record.
+
+If asked about the inventory, report only whether the record exists and the
+relevant metadata; do not share the token or its hint. 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
diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.md
index a697f3f467..59eab8aec2 100644
--- a/frontend-modern/public/docs/UNIFIED_AGENT.md
+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md
@@ -1068,19 +1068,30 @@ agent host, or inspect an already retained excerpt privately. Distinguish:
- **Pulse rejected this agent's API token** from host reporting: keep its HTTP
status and redacted error, separately from the lookup failure.
+If both lookup and host reporting return 401, this is not a lookup-only failure.
+The host log's restore/upgrade explanation is generic, not an established cause
+for that installation. If you already tried reinstalling, do not repeat it to
+collect evidence; check the intended token record below first.
+
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.
+agent targets, open **Settings → API Access** in the Security group. Check
+whether the intended token is listed, its **Created** time, **Last used** value
+and **Scopes**, without revealing or copying its secret. A missing record and a
+listed record with `Never` are different observations; neither proves that the
+service is presenting the same token. Last-used metadata is not a token-use
+audit and does not identify which consumer authenticated. These observations
+do not prove that the running service is using that record.
+
+If asked about the inventory, report only whether the record exists and the
+relevant metadata; do not share the token or its hint. 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
diff --git a/scripts/tests/test_agent_auth_docs.py b/scripts/tests/test_agent_auth_docs.py
index be05010683..a697f13b3f 100644
--- a/scripts/tests/test_agent_auth_docs.py
+++ b/scripts/tests/test_agent_auth_docs.py
@@ -82,6 +82,30 @@ class AgentAuthDocsTest(unittest.TestCase):
self.assertEqual(DOC.read_bytes(),
(ROOT / "frontend-modern/public/docs/UNIFIED_AGENT.md").read_bytes())
+ def test_inventory_guidance_matches_available_navigation_and_metadata(self):
+ text = " ".join(section().split())
+ catalog = (ROOT / "frontend-modern/src/components/Settings/settingsNavCatalog.ts").read_text()
+ api_entry = re.search(r"id: 'api',\s+label: '([^']+)'", catalog)
+ self.assertIsNotNone(api_entry)
+ self.assertIn(f"Settings → {api_entry.group(1)}", text)
+ inventory = (ROOT / "frontend-modern/src/components/Settings/APITokenManager.tsx").read_text()
+ for field in ("Created", "Last used", "Scopes"):
+ self.assertIn(field, inventory)
+ self.assertIn(f"**{field}**", text)
+ self.assertIn("Security group", text)
+ self.assertNotIn("Security → API Tokens", text)
+ self.assertNotIn("presence, expiry", text)
+ self.assertIn("not a token-use audit", text)
+ self.assertIn("do not share the token or its hint", text)
+
+ def test_dual_rejection_does_not_recommend_another_install_or_assume_a_restore(self):
+ text = " ".join(section().split())
+ for fact in ("both lookup and host reporting return 401", "not a lookup-only failure",
+ "restore/upgrade explanation is generic", "not an established cause",
+ "already tried reinstalling", "do not repeat it",
+ "missing record", "service is presenting the same token"):
+ self.assertIn(fact, text)
+
if __name__ == "__main__":
unittest.main()