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.

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.go
index 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 Logging
logger, closeLogger, err := configureAgentLogger(cfg)
if err != nil {
@@ -1167,6 +1178,7 @@ type Config struct {
DisableCeph bool // Disable local Ceph status polling
DisableClusterPeerSensors bool // Keep Proxmox monitoring local and skip SSH sensor collection from cluster peers
SelfTest 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 multiValue
fs.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
+ }
+
// Validation
pulseURL := strings.TrimSpace(*urlFlag)
if pulseURL == "" {
diff --git a/cmd/pulse-agent/url_admission_test.go b/cmd/pulse-agent/url_admission_test.go
new file mode 100644
index 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.md
index 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 completion
Fresh and upgrade callers of `complete_installation_flow` require successful
diff --git a/scripts/install.sh b/scripts/install.sh
index 2fa889a47a..5bee9e6de2 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -6730,6 +6730,16 @@ if [[ "$UNINSTALL" == "true" ]]; then
fi
# --- 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" ]]; then
fail "Missing required argument: --url (or --pulse-url)" "$EXIT_MISSING_ARGS"
fi
@@ -7378,6 +7388,7 @@ if [[ "$ACTION_RUNNER_ENABLED" == "true" ]]; then
fi
chmod 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 installed
diff --git a/scripts/installtests/agent_url_admission_test.go b/scripts/installtests/agent_url_admission_test.go
new file mode 100644
index 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)
+ }
+ }
+}