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 audit investigation responses private and bounded

pulse-triage[bot]b859bb61c84e
diff --git a/docs/AUDIT_LOGGING.md b/docs/AUDIT_LOGGING.md
index ee1e3034b0..ecd4087c15 100644
--- a/docs/AUDIT_LOGGING.md
+++ b/docs/AUDIT_LOGGING.md
@@ -75,56 +75,81 @@ in [API authentication](API.md#-authentication); never paste the token or a
session cookie into a command. For a one-off read, you can instead open the
API path in your signed-in Pulse browser.
-The loopback URLs below apply on the Pulse host. For remote access, use your
-Pulse HTTPS URL with certificate verification enabled. Use curl 7.76 or later,
-keeping `--disable` first to ignore local trace/verbose defaults.
-`--fail-with-body` returns a non-zero exit on HTTP failures, including 401,
-402 and 403. Share only the relevant redacted error, not the header file or
-whole audit response: events can contain usernames, client addresses and paths.
+Define the `pulse_api` helper from [API authentication](API.md#-authentication)
+**in the same Bash session**, using your `audit:read` header file. It is local
+example code, not an installed Pulse command. The helper requires curl 7.76 or
+later and makes one request with five-second connection and twenty-second whole
+request limits. On the Pulse host it uses loopback; for remote access, follow
+that guide's HTTPS-origin and certificate verification instructions.
+
+Each call prints only the HTTP status and a new private response file's location,
+including on HTTP failure. Open the file locally, not in a shared terminal or
+recording: events, summaries and errors can contain usernames, client addresses,
+paths and other identifying details. Keep whole responses and the header file
+private; share only a relevant manually redacted excerpt.
+
+Run only the read relevant to your investigation:
```bash
-# List recent events
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- 'http://127.0.0.1:7655/api/audit?limit=50'
+# List a small page of recent events
+pulse_api GET '/api/audit?limit=50'
# Filter by event type and date range
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- 'http://127.0.0.1:7655/api/audit?event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&success=false'
+pulse_api GET '/api/audit?limit=50&event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&success=false'
# Get audit summary
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- http://127.0.0.1:7655/api/audit/summary
+pulse_api GET /api/audit/summary
```
+HTTP 401, 402, 403, other errors and redirects are not an empty audit history.
+The helper does not follow redirects or retry. A transport failure can leave a
+partial file, not a complete result; preserve the status and original evidence
+rather than looping, resetting the store or changing a licence to make it pass.
+
### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
-| `limit` | integer | Maximum events to return (default: 100) |
+| `limit` | positive integer | List page size (default: 100, capped at 1,000) |
+| `offset` | non-negative integer | List page offset (default: 0) |
| `event` | string | Filter by event type (e.g., `login`, `password_change`) |
| `user` | string | Filter by username |
| `success` | boolean | Filter by success (`true`) or failure (`false`) |
-| `startTime` | ISO 8601 | Start of date range |
-| `endTime` | ISO 8601 | End of date range |
+| `startTime` | RFC3339 | Start of date range, with timezone |
+| `endTime` | RFC3339 | End of date range, strictly after `startTime` |
+
+These parameters describe **the event list**, not every audit endpoint. Its
+response contains an `events` page and `total` matching events; fewer rows than
+`total` do not establish missing history. Keep the same filters when reading
+another page. New events can shift offsets; a sequence of pages is not a
+consistent archival snapshot. Malformed list filters return HTTP 400, not an
+empty result. URL-encode query values; do not put private usernames or other
+identifiers into a shared command or report.
---
## Exporting Audit Data
-Export the audit log for external analysis or compliance archival:
+Use the same helper to save an export privately. For an investigation, prefer
+the relevant event type and known time range over an unfiltered whole-history
+export; replace the example dates with your incident's UTC bounds:
```bash
-umask 077
-export_dir="$(mktemp -d)" &&
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- --output "$export_dir/audit-export.json" \
- http://127.0.0.1:7655/api/audit/export &&
-printf 'Saved private export to %s\n' "$export_dir/audit-export.json"
+pulse_api GET '/api/audit/export?event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z'
```
-This creates a new private directory and prints the file's location only on
-success. It does not reuse filters selected in the UI. Treat the export as
-sensitive data; keep it outside shared repositories and issue attachments.
+The new owner-only response file is created in the helper's private directory.
+It does not reuse filters selected in the UI. Export accepts `event`, `user`,
+`success`, `startTime` and `endTime`, but **not list pagination**: adding `limit`
+or `offset` does not bound an export. With no filters it requests the full
+available history. Unlike the list, export ignores malformed time filters;
+check the dates and returned event times locally rather than assuming HTTP 200
+proves that the intended window was applied.
+
+Keep the export outside shared repositories and issue attachments. A failed or
+incomplete download is not a valid archive. Do not widen or repeat a failed
+export just to fill a report; existing evidence is valid. Dispose of private
+response files under your normal data-retention policy.
---
@@ -135,11 +160,11 @@ captured without a signer remain unsigned. Use **Verify** in the signed-in
Audit Log panel, or the authenticated read below, to check a stored signature:
```bash
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- http://127.0.0.1:7655/api/audit/6b3c9c3c-9a2f-4b3c-9a3b-3d0e8c5c5d45/verify
+pulse_api GET /api/audit/6b3c9c3c-9a2f-4b3c-9a3b-3d0e8c5c5d45/verify
```
-Response:
+Open the saved response privately; a successful verification result has this
+shape (HTTP 200 alone is not signature verification):
```json
{
"available": true,
diff --git a/frontend-modern/public/docs/AUDIT_LOGGING.md b/frontend-modern/public/docs/AUDIT_LOGGING.md
index ee1e3034b0..ecd4087c15 100644
--- a/frontend-modern/public/docs/AUDIT_LOGGING.md
+++ b/frontend-modern/public/docs/AUDIT_LOGGING.md
@@ -75,56 +75,81 @@ in [API authentication](API.md#-authentication); never paste the token or a
session cookie into a command. For a one-off read, you can instead open the
API path in your signed-in Pulse browser.
-The loopback URLs below apply on the Pulse host. For remote access, use your
-Pulse HTTPS URL with certificate verification enabled. Use curl 7.76 or later,
-keeping `--disable` first to ignore local trace/verbose defaults.
-`--fail-with-body` returns a non-zero exit on HTTP failures, including 401,
-402 and 403. Share only the relevant redacted error, not the header file or
-whole audit response: events can contain usernames, client addresses and paths.
+Define the `pulse_api` helper from [API authentication](API.md#-authentication)
+**in the same Bash session**, using your `audit:read` header file. It is local
+example code, not an installed Pulse command. The helper requires curl 7.76 or
+later and makes one request with five-second connection and twenty-second whole
+request limits. On the Pulse host it uses loopback; for remote access, follow
+that guide's HTTPS-origin and certificate verification instructions.
+
+Each call prints only the HTTP status and a new private response file's location,
+including on HTTP failure. Open the file locally, not in a shared terminal or
+recording: events, summaries and errors can contain usernames, client addresses,
+paths and other identifying details. Keep whole responses and the header file
+private; share only a relevant manually redacted excerpt.
+
+Run only the read relevant to your investigation:
```bash
-# List recent events
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- 'http://127.0.0.1:7655/api/audit?limit=50'
+# List a small page of recent events
+pulse_api GET '/api/audit?limit=50'
# Filter by event type and date range
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- 'http://127.0.0.1:7655/api/audit?event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&success=false'
+pulse_api GET '/api/audit?limit=50&event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&success=false'
# Get audit summary
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- http://127.0.0.1:7655/api/audit/summary
+pulse_api GET /api/audit/summary
```
+HTTP 401, 402, 403, other errors and redirects are not an empty audit history.
+The helper does not follow redirects or retry. A transport failure can leave a
+partial file, not a complete result; preserve the status and original evidence
+rather than looping, resetting the store or changing a licence to make it pass.
+
### Query Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
-| `limit` | integer | Maximum events to return (default: 100) |
+| `limit` | positive integer | List page size (default: 100, capped at 1,000) |
+| `offset` | non-negative integer | List page offset (default: 0) |
| `event` | string | Filter by event type (e.g., `login`, `password_change`) |
| `user` | string | Filter by username |
| `success` | boolean | Filter by success (`true`) or failure (`false`) |
-| `startTime` | ISO 8601 | Start of date range |
-| `endTime` | ISO 8601 | End of date range |
+| `startTime` | RFC3339 | Start of date range, with timezone |
+| `endTime` | RFC3339 | End of date range, strictly after `startTime` |
+
+These parameters describe **the event list**, not every audit endpoint. Its
+response contains an `events` page and `total` matching events; fewer rows than
+`total` do not establish missing history. Keep the same filters when reading
+another page. New events can shift offsets; a sequence of pages is not a
+consistent archival snapshot. Malformed list filters return HTTP 400, not an
+empty result. URL-encode query values; do not put private usernames or other
+identifiers into a shared command or report.
---
## Exporting Audit Data
-Export the audit log for external analysis or compliance archival:
+Use the same helper to save an export privately. For an investigation, prefer
+the relevant event type and known time range over an unfiltered whole-history
+export; replace the example dates with your incident's UTC bounds:
```bash
-umask 077
-export_dir="$(mktemp -d)" &&
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- --output "$export_dir/audit-export.json" \
- http://127.0.0.1:7655/api/audit/export &&
-printf 'Saved private export to %s\n' "$export_dir/audit-export.json"
+pulse_api GET '/api/audit/export?event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z'
```
-This creates a new private directory and prints the file's location only on
-success. It does not reuse filters selected in the UI. Treat the export as
-sensitive data; keep it outside shared repositories and issue attachments.
+The new owner-only response file is created in the helper's private directory.
+It does not reuse filters selected in the UI. Export accepts `event`, `user`,
+`success`, `startTime` and `endTime`, but **not list pagination**: adding `limit`
+or `offset` does not bound an export. With no filters it requests the full
+available history. Unlike the list, export ignores malformed time filters;
+check the dates and returned event times locally rather than assuming HTTP 200
+proves that the intended window was applied.
+
+Keep the export outside shared repositories and issue attachments. A failed or
+incomplete download is not a valid archive. Do not widen or repeat a failed
+export just to fill a report; existing evidence is valid. Dispose of private
+response files under your normal data-retention policy.
---
@@ -135,11 +160,11 @@ captured without a signer remain unsigned. Use **Verify** in the signed-in
Audit Log panel, or the authenticated read below, to check a stored signature:
```bash
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- http://127.0.0.1:7655/api/audit/6b3c9c3c-9a2f-4b3c-9a3b-3d0e8c5c5d45/verify
+pulse_api GET /api/audit/6b3c9c3c-9a2f-4b3c-9a3b-3d0e8c5c5d45/verify
```
-Response:
+Open the saved response privately; a successful verification result has this
+shape (HTTP 200 alone is not signature verification):
```json
{
"available": true,
diff --git a/scripts/tests/test_admin_docs.py b/scripts/tests/test_admin_docs.py
index ac59f2f572..aebc1cb988 100644
--- a/scripts/tests/test_admin_docs.py
+++ b/scripts/tests/test_admin_docs.py
@@ -10,11 +10,11 @@ from __future__ import annotations
import json
from pathlib import Path
import re
-import stat
import tempfile
import unittest
-from test_api_auth_docs import ROOT, TEST_TOKEN, exercise_curl, recording_server
+from test_api_auth_docs import (ROOT, TEST_TOKEN, exercise_curl, recording_server,
+ private_recording_server, request_helper)
DOCS = ROOT / "docs"
@@ -44,9 +44,9 @@ EXPECTED = {
),
"AUDIT_LOGGING": (
("GET", "/api/audit?limit=50", None),
- ("GET", "/api/audit?event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&success=false", None),
+ ("GET", "/api/audit?limit=50&event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z&success=false", None),
("GET", "/api/audit/summary", None),
- ("GET", "/api/audit/export", None),
+ ("GET", "/api/audit/export?event=login&startTime=2026-01-01T00:00:00Z&endTime=2026-01-31T23:59:59Z", None),
("GET", "/api/audit/6b3c9c3c-9a2f-4b3c-9a3b-3d0e8c5c5d45/verify", None),
),
"MULTI_TENANT": (
@@ -61,11 +61,19 @@ def recipes(name: str) -> list[str]:
for block in re.findall(r"```bash\n(.*?)```", (DOCS / f"{name}.md").read_text(), re.DOTALL):
# The audit read examples share a fence but are independent operations.
for step in re.split(r"\n(?=# )", block):
- if "curl " in step:
+ if "curl " in step or "pulse_api " in step:
requests.append(step)
return requests
+def executable_recipe(name: str, step: str) -> str:
+ # Use the actual shared helper, not a test-only safe client. Legacy curl
+ # snippets remain executable so the parent control can expose their leak.
+ if name == "AUDIT_LOGGING" and "pulse_api " in step:
+ return request_helper() + "\n" + step
+ return step
+
+
class AdminDocsTest(unittest.TestCase):
def test_shell_recipes_never_expose_credentials_or_override_tls(self):
for name in GUIDES:
@@ -75,7 +83,11 @@ 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)")
- self.assertIn('curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header"', step)
+ if name == "AUDIT_LOGGING":
+ self.assertIn("pulse_api GET ", step)
+ self.assertNotIn("curl ", step)
+ else:
+ self.assertIn('curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header"', step)
if re.search(r"--request (POST|PUT)", step):
self.assertIn("--data-binary @-", step)
self.assertIn("<<'JSON'", step)
@@ -91,7 +103,9 @@ class AdminDocsTest(unittest.TestCase):
for boundary in ("full-access (`*`)", "bound to an authorised administrator", "cannot be modified or deleted", "self-escalation", "complete list", "URL-encode"):
self.assertIn(boundary, rbac)
audit = (DOCS / "AUDIT_LOGGING.md").read_text()
- for boundary in ("audit:read", "audit_logging", "private directory", "redacted error", "does not reuse filters"):
+ for boundary in ("audit:read", "audit_logging", "private directory", "redacted excerpt", "does not reuse filters",
+ "in the same Bash session", "not an installed Pulse command", "not list pagination",
+ "ignores malformed time filters", "partial file", "does not follow redirects or retry"):
self.assertIn(boundary, audit)
org = (DOCS / "MULTI_TENANT.md").read_text()
for boundary in ("session-based user authentication", "403 session_required", "CSRF", "settings:read", "organization binding", "pending invitation", "accept the share", "accessRole"):
@@ -113,7 +127,7 @@ class AdminDocsTest(unittest.TestCase):
for step, (method, path, body) in zip(steps, operations):
with self.subTest(guide=name, method=method, path=path, header=key), tempfile.TemporaryDirectory(prefix="admin docs ") as temporary:
before = len(requests)
- result = exercise_curl(self, Path(temporary), f"{key}: {value}", port, step)
+ result = exercise_curl(self, Path(temporary), f"{key}: {value}", port, executable_recipe(name, step))
self.assertEqual(result.returncode, 0, result.stderr.decode())
self.assertEqual(len(requests), before + 1, "a copied step sends exactly one request")
sent_path, headers, sent_method, sent_body = requests[-1]
@@ -134,28 +148,62 @@ class AdminDocsTest(unittest.TestCase):
for step in recipes(name):
with self.subTest(status=status, guide=name), tempfile.TemporaryDirectory() as temporary:
before = len(requests)
- result = exercise_curl(self, Path(temporary), f"X-API-Token: {TEST_TOKEN}", port, step)
+ result = exercise_curl(self, Path(temporary), f"X-API-Token: {TEST_TOKEN}", port, executable_recipe(name, step))
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"))
- output = exports[0].read_bytes() if exports else result.stdout
+ if name == "AUDIT_LOGGING":
+ 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
self.assertIn(b'{"fixture":true}', output)
- def test_audit_export_creates_a_private_new_directory_and_file(self):
- step = next(step for step in recipes("AUDIT_LOGGING") if "/api/audit/export" in step)
- with recording_server() as (port, _), tempfile.TemporaryDirectory() as temporary:
+ def test_audit_reads_keep_private_success_bodies_in_new_owner_only_files(self):
+ self.assertEqual(len(recipes("AUDIT_LOGGING")), len(EXPECTED["AUDIT_LOGGING"]))
+ with private_recording_server() as (port, requests), tempfile.TemporaryDirectory() as temporary:
home = Path(temporary)
- for _ in range(2):
- result = exercise_curl(self, home, f"X-API-Token: {TEST_TOKEN}", port, step)
- self.assertEqual(result.returncode, 0, result.stderr.decode())
- output = Path(result.stdout.decode().strip().removeprefix("Saved private export to "))
- self.assertEqual(output.parent.parent, home)
- self.assertEqual(stat.S_IMODE(output.parent.stat().st_mode), 0o700)
- self.assertEqual(stat.S_IMODE(output.stat().st_mode), 0o600)
- self.assertEqual(json.loads(output.read_bytes()), {"fixture": True})
- self.assertEqual(len(list(home.glob("*/audit-export.json"))), 2)
+ for header in (f"X-API-Token: {TEST_TOKEN}", f"Authorization: Bearer {TEST_TOKEN}"):
+ for step, (method, path, _) in zip(recipes("AUDIT_LOGGING"), EXPECTED["AUDIT_LOGGING"]):
+ with self.subTest(path=path, header=header.split(":")[0]):
+ before = len(requests)
+ result = exercise_curl(self, home, header, port,
+ executable_recipe("AUDIT_LOGGING", 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.assertIn(b"HTTP 200", result.stdout)
+ # One already-retained response plus ten distinct new responses.
+ self.assertEqual(len(list((home / ".config/pulse").glob("api-response.*"))), 11)
+
+ def test_audit_reads_keep_private_http_error_bodies_and_fail(self):
+ self.assertEqual(len(recipes("AUDIT_LOGGING")), len(EXPECTED["AUDIT_LOGGING"]))
+ for status in (400, 401, 402, 403, 500, 503):
+ with private_recording_server(status) as (port, requests):
+ for step in recipes("AUDIT_LOGGING"):
+ 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("AUDIT_LOGGING", 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_audit_reads_refuse_redirect_success_and_incomplete_transfers(self):
+ self.assertEqual(len(recipes("AUDIT_LOGGING")), len(EXPECTED["AUDIT_LOGGING"]))
+ 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("AUDIT_LOGGING"):
+ 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("AUDIT_LOGGING", step), private_response=True)
+ self.assertEqual(result.returncode, expected_exit, result.stderr.decode())
+ self.assertEqual(len(requests), before + 1, "must not follow redirects or retry partial reads")
if __name__ == "__main__":