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
Make agent setup refuse unsafe paths and incomplete downloads
pulse-triage[bot]9bdd2ab20fc3
diff --git a/docs/UNIFIED_AGENT.md b/docs/UNIFIED_AGENT.mdindex e5b698559e..7d053904a7 100644--- a/docs/UNIFIED_AGENT.md+++ b/docs/UNIFIED_AGENT.md@@ -106,33 +106,82 @@ connection is usually enough for TrueNAS inventory and usage; an agent isoptional for host-local data.1. In that shell, protect the file before opening the editor. Save only the- Pulse agent token, with no quotes or header. Use your own private directory- and regular files, not shared paths or symlinks:+ Pulse agent token, with no quotes or header. This preparation preserves an+ existing regular token file and refuses symlinked or non-regular credential+ paths. **Stop if preparation fails**; do not continue to the installer:```bash- umask 077- mkdir -p "$HOME/.config/pulse"- chmod 700 "$HOME/.config/pulse"- touch "$HOME/.config/pulse/agent-token"- chmod 600 "$HOME/.config/pulse/agent-token"- vi "$HOME/.config/pulse/agent-token"+ (+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ credential_file="$config_dir/agent-token"+ if [ -L "$HOME/.config" ] || [ -L "$config_dir" ] || [ -L "$credential_file" ]; then+ printf 'Refusing a symlinked credential path.\n' >&2+ exit 1+ fi+ if [ -e "$credential_file" ] && [ ! -f "$credential_file" ]; then+ printf 'Credential file must be a regular file.\n' >&2+ exit 1+ fi+ mkdir -p "$config_dir"+ chmod 700 "$config_dir"+ touch "$credential_file"+ chmod 600 "$credential_file"+ vi "$credential_file"+ )```2. Replace `https://pulse.example.com` with your Pulse server's HTTPS address- in both the download and installation commands. Download to a file:+ in both the download and installation commands. Download to a new private+ file. This ignores local curl settings, accepts only HTTP **200** over HTTPS,+ and does not follow redirects or overwrite an existing installer:```bash- curl --fail --silent --show-error --connect-timeout 10 --max-time 60 \- --output "$HOME/.config/pulse/agent-install.sh" \- https://pulse.example.com/install.sh+ (+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ installer_file="$config_dir/agent-install.sh"+ if [ -L "$HOME/.config" ] || [ -L "$config_dir" ] || [ ! -d "$config_dir" ]; then+ printf 'Prepare the private token directory first.\n' >&2+ exit 1+ fi+ if [ -e "$installer_file" ] || [ -L "$installer_file" ]; then+ printf 'Refusing to replace an existing installer path.\n' >&2+ exit 1+ fi+ chmod 700 "$config_dir"+ download_file=$(mktemp "$config_dir/agent-download.XXXXXX")+ curl_exit=0+ status=$(curl --disable --fail --silent --show-error --proto '=https' \+ --connect-timeout 10 --max-time 60 --output "$download_file" \+ --write-out '%{http_code}' https://pulse.example.com/install.sh) || curl_exit=$?+ printf 'HTTP %s\n' "$status"+ [ "$curl_exit" -eq 0 ] || exit "$curl_exit"+ [ "$status" = 200 ]+ mv -n "$download_file" "$installer_file"+ [ ! -e "$download_file" ]+ )```- **Stop if the download fails.** Inspect the saved script before executing- it. Do not bypass certificate verification or pipe an unchecked response- into a privileged shell. For a private CA, add curl's `--cacert` with the- separately verified CA file, and supply the installer's `--cacert` option- for the agent connection as well. Do not substitute GitHub's top-level- `install.sh`: that installs the Pulse server, not the agent.+ **Stop if the download fails.** A temporary download, redirect or TLS error+ is not an installer; do not execute its temporary file. Inspect the saved+ `agent-install.sh` only after a successful download. If that path already+ exists, review it locally rather than deleting or overwriting it blindly;+ retargeting needs the installer from the **new** server, not an older saved+ copy. Preserve any earlier copy separately through normal maintenance+ before downloading again.++ Keep `--disable` first in the curl command: local settings could enable+ tracing, redirects or a TLS bypass. Do not bypass certificate verification+ or pipe an unchecked response into a privileged shell. For a private CA,+ add curl's `--cacert` **after `--disable`**, using a separately verified CA+ file, and supply the installer's `--cacert` option for the agent connection+ as well. A successful download is not signature verification; inspect and+ trust the serving Pulse installation before executing its script. Do not+ substitute GitHub's top-level `install.sh`: that installs the Pulse server,+ not the agent.3. Install with the private token file, adding a profile from[Installation Options](#installation-options) when needed:diff --git a/frontend-modern/public/docs/UNIFIED_AGENT.md b/frontend-modern/public/docs/UNIFIED_AGENT.mdindex e5b698559e..7d053904a7 100644--- a/frontend-modern/public/docs/UNIFIED_AGENT.md+++ b/frontend-modern/public/docs/UNIFIED_AGENT.md@@ -106,33 +106,82 @@ connection is usually enough for TrueNAS inventory and usage; an agent isoptional for host-local data.1. In that shell, protect the file before opening the editor. Save only the- Pulse agent token, with no quotes or header. Use your own private directory- and regular files, not shared paths or symlinks:+ Pulse agent token, with no quotes or header. This preparation preserves an+ existing regular token file and refuses symlinked or non-regular credential+ paths. **Stop if preparation fails**; do not continue to the installer:```bash- umask 077- mkdir -p "$HOME/.config/pulse"- chmod 700 "$HOME/.config/pulse"- touch "$HOME/.config/pulse/agent-token"- chmod 600 "$HOME/.config/pulse/agent-token"- vi "$HOME/.config/pulse/agent-token"+ (+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ credential_file="$config_dir/agent-token"+ if [ -L "$HOME/.config" ] || [ -L "$config_dir" ] || [ -L "$credential_file" ]; then+ printf 'Refusing a symlinked credential path.\n' >&2+ exit 1+ fi+ if [ -e "$credential_file" ] && [ ! -f "$credential_file" ]; then+ printf 'Credential file must be a regular file.\n' >&2+ exit 1+ fi+ mkdir -p "$config_dir"+ chmod 700 "$config_dir"+ touch "$credential_file"+ chmod 600 "$credential_file"+ vi "$credential_file"+ )```2. Replace `https://pulse.example.com` with your Pulse server's HTTPS address- in both the download and installation commands. Download to a file:+ in both the download and installation commands. Download to a new private+ file. This ignores local curl settings, accepts only HTTP **200** over HTTPS,+ and does not follow redirects or overwrite an existing installer:```bash- curl --fail --silent --show-error --connect-timeout 10 --max-time 60 \- --output "$HOME/.config/pulse/agent-install.sh" \- https://pulse.example.com/install.sh+ (+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ installer_file="$config_dir/agent-install.sh"+ if [ -L "$HOME/.config" ] || [ -L "$config_dir" ] || [ ! -d "$config_dir" ]; then+ printf 'Prepare the private token directory first.\n' >&2+ exit 1+ fi+ if [ -e "$installer_file" ] || [ -L "$installer_file" ]; then+ printf 'Refusing to replace an existing installer path.\n' >&2+ exit 1+ fi+ chmod 700 "$config_dir"+ download_file=$(mktemp "$config_dir/agent-download.XXXXXX")+ curl_exit=0+ status=$(curl --disable --fail --silent --show-error --proto '=https' \+ --connect-timeout 10 --max-time 60 --output "$download_file" \+ --write-out '%{http_code}' https://pulse.example.com/install.sh) || curl_exit=$?+ printf 'HTTP %s\n' "$status"+ [ "$curl_exit" -eq 0 ] || exit "$curl_exit"+ [ "$status" = 200 ]+ mv -n "$download_file" "$installer_file"+ [ ! -e "$download_file" ]+ )```- **Stop if the download fails.** Inspect the saved script before executing- it. Do not bypass certificate verification or pipe an unchecked response- into a privileged shell. For a private CA, add curl's `--cacert` with the- separately verified CA file, and supply the installer's `--cacert` option- for the agent connection as well. Do not substitute GitHub's top-level- `install.sh`: that installs the Pulse server, not the agent.+ **Stop if the download fails.** A temporary download, redirect or TLS error+ is not an installer; do not execute its temporary file. Inspect the saved+ `agent-install.sh` only after a successful download. If that path already+ exists, review it locally rather than deleting or overwriting it blindly;+ retargeting needs the installer from the **new** server, not an older saved+ copy. Preserve any earlier copy separately through normal maintenance+ before downloading again.++ Keep `--disable` first in the curl command: local settings could enable+ tracing, redirects or a TLS bypass. Do not bypass certificate verification+ or pipe an unchecked response into a privileged shell. For a private CA,+ add curl's `--cacert` **after `--disable`**, using a separately verified CA+ file, and supply the installer's `--cacert` option for the agent connection+ as well. A successful download is not signature verification; inspect and+ trust the serving Pulse installation before executing its script. Do not+ substitute GitHub's top-level `install.sh`: that installs the Pulse server,+ not the agent.3. Install with the private token file, adding a profile from[Installation Options](#installation-options) when needed:diff --git a/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts b/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.tsnew file mode 100644index 0000000000..7dc6b1bf59--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/unifiedAgentBootstrapGuide.test.ts@@ -0,0 +1,61 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import { renderDocMarkdown } from '../docMarkdown';++const frontendRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');+const source = readFileSync(path.join(frontendRoot, '../docs/UNIFIED_AGENT.md'), 'utf8');++function setupSection() {+ const article = document.createElement('article');+ article.innerHTML = renderDocMarkdown(source, 'UNIFIED_AGENT');+ const heading = article.querySelector('#private-file-installation-linux-macos-and-nas')!;+ const section = document.createElement('section');+ for (+ let node = heading.nextElementSibling;+ node && !/^H[23]$/.test(node.tagName);+ node = node.nextElementSibling+ ) {+ section.append(node.cloneNode(true));+ }+ return section;+}++describe('Unified Agent private-file setup help', () => {+ it('renders preparation and download as self-contained fences before installation', () => {+ const section = setupSection();+ const steps = [...section.querySelectorAll(':scope > ol > li')];+ expect(steps).toHaveLength(3);+ const commands = steps.map((step) => step.querySelector('pre code')?.textContent ?? '');+ for (const command of commands.slice(0, 2)) {+ expect(command.trim()).toMatch(/^\(\s+set -eu\s+umask 077/);+ expect(command.trim()).toMatch(/\)$/);+ }+ expect(commands[0]).toContain('vi "$credential_file"');+ expect(commands[1]).toContain('curl --disable --fail');+ expect(commands[1]).toContain('[ "$status" = 200 ]');+ expect(commands[2]).toContain('--token-file "$HOME/.config/pulse/agent-token"');+ expect(commands.join(' ')).not.toMatch(/--token\s|curl[^|]+\|\s*bash/);+ });++ it('keeps stopping, existing-file and retarget trust boundaries beside the commands', () => {+ const steps = [...setupSection().querySelectorAll(':scope > ol > li')];+ const preparation = steps[0].textContent!.replace(/\s+/g, ' ');+ const download = steps[1].textContent!.replace(/\s+/g, ' ');+ expect(preparation).toContain('Stop if preparation fails');+ expect(preparation).toContain('preserves an existing regular token file');+ expect(preparation).toContain('refuses symlinked or non-regular credential paths');+ expect(download).toContain('Stop if the download fails');+ expect(download).toContain('do not execute its temporary file');+ expect(download).toContain('does not follow redirects or overwrite an existing installer');+ expect(download).toContain('retargeting needs the installer from the new server');+ expect(download).toContain("add curl's --cacert after --disable");+ expect(download).toContain('A successful download is not signature verification');+ });++ it('keeps the existing profile link and ships an identical public help asset', () => {+ expect(setupSection().querySelector('a[href="#installation-options"]')).not.toBeNull();+ expect(readFileSync(path.join(frontendRoot, 'public/docs/UNIFIED_AGENT.md'), 'utf8')).toBe(source);+ });+});diff --git a/scripts/tests/test_agent_docs.py b/scripts/tests/test_agent_docs.pyindex 06725b9f5c..0ad67e2d41 100644--- a/scripts/tests/test_agent_docs.py+++ b/scripts/tests/test_agent_docs.py@@ -84,7 +84,7 @@ class AgentDocsTest(unittest.TestCase):self.assertEqual(count, 18)def test_private_file_preparation_preserves_existing_token(self):- command = recipe(NAMES[0], 'vi "$HOME/.config/pulse/agent-token"')+ command = recipe(NAMES[0], 'credential_file="$config_dir/agent-token"')with tempfile.TemporaryDirectory() as temporary:home = Path(temporary)tools = home / "tools"@@ -100,13 +100,136 @@ class AgentDocsTest(unittest.TestCase):token.write_text(TOKEN + "\n")token.chmod(0o644)token.parent.chmod(0o755)- result = subprocess.run(["bash", "-eu", "-c", command], env=env, capture_output=True)+ # Run the fence as copied, without supplying errexit for it.+ result = subprocess.run(["bash", "-c", command], env=env, capture_output=True, timeout=10)self.assertEqual(result.returncode, 0, result.stderr.decode())self.assertEqual(stat.S_IMODE(token.stat().st_mode), 0o600)self.assertEqual(stat.S_IMODE(token.parent.stat().st_mode), 0o700)self.assertEqual(token.read_text(), TOKEN + "\n" if existing else "")self.assertNotIn(TOKEN.encode(), result.stdout + result.stderr)+ def test_private_file_preparation_refuses_symlinks_and_nonregular_tokens(self):+ command = recipe(NAMES[0], 'credential_file="$config_dir/agent-token"')+ for placement in (".config", ".config/pulse", ".config/pulse/agent-token"):+ for kind in ("symlink", "dangling-symlink", "directory", "fifo"):+ # Directories are normal parents; reject non-regular token files.+ if kind == "directory" and placement != ".config/pulse/agent-token":+ continue+ with self.subTest(placement=placement, kind=kind), tempfile.TemporaryDirectory() as temporary:+ home = Path(temporary)+ path = home / placement+ path.parent.mkdir(parents=True, exist_ok=True)+ target = home / "untouched"+ target.mkdir(mode=0o755)+ target.chmod(0o755)+ witness = target / "agent-token"+ witness.write_text(TOKEN)+ witness.chmod(0o644)+ if kind == "symlink":+ path.symlink_to(witness if placement.endswith("agent-token") else target)+ elif kind == "dangling-symlink":+ path.symlink_to(home / "must-not-be-created")+ elif kind == "directory":+ path.mkdir()+ else:+ os.mkfifo(path)+ tools = home / "tools"+ tools.mkdir()+ editor = tools / "vi"+ editor.write_text('#!/bin/sh\nprintf called > "$EDITOR_RECEIPT"\n')+ editor.chmod(0o700)+ receipt = home / "editor-called"+ env = fixture_environment(home)+ env.update(PATH=f"{tools}:{os.environ['PATH']}", EDITOR_RECEIPT=str(receipt))+ result = subprocess.run(["bash", "-c", command], env=env, capture_output=True, timeout=10)+ self.assertNotEqual(result.returncode, 0)+ self.assertFalse(receipt.exists(), "unsafe preparation must stop before opening the editor")+ self.assertEqual(witness.read_text(), TOKEN)+ self.assertEqual(stat.S_IMODE(witness.stat().st_mode), 0o644)+ self.assertEqual(stat.S_IMODE(target.stat().st_mode), 0o755)+ self.assertFalse((home / "must-not-be-created").exists())+ self.assertNotIn(TOKEN.encode(), result.stdout + result.stderr)++ def test_download_refuses_unsafe_paths_before_contacting_server(self):+ command = recipe(NAMES[0], 'installer_file="$config_dir/agent-install.sh"')+ for placement, kind in ((".config", "symlink"), (".config/pulse", "symlink"),+ (".config/pulse", "missing"),+ (".config/pulse/agent-install.sh", "file"),+ (".config/pulse/agent-install.sh", "directory"),+ (".config/pulse/agent-install.sh", "symlink"),+ (".config/pulse/agent-install.sh", "dangling-symlink")):+ with self.subTest(placement=placement, kind=kind), tempfile.TemporaryDirectory() as temporary:+ home = Path(temporary)+ path = home / placement+ path.parent.mkdir(parents=True, exist_ok=True)+ target = home / "untouched"+ target.mkdir(mode=0o755)+ target.chmod(0o755)+ witness = target / "agent-install.sh"+ witness.write_text("previous inspected installer\n")+ witness.chmod(0o644)+ if kind == "symlink":+ path.symlink_to(witness if placement.endswith(".sh") else target)+ elif kind == "dangling-symlink":+ path.symlink_to(home / "must-not-be-created")+ elif kind == "directory":+ path.mkdir()+ elif kind == "file":+ path.write_text("existing installer\n")+ tools = home / "tools"+ tools.mkdir()+ curl = tools / "curl"+ curl.write_text('#!/bin/sh\nprintf called > "$CURL_RECEIPT"\nexit 19\n')+ curl.chmod(0o700)+ receipt = home / "curl-called"+ env = fixture_environment(home)+ env.update(PATH=f"{tools}:{os.environ['PATH']}", CURL_RECEIPT=str(receipt))+ result = subprocess.run(["bash", "-c", command], env=env, capture_output=True, timeout=10)+ self.assertNotEqual(result.returncode, 0)+ self.assertFalse(receipt.exists(), "unsafe download must stop before invoking curl")+ self.assertEqual(witness.read_text(), "previous inspected installer\n")+ self.assertEqual(stat.S_IMODE(witness.stat().st_mode), 0o644)+ self.assertEqual(stat.S_IMODE(target.stat().st_mode), 0o755)+ if kind == "file":+ self.assertEqual(path.read_text(), "existing installer\n")+ self.assertFalse((home / "must-not-be-created").exists())++ def test_failed_download_or_publish_conflict_never_replaces_installer(self):+ command = recipe(NAMES[0], 'installer_file="$config_dir/agent-install.sh"')+ for mode, expected_exit in (("partial", 23), ("publish-conflict", 1)):+ with self.subTest(mode=mode), tempfile.TemporaryDirectory() as temporary:+ home = Path(temporary)+ private = home / ".config/pulse"+ private.mkdir(parents=True, mode=0o700)+ tools = home / "tools"+ tools.mkdir()+ curl = tools / "curl"+ curl.write_text('''#!/usr/bin/env python3+import os, sys+from pathlib import Path+args = sys.argv[1:]+assert args[0] == '--disable'+Path(args[args.index('--output') + 1]).write_text('downloaded prefix\\n')+print('200', end='')+if os.environ['DOWNLOAD_MODE'] == 'partial':+ sys.exit(23)+Path(os.environ['HOME'], '.config/pulse/agent-install.sh').write_text('other saved installer\\n')+''')+ curl.chmod(0o700)+ env = fixture_environment(home)+ env.update(PATH=f"{tools}:{os.environ['PATH']}", DOWNLOAD_MODE=mode)+ result = subprocess.run(["bash", "-c", command], env=env, capture_output=True, timeout=10)+ self.assertEqual(result.returncode, expected_exit, result.stderr.decode())+ installer = private / "agent-install.sh"+ if mode == "partial":+ self.assertFalse(installer.exists())+ else:+ self.assertEqual(installer.read_text(), "other saved installer\n")+ downloads = list(private.glob("agent-download.*"))+ self.assertEqual(len(downloads), 1)+ self.assertEqual(downloads[0].read_text(), "downloaded prefix\n")+ self.assertEqual(stat.S_IMODE(downloads[0].stat().st_mode), 0o600)+def test_windows_file_handoff_matches_installer_contract(self):windows = "\n".join(blocks(NAMES[0], "powershell"))for expected in ("-ErrorAction Stop", "/inheritance:r", "*${userSid}:(OI)(CI)F",@@ -131,9 +254,14 @@ class AgentDocsTest(unittest.TestCase):"os.execv(os.environ['REAL_CURL'], [os.environ['REAL_CURL'], *sys.argv[1:]])\n")recorder.chmod(0o700)+ trace = home / "curl-trace.txt"+ (home / ".curlrc").write_text(+ f'header = "X-Curlrc-Injected: {TOKEN}"\ninsecure\nlocation\ntrace-ascii = "{trace}"\n'+ )env = fixture_environment(home)env.update(PATH=f"{tools}:{os.environ['PATH']}", REAL_CURL=shutil.which("curl"),- CURL_RECEIPT=str(home / "curl-argv.json"))+ CURL_RECEIPT=str(home / "curl-argv.json"), CURL_HOME=str(home),+ XDG_CONFIG_HOME=str(home / ".config"))command = command.replace("https://pulse.example.com", f"https://{hostname}:{port}")command = command.replace("https://raw.githubusercontent.com", f"https://{hostname}:{port}")if ca is not None:@@ -141,7 +269,7 @@ class AgentDocsTest(unittest.TestCase):command = command.replace("curl --disable ", f'curl --disable --cacert "{ca}" ', 1)else:command = command.replace("curl ", f'curl --cacert "{ca}" ', 1)- result = subprocess.run(["bash", "-eu", "-c", command], env=env, capture_output=True, timeout=20)+ result = subprocess.run(["bash", "-c", command], env=env, capture_output=True, timeout=20)argv = json.loads((home / "curl-argv.json").read_text())self.assertNotIn(TOKEN, " ".join(argv))self.assertNotIn(TOKEN.encode(), result.stdout + result.stderr)@@ -149,17 +277,19 @@ class AgentDocsTest(unittest.TestCase):self.assertIn(argument, argv)self.assertNotIn("--insecure", argv)self.assertNotIn("-k", argv)- if "sensor-cleanup-download.XXXXXX" in command:- self.assertEqual(argv[0], "--disable")+ self.assertEqual(argv[0], "--disable")+ self.assertFalse(trace.exists(), "local curl settings must not enable tracing")return resultdef test_downloads_require_verified_tls_and_success(self):for name, path, needle, output in (- (NAMES[0], "/install.sh", '--output "$HOME/.config/pulse/agent-install.sh"', "agent-install.sh"),+ (NAMES[0], "/install.sh", 'installer_file="$config_dir/agent-install.sh"', "agent-install.sh"),(NAMES[1], CLEANUP_PATH, 'helper_file="$config_dir/sensor-proxy-uninstall.sh"', "sensor-proxy-uninstall.sh"),):for status, ca, hostname, expected in ((200, self.cert, "localhost", 0),+ (204, self.cert, "localhost", 1),+ (302, self.cert, "localhost", 1),(403, self.cert, "localhost", 22),(200, None, "localhost", 60),(200, self.other_cert, "localhost", 60),@@ -173,9 +303,8 @@ class AgentDocsTest(unittest.TestCase):self.assertEqual(result.returncode, expected, result.stderr.decode())if expected == 0:self.assertEqual((home / ".config/pulse" / output).read_bytes(), b"# harmless installer fixture\n")- if name == NAMES[1]:- self.assertEqual(stat.S_IMODE((home / ".config/pulse" / output).stat().st_mode), 0o600)- elif name == NAMES[1]:+ self.assertEqual(stat.S_IMODE((home / ".config/pulse" / output).stat().st_mode), 0o600)+ else:self.assertFalse((home / ".config/pulse" / output).exists(),"a failed temporary download must not become the cleanup helper")if expected == 60:@@ -183,6 +312,8 @@ class AgentDocsTest(unittest.TestCase):for requested_path, headers in requests:self.assertEqual(requested_path, path)self.assertNotIn("Authorization", headers)+ self.assertNotIn("X-Curlrc-Injected", headers)+ self.assertLessEqual(len(requests), 1, "a redirect or error must not trigger another request")def test_every_profile_passes_only_private_file_not_token_arguments(self):profiles = []