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.

Keep organisation API read recipes private and bounded

pulse-triage[bot]569a77b3f995
diff --git a/docs/MULTI_TENANT.md b/docs/MULTI_TENANT.md
index 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`, even
when 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 organization
binding is an access boundary: changing a URL or `X-Pulse-Org-ID` header does
not 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 Estates
diff --git a/frontend-modern/public/docs/MULTI_TENANT.md b/frontend-modern/public/docs/MULTI_TENANT.md
index 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`, even
when 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 organization
binding is an access boundary: changing a URL or `X-Pulse-Org-ID` header does
not 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 Estates
diff --git a/scripts/tests/test_admin_docs.py b/scripts/tests/test_admin_docs.py
index 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()