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 credential-bearing API bodies out of shell history

pulse-triage[bot]08f9b51ee512
diff --git a/docs/API.md b/docs/API.md
index 4f687ff359..13d741558c 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -147,6 +147,62 @@ verbose/trace output when sharing a result. Share only the relevant redacted
error, not the whole infrastructure response. Revoke tokens that are no longer
needed in Pulse's API Access settings.
+### Private JSON request bodies
+
+A private authentication header does **not** protect a secret copied into a
+request body on the command line. Keep passwords, client secrets and tokens out
+of shell arguments, `echo`, pasted here-documents and shared terminal recordings.
+The JSON examples on this page describe fields; do not replace their placeholders
+with real credentials in a shell command. Prefer the signed-in settings UI for
+one-off credential changes.
+
+If you deliberately need the existing [token validation endpoint](#validate-api-token-admin-session-or-settingswrite-token),
+define `pulse_api` above in the same Bash session and use a **separate, already
+authorised** `settings:write` header file. Put the token to check in a new private
+JSON file using an editor, then redirect that file into the helper:
+
+```bash
+(
+ set -eu
+ umask 077
+ body_dir="$HOME/.config/pulse"
+ if [ -L "$HOME/.config" ] || [ -L "$body_dir" ]; then
+ printf 'Refusing a symlinked request directory.\n' >&2
+ exit 1
+ fi
+ mkdir -p "$body_dir"
+ chmod 700 "$body_dir"
+ body_file=$(mktemp "$body_dir/api-body.XXXXXX")
+ printf 'Private request body: %s\n' "$body_file"
+ vi "$body_file"
+ if [ -L "$body_file" ] || [ ! -f "$body_file" ]; then
+ printf 'Request body must remain a regular file.\n' >&2
+ exit 1
+ fi
+ chmod 600 "$body_file"
+ pulse_api POST /api/security/validate-token < "$body_file"
+)
+```
+
+In the editor, save this JSON with the token you intend to check:
+
+```json
+{ "token": "<token-to-check>" }
+```
+
+The token being checked is **not** the header credential authorising validation.
+Do not widen a monitoring token merely to run this example; an ordinary protected
+read with that token checks its own access. Validation returns HTTP 200 for both
+`valid: true` and `valid: false`; inspect the saved private response, not just the
+status. A valid result updates last-used time but does not prove permission for
+another endpoint, an agent's connection or a completed operation.
+
+Preparation or editor failure stops before sending; the request is not retried.
+The body and response files remain private even after failure, and each new body
+gets a fresh filename rather than overwriting an earlier one. Keep them and any
+editor swap/backup files outside shared repositories and diagnostics, and dispose
+of them under your normal secret-retention policy. Do not print or attach them.
+
### Bearer Token
The same API token can use a Bearer header instead. Replace the header file's
@@ -1180,9 +1236,10 @@ API-token callers must hold every scope on the target token.
### Validate API Token (admin session or `settings:write` token)
`POST /api/security/validate-token`
-```json
-{ "token": "raw-token" }
-```
+
+The request body contains a secret. Use the [private JSON body recipe](#private-json-request-bodies)
+above; do not paste the token into a shell command.
+
Returns `{ "valid": true, "message": "Token is valid" }` for a known, unexpired token. An unknown or expired token returns HTTP 200 with `"valid": false` and `"message": "Token is invalid"`. An empty `token` returns HTTP 400 with `"valid": false` and `"message": "Token is required"`. When no API tokens are configured, the response is HTTP 200 with `"valid": false` and `"message": "API token authentication is not configured"`. API-token callers need the `settings:write` scope; a token without it gets HTTP 403. Non-admin proxy-auth callers get HTTP 403. Requests over the rate limit get HTTP 429. A successful validation updates the token's last-used time. This endpoint is not gated by the Pro audit licence.
### Recovery sessions (direct loopback)
diff --git a/frontend-modern/public/docs/API.md b/frontend-modern/public/docs/API.md
index 4f687ff359..13d741558c 100644
--- a/frontend-modern/public/docs/API.md
+++ b/frontend-modern/public/docs/API.md
@@ -147,6 +147,62 @@ verbose/trace output when sharing a result. Share only the relevant redacted
error, not the whole infrastructure response. Revoke tokens that are no longer
needed in Pulse's API Access settings.
+### Private JSON request bodies
+
+A private authentication header does **not** protect a secret copied into a
+request body on the command line. Keep passwords, client secrets and tokens out
+of shell arguments, `echo`, pasted here-documents and shared terminal recordings.
+The JSON examples on this page describe fields; do not replace their placeholders
+with real credentials in a shell command. Prefer the signed-in settings UI for
+one-off credential changes.
+
+If you deliberately need the existing [token validation endpoint](#validate-api-token-admin-session-or-settingswrite-token),
+define `pulse_api` above in the same Bash session and use a **separate, already
+authorised** `settings:write` header file. Put the token to check in a new private
+JSON file using an editor, then redirect that file into the helper:
+
+```bash
+(
+ set -eu
+ umask 077
+ body_dir="$HOME/.config/pulse"
+ if [ -L "$HOME/.config" ] || [ -L "$body_dir" ]; then
+ printf 'Refusing a symlinked request directory.\n' >&2
+ exit 1
+ fi
+ mkdir -p "$body_dir"
+ chmod 700 "$body_dir"
+ body_file=$(mktemp "$body_dir/api-body.XXXXXX")
+ printf 'Private request body: %s\n' "$body_file"
+ vi "$body_file"
+ if [ -L "$body_file" ] || [ ! -f "$body_file" ]; then
+ printf 'Request body must remain a regular file.\n' >&2
+ exit 1
+ fi
+ chmod 600 "$body_file"
+ pulse_api POST /api/security/validate-token < "$body_file"
+)
+```
+
+In the editor, save this JSON with the token you intend to check:
+
+```json
+{ "token": "<token-to-check>" }
+```
+
+The token being checked is **not** the header credential authorising validation.
+Do not widen a monitoring token merely to run this example; an ordinary protected
+read with that token checks its own access. Validation returns HTTP 200 for both
+`valid: true` and `valid: false`; inspect the saved private response, not just the
+status. A valid result updates last-used time but does not prove permission for
+another endpoint, an agent's connection or a completed operation.
+
+Preparation or editor failure stops before sending; the request is not retried.
+The body and response files remain private even after failure, and each new body
+gets a fresh filename rather than overwriting an earlier one. Keep them and any
+editor swap/backup files outside shared repositories and diagnostics, and dispose
+of them under your normal secret-retention policy. Do not print or attach them.
+
### Bearer Token
The same API token can use a Bearer header instead. Replace the header file's
@@ -1180,9 +1236,10 @@ API-token callers must hold every scope on the target token.
### Validate API Token (admin session or `settings:write` token)
`POST /api/security/validate-token`
-```json
-{ "token": "raw-token" }
-```
+
+The request body contains a secret. Use the [private JSON body recipe](#private-json-request-bodies)
+above; do not paste the token into a shell command.
+
Returns `{ "valid": true, "message": "Token is valid" }` for a known, unexpired token. An unknown or expired token returns HTTP 200 with `"valid": false` and `"message": "Token is invalid"`. An empty `token` returns HTTP 400 with `"valid": false` and `"message": "Token is required"`. When no API tokens are configured, the response is HTTP 200 with `"valid": false` and `"message": "API token authentication is not configured"`. API-token callers need the `settings:write` scope; a token without it gets HTTP 403. Non-admin proxy-auth callers get HTTP 403. Requests over the rate limit get HTTP 429. A successful validation updates the token's last-used time. This endpoint is not gated by the Pro audit licence.
### Recovery sessions (direct loopback)
diff --git a/scripts/tests/test_api_secret_body_docs.py b/scripts/tests/test_api_secret_body_docs.py
new file mode 100644
index 0000000000..c5aef4ab99
--- /dev/null
+++ b/scripts/tests/test_api_secret_body_docs.py
@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Execute the copied secret-body recipe, never real credentials or services."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import re
+import stat
+import subprocess
+import tempfile
+import unittest
+
+from test_api_auth_docs import (
+ DOC, TEST_TOKEN, exercise_curl, private_recording_server, recording_server,
+ request_helper,
+)
+
+
+BODY_TOKEN = "synthetic-body-secret-not-the-header"
+BODY = json.dumps({"token": BODY_TOKEN}) + "\n"
+
+
+def body_recipe() -> str:
+ blocks = re.findall(r"```bash\n(.*?)```", DOC.read_text(), re.DOTALL)
+ matches = [block for block in blocks if 'body_file=$(mktemp ' in block]
+ if len(matches) != 1:
+ raise AssertionError("expected one executable private JSON recipe")
+ return matches[0]
+
+
+def editor(home: Path, source: str | None = None) -> None:
+ tools = home / "tools"
+ tools.mkdir(exist_ok=True)
+ vi = tools / "vi"
+ vi.write_text(source or (
+ "#!/usr/bin/env python3\nimport json, os, stat, sys\nfrom pathlib import Path\n"
+ "p = Path(sys.argv[1])\n"
+ "assert len(sys.argv) == 2\n"
+ "assert p.parent == Path(os.environ['HOME']) / '.config/pulse'\n"
+ "assert p.name.startswith('api-body.')\n"
+ "assert stat.S_IMODE(p.stat().st_mode) == 0o600\n"
+ "assert stat.S_IMODE(p.parent.stat().st_mode) == 0o700\n"
+ "assert p.read_bytes() == b''\n"
+ f"p.write_text({BODY!r})\n"
+ "(Path(os.environ['HOME']) / 'editor-argv.json').write_text(json.dumps(sys.argv[1:]))\n"
+ ))
+ vi.chmod(0o700)
+
+
+class APISecretBodyDocsTest(unittest.TestCase):
+ def test_copied_body_uses_stdin_not_shell_arguments_or_history_literals(self):
+ recipe = body_recipe()
+ self.assertNotIn(BODY_TOKEN, recipe)
+ self.assertIn('pulse_api POST /api/security/validate-token < "$body_file"', recipe)
+ self.assertNotIn("<<", recipe)
+ self.assertNotIn("--data", recipe)
+ guide = DOC.read_text()
+ for boundary in ("separate, already", "settings:write", "valid: false",
+ "does not prove permission", "shell arguments", "swap/backup",
+ "Do not widen a monitoring token"):
+ self.assertIn(boundary, guide)
+
+ def test_real_transport_keeps_both_secrets_private_and_preserves_previous_files(self):
+ for key, value in (("X-API-Token", TEST_TOKEN), ("Authorization", "Bearer " + TEST_TOKEN)):
+ for status, partial, expected_exit in ((200, False, 0), (400, False, 22),
+ (403, False, 22), (302, False, 1),
+ (200, True, 18)):
+ with self.subTest(header=key, status=status, partial=partial), \
+ tempfile.TemporaryDirectory() as temporary, \
+ private_recording_server(status, partial) as (port, requests):
+ home = Path(temporary)
+ editor(home)
+ directory = home / ".config/pulse"
+ directory.mkdir(parents=True)
+ previous = directory / "api-body.previous"
+ previous.write_text("retain earlier secret body\n")
+ previous.chmod(0o600)
+ for _ in range(2):
+ before = {p: p.read_bytes() for p in directory.glob("api-body.*")}
+ result = exercise_curl(self, home, f"{key}: {value}", port,
+ request_helper() + "\n" + body_recipe(),
+ private_response=True)
+ self.assertEqual(result.returncode, expected_exit, result.stderr.decode())
+ added = set(directory.glob("api-body.*")) - before.keys()
+ self.assertEqual(len(added), 1)
+ body = added.pop()
+ self.assertEqual(body.read_text(), BODY)
+ self.assertEqual(stat.S_IMODE(body.stat().st_mode), 0o600)
+ self.assertIn(str(body).encode(), result.stdout)
+ self.assertNotIn(BODY_TOKEN.encode(), result.stdout + result.stderr)
+ self.assertNotIn(BODY_TOKEN, (home / "argv.json").read_text())
+ self.assertEqual(json.loads((home / "editor-argv.json").read_text()), [str(body)])
+ for p, content in before.items():
+ self.assertEqual(p.read_bytes(), content)
+ path, headers, method, payload = requests[-1]
+ self.assertEqual((method, path), ("POST", "/api/security/validate-token"))
+ self.assertEqual(headers[key], value)
+ self.assertEqual(json.loads(payload), {"token": BODY_TOKEN})
+ self.assertEqual(len(requests), 2, "one deliberate call each, never a redirect or retry")
+
+ def test_http_success_does_not_turn_invalid_token_into_valid_result(self):
+ response = b'{"valid":false,"message":"Token is invalid"}\n'
+ with tempfile.TemporaryDirectory() as temporary, \
+ recording_server(response=response) as (port, requests):
+ home = Path(temporary)
+ editor(home)
+ result = exercise_curl(self, home, "X-API-Token: " + TEST_TOKEN, port,
+ request_helper() + "\n" + body_recipe())
+ self.assertEqual(result.returncode, 0, "helper reports HTTP success, not token validity")
+ files = list((home / ".config/pulse").glob("api-response.*"))
+ self.assertEqual(len(files), 1)
+ self.assertIs(json.loads(files[0].read_bytes())["valid"], False)
+ self.assertEqual(stat.S_IMODE(files[0].stat().st_mode), 0o600)
+ self.assertEqual(len(requests), 1)
+
+ def run_stopped_recipe(self, home: Path) -> subprocess.CompletedProcess:
+ mock = 'pulse_api() { : > "$HOME/request-called"; }\n'
+ result = subprocess.run(["bash", "-c", mock + body_recipe()], capture_output=True,
+ env=dict(os.environ, HOME=str(home),
+ PATH=f"{home / 'tools'}:{os.environ['PATH']}"), timeout=10)
+ self.assertFalse((home / "request-called").exists())
+ return result
+
+ def test_preparation_and_editor_fail_closed_in_an_ordinary_shell(self):
+ for command in ("mkdir", "chmod", "mktemp", "vi"):
+ with self.subTest(command=command), tempfile.TemporaryDirectory() as temporary:
+ home = Path(temporary)
+ editor(home)
+ failure = home / "tools" / command
+ failure.write_text("#!/bin/sh\nexit 73\n")
+ failure.chmod(0o700)
+ self.assertEqual(self.run_stopped_recipe(home).returncode, 73)
+
+ def test_symlinked_directories_are_rejected_without_changing_the_target(self):
+ for component in (".config", ".config/pulse"):
+ with self.subTest(component=component), tempfile.TemporaryDirectory() as temporary:
+ root = Path(temporary)
+ home, target = root / "home", root / "target"
+ home.mkdir()
+ target.mkdir(mode=0o755)
+ editor(home)
+ link = home / component
+ link.parent.mkdir(parents=True, exist_ok=True)
+ link.symlink_to(target)
+ self.assertEqual(self.run_stopped_recipe(home).returncode, 1)
+ self.assertEqual(stat.S_IMODE(target.stat().st_mode), 0o755)
+ self.assertEqual(list(target.iterdir()), [])
+
+ def test_editor_replaced_symlink_is_rejected_before_read_or_chmod(self):
+ with tempfile.TemporaryDirectory() as temporary:
+ home = Path(temporary)
+ target = home / "keep-private-original"
+ target.write_text("unchanged\n")
+ target.chmod(0o644)
+ editor(home, "#!/usr/bin/env python3\nimport os, sys\nfrom pathlib import Path\n"
+ "p=Path(sys.argv[1]); p.unlink(); p.symlink_to(Path(os.environ['HOME'])/'keep-private-original')\n")
+ self.assertEqual(self.run_stopped_recipe(home).returncode, 1)
+ self.assertEqual(target.read_text(), "unchanged\n")
+ self.assertEqual(stat.S_IMODE(target.stat().st_mode), 0o644)
+
+
+if __name__ == "__main__":
+ unittest.main()