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.

Distinguish login failures by credential source and request path

pulse-triage[bot]c17d65074bc9
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 726df71068..8c5cb2c99e 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -14,9 +14,9 @@ matches how this self-hosted instance authenticates:
Pulse administrator. If the administrator deliberately kept local login as a
fallback, they can open the Pulse URL with `?show_local=true`; this only
reveals the existing local form and does not reset credentials.
-- **Temporary lockout**: wait for the lockout to expire. Another signed-in
- administrator can use the lockout reset in Pulse; password recovery is not
- required.
+- **Temporary lockout**: wait for the displayed lockout to expire. An authorised
+ administrator can use the [manual recovery API](../SECURITY.md#manual-recovery-admin);
+ this does not reset a password or bypass SSO.
#### Recover the existing local administrator login
@@ -190,13 +190,56 @@ origins, not a credential-bearing request or HAR file.
### Authentication
#### "Invalid username or password" after setup
-- **Docker Compose**: Did you escape the `$` signs in your hash? Use `$$2a$$...`.
-- **Truncated Hash**: Ensure your bcrypt hash is exactly 60 characters.
+
+When the local login form reports this error, stop repeated password guesses:
+failed attempts count against both the username and client IP. Privately check
+the existing username and the active credential source. Deployment-supplied
+`PULSE_AUTH_USER` and `PULSE_AUTH_PASS` take precedence over Pulse's generated
+`.env`, so changing only that file may leave the running password unchanged.
+
+A bcrypt hash must be complete (60 characters). Compose YAML interpolation,
+Docker `--env-file` and Pulse's generated `.env` use different quoting rules;
+do not blindly replace every `$` with `$$`. Follow the
+[authentication-file guidance](CONFIGURATION.md#private-docker-authentication-file)
+for your actual source, keeping hashes and resolved deployment configuration
+private. If the password is genuinely lost, use
+[deployment-specific recovery](#i-forgot-my-password), not setup or re-enrolment.
#### Cannot login / 401 Unauthorized
-- Clear browser cookies.
-- Check if your IP is locked out (wait 15 mins).
-- If another admin can log in, use `POST /api/security/reset-lockout` to clear the lockout for your username or IP.
+
+Identify which request failed before clearing cookies or changing credentials:
+
+- **Browser session:** a 401 on an ordinary UI request can mean a missing or
+ expired session, not a wrong password. Open the same public Pulse URL in a
+ fresh browser session and sign in through the configured method. Preserve any
+ working administrator session; do not clear unrelated sites' cookies.
+- **SSO or proxy login:** use the identity-provider or Pulse administrator's
+ recovery path. Check the [proxy authentication guide](PROXY_AUTH.md) when the
+ proxy signs you in but Pulse rejects the request. A local lockout reset does
+ not repair an identity-provider account or missing trusted proxy headers.
+- **Local login form:** an **Account locked** response gives the remaining wait.
+ Lockout applies separately to username and client IP, normally for 15 minutes;
+ clearing cookies does not reset it. A **Too many requests** response (429) is
+ rate limiting, not proof that the password is wrong. Wait rather than retrying
+ rapidly, restarting Pulse or disabling authentication.
+- **API client:** a missing or invalid API token can cause 401 even when browser
+ login works. Check the token's status and intended permissions privately.
+ A 403 can instead mean insufficient permissions or failed CSRF protection;
+ do not disable those checks or reset the password to repair API access. Use
+ the [private header-file examples](../SECURITY.md#usage), never a token or
+ session cookie pasted into a command or URL.
+
+Manual lockout reset requires an authenticated administrator with
+`settings:write` authority; session requests also require CSRF protection. The
+[manual recovery API](../SECURITY.md#manual-recovery-admin) resets one username
+or IP identifier at a time, not a password, SSO account or every lockout. Do not
+assume resetting the username also clears a separately locked IP.
+
+For a report, retain the time, sign-in method, redacted error, HTTP status and
+request path (without query strings). Keep passwords, hashes, cookies, tokens,
+full headers, **Copy as cURL** commands and network exports private. A 401 alone
+does not justify deleting configuration, recreating the data volume or
+re-enrolling agents.
#### Audit Log verification shows unsigned events
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 726df71068..8c5cb2c99e 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -14,9 +14,9 @@ matches how this self-hosted instance authenticates:
Pulse administrator. If the administrator deliberately kept local login as a
fallback, they can open the Pulse URL with `?show_local=true`; this only
reveals the existing local form and does not reset credentials.
-- **Temporary lockout**: wait for the lockout to expire. Another signed-in
- administrator can use the lockout reset in Pulse; password recovery is not
- required.
+- **Temporary lockout**: wait for the displayed lockout to expire. An authorised
+ administrator can use the [manual recovery API](../SECURITY.md#manual-recovery-admin);
+ this does not reset a password or bypass SSO.
#### Recover the existing local administrator login
@@ -190,13 +190,56 @@ origins, not a credential-bearing request or HAR file.
### Authentication
#### "Invalid username or password" after setup
-- **Docker Compose**: Did you escape the `$` signs in your hash? Use `$$2a$$...`.
-- **Truncated Hash**: Ensure your bcrypt hash is exactly 60 characters.
+
+When the local login form reports this error, stop repeated password guesses:
+failed attempts count against both the username and client IP. Privately check
+the existing username and the active credential source. Deployment-supplied
+`PULSE_AUTH_USER` and `PULSE_AUTH_PASS` take precedence over Pulse's generated
+`.env`, so changing only that file may leave the running password unchanged.
+
+A bcrypt hash must be complete (60 characters). Compose YAML interpolation,
+Docker `--env-file` and Pulse's generated `.env` use different quoting rules;
+do not blindly replace every `$` with `$$`. Follow the
+[authentication-file guidance](CONFIGURATION.md#private-docker-authentication-file)
+for your actual source, keeping hashes and resolved deployment configuration
+private. If the password is genuinely lost, use
+[deployment-specific recovery](#i-forgot-my-password), not setup or re-enrolment.
#### Cannot login / 401 Unauthorized
-- Clear browser cookies.
-- Check if your IP is locked out (wait 15 mins).
-- If another admin can log in, use `POST /api/security/reset-lockout` to clear the lockout for your username or IP.
+
+Identify which request failed before clearing cookies or changing credentials:
+
+- **Browser session:** a 401 on an ordinary UI request can mean a missing or
+ expired session, not a wrong password. Open the same public Pulse URL in a
+ fresh browser session and sign in through the configured method. Preserve any
+ working administrator session; do not clear unrelated sites' cookies.
+- **SSO or proxy login:** use the identity-provider or Pulse administrator's
+ recovery path. Check the [proxy authentication guide](PROXY_AUTH.md) when the
+ proxy signs you in but Pulse rejects the request. A local lockout reset does
+ not repair an identity-provider account or missing trusted proxy headers.
+- **Local login form:** an **Account locked** response gives the remaining wait.
+ Lockout applies separately to username and client IP, normally for 15 minutes;
+ clearing cookies does not reset it. A **Too many requests** response (429) is
+ rate limiting, not proof that the password is wrong. Wait rather than retrying
+ rapidly, restarting Pulse or disabling authentication.
+- **API client:** a missing or invalid API token can cause 401 even when browser
+ login works. Check the token's status and intended permissions privately.
+ A 403 can instead mean insufficient permissions or failed CSRF protection;
+ do not disable those checks or reset the password to repair API access. Use
+ the [private header-file examples](../SECURITY.md#usage), never a token or
+ session cookie pasted into a command or URL.
+
+Manual lockout reset requires an authenticated administrator with
+`settings:write` authority; session requests also require CSRF protection. The
+[manual recovery API](../SECURITY.md#manual-recovery-admin) resets one username
+or IP identifier at a time, not a password, SSO account or every lockout. Do not
+assume resetting the username also clears a separately locked IP.
+
+For a report, retain the time, sign-in method, redacted error, HTTP status and
+request path (without query strings). Keep passwords, hashes, cookies, tokens,
+full headers, **Copy as cURL** commands and network exports private. A 401 alone
+does not justify deleting configuration, recreating the data volume or
+re-enrolling agents.
#### Audit Log verification shows unsigned events
diff --git a/scripts/tests/test_login_troubleshooting_docs.py b/scripts/tests/test_login_troubleshooting_docs.py
new file mode 100644
index 0000000000..b9d28c4fc4
--- /dev/null
+++ b/scripts/tests/test_login_troubleshooting_docs.py
@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""Keep existing login help distinct by credential source and failure path.
+
+These are documentation/source-consistency checks, not authentication or
+installed recovery tests. No credentials, network or service changes are used.
+"""
+
+from pathlib import Path
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def section(heading: str) -> str:
+ text = (ROOT / "docs/TROUBLESHOOTING.md").read_text(encoding="utf-8")
+ return " ".join(text.split(heading + "\n", 1)[1].split("\n#### ", 1)[0].split())
+
+
+class LoginTroubleshootingDocsTest(unittest.TestCase):
+ def test_local_credentials_use_actual_precedence_and_file_format(self):
+ text = section('#### "Invalid username or password" after setup')
+ for expected in (
+ "stop repeated password guesses", "username and client IP",
+ "Deployment-supplied", "take precedence", "running password unchanged",
+ "60 characters", "Compose YAML interpolation", "Docker `--env-file`",
+ "different quoting rules", "do not blindly replace every `$` with `$$`",
+ "CONFIGURATION.md#private-docker-authentication-file",
+ "keeping hashes and resolved deployment configuration private",
+ "#i-forgot-my-password", "not setup or re-enrolment",
+ ):
+ with self.subTest(statement=expected):
+ self.assertIn(expected, text)
+ self.assertNotIn("Use `$$2a$$...`", text)
+
+ def test_browser_sso_and_api_failures_are_not_treated_as_one_password_problem(self):
+ text = section("#### Cannot login / 401 Unauthorized")
+ for expected in (
+ "Browser session", "missing or expired session, not a wrong password",
+ "same public Pulse URL", "fresh browser session",
+ "Preserve any working administrator session", "SSO or proxy login",
+ "PROXY_AUTH.md", "missing trusted proxy headers", "API client",
+ "missing or invalid API token", "even when browser login works",
+ "insufficient permissions or failed CSRF protection",
+ "do not disable those checks or reset the password",
+ ):
+ with self.subTest(statement=expected):
+ self.assertIn(expected, text)
+ self.assertNotIn("- Clear browser cookies.", text)
+
+ def test_lockout_rate_limit_and_identifier_reset_are_distinct(self):
+ text = section("#### Cannot login / 401 Unauthorized")
+ for expected in (
+ "Account locked", "remaining wait", "separately to username and client IP",
+ "clearing cookies does not reset it", "Too many requests", "429",
+ "rate limiting, not proof that the password is wrong",
+ "Wait rather than retrying rapidly, restarting Pulse or disabling authentication",
+ "authenticated administrator", "`settings:write`", "CSRF protection",
+ "resets one username or IP identifier at a time",
+ "not a password, SSO account or every lockout",
+ "Do not assume resetting the username also clears a separately locked IP",
+ "../SECURITY.md#manual-recovery-admin",
+ ):
+ with self.subTest(statement=expected):
+ self.assertIn(expected, text)
+
+ def test_reporting_preserves_state_and_does_not_request_secrets(self):
+ text = section("#### Cannot login / 401 Unauthorized")
+ for expected in (
+ "private header-file examples", "../SECURITY.md#usage",
+ "never a token or session cookie pasted into a command or URL",
+ "request path (without query strings)", "passwords, hashes, cookies, tokens",
+ "full headers", "Copy as cURL", "network exports private",
+ "does not justify deleting configuration, recreating the data volume",
+ "re-enrolling agents",
+ ):
+ with self.subTest(statement=expected):
+ self.assertIn(expected, text)
+ self.assertNotIn("```", text) # Links to the established private recipe only.
+
+ def test_guidance_still_matches_current_source_boundaries(self):
+ router = (ROOT / "internal/api/router.go").read_text(encoding="utf-8")
+ login = router.split("func (r *Router) handleLogin(", 1)[1].split(
+ "// handleResetLockout", 1
+ )[0]
+ for marker in (
+ "GetLockoutInfo(loginReq.Username)", "GetLockoutInfo(clientIP)",
+ '"account_locked"', "http.StatusForbidden", '"remainingMinutes"',
+ '"rate_limit"', "http.StatusTooManyRequests", '"invalid_credentials"',
+ "http.StatusUnauthorized",
+ ):
+ self.assertIn(marker, login)
+ reset = router.split("func (r *Router) handleResetLockout(", 1)[1].split(
+ "// handleState", 1
+ )[0]
+ for marker in ("RequireAdmin", "ensureSettingsWriteScope", "ResetLockout(resetReq.Identifier)"):
+ self.assertIn(marker, reset)
+ security = (ROOT / "internal/api/security.go").read_text(encoding="utf-8")
+ self.assertIn("lockoutDuration = 15 * time.Minute", security)
+ auth = (ROOT / "internal/api/auth.go").read_text(encoding="utf-8")
+ self.assertIn('"Invalid API token", http.StatusUnauthorized', auth)
+ self.assertIn("ValidateAndExtendSession(cookie.Value)", auth)
+
+ def test_quick_recovery_links_and_served_copy_do_not_invent_a_reset_ui(self):
+ text = (ROOT / "docs/TROUBLESHOOTING.md").read_text(encoding="utf-8")
+ quick = " ".join(text.split("### I forgot my password\n", 1)[1].split(
+ "#### Recover the existing local administrator login", 1
+ )[0].split())
+ self.assertIn("../SECURITY.md#manual-recovery-admin", quick)
+ self.assertNotIn("use the lockout reset in Pulse", quick)
+ self.assertEqual(
+ (ROOT / "docs/TROUBLESHOOTING.md").read_bytes(),
+ (ROOT / "frontend-modern/public/docs/TROUBLESHOOTING.md").read_bytes(),
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()