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.

Retain Unix agent credentials when the saved server URL is missing

pulse-triage[bot]03b8808c045c
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
index 5bdce283b9..b8355cfbee 100644
--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
@@ -15,6 +15,29 @@
## Purpose
+### Unix removal retains credentials when connection recovery is incomplete
+
+After existing installed-state recovery, the unified Unix installer checks for
+collector credentials before considering whether a Pulse URL was recovered.
+Any inline credential or selected/runtime/legacy/helper token-file entry,
+including an empty or unreadable file, broken symlink or FIFO, requires
+an authenticated exact-record removal confirmation before local teardown.
+A missing URL fails with a credential-safe same-instance recovery message;
+it cannot turn credential-bearing removal into the local-only path. No
+transport request, process stop, service stop or state deletion follows that
+refusal. Server refusal, unknown confirmation and identity mismatch retain
+state as before; confirmation does not widen trusted path-removal authority.
+Credential-free removal remains local-only, with or without a saved URL.
+
+`TestInstallSHUninstallRetainsCredentialsWhenSavedURLIsMissing` runs the
+production admission, credential-presence, record-confirmation and initial
+state-directory cleanup functions through `agent_uninstall_state.py`. Its
+seventeen confined cases use private files and service/transport doubles,
+not a privileged installer or native service manager. These checks do not
+establish Windows, actual TLS, saved-state discovery, a published fix or
+whole-issue installed removal acceptance.
+
+
### Selected agent credential files retain their own authority
The real agent flag-loading path resolves a non-empty explicit `--token` before
diff --git a/docs/release-control/v6/internal/subsystems/deployment-installability.md b/docs/release-control/v6/internal/subsystems/deployment-installability.md
index c85ff3cd20..1017f993b5 100644
--- a/docs/release-control/v6/internal/subsystems/deployment-installability.md
+++ b/docs/release-control/v6/internal/subsystems/deployment-installability.md
@@ -15,6 +15,29 @@
## Purpose
+### Unix removal retains credentials when connection recovery is incomplete
+
+After existing installed-state recovery, the unified Unix installer checks for
+collector credentials before considering whether a Pulse URL was recovered.
+Any inline credential or selected/runtime/legacy/helper token-file entry,
+including an empty or unreadable file, broken symlink or FIFO, requires
+an authenticated exact-record removal confirmation before local teardown.
+A missing URL fails with a credential-safe same-instance recovery message;
+it cannot turn credential-bearing removal into the local-only path. No
+transport request, process stop, service stop or state deletion follows that
+refusal. Server refusal, unknown confirmation and identity mismatch retain
+state as before; confirmation does not widen trusted path-removal authority.
+Credential-free removal remains local-only, with or without a saved URL.
+
+`TestInstallSHUninstallRetainsCredentialsWhenSavedURLIsMissing` runs the
+production admission, credential-presence, record-confirmation and initial
+state-directory cleanup functions through `agent_uninstall_state.py`. Its
+seventeen confined cases use private files and service/transport doubles,
+not a privileged installer or native service manager. These checks do not
+establish Windows, actual TLS, saved-state discovery, a published fix or
+whole-issue installed removal acceptance.
+
+
### Docker server update plans preserve the saved deployment
The existing update-plan API and banner's copyable instructions must not guess
diff --git a/scripts/install.sh b/scripts/install.sh
index 2902338145..9ed853a20f 100755
--- a/scripts/install.sh
+++ b/scripts/install.sh
@@ -5533,7 +5533,10 @@ if [[ "$UNINSTALL" == "true" ]]; then
# A credential-bearing install must durably remove its exact server record
# through the same CA/fingerprint/no-proxy transport used by lifecycle
# migration before any local credential or service state is deleted.
- if [[ -n "$PULSE_URL" ]] && collector_credential_state_present; then
+ if collector_credential_state_present; then
+ if [[ -z "$PULSE_URL" ]]; then
+ fail "The saved Pulse URL is missing; local credentials and services were retained. Restore saved connection state or provide --url for the same trusted Pulse instance and retry uninstall." "$EXIT_MISSING_ARGS"
+ fi
log_info "Authenticating Pulse server removal before local teardown..."
if ! uninstall_collector_registration; then
fail "Pulse did not durably confirm collector removal; local credentials and services were retained. Restore trusted server connectivity and retry uninstall." "$EXIT_GENERAL"
diff --git a/scripts/installtests/agent_uninstall_state.py b/scripts/installtests/agent_uninstall_state.py
new file mode 100644
index 0000000000..530f5c4693
--- /dev/null
+++ b/scripts/installtests/agent_uninstall_state.py
@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Execute the Unix uninstall admission and initial teardown, not a root installer.
+
+Production credential detection, record confirmation and directory-authority
+functions remain intact. Only transport and service/process operations are
+private doubles; deletion is confined to three owned temporary directories.
+These controls are not native installation, TLS or provider acceptance.
+"""
+
+import os
+from pathlib import Path
+import shlex
+import stat
+import subprocess
+import tempfile
+import unittest
+
+ROOT = Path(__file__).resolve().parents[2]
+SOURCE = Path(os.environ.get("PULSE_AGENT_UNINSTALL_SOURCE", ROOT / "scripts/install.sh"))
+
+
+def function(source, name):
+ return name + "() {" + source.split(name + "() {", 1)[1].split("\n}\n", 1)[0] + "\n}\n"
+
+
+def snapshot(root):
+ result = {}
+ for path in sorted(root.rglob("*")):
+ if path.name == "events":
+ continue
+ mode = path.lstat().st_mode
+ payload = os.readlink(path) if stat.S_ISLNK(mode) else (
+ path.read_bytes() if stat.S_ISREG(mode) and mode & stat.S_IRUSR else None)
+ result[str(path.relative_to(root))] = (mode, payload, path.lstat().st_size, path.lstat().st_ino)
+ return result
+
+
+class UnixUninstallState(unittest.TestCase):
+ source = SOURCE.read_text()
+
+ def exercise(self, credential="runtime", url="", reply="confirmed", authority=True):
+ source = self.source
+ # Keep the real entry and all initial credential/service/state teardown.
+ # Stop before unrelated platform boot/log cleanup; never run it on a host.
+ entry = source.split("# --- Uninstall Logic ---\n", 1)[1].split(
+ " # Remove least-privilege helper artifacts.", 1)[0] + "fi\n"
+ names = ("collector_credential_state_present", "uninstall_collector_registration",
+ "remove_authorized_runtime_dir", "remove_agent_state_dir",
+ "remove_privileged_helper_state_dir", "remove_safe_profile_state_dir", "fail")
+ with tempfile.TemporaryDirectory() as temporary:
+ root = Path(temporary)
+ state, helper, profile = (root / name for name in ("state", "helper", "profile"))
+ for directory in (state, helper, profile):
+ directory.mkdir(mode=0o700)
+ (directory / "identity").write_text("owned-instance\n")
+ (state / "connection.env").write_text("PULSE_AGENT_ID='owned-agent'\n")
+ (state / "agent-id").write_text("owned-agent\n")
+ service = root / "service"
+ service.write_text("active\n")
+ (root / "unrelated").write_text("do not change\n")
+ token = ""
+ selected = root / "selected-token"
+ if credential == "inline":
+ token = "synthetic-collector-credential"
+ elif credential != "none":
+ path = {"legacy": state / "token", "selected": selected,
+ "helper": helper / "token"}.get(credential, state / "runtime.token")
+ if credential == "broken-link":
+ path.symlink_to(root / "missing-token")
+ elif credential == "fifo":
+ os.mkfifo(path, 0o600)
+ else:
+ path.write_text("" if credential == "empty" else "synthetic-collector-credential\n")
+ path.chmod(0 if credential == "unreadable" else 0o600)
+ before = snapshot(root)
+ values = {"STATE_DIR": state, "PRIVILEGED_HELPER_STATE_DIR": helper,
+ "PRIVILEGED_HELPER_CREDENTIAL_DIR": helper, "SAFE_PROFILE_STATE_DIR": profile,
+ "STATE_DIR_REMOVAL_AUTHORITY": state if authority else "",
+ "PRIVILEGED_HELPER_STATE_DIR_REMOVAL_AUTHORITY": helper,
+ "SAFE_PROFILE_STATE_DIR_REMOVAL_AUTHORITY": profile,
+ "PULSE_TOKEN": token, "RUNTIME_TOKEN_FILE": selected,
+ "PULSE_URL": url, "AGENT_ID": "owned-agent", "HOSTNAME_OVERRIDE": "owned-host",
+ "EVENTS": root / "events", "SERVICE": service, "REPLY": reply}
+ setup = "\n".join(f"{key}={shlex.quote(str(value))}" for key, value in values.items())
+ functions = "\n".join(function(source, name) for name in names)
+ # A whitelist protects the fixture even if production cleanup changes.
+ shell = r'''
+set -euo pipefail
+UNINSTALL=true AGENT_NAME=pulse-agent EXIT_GENERAL=1 EXIT_MISSING_ARGS=16
+OUTPUT_FORMAT=text NON_INTERACTIVE=true
+log_info() { :; }
+log_warn() { printf 'warning:%s\n' "$*"; }
+log_error() { printf 'error:%s\n' "$*"; }
+recover_agent_id_from_state_file() { printf 'owned-agent\n'; }
+run_collector_lifecycle_command() {
+ printf 'request:%s\n' "$*" >> "$EVENTS"
+ case "$REPLY" in
+ confirmed) printf 'owned-agent\n' ;;
+ mismatch) printf 'different-agent\n' ;;
+ empty) : ;;
+ refused|lost-response) return 1 ;;
+ *) return 90 ;;
+ esac
+}
+pkill() { printf 'process-stop\n' >> "$EVENTS"; }
+sleep() { :; }
+systemctl() { return 91; }
+teardown_action_runner_service() { printf 'runner-stop\n' >> "$EVENTS"; }
+teardown_privileged_helper_service() { printf 'helper-stop\n' >> "$EVENTS"; }
+teardown_systemd_agent_service() { printf 'service-stop\n' >> "$EVENTS"; printf 'stopped\n' > "$SERVICE"; }
+rm() {
+ [[ $# == 3 && "$1" == -rf && "$2" == -- ]] || return 92
+ [[ "$3" == "$STATE_DIR" || "$3" == "$PRIVILEGED_HELPER_STATE_DIR" || "$3" == "$SAFE_PROFILE_STATE_DIR" ]] || return 93
+ printf 'state-remove\n' >> "$EVENTS"
+ command rm "$@"
+}
+'''
+ result = subprocess.run(["bash", "-c", shell + "\n" + setup + "\n" + functions +
+ "\nmain() {\n" + entry + "}\nmain\n"],
+ capture_output=True, text=True, timeout=5)
+ events = (root / "events").read_text() if (root / "events").exists() else ""
+ after = snapshot(root)
+ return result, events, before, after
+
+ def test_missing_url_retains_every_credential_representation_without_a_request(self):
+ for kind in ("inline", "runtime", "legacy", "selected", "helper", "empty",
+ "unreadable", "broken-link", "fifo"):
+ with self.subTest(credential=kind):
+ result, events, before, after = self.exercise(kind)
+ self.assertEqual(result.returncode, 16, result.stderr)
+ self.assertIn("same trusted Pulse instance", result.stdout)
+ self.assertNotIn("synthetic-collector-credential", result.stdout + result.stderr)
+ self.assertEqual(events, "")
+ self.assertEqual(after, before)
+
+ def test_server_refusal_unknown_or_other_identity_retains_service_and_state(self):
+ for reply in ("refused", "lost-response", "empty", "mismatch"):
+ with self.subTest(reply=reply):
+ result, events, before, after = self.exercise(url="https://pulse.invalid", reply=reply)
+ self.assertEqual(result.returncode, 1, result.stderr)
+ self.assertEqual(events, "request:collector-uninstall --agent-id owned-agent --hostname owned-host\n")
+ self.assertEqual(after, before)
+
+ def test_exact_confirmation_precedes_process_service_and_state_teardown(self):
+ result, events, before, after = self.exercise(url="https://pulse.invalid")
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertEqual(events.splitlines(), [
+ "request:collector-uninstall --agent-id owned-agent --hostname owned-host",
+ "process-stop", "process-stop", "runner-stop", "helper-stop", "service-stop",
+ "state-remove", "state-remove", "state-remove"])
+ self.assertEqual(set(after), {"service", "unrelated"})
+ self.assertEqual(after["service"][1], b"stopped\n")
+ self.assertEqual(after["unrelated"], before["unrelated"])
+
+ def test_credential_free_local_only_removal_needs_no_url_or_request(self):
+ for url in ("", "https://pulse.invalid"):
+ with self.subTest(url=url):
+ result, events, before, after = self.exercise("none", url=url)
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertNotIn("request:", events)
+ self.assertEqual(set(after), {"service", "unrelated"})
+ self.assertEqual(after["unrelated"], before["unrelated"])
+
+ def test_server_confirmation_does_not_grant_unknown_path_removal(self):
+ result, events, before, after = self.exercise(url="https://pulse.invalid", authority=False)
+ self.assertEqual(result.returncode, 0, result.stderr)
+ self.assertEqual(events.count("state-remove\n"), 2)
+ self.assertIn("without exact trusted lifecycle authority", result.stdout)
+ for name in ("state", "state/runtime.token", "state/agent-id", "state/connection.env"):
+ self.assertEqual(after[name], before[name])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/installtests/install_sh_test.go b/scripts/installtests/install_sh_test.go
index 2acfad95e3..d1de72ef47 100644
--- a/scripts/installtests/install_sh_test.go
+++ b/scripts/installtests/install_sh_test.go
@@ -8259,3 +8259,30 @@ func TestInstallSHLegacyAgentIDRecoveryAccountsForEveryByte(t *testing.T) {
})
}
}
+
+// Run the production Unix removal gate through private state/service/transport
+// doubles. Native platform installation and actual transport remain separate.
+func TestInstallSHUninstallRetainsCredentialsWhenSavedURLIsMissing(t *testing.T) {
+ ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
+ defer cancel()
+ cmd := exec.CommandContext(ctx, "python3", repoFile("scripts", "installtests", "agent_uninstall_state.py"), "-v")
+ output, err := cmd.CombinedOutput()
+ if err != nil {
+ t.Fatalf("Unix removal state controls: %v\n%s", err, output)
+ }
+ for _, name := range []string{
+ "test_missing_url_retains_every_credential_representation_without_a_request",
+ "test_server_refusal_unknown_or_other_identity_retains_service_and_state",
+ "test_exact_confirmation_precedes_process_service_and_state_teardown",
+ "test_credential_free_local_only_removal_needs_no_url_or_request",
+ "test_server_confirmation_does_not_grant_unknown_path_removal",
+ } {
+ if !strings.Contains(string(output), name+" (__main__.UnixUninstallState."+name+") ... ok") {
+ t.Fatalf("Unix removal control %s did not pass:\n%s", name, output)
+ }
+ }
+ if !strings.Contains(string(output), "\nRan 5 tests in ") || !strings.Contains(string(output), "\nOK\n") {
+ t.Fatalf("incomplete Unix removal state verdict:\n%s", output)
+ }
+ t.Logf("%s", output)
+}