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
Keep organisation API read recipes private and bounded
pulse-triage[bot]569a77b3f995
diff --git a/docs/MULTI_TENANT.md b/docs/MULTI_TENANT.mdindex 4e7e4d070d..884b020058 100644--- a/docs/MULTI_TENANT.md+++ b/docs/MULTI_TENANT.md@@ -63,18 +63,31 @@ organization role; API tokens are rejected with `403 session_required`, evenwhen they have `settings:write`. The UI handles the session and CSRF protection.Do not extract a session cookie or CSRF token into a shell command.-The read-only curl examples use an org-bound token with `settings:read` and-the private header file from [API authentication](API.md#-authentication).+The read-only examples use an org-bound token with `settings:read`. Define the+`pulse_api` helper and prepare its private header file from+[API authentication](API.md#-authentication) in the same Bash session. This is+local example code, not an installed Pulse command.Keep the token out of command lines, URLs and reports. A token's organizationbinding is an access boundary: changing a URL or `X-Pulse-Org-ID` header doesnot grant it access to another organization.-Use curl 7.76 or later. Keep `--disable` first to ignore local trace/verbose-defaults; `--fail-with-body` makes HTTP failures return a non-zero exit. The-loopback URLs apply on the Pulse host; remotely, use your Pulse HTTPS URL and-keep certificate verification enabled. Replace the example organization ID-`production-datacenter` with your own. Run requests separately, and share only-the relevant redacted error, not whole member or infrastructure responses.+The helper requires curl 7.76 or later, ignores local trace/verbose defaults,+and applies a five-second connection limit and twenty-second whole-request+limit. It does not follow redirects or retry. It prints only the HTTP status+and the path to a new owner-only file containing the response, including on+HTTP failure. Member identities, resource details and error bodies stay out of+terminal output; open the file privately and share only a relevant redacted+excerpt, not whole member, share or infrastructure responses. A partial file+after a transport failure is not a complete list or proof that no members or+shares exist. HTTP 401/402/403 and redirects are not successful reads; do not+widen a token or use a session cookie to bypass them.++The helper's loopback origin applies on the Pulse host; remotely, follow its+HTTPS instructions and keep certificate verification enabled. Replace the+example organization ID `production-datacenter` with your own, and run each+read separately. The helper's support for other HTTP methods does not make+organization mutations token-authenticated; keep those changes in the+signed-in UI with its session and CSRF protection.## Managing Organizations@@ -106,8 +119,7 @@ Use the **Org Switcher** dropdown in the header. When you switch:**Read-only API:**```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- http://127.0.0.1:7655/api/orgs/production-datacenter/members+pulse_api GET /api/orgs/production-datacenter/members```**Invite or update a member:** use the Access panel as an owner or admin.@@ -154,8 +166,7 @@ again, so the target must accept the new grant.**Read-only incoming shares:**```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- http://127.0.0.1:7655/api/orgs/production-datacenter/shares/incoming+pulse_api GET /api/orgs/production-datacenter/shares/incoming```## Monitoring Multiple Internal Estatesdiff --git a/frontend-modern/public/docs/MULTI_TENANT.md b/frontend-modern/public/docs/MULTI_TENANT.mdindex 4e7e4d070d..884b020058 100644--- a/frontend-modern/public/docs/MULTI_TENANT.md+++ b/frontend-modern/public/docs/MULTI_TENANT.md@@ -63,18 +63,31 @@ organization role; API tokens are rejected with `403 session_required`, evenwhen they have `settings:write`. The UI handles the session and CSRF protection.Do not extract a session cookie or CSRF token into a shell command.-The read-only curl examples use an org-bound token with `settings:read` and-the private header file from [API authentication](API.md#-authentication).+The read-only examples use an org-bound token with `settings:read`. Define the+`pulse_api` helper and prepare its private header file from+[API authentication](API.md#-authentication) in the same Bash session. This is+local example code, not an installed Pulse command.Keep the token out of command lines, URLs and reports. A token's organizationbinding is an access boundary: changing a URL or `X-Pulse-Org-ID` header doesnot grant it access to another organization.-Use curl 7.76 or later. Keep `--disable` first to ignore local trace/verbose-defaults; `--fail-with-body` makes HTTP failures return a non-zero exit. The-loopback URLs apply on the Pulse host; remotely, use your Pulse HTTPS URL and-keep certificate verification enabled. Replace the example organization ID-`production-datacenter` with your own. Run requests separately, and share only-the relevant redacted error, not whole member or infrastructure responses.+The helper requires curl 7.76 or later, ignores local trace/verbose defaults,+and applies a five-second connection limit and twenty-second whole-request+limit. It does not follow redirects or retry. It prints only the HTTP status+and the path to a new owner-only file containing the response, including on+HTTP failure. Member identities, resource details and error bodies stay out of+terminal output; open the file privately and share only a relevant redacted+excerpt, not whole member, share or infrastructure responses. A partial file+after a transport failure is not a complete list or proof that no members or+shares exist. HTTP 401/402/403 and redirects are not successful reads; do not+widen a token or use a session cookie to bypass them.++The helper's loopback origin applies on the Pulse host; remotely, follow its+HTTPS instructions and keep certificate verification enabled. Replace the+example organization ID `production-datacenter` with your own, and run each+read separately. The helper's support for other HTTP methods does not make+organization mutations token-authenticated; keep those changes in the+signed-in UI with its session and CSRF protection.## Managing Organizations@@ -106,8 +119,7 @@ Use the **Org Switcher** dropdown in the header. When you switch:**Read-only API:**```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- http://127.0.0.1:7655/api/orgs/production-datacenter/members+pulse_api GET /api/orgs/production-datacenter/members```**Invite or update a member:** use the Access panel as an owner or admin.@@ -154,8 +166,7 @@ again, so the target must accept the new grant.**Read-only incoming shares:**```bash-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \- http://127.0.0.1:7655/api/orgs/production-datacenter/shares/incoming+pulse_api GET /api/orgs/production-datacenter/shares/incoming```## Monitoring Multiple Internal Estatesdiff --git a/scripts/tests/test_admin_docs.py b/scripts/tests/test_admin_docs.pyindex 268aef8201..ab4c916215 100644--- a/scripts/tests/test_admin_docs.py+++ b/scripts/tests/test_admin_docs.py@@ -83,11 +83,8 @@ class AdminDocsTest(unittest.TestCase):for step in steps:self.assertNotRegex(step, r"(?:\b\w*TOKEN=|Authorization:|X-API-Token:|Bearer\s|--cookie\b)")self.assertNotRegex(step, r"(?:--insecure|--verbose|--trace\S*|--location|\s-k\b)")- if name in ("AUDIT_LOGGING", "RBAC"):- self.assertIn("pulse_api ", step)- self.assertNotIn("curl ", step)- else:- self.assertIn('curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header"', step)+ self.assertIn("pulse_api ", step)+ self.assertNotIn("curl ", step)if re.search(r"(?:--request|pulse_api) (POST|PUT)", step):self.assertIn("--data-binary @-", request_helper() if "pulse_api " in step else step)self.assertIn("<<'JSON'", step)@@ -152,15 +149,11 @@ class AdminDocsTest(unittest.TestCase):self.assertEqual(result.returncode, 22, result.stderr.decode())self.assertEqual(len(requests), before + 1)self.assertNotIn(b"Saved private export", result.stdout)- # curl preserves an error body, in stdout or the requested file.- exports = list(Path(temporary).glob("*/audit-export.json"))- if name in ("AUDIT_LOGGING", "RBAC"):- responses = list((Path(temporary) / ".config/pulse").glob("api-response.*"))- self.assertEqual(len(responses), 1)- output = responses[0].read_bytes()- self.assertNotIn(b'{"fixture":true}', result.stdout)- else:- output = exports[0].read_bytes() if exports else result.stdout+ # Every guide preserves the error in a private response file.+ responses = list((Path(temporary) / ".config/pulse").glob("api-response.*"))+ self.assertEqual(len(responses), 1)+ output = responses[0].read_bytes()+ self.assertNotIn(b'{"fixture":true}', result.stdout)self.assertIn(b'{"fixture":true}', output)def test_audit_reads_keep_private_success_bodies_in_new_owner_only_files(self):@@ -255,6 +248,60 @@ class AdminDocsTest(unittest.TestCase):self.assertEqual(result.returncode, expected_exit, result.stderr.decode())self.assertEqual(len(requests), before + 1, "an uncertain mutation must not be repeated or redirected")+ def test_org_guidance_preserves_private_bounded_reads_and_session_mutations(self):+ guide = (DOCS / "MULTI_TENANT.md").read_text()+ for boundary in ("in the same Bash session", "not an installed Pulse command",+ "five-second", "twenty-second", "does not follow redirects or retry",+ "owner-only file", "redacted", "partial file", "not a complete list",+ "HTTP 401/402/403", "do not", "widen a token",+ "mutations token-authenticated", "signed-in UI", "CSRF"):+ self.assertIn(boundary, guide)+ for step in recipes("MULTI_TENANT"):+ self.assertRegex(step, r"^pulse_api GET /api/orgs/")+ self.assertNotIn("curl ", step)++ def test_org_reads_keep_private_success_bodies_in_new_owner_only_files(self):+ steps = recipes("MULTI_TENANT")+ self.assertEqual(len(steps), len(EXPECTED["MULTI_TENANT"]))+ with private_recording_server() as (port, requests), tempfile.TemporaryDirectory(prefix="org docs ") as temporary:+ home = Path(temporary)+ for header in (f"X-API-Token: {TEST_TOKEN}", f"Authorization: Bearer {TEST_TOKEN}"):+ for step, (method, path, _) in zip(steps, EXPECTED["MULTI_TENANT"]):+ with self.subTest(path=path, header=header.split(":")[0]):+ before = len(requests)+ result = exercise_curl(self, home, header, port,+ executable_recipe("MULTI_TENANT", step), private_response=True)+ self.assertEqual(result.returncode, 0, result.stderr.decode())+ self.assertEqual(len(requests), before + 1)+ self.assertEqual((requests[-1][2], requests[-1][0]), (method, path))+ self.assertEqual(requests[-1][3], b"", "organization reads send no mutation body")+ self.assertIn(b"HTTP 200", result.stdout)+ # Four reads retain four new files without overwriting the old response.+ self.assertEqual(len(list((home / ".config/pulse").glob("api-response.*"))), 5)++ def test_org_reads_keep_private_http_errors_and_fail_without_retry(self):+ for status in (400, 401, 402, 403, 500, 503):+ with private_recording_server(status) as (port, requests):+ for step in recipes("MULTI_TENANT"):+ with self.subTest(status=status, step=step), tempfile.TemporaryDirectory() as temporary:+ before = len(requests)+ result = exercise_curl(self, Path(temporary), f"X-API-Token: {TEST_TOKEN}", port,+ executable_recipe("MULTI_TENANT", step), private_response=True)+ self.assertEqual(result.returncode, 22, result.stderr.decode())+ self.assertEqual(len(requests), before + 1)+ self.assertIn(f"HTTP {status}".encode(), result.stdout)++ def test_org_reads_refuse_redirect_success_and_incomplete_transfer_retry(self):+ for status, partial, expected_exit in ((302, False, 1), (200, True, 18)):+ with private_recording_server(status, partial) as (port, requests):+ for step in recipes("MULTI_TENANT"):+ with self.subTest(status=status, partial=partial, step=step), tempfile.TemporaryDirectory() as temporary:+ before = len(requests)+ result = exercise_curl(self, Path(temporary), f"X-API-Token: {TEST_TOKEN}", port,+ executable_recipe("MULTI_TENANT", step), private_response=True)+ self.assertEqual(result.returncode, expected_exit, result.stderr.decode())+ self.assertEqual(len(requests), before + 1, "do not follow redirects or retry partial reads")+if __name__ == "__main__":unittest.main()