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
Keep agent installer guidance off token arguments and HTTP pipes
pulse-triage[bot]2b0b134dfac7
diff --git a/scripts/install.sh b/scripts/install.shindex 0320b7addd..e5dda1e115 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -4,8 +4,12 @@# Supports: Linux (systemd, OpenRC, SysV init), macOS (launchd), FreeBSD (rc.d), Synology DSM (6.x/7+), Unraid, QNAP QTS/QuTS hero, TrueNAS## Usage:-# curl -fsSL http://pulse/install.sh | bash -s -- --url http://pulse --token <token> [options]-# curl -fsSL http://pulse/install.sh | bash -s -- --update --url http://pulse [options]+# Download over verified HTTPS to a private file and inspect it first. See:+# docs/UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nas+# bash "$HOME/.config/pulse/agent-install.sh" --url https://pulse.example.com --token-file "$HOME/.config/pulse/agent-token" [options]+# bash "$HOME/.config/pulse/agent-install.sh" --update+# Use the target host's root/admin shell where required. Never put a token+# in command history or process arguments; the caller owns input-file cleanup.## Options:# --enable-host Enable host metrics (default: true)@@ -540,15 +544,23 @@ verify_download_signature() {}show_help() {- cat <<EOF+ cat <<'EOF'Pulse Unified Agent InstallerUsage:- install.sh [options]+ bash "$HOME/.config/pulse/agent-install.sh" --url https://pulse.example.com --token-file "$HOME/.config/pulse/agent-token" [options]+ bash "$HOME/.config/pulse/agent-install.sh" --update++Download over verified HTTPS to a private file and inspect it before running.+Keep API tokens out of command history and process arguments. Prefer --token-file;+the caller owns input-file cleanup. Use the target host's root/admin shell where+required. For private-file preparation and platform requirements, see:+ https://github.com/rcourtman/Pulse/blob/main/docs/UNIFIED_AGENT.md#private-file-installation-linux-macos-and-nasOptions:- --url <url> Pulse server URL (e.g. http://pulse:7655)- --token <token> Pulse API token+ --url <url> Pulse server URL (e.g. https://pulse.example.com)+ --token-file <path> Read token from a private file; the caller owns its cleanup+ --token <token> Compatibility option; exposes the token in process arguments (prefer --token-file)--interval <duration> Reporting interval (default: 30s)--enable-host Enable host metrics (default: true)--disable-host Disable host metrics@@ -588,7 +600,6 @@ Options:--retarget Point an existing agent at --url using saved identity and token--uninstall Remove the agent--non-interactive Skip TTY prompts (for automated/scripted installs)- --token-file <path> Read token from a private file; the caller owns its cleanup--pulse-url <url> Alias for --url--preflight-only Run preflight checks and exit (no install)--output <format> Output format: text (default) or jsondiff --git a/scripts/tests/test_agent_installer_help.py b/scripts/tests/test_agent_installer_help.pynew file mode 100644index 0000000000..2607c6bdf3--- /dev/null+++ b/scripts/tests/test_agent_installer_help.py@@ -0,0 +1,116 @@+#!/usr/bin/env python3+"""Exercise the shipped CLI guidance without installing or contacting a server."""++import json+import os+from pathlib import Path+import shutil+import subprocess+import tempfile+import unittest+++ROOT = Path(__file__).resolve().parents[2]+INSTALLER = ROOT / "scripts/install.sh"+TOKEN = "synthetic-help-token-not-for-argv"+++def help_text(flag="--help"):+ with tempfile.TemporaryDirectory() as directory:+ home = Path(directory)+ tools = home / "tools"+ tools.mkdir()+ marker = home / "unexpected-operation"+ # Help must return before network, privilege or service operations.+ for name in ("curl", "wget", "sudo", "systemctl", "launchctl", "service"):+ tool = tools / name+ tool.write_text('#!/bin/sh\nprintf "%s\\n" "$0" >> "$HELP_OPERATION_LOG"\nexit 91\n')+ tool.chmod(0o700)+ env = dict(os.environ, HOME=str(home), PULSE_TOKEN=TOKEN,+ PATH=str(tools) + os.pathsep + os.environ["PATH"],+ HELP_OPERATION_LOG=str(marker))+ result = subprocess.run([shutil.which("bash"), str(INSTALLER), flag],+ env=env, capture_output=True, text=True, timeout=5)+ if result.returncode or result.stderr or marker.exists():+ raise AssertionError(f"help was not side-effect free: {result.returncode}, {result.stderr!r}")+ if TOKEN in result.stdout or str(home) in result.stdout:+ raise AssertionError("help expanded caller data instead of printing reusable guidance")+ return result.stdout+++def examples(text):+ usage = text.split("Usage:\n", 1)[1].split("\n\n", 1)[0]+ commands = [line.strip().removesuffix(" [options]") for line in usage.splitlines()+ if line.strip()]+ if len(commands) != 2 or not all(line.startswith("bash ") for line in commands):+ raise AssertionError("expected install and saved-state update commands")+ return commands+++class AgentInstallerHelpTest(unittest.TestCase):+ def test_both_help_flags_return_before_mutation(self):+ self.assertEqual(help_text("--help"), help_text("-h"))++ def test_help_prefers_private_file_and_explains_preparation(self):+ text = help_text()+ self.assertLess(text.index("--token-file <path>"), text.index("--token <token>"))+ for fact in ("verified HTTPS", "inspect it before running", "private-file preparation",+ "root/admin shell", "caller owns input-file cleanup",+ "exposes the token in process arguments", "#private-file-installation-linux-macos-and-nas"):+ self.assertIn(fact, text)+ usage = "\n".join(examples(text))+ self.assertNotRegex(usage, r"--token(?:\s|=)|http://|\|\s*(?:sudo\s+)?bash")+ self.assertIn('https://pulse.example.com --token-file "$HOME/.config/pulse/agent-token"', usage)++ def test_source_header_and_shipped_help_recommend_the_same_commands(self):+ header = INSTALLER.read_text().split("# Usage:\n", 1)[1].split("\n# Options:", 1)[0]+ commands = [line.removeprefix("# ").removesuffix(" [options]")+ for line in header.splitlines() if line.startswith("# bash ")]+ self.assertEqual(commands, examples(help_text()))+ self.assertNotRegex(header, r"--token(?:\s|=)|http://|curl[^\n]*\|")+ self.assertIn("inspect it first", header)++ def test_copied_help_commands_preserve_private_paths_and_saved_update(self):+ commands = examples(help_text())+ with tempfile.TemporaryDirectory(prefix="pulse help space ") as directory:+ home = Path(directory)+ private = home / ".config/pulse"+ private.mkdir(parents=True, mode=0o700)+ token = private / "agent-token"+ token.write_text(TOKEN + "\n")+ token.chmod(0o600)+ receipt = home / "argv.json"+ # Only a closed argument receiver, never the real installer.+ stub = private / "agent-install.sh"+ stub.write_text('''#!/usr/bin/env bash+set -eu+python3 - "$@" <<'PY'+import json, os, pathlib, stat, sys+args = sys.argv[1:]+if args != ["--update"]:+ assert args == ["--url", "https://pulse.example.com", "--token-file",+ str(pathlib.Path.home() / ".config/pulse/agent-token")]+ token = pathlib.Path(args[-1])+ assert stat.S_IMODE(token.stat().st_mode) == 0o600+ assert token.read_text().strip() == os.environ["EXPECTED_TOKEN"]+assert os.environ["EXPECTED_TOKEN"] not in args+pathlib.Path(os.environ["ARGV_RECEIPT"]).write_text(json.dumps(args))+PY+''')+ env = dict(os.environ, HOME=str(home), EXPECTED_TOKEN=TOKEN, ARGV_RECEIPT=str(receipt))+ for command in commands:+ with self.subTest(command=command):+ receipt.unlink(missing_ok=True)+ result = subprocess.run(["bash", "-eu", "-c", command], env=env,+ capture_output=True, text=True, timeout=5)+ self.assertEqual(result.returncode, 0, result.stderr)+ self.assertTrue(receipt.is_file(), "copied example did not invoke its installer")+ args = json.loads(receipt.read_text())+ self.assertEqual(args, ["--update"] if command.endswith("--update") else+ ["--url", "https://pulse.example.com", "--token-file", str(token)])+ self.assertNotIn(TOKEN, result.stdout + result.stderr + receipt.read_text())+ self.assertEqual(token.read_text(), TOKEN + "\n", "caller-owned credential changed")+++if __name__ == "__main__":+ unittest.main()