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
Validate agent URL policy before replacing an installation
pulse-triage[bot]1ea913fe1691
diff --git a/cmd/pulse-agent/main.go b/cmd/pulse-agent/main.goindex fb090b34a8..4408a86808 100644--- a/cmd/pulse-agent/main.go+++ b/cmd/pulse-agent/main.go@@ -304,6 +304,17 @@ func run(ctx context.Context, args []string, getenv func(string) string) error {return fmt.Errorf("failed to load unified agent configuration: %w", err)}+ // The installer runs this on the verified staged executable before changing+ // a service or its saved credentials. Use the modules' primary-destination+ // policy, without logging, enrollment, identity persistence or listeners.+ if cfg.ValidateURLOnly {+ if _, err := agenttarget.NormalizePulseURL(cfg.PulseURL, true, cfg.AllowPlaintextHTTP); err != nil {+ return fmt.Errorf("invalid pulse URL: %w", err)+ }+ fmt.Println("Pulse URL validation passed")+ return nil+ }+// 2. Setup Logginglogger, closeLogger, err := configureAgentLogger(cfg)if err != nil {@@ -1167,6 +1178,7 @@ type Config struct {DisableCeph bool // Disable local Ceph status pollingDisableClusterPeerSensors bool // Keep Proxmox monitoring local and skip SSH sensor collection from cluster peersSelfTest bool // Perform self-test and exit+ ValidateURLOnly bool // Check primary URL policy without starting or changing an installation// AvailabilityTargets are externally probed availability checks assigned to// this agent by the server. Remote config is the only source.@@ -1389,6 +1401,7 @@ func loadConfig(args []string, getenv func(string) string) (Config, error) {disableClusterPeerSensorsFlag := fs.Bool("disable-cluster-peer-sensors", utils.ParseBool(envDisableClusterPeerSensors), "Skip SSH sensor collection from Proxmox cluster peers")showVersion := fs.Bool("version", false, "Print the agent version and exit")selfTest := fs.Bool("self-test", false, "Perform self-test and exit (used during auto-update)")+ validateURL := fs.Bool("validate-url", false, "Validate the primary Pulse URL policy and exit without reading credentials, writing state or starting modules")var tagFlags multiValuefs.Var(&tagFlags, "tag", "Tag to apply (repeatable)")@@ -1410,6 +1423,19 @@ func loadConfig(args []string, getenv func(string) string) (Config, error) {return Config{}, flag.ErrHelp}+ if *validateURL {+ // Do not let saved credentials, enrollment, observers or log paths make+ // this read-only URL check touch an existing installation. In particular,+ // --insecure is not plaintext consent. The installer explicitly disables+ // plaintext consent, matching the service configuration it will render.+ securityutil.SetOperatorPlaintextHTTPConsent(*allowPlaintextHTTPFlag)+ return Config{+ PulseURL: strings.TrimSpace(*urlFlag),+ AllowPlaintextHTTP: *allowPlaintextHTTPFlag,+ ValidateURLOnly: true,+ }, nil+ }+// ValidationpulseURL := strings.TrimSpace(*urlFlag)if pulseURL == "" {diff --git a/cmd/pulse-agent/url_admission_test.go b/cmd/pulse-agent/url_admission_test.gonew file mode 100644index 0000000000..790e9f5a93--- /dev/null+++ b/cmd/pulse-agent/url_admission_test.go@@ -0,0 +1,89 @@+package main++import (+ "context"+ "os"+ "path/filepath"+ "strings"+ "testing"++ "github.com/rcourtman/pulse-go-rewrite/pkg/securityutil"+)++func TestRunValidateURLIsReadOnly(t *testing.T) {+ t.Cleanup(func() { securityutil.SetOperatorPlaintextHTTPConsent(false) })+ for _, tc := range []struct {+ name, url string+ insecure bool+ wantError bool+ }{+ {name: "https", url: "https://pulse.example.invalid/base"},+ {name: "loopback", url: "http://127.0.0.1:7655"},+ {name: "private", url: "http://192.168.1.20:7655"},+ {name: "local-hostname", url: "http://pulse:7655"},+ {name: "public", url: "http://203.0.113.10", wantError: true},+ {name: "insecure-is-not-http-consent", url: "http://203.0.113.10", insecure: true, wantError: true},+ {name: "unresolved", url: "http://pulse.example.invalid", wantError: true},+ {name: "userinfo", url: "https://user:[email protected]", wantError: true},+ {name: "wrong-scheme", url: "ftp://pulse.example.invalid", wantError: true},+ {name: "missing", wantError: true},+ } {+ t.Run(tc.name, func(t *testing.T) {+ stateDir := t.TempDir()+ files := map[string]string{"agent-id": "existing-id\n", "token": "existing-token\n", "runtime.token": "existing-runtime\n", "connection.env": "existing-connection\n", "install.sh": "existing-recovery\n"}+ for name, value := range files {+ if err := os.WriteFile(filepath.Join(stateDir, name), []byte(value), 0600); err != nil {+ t.Fatal(err)+ }+ }+ if err := os.Chmod(stateDir, 0750); err != nil {+ t.Fatal(err)+ }+ getenv := func(key string) string {+ if key == "PULSE_INSECURE_SKIP_VERIFY" && tc.insecure {+ return "true"+ }+ return ""+ }+ // Missing credential/observer files and enrollment must not be read or+ // run. A configured log must not be created even on invalid input.+ err := run(context.Background(), []string{"--validate-url", "--url", tc.url, "--state-dir", stateDir,+ "--token-file", filepath.Join(stateDir, "absent-token"), "--observers-file", filepath.Join(stateDir, "absent-observers"),+ "--log-file", filepath.Join(stateDir, "absent-log"), "--enroll"}, getenv)+ if (err != nil) != tc.wantError || (err != nil && !strings.Contains(err.Error(), "invalid pulse URL")) {+ t.Fatalf("URL admission error=%v, want rejection=%t", err, tc.wantError)+ }+ entries, err := os.ReadDir(stateDir)+ if err != nil || len(entries) != len(files) {+ t.Fatalf("URL check added state/log files: %v, %v", entries, err)+ }+ info, err := os.Stat(stateDir)+ if err != nil || info.Mode().Perm() != 0750 {+ t.Fatalf("URL check changed state directory permissions: %v, %v", info, err)+ }+ for name, value := range files {+ path := filepath.Join(stateDir, name)+ got, err := os.ReadFile(path)+ info, statErr := os.Stat(path)+ if err != nil || statErr != nil || string(got) != value || info.Mode().Perm() != 0600 {+ t.Fatalf("URL check changed %s: %q, %v, %v", name, got, err, statErr)+ }+ }+ })+ }+}++func TestURLValidationKeepsExplicitPlaintextConsentSeparate(t *testing.T) {+ t.Cleanup(func() { securityutil.SetOperatorPlaintextHTTPConsent(false) })+ for _, allow := range []bool{false, true} {+ cfg, err := loadConfig([]string{"--validate-url", "--url", "http://203.0.113.10", "--insecure"}, func(key string) string {+ if key == "PULSE_AGENT_ALLOW_PLAINTEXT_HTTP" && allow {+ return "true"+ }+ return ""+ })+ if err != nil || !cfg.ValidateURLOnly || cfg.AllowPlaintextHTTP != allow {+ t.Fatalf("explicit URL-check consent: %+v, %v", cfg, err)+ }+ }+}diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.mdindex 416c78e83c..d7ae134d77 100644--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md@@ -15,6 +15,32 @@## Purpose+### Unix agent URL admission precedes replacement++After checksum and signature verification, the Unix installer runs the staged+collector's `--validate-url` mode before safe-profile transactions, credential+reduction, service stops, binary replacement or service/state rendering. The+mode uses `agenttarget.NormalizePulseURL` with the authoritative primary policy,+but reads no credentials or observer files, creates no logs/state/listeners,+and performs no enrollment. It is URL-policy admission, not reachability,+TLS trust, authenticated reporting or sustained module health.++The installer explicitly sets `--allow-plaintext-http=false`: neither inherited+plaintext consent nor `--insecure` authorises a configuration that its rendered+service would reject. HTTPS and existing local/private HTTP policy remain+unchanged. An unsupported or unexecutable staged validator fails closed with+preflight exit 14 and a state-preservation explanation; it never falls back to+an older `--self-test`, which does not establish URL admissibility. Temporary+staging may be cleaned up; the installed service and saved credentials stay+intact. The reachability-only `--preflight-only` path still performs metadata+checks, not executable validation.++`TestRunValidateURLIsReadOnly`, `TestAgentInstallerURLAdmission` and+`TestAgentURLAdmissionPrecedesInstallMutation` cover production URL policy,+actual built CLI/installer admission, inherited consent, file/mode preservation+and trust-before-validation-before-mutation order. These are confined source+fixtures, not original-host recovery or native service acceptance.+### Unix installer startup failure is not successful completionFresh and upgrade callers of `complete_installation_flow` require successfuldiff --git a/scripts/install.sh b/scripts/install.shindex 2fa889a47a..5bee9e6de2 100755--- a/scripts/install.sh+++ b/scripts/install.sh@@ -6730,6 +6730,16 @@ if [[ "$UNINSTALL" == "true" ]]; thenfi# --- Validation ---+# Invoke only a checksum/signature-verified staged binary. This is deliberately+# not --self-test (older agents return before their URL policy is checked).+validate_staged_agent_url() {+ local staged_binary="$1"+ if ! "$staged_binary" --validate-url --url "$PULSE_URL" --allow-plaintext-http=false >/dev/null 2>&1; then+ fail "Could not validate the Pulse URL with the downloaded agent. Use the exact HTTPS server address; --insecure does not permit HTTP. Check DNS and that the downloaded agent can run. The installed service and saved credentials have not been changed." "$EXIT_PREFLIGHT_FAILED"+ fi+ json_event "preflight" "agent_url_validated" "Downloaded agent accepted the Pulse URL"+}+if [[ -z "$PULSE_URL" ]]; thenfail "Missing required argument: --url (or --pulse-url)" "$EXIT_MISSING_ARGS"fi@@ -7378,6 +7388,7 @@ if [[ "$ACTION_RUNNER_ENABLED" == "true" ]]; thenfichmod 0755 "$TMP_BIN"+validate_staged_agent_url "$TMP_BIN"if [[ "$SAFE_PROFILE_ACTION" == "apply" ]]; then# The irreversible server-side reduction must run only through the staged# binary whose checksum/signature have just been verified. The installeddiff --git a/scripts/installtests/agent_url_admission_test.go b/scripts/installtests/agent_url_admission_test.gonew file mode 100644index 0000000000..93a6ecb628--- /dev/null+++ b/scripts/installtests/agent_url_admission_test.go@@ -0,0 +1,125 @@+package installtests++import (+ "context"+ "crypto/sha256"+ "errors"+ "fmt"+ "os"+ "os/exec"+ "path/filepath"+ "runtime"+ "strings"+ "testing"+ "time"+)++// The ordinary repository test command builds the real CLI. Only the service+// and saved installation are fixtures; URL policy is never reimplemented here.+func TestAgentInstallerURLAdmission(t *testing.T) {+ if runtime.GOOS == "windows" {+ t.Skip("Unix installer")+ }+ buildDir := t.TempDir()+ binary := filepath.Join(buildDir, "pulse-agent")+ ctx, cancel := context.WithTimeout(context.Background(), 3*time.Minute)+ defer cancel()+ build := exec.CommandContext(ctx, "go", "build", "-o", binary, "./cmd/pulse-agent")+ build.Dir = repoFile()+ if out, err := build.CombinedOutput(); err != nil {+ t.Fatalf("build real staged agent: %v\n%s", err, out)+ }+ binaryBytes, err := os.ReadFile(binary)+ if err != nil {+ t.Fatal(err)+ }+ t.Logf("actual staged agent sha256=%x bytes=%d", sha256.Sum256(binaryBytes), len(binaryBytes))+ functions := extractInstallShellFunction(t, "fail") + "\n" + extractInstallShellFunction(t, "json_event") + "\n" + extractInstallShellFunction(t, "validate_staged_agent_url")+ for _, tc := range []struct {+ name, url string+ wantExit int+ }{+ {"https", "https://pulse.example.invalid", 0},+ {"private", "http://192.168.1.20:7655", 0},+ {"loopback", "http://127.0.0.1:7655", 0},+ {"local-hostname", "http://pulse:7655", 0},+ {"public-http-despite-insecure-and-env-consent", "http://203.0.113.10", 14},+ {"unresolved-http", "http://pulse.example.invalid", 14},+ {"missing-url", "", 14},+ } {+ t.Run(tc.name, func(t *testing.T) {+ dir := t.TempDir()+ preserved := map[string]string{"pulse-agent": "installed-predecessor\n", "agent-id": "saved-identity\n", "runtime.token": "saved-runtime\n", "token": "saved-token\n", "connection.env": "saved-connection\n", "pulse-agent.service": "saved-service\n", "install.sh": "saved-recovery\n"}+ for name, value := range preserved {+ if err := os.WriteFile(filepath.Join(dir, name), []byte(value), 0600); err != nil {+ t.Fatal(err)+ }+ }+ script := fmt.Sprintf(`set -euo pipefail+OUTPUT_FORMAT=json+NON_INTERACTIVE=true+EXIT_PREFLIGHT_FAILED=14+INSECURE=true+PULSE_URL=%q+%s+validate_staged_agent_url %q+printf 'ADMITTED\n'+`, tc.url, functions, binary)+ runCtx, stop := context.WithTimeout(context.Background(), 15*time.Second)+ defer stop()+ cmd := exec.CommandContext(runCtx, "bash", "-c", script)+ cmd.Env = append(os.Environ(), "PULSE_AGENT_ALLOW_PLAINTEXT_HTTP=true", "PULSE_STATE_DIR="+dir, "PULSE_LOG_FILE="+filepath.Join(dir, "unexpected.log"))+ output, err := cmd.CombinedOutput()+ exit := 0+ if err != nil {+ var failure *exec.ExitError+ if !errors.As(err, &failure) {+ t.Fatal(err)+ }+ exit = failure.ExitCode()+ }+ text := string(output)+ if runCtx.Err() != nil || exit != tc.wantExit || strings.Contains(text, "ADMITTED") != (tc.wantExit == 0) {+ t.Fatalf("URL gate exit=%d, want=%d, timeout=%v\n%s", exit, tc.wantExit, runCtx.Err(), text)+ }+ if tc.wantExit != 0 && (!strings.Contains(text, `"exitCode":14`) || !strings.Contains(text, "saved credentials have not been changed")) {+ t.Fatalf("missing truthful failure: %s", text)+ }+ for name, value := range preserved {+ path := filepath.Join(dir, name)+ got, err := os.ReadFile(path)+ info, statErr := os.Stat(path)+ if err != nil || statErr != nil || string(got) != value || info.Mode().Perm() != 0600 {+ t.Fatalf("URL admission changed %s", name)+ }+ }+ entries, err := os.ReadDir(dir)+ if err != nil || len(entries) != len(preserved) {+ t.Fatalf("URL admission added state/log files: %v, %v", entries, err)+ }+ })+ }+}++func TestAgentURLAdmissionPrecedesInstallMutation(t *testing.T) {+ source, err := os.ReadFile(repoFile("scripts", "install.sh"))+ if err != nil {+ t.Fatal(err)+ }+ text := string(source)+ start := strings.Index(text, "# Release metadata verification")+ if start < 0 {+ t.Fatal("missing staged trust boundary")+ }+ text = text[start:]+ gate := strings.Index(text, `validate_staged_agent_url "$TMP_BIN"`)+ trust := strings.Index(text, `verify_download_signature "$TMP_BIN"`)+ if gate < 0 || trust < 0 || trust >= gate {+ t.Fatal("URL admission must execute the verified staged agent")+ }+ for _, mutation := range []string{"safe_profile_begin_transaction", "reduce_safe_profile_collector_authority", "stop_existing_agent_service", `systemctl stop "${AGENT_NAME}"`, `mv "$TMP_BIN" "${INSTALL_DIR}/${BINARY_NAME}"`} {+ if index := strings.Index(text, mutation); index < 0 || index <= gate {+ t.Errorf("URL admission must precede %s", mutation)+ }+ }+}