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.

Explain damaged bare host tokens without credential churn

pulse-triage[bot]5db15c93662a
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.md
index 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 address
in both the download and installation commands. Download to a new private
file. 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 the
right 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 cannot
safely 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.md
index 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 address
in both the download and installation commands. Download to a new private
file. 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 the
right 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 cannot
safely 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.py
index 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()