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
Explain damaged bare host tokens without credential churn
pulse-triage[bot]5db15c93662a
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex c4cacd70f4..645b461fcd 100644--- a/docs/UNIFIED_AGENT.md+++ b/docs/UNIFIED_AGENT.md@@ -137,6 +137,15 @@ optional for host-local data.existing authentication failure, use the [token-file format guidance](#token-file-format-is-not-shell-syntax)before changing the saved credential or running another installation.+ Before a first installation, check the complete value privately against the+ token just generated, not only its visible ends. Current **Infrastructure →+ Install on a host** tokens contain exactly **64 lowercase hexadecimal+ characters** (`0–9`, `a–f`); duplicated characters or an internal space or+ newline are not part of that value. This describes that generator, not every+ legacy, manually supplied or bootstrap credential. A matching shape alone+ does not authenticate a token. Keep the value out of commands, terminal+ output, screenshots and reports.+2. Replace `https://pulse.example.com` with your Pulse server's HTTPS addressin both the download and installation commands. Download to a new privatefile. This ignores local curl settings, accepts only HTTP **200** over HTTPS,@@ -1190,12 +1199,22 @@ assignment. These file forms therefore mean different things:| Bare token, possibly followed by a newline | The token value; this does not prove it matches the intended record or Pulse instance. || Token surrounded by single or double quotes | The quotes remain part of the credential. || Assignment prefix such as `PULSE_TOKEN=` or `export` | The prefix remains part of the credential; this is not an environment-file parser. |+| Duplicated or missing characters, or whitespace inside a bare value | These change the credential; trimming the file's ends does not repair them. || Unknown | The format and cause remain unknown; no new installation is needed to complete a report. |Quotes or a prefix can cause rejection even when the intended record has theright scopes. A rejected credential can leave that record showing `Never`;this does not identify the cause of a particular installation's failure.+**Bare does not mean intact.** For a token from the current **Infrastructure →+Install on a host** generator, privately check the 64-character lowercase+hexadecimal shape described in [private-file installation](#private-file-installation-linux-macos-and-nas).+The inventory's **Hint** shows only the first six and last four characters:+duplicated or changed middle characters can leave both ends matching. Even an+intact shape and matching hint do not prove full equality, the intended Pulse+instance or accepted reporting. Do not apply this shape check to other token+families or rotate a working credential because it looks different.+Use how the file was saved or an existing private observation. If you cannotsafely tell, say **unknown**. If asked, report only **bare**, **quoted**,**prefixed** or **unknown**, not the value, length, hint, screenshot or file.diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex c4cacd70f4..645b461fcd 100644--- a/frontend-modern/public/docs/UNIFIED_AGENT.md+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md@@ -137,6 +137,15 @@ optional for host-local data.existing authentication failure, use the [token-file format guidance](#token-file-format-is-not-shell-syntax)before changing the saved credential or running another installation.+ Before a first installation, check the complete value privately against the+ token just generated, not only its visible ends. Current **Infrastructure →+ Install on a host** tokens contain exactly **64 lowercase hexadecimal+ characters** (`0–9`, `a–f`); duplicated characters or an internal space or+ newline are not part of that value. This describes that generator, not every+ legacy, manually supplied or bootstrap credential. A matching shape alone+ does not authenticate a token. Keep the value out of commands, terminal+ output, screenshots and reports.+2. Replace `https://pulse.example.com` with your Pulse server's HTTPS addressin both the download and installation commands. Download to a new privatefile. This ignores local curl settings, accepts only HTTP **200** over HTTPS,@@ -1190,12 +1199,22 @@ assignment. These file forms therefore mean different things:| Bare token, possibly followed by a newline | The token value; this does not prove it matches the intended record or Pulse instance. || Token surrounded by single or double quotes | The quotes remain part of the credential. || Assignment prefix such as `PULSE_TOKEN=` or `export` | The prefix remains part of the credential; this is not an environment-file parser. |+| Duplicated or missing characters, or whitespace inside a bare value | These change the credential; trimming the file's ends does not repair them. || Unknown | The format and cause remain unknown; no new installation is needed to complete a report. |Quotes or a prefix can cause rejection even when the intended record has theright scopes. A rejected credential can leave that record showing `Never`;this does not identify the cause of a particular installation's failure.+**Bare does not mean intact.** For a token from the current **Infrastructure →+Install on a host** generator, privately check the 64-character lowercase+hexadecimal shape described in [private-file installation](#private-file-installation-linux-macos-and-nas).+The inventory's **Hint** shows only the first six and last four characters:+duplicated or changed middle characters can leave both ends matching. Even an+intact shape and matching hint do not prove full equality, the intended Pulse+instance or accepted reporting. Do not apply this shape check to other token+families or rotate a working credential because it looks different.+Use how the file was saved or an existing private observation. If you cannotsafely tell, say **unknown**. If asked, report only **bare**, **quoted**,**prefixed** or **unknown**, not the value, length, hint, screenshot or file.diff --git a/scripts/tests/test_agent_auth_docs.py b/scripts/tests/test_agent_auth_docs.pyindex e205865aa1..9a361ccb9a 100644--- a/scripts/tests/test_agent_auth_docs.py+++ b/scripts/tests/test_agent_auth_docs.py@@ -188,6 +188,40 @@ class AgentAuthDocsTest(unittest.TestCase):self.assertIn(fact, text)self.assertIn("#token-file-format-is-not-shell-syntax", DOC.read_text())+ def test_first_install_checks_the_whole_current_host_token_privately(self):+ guide = DOC.read_text(encoding="utf-8")+ preparation = " ".join(guide.split("### Private-file installation: Linux, macOS and NAS", 1)[1]+ .split("2. Replace", 1)[0].split())+ issuance = (ROOT / "internal/api/agenttokens/install.go").read_text()+ self.assertIn("rawToken, err := internalauth.GenerateAPIToken()", issuance)+ generator = (ROOT / "pkg/auth/token.go").read_text().split(+ "func GenerateAPIToken()", 1)[1].split("// HashAPIToken", 1)[0]+ self.assertIn("make([]byte, 32)", generator)+ self.assertIn("hex.EncodeToString(bytes)", generator)+ for fact in ("Before a first installation", "complete value privately",+ "not only its visible ends", "64 lowercase hexadecimal",+ "duplicated characters", "internal space or newline",+ "not every legacy, manually supplied or bootstrap credential",+ "matching shape alone does not authenticate",+ "commands, terminal output, screenshots and reports"):+ self.assertIn(fact, preparation)++ def test_bare_file_can_be_damaged_without_changing_its_hint(self):+ text = " ".join(section().split())+ metadata = (ROOT / "internal/config/api_tokens.go").read_text()+ prefix = metadata.split("func tokenPrefix(", 1)[1].split("// tokenSuffix", 1)[0]+ suffix = metadata.split("func tokenSuffix(", 1)[1].split("// HasAPITokens", 1)[0]+ self.assertIn("value[:6]", prefix)+ self.assertIn("value[len(value)-4:]", suffix)+ for fact in ("Bare does not mean intact", "Duplicated or missing characters",+ "whitespace inside a bare value", "trimming the file's ends does not repair",+ "first six and last four characters", "middle characters can leave both ends matching",+ "do not prove full equality", "intended Pulse instance or accepted reporting",+ "Do not apply this shape check to other token families",+ "rotate a working credential because it looks different"):+ self.assertIn(fact, text)+ self.assertIn("#private-file-installation-linux-macos-and-nas", section())+if __name__ == "__main__":unittest.main()