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
Refuse unsafe Docker authentication file paths in setup help
pulse-triage[bot]d4f23d16023d
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.mdindex 76b92778cb..83d2a7ee12 100644--- a/docs/CONFIGURATION.md+++ b/docs/CONFIGURATION.md@@ -89,17 +89,33 @@ password supplied by your deployment manager; update that managed source too.If automation must skip browser setup, keep the credentials in a private file,not a `docker run -e PULSE_AUTH_PASS=...` command, shell history or a shared-Compose file. On the Docker host, prepare the file below. These commands do not-erase an existing file; edit it locally, without printing its contents:+Compose file. On the Docker host, use your own trusted home directory and+prepare the file below. It refuses symlinks (including `.config`), non-directory+parents and non-regular credential files before changing permissions or opening+the editor. It preserves an existing regular file's contents; edit it locally,+without printing them. Do not run this while another process is changing these+paths; these checks are not protection against concurrent path replacement.```bash(- set -e+ set -euumask 077auth_dir="$HOME/.config/pulse"auth_file="$auth_dir/docker-auth.env"- if [ -L "$auth_dir" ] || [ -L "$auth_file" ]; then- printf 'Refusing a symlinked credential path.\n' >&2+ for path in "$HOME/.config" "$auth_dir" "$auth_file"; do+ if [ -L "$path" ]; then+ printf 'Refusing a symlinked credential path.\n' >&2+ exit 1+ fi+ done+ for directory in "$HOME/.config" "$auth_dir"; do+ if [ -e "$directory" ] && [ ! -d "$directory" ]; then+ printf 'Credential parent is not a directory; stopping.\n' >&2+ exit 1+ fi+ done+ if [ -e "$auth_file" ] && [ ! -f "$auth_file" ]; then+ printf 'Credential file is not a regular file; stopping.\n' >&2exit 1fimkdir -p "$auth_dir"@@ -110,6 +126,11 @@ erase an existing file; edit it locally, without printing its contents:)```+If a path is refused, stop. Do not unlink it, overwrite its target, add `sudo`+or weaken the checks. Use browser bootstrap setup instead, or have the local+administrator establish a trusted private path. The launch step below checks+the paths again and restores owner-only permissions before contacting Docker.+In that editor, enter these two settings and replace the placeholder with a**complete bcrypt hash** generated by a trusted local tool with an interactivepassword prompt. Do not put the password in that tool's command arguments.@@ -126,16 +147,27 @@ tag you intend to install, then run:```bash(- set -e- if [ ! -s "$HOME/.config/pulse/docker-auth.env" ]; then+ set -eu+ auth_dir="$HOME/.config/pulse"+ auth_file="$auth_dir/docker-auth.env"+ for path in "$HOME/.config" "$auth_dir" "$auth_file"; do+ if [ -L "$path" ]; then+ printf 'Refusing a symlinked credential path.\n' >&2+ exit 1+ fi+ done+ if [ ! -d "$HOME/.config" ] || [ ! -d "$auth_dir" ] || \+ [ ! -f "$auth_file" ] || [ ! -s "$auth_file" ]; thenprintf 'Prepare the private authentication file first.\n' >&2exit 1fi+ chmod 700 "$auth_dir"+ chmod 600 "$auth_file"docker run -d \--name pulse \-p 7655:7655 \-v pulse_data:/data \- --env-file "$HOME/.config/pulse/docker-auth.env" \+ --env-file "$auth_file" \-e PULSE_DEPLOYMENT_METHOD=docker_run \--restart unless-stopped \rcourtman/pulse:vX.Y.Zdiff --git a/frontend-modern/public/docs/CONFIGURATION.md b/frontend-modern/public/docs/CONFIGURATION.mdindex 76b92778cb..83d2a7ee12 100644--- a/frontend-modern/public/docs/CONFIGURATION.md+++ b/frontend-modern/public/docs/CONFIGURATION.md@@ -89,17 +89,33 @@ password supplied by your deployment manager; update that managed source too.If automation must skip browser setup, keep the credentials in a private file,not a `docker run -e PULSE_AUTH_PASS=...` command, shell history or a shared-Compose file. On the Docker host, prepare the file below. These commands do not-erase an existing file; edit it locally, without printing its contents:+Compose file. On the Docker host, use your own trusted home directory and+prepare the file below. It refuses symlinks (including `.config`), non-directory+parents and non-regular credential files before changing permissions or opening+the editor. It preserves an existing regular file's contents; edit it locally,+without printing them. Do not run this while another process is changing these+paths; these checks are not protection against concurrent path replacement.```bash(- set -e+ set -euumask 077auth_dir="$HOME/.config/pulse"auth_file="$auth_dir/docker-auth.env"- if [ -L "$auth_dir" ] || [ -L "$auth_file" ]; then- printf 'Refusing a symlinked credential path.\n' >&2+ for path in "$HOME/.config" "$auth_dir" "$auth_file"; do+ if [ -L "$path" ]; then+ printf 'Refusing a symlinked credential path.\n' >&2+ exit 1+ fi+ done+ for directory in "$HOME/.config" "$auth_dir"; do+ if [ -e "$directory" ] && [ ! -d "$directory" ]; then+ printf 'Credential parent is not a directory; stopping.\n' >&2+ exit 1+ fi+ done+ if [ -e "$auth_file" ] && [ ! -f "$auth_file" ]; then+ printf 'Credential file is not a regular file; stopping.\n' >&2exit 1fimkdir -p "$auth_dir"@@ -110,6 +126,11 @@ erase an existing file; edit it locally, without printing its contents:)```+If a path is refused, stop. Do not unlink it, overwrite its target, add `sudo`+or weaken the checks. Use browser bootstrap setup instead, or have the local+administrator establish a trusted private path. The launch step below checks+the paths again and restores owner-only permissions before contacting Docker.+In that editor, enter these two settings and replace the placeholder with a**complete bcrypt hash** generated by a trusted local tool with an interactivepassword prompt. Do not put the password in that tool's command arguments.@@ -126,16 +147,27 @@ tag you intend to install, then run:```bash(- set -e- if [ ! -s "$HOME/.config/pulse/docker-auth.env" ]; then+ set -eu+ auth_dir="$HOME/.config/pulse"+ auth_file="$auth_dir/docker-auth.env"+ for path in "$HOME/.config" "$auth_dir" "$auth_file"; do+ if [ -L "$path" ]; then+ printf 'Refusing a symlinked credential path.\n' >&2+ exit 1+ fi+ done+ if [ ! -d "$HOME/.config" ] || [ ! -d "$auth_dir" ] || \+ [ ! -f "$auth_file" ] || [ ! -s "$auth_file" ]; thenprintf 'Prepare the private authentication file first.\n' >&2exit 1fi+ chmod 700 "$auth_dir"+ chmod 600 "$auth_file"docker run -d \--name pulse \-p 7655:7655 \-v pulse_data:/data \- --env-file "$HOME/.config/pulse/docker-auth.env" \+ --env-file "$auth_file" \-e PULSE_DEPLOYMENT_METHOD=docker_run \--restart unless-stopped \rcourtman/pulse:vX.Y.Zdiff --git a/scripts/tests/test_configuration_auth_docs.py b/scripts/tests/test_configuration_auth_docs.pyindex cbc44aa3ec..07848d5840 100644--- a/scripts/tests/test_configuration_auth_docs.py+++ b/scripts/tests/test_configuration_auth_docs.py@@ -44,12 +44,14 @@ sys.exit(int(os.environ.get('EDITOR_EXIT', '0')))'''DOCKER = '''#!/usr/bin/env python3-import json, os, sys+import json, os, stat, sysfrom pathlib import Pathargs = sys.argv[1:]p = Path(args[args.index('--env-file') + 1])assert p == Path.home() / '.config/pulse/docker-auth.env'assert p.read_text() == os.environ['EXPECTED_FILE']+assert stat.S_IMODE(p.stat().st_mode) == 0o600+assert stat.S_IMODE(p.parent.stat().st_mode) == 0o700assert os.environ['FIXTURE_HASH'] not in ' '.join(args)assert not any(a.startswith('PULSE_AUTH_PASS=') for a in args)(Path.home() / 'docker.json').write_text(json.dumps(args))@@ -165,6 +167,87 @@ class ConfigurationAuthDocsTest(unittest.TestCase):self.assertEqual(result.returncode, 23)self.assertEqual(path.read_text(), CONTENT)+ def test_both_steps_reject_unsafe_paths_before_any_operation(self):+ for needle in ('vi "$auth_file"', "docker run -d"):+ for placement in (".config", ".config/pulse", ".config/pulse/docker-auth.env"):+ for kind in ("symlink", "dangling-symlink", "fifo", "wrong-type"):+ with self.subTest(recipe=needle, path=placement, kind=kind), \+ tempfile.TemporaryDirectory(prefix="auth paths ") as temp:+ home = Path(temp)+ path = home / placement+ path.parent.mkdir(parents=True, exist_ok=True)+ outside = home / "untouched"+ outside.mkdir(mode=0o755)+ witness = outside / "docker-auth.env"+ witness.write_text(CONTENT)+ witness.chmod(0o644)+ before = (witness.stat(), outside.stat())+ file_path = placement.endswith(".env")+ if kind == "symlink":+ path.symlink_to(witness if file_path else outside)+ elif kind == "dangling-symlink":+ path.symlink_to(home / "must-not-be-created")+ elif kind == "fifo":+ os.mkfifo(path)+ elif file_path:+ path.mkdir()+ else:+ path.write_text("not a directory")+ original = path.lstat()+ tools = home / "tools"+ tools.mkdir()+ receipt = home / "operation-called"+ for name in ("mkdir", "chmod", "touch", "vi", "docker"):+ tool = tools / name+ tool.write_text('#!/bin/sh\nprintf called >> "$OPERATION_RECEIPT"\nexit 23\n')+ tool.chmod(0o700)+ env = {**os.environ, "HOME": str(home),+ "PATH": f"{tools}:{os.environ['PATH']}",+ "OPERATION_RECEIPT": str(receipt)}+ result = subprocess.run(["bash", "-c", recipe(needle)],+ env=env, capture_output=True, timeout=10)+ self.assertNotEqual(result.returncode, 0)+ self.assertFalse(receipt.exists(), "must stop before mutation, editor or Docker")+ self.assertEqual(path.lstat(), original)+ self.assertEqual((witness.stat(), outside.stat()), before)+ self.assertEqual(witness.read_text(), CONTENT)+ self.assertFalse((home / "must-not-be-created").exists())+ self.assertNotIn(HASH.encode(), result.stdout + result.stderr)++ def test_preparation_command_failures_stop_before_editor(self):+ for failed in ("mkdir", "chmod", "touch"):+ with self.subTest(failed=failed), tempfile.TemporaryDirectory() as temp:+ home = Path(temp)+ env = environment(home)+ tool = home / "tools" / failed+ tool.write_text('#!/bin/sh\nexit 23\n')+ tool.chmod(0o700)+ result = subprocess.run(["bash", "-c", recipe('vi "$auth_file"')],+ env=env, capture_output=True, timeout=10)+ self.assertEqual(result.returncode, 23)+ self.assertFalse((home / "editor.json").exists())++ def test_launch_protects_existing_file_and_stops_on_permission_failure(self):+ for fail in (False, True):+ with self.subTest(fail=fail), tempfile.TemporaryDirectory() as temp:+ home = Path(temp)+ path = private_file(home)+ path.chmod(0o644)+ path.parent.chmod(0o755)+ env = environment(home)+ if fail:+ tool = home / "tools/chmod"+ tool.write_text('#!/bin/sh\nexit 23\n')+ tool.chmod(0o700)+ result = subprocess.run(["bash", "-c", recipe("docker run -d")],+ env=env, capture_output=True, timeout=10)+ self.assertEqual(result.returncode, 23 if fail else 0, result.stderr.decode())+ self.assertEqual((home / "docker.json").exists(), not fail)+ self.assertEqual(path.read_text(), CONTENT)+ self.assertEqual(stat.S_IMODE(path.stat().st_mode), 0o644 if fail else 0o600)+ self.assertEqual(stat.S_IMODE(path.parent.stat().st_mode), 0o755 if fail else 0o700)+ self.assertNotIn(HASH.encode(), result.stdout + result.stderr)+def test_launch_passes_only_private_path_and_preserves_hash_bytes(self):with tempfile.TemporaryDirectory(prefix="auth docs ") as temp:home = Path(temp)