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.

Refuse unsafe Docker authentication file paths in setup help

pulse-triage[bot]d4f23d16023d
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 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 -eu
umask 077
auth_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' >&2
exit 1
fi
mkdir -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 interactive
password 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" ]; then
printf 'Prepare the private authentication file first.\n' >&2
exit 1
fi
+ 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.Z
diff --git a/frontend-modern/public/docs/CONFIGURATION.md b/frontend-modern/public/docs/CONFIGURATION.md
index 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 -eu
umask 077
auth_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' >&2
exit 1
fi
mkdir -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 interactive
password 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" ]; then
printf 'Prepare the private authentication file first.\n' >&2
exit 1
fi
+ 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.Z
diff --git a/scripts/tests/test_configuration_auth_docs.py b/scripts/tests/test_configuration_auth_docs.py
index 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, sys
from pathlib import Path
args = 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) == 0o700
assert 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)