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 security recovery requests private and single-step

pulse-triage[bot]c3bae909b85b
diff --git a/SECURITY.md b/SECURITY.md
index 3776906408..a260026cb2 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -437,38 +437,59 @@ than assuming a later hash removed those copies.
#### Usage
-For automation, first follow the
-[API guide's private header-file preparation](docs/API.md#-authentication) on
-the machine running curl. It supports either `X-API-Token` or Bearer
-authentication without putting the token in arguments. Keep `--disable` first
-to ignore local curl defaults that could enable credential-bearing trace
-output; do not add verbose/trace options or follow redirects with credentials.
+For automation, follow the [API guide's private header-file preparation and
+`pulse_api` helper](docs/API.md#-authentication) on the trusted machine running
+curl. Define the helper in the **same Bash session** before using the examples
+below; it is example code, not an installed Pulse command. It supports either
+`X-API-Token` or Bearer authentication without putting a token in arguments.
These requests need curl 7.76 or later.
+The helper sends one bounded request, prints only its HTTP status and a private
+response-file path, and preserves earlier responses. It ignores local curl
+configuration, bypasses environment proxies for the default loopback origin,
+and does not follow redirects or retry an uncertain request. Response bodies,
+including errors that can echo credentials, stay out of terminal output.
+
Check protected access with a `monitoring:read` token:
```bash
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- http://127.0.0.1:7655/api/state/summary
+pulse_api GET /api/state/summary
```
`/api/health` is public, so a successful response there does **not** validate a
-token. The loopback URLs here apply only on the Pulse host. For remote access,
-substitute your verified HTTPS address in each request; use a separately
-verified private CA where necessary, not `--insecure`. Do not share unredacted
-infrastructure responses, credential files or configuration exports.
+token. The helper's default loopback origin applies only on the Pulse host.
+For remote access, configure your verified HTTPS origin **in the helper**, using
+the API guide's transport settings and a separately verified private CA where
+necessary, never `--insecure`. Do not share unredacted infrastructure responses,
+credential files or configuration exports.
For an encrypted configuration export, use a separate `settings:read` token in
the header file. Prepare the private request file without placing the
-passphrase in a command:
+passphrase in a command. This preserves an existing regular file and stops
+before the editor if a path is symlinked, not a regular file, or preparation
+fails. Use a trusted home directory; these checks do not protect against
+concurrent path replacement:
```bash
-umask 077
-mkdir -p "$HOME/.config/pulse"
-chmod 700 "$HOME/.config/pulse"
-touch "$HOME/.config/pulse/export-request.json"
-chmod 600 "$HOME/.config/pulse/export-request.json"
-vi "$HOME/.config/pulse/export-request.json"
+(
+ set -eu
+ umask 077
+ request_dir="$HOME/.config/pulse"
+ request_file="$request_dir/export-request.json"
+ if [ -L "$HOME/.config" ] || [ -L "$request_dir" ] || [ -L "$request_file" ]; then
+ printf 'Refusing a symlinked export-request path.\n' >&2
+ exit 1
+ fi
+ if [ -e "$request_file" ] && [ ! -f "$request_file" ]; then
+ printf 'Export request must be a regular file.\n' >&2
+ exit 1
+ fi
+ mkdir -p "$request_dir"
+ chmod 700 "$request_dir"
+ touch "$request_file"
+ chmod 600 "$request_file"
+ vi "$request_file"
+)
```
In the editor, save this JSON with a strong, unique passphrase of at least
@@ -478,29 +499,34 @@ In the editor, save this JSON with a strong, unique passphrase of at least
{"passphrase":"replace-with-a-strong-unique-passphrase"}
```
-Then send the private file and save the response in a new private directory:
+If a path is refused, stop and choose a private regular file through your normal
+credential-management procedure; do not unlink an unfamiliar path, add `sudo`
+or relax permissions to get past the check. Then send the private file through
+the helper, checking its path again before reading it:
```bash
-umask 077
-export_dir=$(mktemp -d "$HOME/pulse-export.XXXXXX")
-if curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- --request POST --header "Content-Type: application/json" \
- --data-binary "@$HOME/.config/pulse/export-request.json" \
- --output "$export_dir/config-export.json" \
- http://127.0.0.1:7655/api/config/export; then
- printf 'Export response saved to %s\n' "$export_dir/config-export.json"
-else
- status=$?
- printf 'Export failed; do not import the response in %s\n' "$export_dir" >&2
- exit "$status"
-fi
+(
+ set -eu
+ request_dir="$HOME/.config/pulse"
+ request_file="$request_dir/export-request.json"
+ if [ -L "$HOME/.config" ] || [ -L "$request_dir" ] || [ -L "$request_file" ] || [ ! -f "$request_file" ]; then
+ printf 'Prepare a regular, private export request first.\n' >&2
+ exit 1
+ fi
+ chmod 700 "$request_dir"
+ chmod 600 "$request_file"
+ pulse_api POST /api/config/export < "$request_file"
+)
```
-The successful response contains the encrypted bundle in `data`; it is not a
-plain configuration file. A failed response may contain an error instead of a
-bundle: never import it or treat file creation as success. Keep the passphrase
-separate from the export. Remove the temporary request file when no longer
-needed; do not include it in a diagnostics archive.
+Open the reported private response file locally. A 2xx status is HTTP success,
+not proof of an import or tested recovery. The successful export response
+contains the encrypted bundle in `data`; it is not a plain configuration file.
+An error or redirect is not a successful export, and a partial file after a
+transport failure is not a complete result. Never import one or treat file
+creation as success. Do not repeat an uncertain request just to obtain a clean
+response. Keep the passphrase separate from the export. Remove the temporary
+request file when no longer needed; do not include it in a diagnostics archive.
Configuration export accepts a token with `settings:read`; import accepts a
token with `settings:write`. Both `X-API-Token` and `Authorization: Bearer`
@@ -629,13 +655,13 @@ Notes:
#### Endpoint
```bash
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- http://127.0.0.1:7655/api/monitoring/scheduler/health
+pulse_api GET /api/monitoring/scheduler/health
```
-Use the [private header-file preparation](#usage) and a `monitoring:read`
-token. The non-zero HTTP-error exit matters; piping an unauthenticated error
-straight to `jq` can make a failed request look successful.
+First [prepare the private header file and define `pulse_api`](#usage) in the
+same Bash session, using a `monitoring:read` token. Inspect the saved response
+privately. A non-zero exit is not health evidence; piping an unauthenticated
+error straight to `jq` can make a failed request look successful.
#### Security Use Cases
1. **Anomaly Detection**
@@ -746,22 +772,30 @@ security audit, and absence from one excerpt is not proof that no secret leaked.
### Manual Recovery (Admin)
Administrators with API access can manually reset a temporary lockout; this does
-not reset a password or bypass SSO. Use the [private header file](#usage) with a
-`settings:write` token. Session-authenticated API requests also require CSRF
-protection; do not copy a session cookie into a command.
+not reset a password or bypass SSO. First [prepare the private header file and
+define `pulse_api`](#usage) in the same Bash session, using a `settings:write`
+token. Session-authenticated API requests also require CSRF protection; do not
+copy a session cookie into a command.
+
+Choose **one** request for the affected identifier and replace its placeholder
+locally. A username and client IP have separate counters; resetting one does
+not reset the other. This does not clear every lockout or change any credential.
+Inspect the private response and the affected login's ordinary result before
+considering a different identifier; do not run both examples as a batch or
+repeat an uncertain POST.
```bash
# Reset lockout for a specific username
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- --request POST --header "Content-Type: application/json" --data-binary @- \
- http://127.0.0.1:7655/api/security/reset-lockout <<'JSON'
+pulse_api POST /api/security/reset-lockout <<'JSON'
{"identifier":"username"}
JSON
+```
+Or, for the affected client IP:
+
+```bash
# Reset lockout for an IP address
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- --request POST --header "Content-Type: application/json" --data-binary @- \
- http://127.0.0.1:7655/api/security/reset-lockout <<'JSON'
+pulse_api POST /api/security/reset-lockout <<'JSON'
{"identifier":"198.51.100.100"}
JSON
```
diff --git a/frontend-modern/public/docs/SECURITY.md b/frontend-modern/public/docs/SECURITY.md
index 3776906408..a260026cb2 100644
--- a/frontend-modern/public/docs/SECURITY.md
+++ b/frontend-modern/public/docs/SECURITY.md
@@ -437,38 +437,59 @@ than assuming a later hash removed those copies.
#### Usage
-For automation, first follow the
-[API guide's private header-file preparation](docs/API.md#-authentication) on
-the machine running curl. It supports either `X-API-Token` or Bearer
-authentication without putting the token in arguments. Keep `--disable` first
-to ignore local curl defaults that could enable credential-bearing trace
-output; do not add verbose/trace options or follow redirects with credentials.
+For automation, follow the [API guide's private header-file preparation and
+`pulse_api` helper](docs/API.md#-authentication) on the trusted machine running
+curl. Define the helper in the **same Bash session** before using the examples
+below; it is example code, not an installed Pulse command. It supports either
+`X-API-Token` or Bearer authentication without putting a token in arguments.
These requests need curl 7.76 or later.
+The helper sends one bounded request, prints only its HTTP status and a private
+response-file path, and preserves earlier responses. It ignores local curl
+configuration, bypasses environment proxies for the default loopback origin,
+and does not follow redirects or retry an uncertain request. Response bodies,
+including errors that can echo credentials, stay out of terminal output.
+
Check protected access with a `monitoring:read` token:
```bash
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- http://127.0.0.1:7655/api/state/summary
+pulse_api GET /api/state/summary
```
`/api/health` is public, so a successful response there does **not** validate a
-token. The loopback URLs here apply only on the Pulse host. For remote access,
-substitute your verified HTTPS address in each request; use a separately
-verified private CA where necessary, not `--insecure`. Do not share unredacted
-infrastructure responses, credential files or configuration exports.
+token. The helper's default loopback origin applies only on the Pulse host.
+For remote access, configure your verified HTTPS origin **in the helper**, using
+the API guide's transport settings and a separately verified private CA where
+necessary, never `--insecure`. Do not share unredacted infrastructure responses,
+credential files or configuration exports.
For an encrypted configuration export, use a separate `settings:read` token in
the header file. Prepare the private request file without placing the
-passphrase in a command:
+passphrase in a command. This preserves an existing regular file and stops
+before the editor if a path is symlinked, not a regular file, or preparation
+fails. Use a trusted home directory; these checks do not protect against
+concurrent path replacement:
```bash
-umask 077
-mkdir -p "$HOME/.config/pulse"
-chmod 700 "$HOME/.config/pulse"
-touch "$HOME/.config/pulse/export-request.json"
-chmod 600 "$HOME/.config/pulse/export-request.json"
-vi "$HOME/.config/pulse/export-request.json"
+(
+ set -eu
+ umask 077
+ request_dir="$HOME/.config/pulse"
+ request_file="$request_dir/export-request.json"
+ if [ -L "$HOME/.config" ] || [ -L "$request_dir" ] || [ -L "$request_file" ]; then
+ printf 'Refusing a symlinked export-request path.\n' >&2
+ exit 1
+ fi
+ if [ -e "$request_file" ] && [ ! -f "$request_file" ]; then
+ printf 'Export request must be a regular file.\n' >&2
+ exit 1
+ fi
+ mkdir -p "$request_dir"
+ chmod 700 "$request_dir"
+ touch "$request_file"
+ chmod 600 "$request_file"
+ vi "$request_file"
+)
```
In the editor, save this JSON with a strong, unique passphrase of at least
@@ -478,29 +499,34 @@ In the editor, save this JSON with a strong, unique passphrase of at least
{"passphrase":"replace-with-a-strong-unique-passphrase"}
```
-Then send the private file and save the response in a new private directory:
+If a path is refused, stop and choose a private regular file through your normal
+credential-management procedure; do not unlink an unfamiliar path, add `sudo`
+or relax permissions to get past the check. Then send the private file through
+the helper, checking its path again before reading it:
```bash
-umask 077
-export_dir=$(mktemp -d "$HOME/pulse-export.XXXXXX")
-if curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- --request POST --header "Content-Type: application/json" \
- --data-binary "@$HOME/.config/pulse/export-request.json" \
- --output "$export_dir/config-export.json" \
- http://127.0.0.1:7655/api/config/export; then
- printf 'Export response saved to %s\n' "$export_dir/config-export.json"
-else
- status=$?
- printf 'Export failed; do not import the response in %s\n' "$export_dir" >&2
- exit "$status"
-fi
+(
+ set -eu
+ request_dir="$HOME/.config/pulse"
+ request_file="$request_dir/export-request.json"
+ if [ -L "$HOME/.config" ] || [ -L "$request_dir" ] || [ -L "$request_file" ] || [ ! -f "$request_file" ]; then
+ printf 'Prepare a regular, private export request first.\n' >&2
+ exit 1
+ fi
+ chmod 700 "$request_dir"
+ chmod 600 "$request_file"
+ pulse_api POST /api/config/export < "$request_file"
+)
```
-The successful response contains the encrypted bundle in `data`; it is not a
-plain configuration file. A failed response may contain an error instead of a
-bundle: never import it or treat file creation as success. Keep the passphrase
-separate from the export. Remove the temporary request file when no longer
-needed; do not include it in a diagnostics archive.
+Open the reported private response file locally. A 2xx status is HTTP success,
+not proof of an import or tested recovery. The successful export response
+contains the encrypted bundle in `data`; it is not a plain configuration file.
+An error or redirect is not a successful export, and a partial file after a
+transport failure is not a complete result. Never import one or treat file
+creation as success. Do not repeat an uncertain request just to obtain a clean
+response. Keep the passphrase separate from the export. Remove the temporary
+request file when no longer needed; do not include it in a diagnostics archive.
Configuration export accepts a token with `settings:read`; import accepts a
token with `settings:write`. Both `X-API-Token` and `Authorization: Bearer`
@@ -629,13 +655,13 @@ Notes:
#### Endpoint
```bash
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- http://127.0.0.1:7655/api/monitoring/scheduler/health
+pulse_api GET /api/monitoring/scheduler/health
```
-Use the [private header-file preparation](#usage) and a `monitoring:read`
-token. The non-zero HTTP-error exit matters; piping an unauthenticated error
-straight to `jq` can make a failed request look successful.
+First [prepare the private header file and define `pulse_api`](#usage) in the
+same Bash session, using a `monitoring:read` token. Inspect the saved response
+privately. A non-zero exit is not health evidence; piping an unauthenticated
+error straight to `jq` can make a failed request look successful.
#### Security Use Cases
1. **Anomaly Detection**
@@ -746,22 +772,30 @@ security audit, and absence from one excerpt is not proof that no secret leaked.
### Manual Recovery (Admin)
Administrators with API access can manually reset a temporary lockout; this does
-not reset a password or bypass SSO. Use the [private header file](#usage) with a
-`settings:write` token. Session-authenticated API requests also require CSRF
-protection; do not copy a session cookie into a command.
+not reset a password or bypass SSO. First [prepare the private header file and
+define `pulse_api`](#usage) in the same Bash session, using a `settings:write`
+token. Session-authenticated API requests also require CSRF protection; do not
+copy a session cookie into a command.
+
+Choose **one** request for the affected identifier and replace its placeholder
+locally. A username and client IP have separate counters; resetting one does
+not reset the other. This does not clear every lockout or change any credential.
+Inspect the private response and the affected login's ordinary result before
+considering a different identifier; do not run both examples as a batch or
+repeat an uncertain POST.
```bash
# Reset lockout for a specific username
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- --request POST --header "Content-Type: application/json" --data-binary @- \
- http://127.0.0.1:7655/api/security/reset-lockout <<'JSON'
+pulse_api POST /api/security/reset-lockout <<'JSON'
{"identifier":"username"}
JSON
+```
+Or, for the affected client IP:
+
+```bash
# Reset lockout for an IP address
-curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header" \
- --request POST --header "Content-Type: application/json" --data-binary @- \
- http://127.0.0.1:7655/api/security/reset-lockout <<'JSON'
+pulse_api POST /api/security/reset-lockout <<'JSON'
{"identifier":"198.51.100.100"}
JSON
```
diff --git a/scripts/tests/test_api_auth_docs.py b/scripts/tests/test_api_auth_docs.py
index 7fb1efedb2..2b5e3369a3 100644
--- a/scripts/tests/test_api_auth_docs.py
+++ b/scripts/tests/test_api_auth_docs.py
@@ -119,7 +119,7 @@ def private_recording_server(status: int = 200, partial: bool = False):
def exercise_curl(case: unittest.TestCase, home: Path, header_text: str, port: int, request: str,
- *, private_response: bool = False):
+ *, private_response: bool = False, proxy_port: int | None = None):
"""Execute the exact copied recipe; capture argv and hostile curl defaults."""
header = home / ".config/pulse/api-header"
header.parent.mkdir(parents=True, exist_ok=True)
@@ -159,6 +159,12 @@ def exercise_curl(case: unittest.TestCase, home: Path, header_text: str, port: i
for key in list(env):
if key.lower().endswith("_proxy"):
del env[key]
+ if proxy_port is not None:
+ # A guest-local recording proxy witnesses whether a copied loopback
+ # recipe can disclose its credential through inherited proxy settings.
+ proxy = f"http://127.0.0.1:{proxy_port}"
+ env.update(http_proxy=proxy, HTTPS_PROXY=proxy, ALL_PROXY=proxy,
+ no_proxy="", NO_PROXY="")
request = request.replace("http://127.0.0.1:7655", f"http://127.0.0.1:{port}")
result = subprocess.run(["bash", "-eu", "-c", request], env=env, capture_output=True, timeout=10)
calls = [json.loads(line) for line in receipt.read_text().splitlines()]
diff --git a/scripts/tests/test_security_docs.py b/scripts/tests/test_security_docs.py
index 99447d0006..6e63099aab 100644
--- a/scripts/tests/test_security_docs.py
+++ b/scripts/tests/test_security_docs.py
@@ -17,7 +17,9 @@ import subprocess
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,
+ private_recording_server, recording_server,
+ request_helper)
DOC = ROOT / "SECURITY.md"
@@ -37,7 +39,7 @@ def blocks() -> list[str]:
def recipes() -> list[str]:
return [step for block in blocks() for step in re.split(r"\n(?=# )", block)
- if "curl " in step]
+ if "pulse_api " in step]
def private_export_request(home: Path):
@@ -52,26 +54,31 @@ class SecurityDocsTest(unittest.TestCase):
self.assertEqual(DOC.read_bytes(),
(ROOT / "frontend-modern/public/docs/SECURITY.md").read_bytes())
- def test_copied_requests_never_expose_credentials_or_weaken_tls(self):
+ def test_copied_requests_use_the_existing_private_response_helper(self):
requests = recipes()
self.assertEqual(len(requests), len(EXPECTED))
- for request in requests:
+ for request, (method, path, _body) in zip(requests, EXPECTED):
+ self.assertEqual(request.count("pulse_api "), 1,
+ "each copied block must send only its selected operation")
+ self.assertIn(f"pulse_api {method} {path}", request)
self.assertNotRegex(request, r"(?:\b\w*TOKEN=|X-API-Token:|Authorization:|Bearer\s|--cookie\b)")
self.assertNotRegex(request, r"(?:--insecure|--verbose|--trace\S*|--location|\s-k\b)")
- self.assertIn('curl --disable --fail-with-body --header "@$HOME/.config/pulse/api-header"', request)
- if "/api/config/export" in request:
- self.assertIn('--data-binary "@$HOME/.config/pulse/export-request.json"', request)
+ if path == "/api/config/export":
+ self.assertIn('pulse_api POST /api/config/export < "$request_file"', request)
self.assertNotIn('"passphrase":', request)
- elif "--request POST" in request:
- self.assertIn("--data-binary @-", request)
+ elif method == "POST":
self.assertIn("<<'JSON'", request)
shell = "\n".join(blocks())
- self.assertNotRegex(shell, r"(?:--token\s|PULSE_AUTH_PASS=|API_TOKEN[S]?=|curl[^\n]*\|)")
+ self.assertNotRegex(shell, r"(?:--token\s|PULSE_AUTH_PASS=|API_TOKEN[S]?=|curl\s)")
self.assertNotIn("rm -rf", shell)
self.assertNotIn("authorized_keys", shell)
+ for block in blocks():
+ subprocess.run(["bash", "-n", "-c", block], check=True, capture_output=True)
+
+ def export_preparation(self):
+ return next(block for block in blocks() if 'vi "$request_file"' in block)
def test_export_preparation_protects_new_and_existing_files_without_erasing_them(self):
- preparation = next(block for block in blocks() if 'vi "$HOME/.config/pulse/export-request.json"' in block)
with tempfile.TemporaryDirectory() as temporary:
home = Path(temporary)
tools = home / "tools"
@@ -87,21 +94,25 @@ class SecurityDocsTest(unittest.TestCase):
private_export_request(home)
request.chmod(0o644)
request.parent.chmod(0o755)
- subprocess.run(["bash", "-eu", "-c", preparation], env=env, check=True, timeout=10)
+ # No caller-provided -e: the copied block must fail closed.
+ subprocess.run(["bash", "-c", self.export_preparation()], env=env, check=True, timeout=10)
self.assertEqual(stat.S_IMODE(request.stat().st_mode), 0o600)
self.assertEqual(stat.S_IMODE(request.parent.stat().st_mode), 0o700)
self.assertEqual(request.read_text(), json.dumps({"passphrase": TEST_PASSPHRASE}) if existing else "")
def test_exact_methods_paths_and_bodies_with_both_supported_headers(self):
- steps = recipes()
- with recording_server() as (port, requests):
+ with private_recording_server() as (port, requests):
for key, value in (("X-API-Token", TEST_TOKEN), ("Authorization", "Bearer " + TEST_TOKEN)):
- for step, (method, path, body) in zip(steps, EXPECTED):
+ for step, (method, path, body) in zip(recipes(), EXPECTED):
with self.subTest(header=key, method=method, path=path), tempfile.TemporaryDirectory() as temporary:
home = Path(temporary)
private_export_request(home)
- result = exercise_curl(self, home, f"{key}: {value}", port, step)
+ before = len(requests)
+ result = exercise_curl(self, home, f"{key}: {value}", port,
+ request_helper() + "\n" + step,
+ private_response=True)
self.assertEqual(result.returncode, 0, result.stderr.decode())
+ self.assertEqual(len(requests), before + 1)
self.assertEqual(requests[-1][0], path)
self.assertEqual(requests[-1][1][key], value)
self.assertNotIn("X-Curlrc-Injected", requests[-1][1])
@@ -109,39 +120,116 @@ class SecurityDocsTest(unittest.TestCase):
self.assertEqual(json.loads(requests[-1][3]) if body is not None else None, body)
self.assertNotIn(TEST_PASSPHRASE.encode(), result.stdout + result.stderr)
self.assertNotIn(TEST_PASSPHRASE, (home / "argv.json").read_text())
- if path == "/api/config/export":
- self.check_export_files(home, result, success=True)
-
- def check_export_files(self, home: Path, result, *, success: bool):
- directories = list(home.glob("pulse-export.*"))
- self.assertEqual(len(directories), 1)
- directory = directories[0]
- output = directory / "config-export.json"
- self.assertEqual(stat.S_IMODE(directory.stat().st_mode), 0o700)
- self.assertEqual(stat.S_IMODE(output.stat().st_mode), 0o600)
- # A recording server does not prove encryption. This only checks the
- # exact response is saved privately, with truthful HTTP success/failure.
- self.assertEqual(output.read_text(), '{"fixture":true}\n')
- self.assertNotIn(TEST_TOKEN, output.read_text())
- self.assertNotIn(TEST_PASSPHRASE, output.read_text())
- if success:
- self.assertIn(b"Export response saved", result.stdout)
- else:
- self.assertNotIn(b"Export response saved", result.stdout)
- self.assertIn(b"Export failed; do not import", result.stderr)
-
- def test_unauthorised_and_wrong_scope_responses_never_report_success(self):
- for status in (401, 403, 500):
- with self.subTest(status=status), recording_server(status) as (port, requests):
- for step, (_, path, _) in zip(recipes(), EXPECTED):
- with self.subTest(path=path), tempfile.TemporaryDirectory() as temporary:
+
+ def test_loopback_security_requests_bypass_environment_proxy(self):
+ with private_recording_server() as (port, requests), recording_server() as (proxy_port, proxy_requests):
+ for step, (method, path, _body) in zip(recipes(), EXPECTED):
+ with self.subTest(method=method, path=path), tempfile.TemporaryDirectory() as temporary:
+ home = Path(temporary)
+ private_export_request(home)
+ before = len(requests)
+ result = exercise_curl(self, home, f"X-API-Token: {TEST_TOKEN}", port,
+ request_helper() + "\n" + step,
+ private_response=True, proxy_port=proxy_port)
+ self.assertEqual(result.returncode, 0, result.stderr.decode())
+ self.assertEqual(len(requests), before + 1)
+ self.assertEqual(requests[-1][0], path)
+ self.assertEqual(proxy_requests, [], "proxy received a private loopback request")
+
+ def test_http_errors_redirects_and_partial_bodies_fail_privately_without_retry(self):
+ for status, partial, expected_exit in ((401, False, 22), (403, False, 22),
+ (500, False, 22), (302, False, 1),
+ (200, True, 18)):
+ with self.subTest(status=status, partial=partial), private_recording_server(status, partial) as (port, requests):
+ for step, (method, path, _body) in zip(recipes(), EXPECTED):
+ with self.subTest(method=method, path=path), tempfile.TemporaryDirectory() as temporary:
home = Path(temporary)
private_export_request(home)
- result = exercise_curl(self, home, f"X-API-Token: {TEST_TOKEN}", port, step)
- self.assertNotEqual(result.returncode, 0)
+ before = len(requests)
+ result = exercise_curl(self, home, f"X-API-Token: {TEST_TOKEN}", port,
+ request_helper() + "\n" + step,
+ private_response=True)
+ self.assertEqual(result.returncode, expected_exit, result.stderr.decode())
+ self.assertEqual(len(requests), before + 1,
+ "a failed or uncertain operation must not be retried or redirected")
self.assertEqual(requests[-1][0], path)
- if path == "/api/config/export":
- self.check_export_files(home, result, success=False)
+ self.assertNotIn(TEST_PASSPHRASE.encode(), result.stdout + result.stderr)
+
+ def test_export_paths_are_checked_before_editor_or_transport(self):
+ export = next(step for step in recipes() if "/api/config/export" in step)
+ for operation, script in (("prepare", self.export_preparation()),
+ ("send", export)):
+ for component in (".config", ".config/pulse", ".config/pulse/export-request.json"):
+ for kind in ("symlink", "dangling", "wrong-type"):
+ with self.subTest(operation=operation, component=component, kind=kind), tempfile.TemporaryDirectory() as temporary:
+ home = Path(temporary) / "home"
+ home.mkdir()
+ node = home / component
+ node.parent.mkdir(parents=True, exist_ok=True)
+ target = Path(temporary) / "target"
+ is_file = component.endswith(".json")
+ if kind != "dangling":
+ if is_file:
+ target.write_text("preserve existing sensitive fixture\n")
+ target.chmod(0o640)
+ else:
+ target.mkdir()
+ target.chmod(0o750)
+ if kind == "wrong-type":
+ if is_file:
+ os.mkfifo(node)
+ else:
+ node.write_text("not a directory\n")
+ else:
+ node.symlink_to(target)
+ tools = home / "tools"
+ tools.mkdir()
+ for name in ("vi", "curl"):
+ tool = tools / name
+ tool.write_text(f'#!/bin/sh\n: > "$HOME/{name}-called"\nexit 79\n')
+ tool.chmod(0o700)
+ before_mode = stat.S_IMODE(target.stat().st_mode) if target.exists() else None
+ env = dict(os.environ, HOME=str(home), PATH=f"{tools}:{os.environ['PATH']}")
+ result = subprocess.run(["bash", "-c", request_helper() + "\n" + script],
+ env=env, capture_output=True, timeout=10)
+ self.assertNotEqual(result.returncode, 0)
+ self.assertFalse((home / "vi-called").exists())
+ self.assertFalse((home / "curl-called").exists())
+ self.assertNotIn(TEST_PASSPHRASE.encode(), result.stdout + result.stderr)
+ if before_mode is not None:
+ self.assertEqual(stat.S_IMODE(target.stat().st_mode), before_mode)
+ if is_file:
+ self.assertEqual(target.read_text(), "preserve existing sensitive fixture\n")
+ else:
+ self.assertEqual(list(target.iterdir()), [])
+ else:
+ self.assertFalse(target.exists())
+
+ def test_preparation_failures_stop_before_editor_and_send_failures_before_transport(self):
+ export = next(step for step in recipes() if "/api/config/export" in step)
+ for operation, script, commands in (("prepare", self.export_preparation(), ("mkdir", "chmod", "touch")),
+ ("send", export, ("chmod",))):
+ for command in commands:
+ with self.subTest(operation=operation, command=command), tempfile.TemporaryDirectory() as temporary:
+ home = Path(temporary)
+ private_export_request(home)
+ tools = home / "tools"
+ tools.mkdir()
+ for name in ("vi", "curl"):
+ tool = tools / name
+ tool.write_text(f'#!/bin/sh\n: > "$HOME/{name}-called"\n')
+ tool.chmod(0o700)
+ failure = tools / command
+ failure.write_text("#!/bin/sh\nexit 73\n")
+ failure.chmod(0o700)
+ env = dict(os.environ, HOME=str(home), PATH=f"{tools}:{os.environ['PATH']}")
+ result = subprocess.run(["bash", "-c", request_helper() + "\n" + script],
+ env=env, capture_output=True, timeout=10)
+ self.assertEqual(result.returncode, 73)
+ self.assertFalse((home / "vi-called").exists())
+ self.assertFalse((home / "curl-called").exists())
+ self.assertEqual((home / ".config/pulse/export-request.json").read_text(),
+ json.dumps({"passphrase": TEST_PASSPHRASE}))
def test_guidance_retains_authority_and_credential_lifecycle_boundaries(self):
guide = " ".join(DOC.read_text().split())
@@ -154,6 +242,14 @@ class SecurityDocsTest(unittest.TestCase):
self.assertTrue(boundary in guide, f"missing safety boundary: {boundary}")
self.assertIn("docs/UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nas", guide)
self.assertIn("docs/TROUBLESHOOTING.md#i-forgot-my-password", guide)
+ for boundary in ("same Bash session", "not an installed Pulse command",
+ "prints only its HTTP status", "preserves earlier responses",
+ "bypasses environment proxies", "does not follow redirects",
+ "private response-file path", "not a complete result",
+ "not proof of an import or tested recovery", "concurrent path replacement",
+ "Choose **one** request", "separate counters",
+ "do not run both examples as a batch", "repeat an uncertain POST"):
+ self.assertIn(boundary, guide)
self.assertNotIn("### What's **Not** Encrypted", guide)
def test_encrypted_file_examples_match_the_actual_store_and_data_path(self):