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 PBS credentials, diagnostics and installer preparation private
pulse-triage[bot]bcbf7f099219
diff --git a/docs/PBS.md b/docs/PBS.mdindex 2c8affcab3..8f31f3cda4 100644--- a/docs/PBS.md+++ b/docs/PBS.md@@ -86,27 +86,67 @@ for monitoring.On the PBS host, enter an administrator root shell before preparing the privatefile below. In the editor, save only the Pulse agent token, with no header or-quotes; never put the secret in a command argument:+quotes; never put the secret in a command argument. The preparation preserves+an existing file and refuses symlinked or non-regular credential paths. Stop+if it fails; do not continue to the installer:```bash-umask 077-mkdir -p "$HOME/.config/pulse"-chmod 700 "$HOME/.config/pulse"-touch "$HOME/.config/pulse/pbs-agent-token"-chmod 600 "$HOME/.config/pulse/pbs-agent-token"-vi "$HOME/.config/pulse/pbs-agent-token"+(+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ credential_file="$config_dir/pbs-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"+)```Download the agent installer from **your Pulse server's HTTPS address**, theninspect the saved script before running it. Replace the example Pulse URL inboth commands. Stop if the download fails; run the next command only after a-successful download and inspection. Do not substitute GitHub's top-level `install.sh`: that installs-the Pulse server, not the agent.+successful HTTP **200** download and inspection. This ignores curl configuration+and saves only a successful download to the installer path. It refuses an+existing installer rather than overwriting it; review that file locally before+deciding whether a new download is needed. Do not substitute GitHub's top-level+`install.sh`: that installs the Pulse server, not the agent.```bash-curl --fail --silent --show-error \- --output "$HOME/.config/pulse/pbs-agent-install.sh" \- https://pulse.example.com/install.sh+(+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ installer_file="$config_dir/pbs-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/pbs-agent-download.XXXXXX")+ curl_exit=0+ status=$(curl --disable --fail --silent --show-error --proto '=https' \+ --connect-timeout 5 --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" ]+)``````bash@@ -117,7 +157,10 @@ bash "$HOME/.config/pulse/pbs-agent-install.sh" \```Do not bypass certificate checks to fetch or run the installer. Use a trusted-Pulse certificate or a CA file you verified separately. See+Pulse certificate or add `--cacert` with a CA file you verified separately.+A failed or redirected download is not an installer: do not run its temporary+file. Keep `--disable` first in both curl examples on this page; it ignores+local settings that could enable tracing, bypass TLS or follow redirects. See[Unified Agent Setup](UNIFIED_AGENT.md) for installer trust and other profiles.After installation, check a fresh agent report and the host's`pulse-agent --version`; installation or hardware capacity alone does not prove@@ -177,15 +220,30 @@ another machine does not prove that Pulse can reach PBS.```- **Authentication/permissions:** test a datastore request, not just `/version`.- Prepare a private header file on the machine running curl:+ Prepare a private header file on the machine running curl. Stop if preparation+ fails; an existing file is preserved, and symlinked or non-regular credential+ paths are refused before opening the editor:```bash- umask 077- mkdir -p "$HOME/.config/pulse"- chmod 700 "$HOME/.config/pulse"- touch "$HOME/.config/pulse/pbs-header"- chmod 600 "$HOME/.config/pulse/pbs-header"- vi "$HOME/.config/pulse/pbs-header"+ (+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ credential_file="$config_dir/pbs-header"+ 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"+ )```In the editor, save this line, replacing `<pbs-token-secret>` with the secret@@ -195,12 +253,33 @@ another machine does not prove that Pulse can reach PBS.Authorization: PBSAPIToken=pulse-monitor@pbs!pulse-token:<pbs-token-secret>```- Then use curl 7.76 or later, with your PBS hostname:+ Then use curl 7.76 or later, with your PBS hostname. The request prints only+ the HTTP status and a new private response-file path; inspect that file locally,+ not in a public terminal recording or thread:```bash- curl --fail-with-body --silent --show-error --connect-timeout 5 --max-time 15 \- --header "@$HOME/.config/pulse/pbs-header" \- https://pbs.example.com:8007/api2/json/admin/datastore+ (+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ credential_file="$config_dir/pbs-header"+ if [ -L "$HOME/.config" ] || [ -L "$config_dir" ] || [ -L "$credential_file" ] || [ ! -f "$credential_file" ]; then+ printf 'Prepare the private header file first.\n' >&2+ exit 1+ fi+ chmod 700 "$config_dir"+ chmod 600 "$credential_file"+ result_file=$(mktemp "$config_dir/pbs-response.XXXXXX")+ printf 'Private response file: %s\n' "$result_file"+ curl_exit=0+ status=$(curl --disable --fail-with-body --silent --show-error --proto '=https' \+ --connect-timeout 5 --max-time 15 --header "@$credential_file" \+ --output "$result_file" --write-out '%{http_code}' \+ https://pbs.example.com:8007/api2/json/admin/datastore) || curl_exit=$?+ printf 'HTTP %s\n' "$status"+ [ "$curl_exit" -eq 0 ] || exit "$curl_exit"+ [ "$status" = 200 ]+ )```For curl with a private CA or self-signed certificate, add@@ -209,7 +288,9 @@ another machine does not prove that Pulse can reach PBS.use `--insecure` or `-k`.`401` means authentication was rejected; `403` means the requested access was- refused. Both return a non-zero curl exit while retaining the error body.+ refused. Both return a non-zero curl exit while retaining the error body+ privately. A redirect or `000` is not successful access; this command neither+ follows redirects nor retries.Inspect the existing token and both `Audit` grants before replacing anything.A `200` response listing the expected datastore establishes access to thatlist, not successful collection of every backup, job or History graph. Andiff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.mdindex 2c8affcab3..8f31f3cda4 100644--- a/frontend-modern/public/docs/PBS.md+++ b/frontend-modern/public/docs/PBS.md@@ -86,27 +86,67 @@ for monitoring.On the PBS host, enter an administrator root shell before preparing the privatefile below. In the editor, save only the Pulse agent token, with no header or-quotes; never put the secret in a command argument:+quotes; never put the secret in a command argument. The preparation preserves+an existing file and refuses symlinked or non-regular credential paths. Stop+if it fails; do not continue to the installer:```bash-umask 077-mkdir -p "$HOME/.config/pulse"-chmod 700 "$HOME/.config/pulse"-touch "$HOME/.config/pulse/pbs-agent-token"-chmod 600 "$HOME/.config/pulse/pbs-agent-token"-vi "$HOME/.config/pulse/pbs-agent-token"+(+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ credential_file="$config_dir/pbs-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"+)```Download the agent installer from **your Pulse server's HTTPS address**, theninspect the saved script before running it. Replace the example Pulse URL inboth commands. Stop if the download fails; run the next command only after a-successful download and inspection. Do not substitute GitHub's top-level `install.sh`: that installs-the Pulse server, not the agent.+successful HTTP **200** download and inspection. This ignores curl configuration+and saves only a successful download to the installer path. It refuses an+existing installer rather than overwriting it; review that file locally before+deciding whether a new download is needed. Do not substitute GitHub's top-level+`install.sh`: that installs the Pulse server, not the agent.```bash-curl --fail --silent --show-error \- --output "$HOME/.config/pulse/pbs-agent-install.sh" \- https://pulse.example.com/install.sh+(+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ installer_file="$config_dir/pbs-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/pbs-agent-download.XXXXXX")+ curl_exit=0+ status=$(curl --disable --fail --silent --show-error --proto '=https' \+ --connect-timeout 5 --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" ]+)``````bash@@ -117,7 +157,10 @@ bash "$HOME/.config/pulse/pbs-agent-install.sh" \```Do not bypass certificate checks to fetch or run the installer. Use a trusted-Pulse certificate or a CA file you verified separately. See+Pulse certificate or add `--cacert` with a CA file you verified separately.+A failed or redirected download is not an installer: do not run its temporary+file. Keep `--disable` first in both curl examples on this page; it ignores+local settings that could enable tracing, bypass TLS or follow redirects. See[Unified Agent Setup](UNIFIED_AGENT.md) for installer trust and other profiles.After installation, check a fresh agent report and the host's`pulse-agent --version`; installation or hardware capacity alone does not prove@@ -177,15 +220,30 @@ another machine does not prove that Pulse can reach PBS.```- **Authentication/permissions:** test a datastore request, not just `/version`.- Prepare a private header file on the machine running curl:+ Prepare a private header file on the machine running curl. Stop if preparation+ fails; an existing file is preserved, and symlinked or non-regular credential+ paths are refused before opening the editor:```bash- umask 077- mkdir -p "$HOME/.config/pulse"- chmod 700 "$HOME/.config/pulse"- touch "$HOME/.config/pulse/pbs-header"- chmod 600 "$HOME/.config/pulse/pbs-header"- vi "$HOME/.config/pulse/pbs-header"+ (+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ credential_file="$config_dir/pbs-header"+ 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"+ )```In the editor, save this line, replacing `<pbs-token-secret>` with the secret@@ -195,12 +253,33 @@ another machine does not prove that Pulse can reach PBS.Authorization: PBSAPIToken=pulse-monitor@pbs!pulse-token:<pbs-token-secret>```- Then use curl 7.76 or later, with your PBS hostname:+ Then use curl 7.76 or later, with your PBS hostname. The request prints only+ the HTTP status and a new private response-file path; inspect that file locally,+ not in a public terminal recording or thread:```bash- curl --fail-with-body --silent --show-error --connect-timeout 5 --max-time 15 \- --header "@$HOME/.config/pulse/pbs-header" \- https://pbs.example.com:8007/api2/json/admin/datastore+ (+ set -eu+ umask 077+ config_dir="$HOME/.config/pulse"+ credential_file="$config_dir/pbs-header"+ if [ -L "$HOME/.config" ] || [ -L "$config_dir" ] || [ -L "$credential_file" ] || [ ! -f "$credential_file" ]; then+ printf 'Prepare the private header file first.\n' >&2+ exit 1+ fi+ chmod 700 "$config_dir"+ chmod 600 "$credential_file"+ result_file=$(mktemp "$config_dir/pbs-response.XXXXXX")+ printf 'Private response file: %s\n' "$result_file"+ curl_exit=0+ status=$(curl --disable --fail-with-body --silent --show-error --proto '=https' \+ --connect-timeout 5 --max-time 15 --header "@$credential_file" \+ --output "$result_file" --write-out '%{http_code}' \+ https://pbs.example.com:8007/api2/json/admin/datastore) || curl_exit=$?+ printf 'HTTP %s\n' "$status"+ [ "$curl_exit" -eq 0 ] || exit "$curl_exit"+ [ "$status" = 200 ]+ )```For curl with a private CA or self-signed certificate, add@@ -209,7 +288,9 @@ another machine does not prove that Pulse can reach PBS.use `--insecure` or `-k`.`401` means authentication was rejected; `403` means the requested access was- refused. Both return a non-zero curl exit while retaining the error body.+ refused. Both return a non-zero curl exit while retaining the error body+ privately. A redirect or `000` is not successful access; this command neither+ follows redirects nor retries.Inspect the existing token and both `Audit` grants before replacing anything.A `200` response listing the expected datastore establishes access to thatlist, not successful collection of every backup, job or History graph. Andiff --git a/scripts/installtests/pbs_api_guidance_test.go b/scripts/installtests/pbs_api_guidance_test.gonew file mode 100644index 0000000000..fa42e79e87--- /dev/null+++ b/scripts/installtests/pbs_api_guidance_test.go@@ -0,0 +1,447 @@+package installtests++import (+ "context"+ "encoding/pem"+ "fmt"+ "io"+ "log"+ "net/http"+ "net/http/httptest"+ "os"+ "os/exec"+ "path/filepath"+ "regexp"+ "strings"+ "testing"+ "time"+)++// Extract the actual copied commands, including the old guide for an exact+// parent control. These tests contact only synthetic peers in the proof VM.+func pbsAPIBlocks(doc string) ([4]string, error) {+ var blocks [4]string+ for _, match := range regexp.MustCompile("(?s)```bash\n(.*?)```").FindAllStringSubmatch(doc, -1) {+ block := match[1]+ index := -1+ switch {+ case strings.Contains(block, "pbs-agent-token") && strings.Contains(block, "vi "):+ index = 0+ case strings.Contains(block, "pbs-header") && strings.Contains(block, "vi "):+ index = 1+ case strings.Contains(block, "pbs-agent-install.sh") && strings.Contains(block, "curl "):+ index = 2+ case strings.Contains(block, "https://pbs.example.com:8007/api2/json/admin/datastore"):+ index = 3+ }+ if index >= 0 {+ if blocks[index] != "" {+ return blocks, fmt.Errorf("duplicate PBS recipe %d", index)+ }+ blocks[index] = block+ }+ }+ for i, block := range blocks {+ if block == "" {+ return blocks, fmt.Errorf("missing PBS recipe %d", i)+ }+ }+ return blocks, nil+}++func pbsAPISafety(blocks [4]string) error {+ for i, block := range blocks {+ required := []string{"set -eu", "umask 077", `[ -L "$HOME/.config" ]`, `[ -L "$config_dir" ]`, `chmod 700 "$config_dir"`}+ if i < 2 {+ required = append(required, `[ -L "$credential_file" ]`, `[ ! -f "$credential_file" ]`, `chmod 600 "$credential_file"`, `vi "$credential_file"`)+ } else {+ required = append(required, "curl --disable ", "--silent --show-error --proto '=https'", "--connect-timeout 5",+ `--write-out '%{http_code}'`, `printf 'HTTP %s\n' "$status"`, `[ "$curl_exit" -eq 0 ] || exit "$curl_exit"`, `[ "$status" = 200 ]`)+ if i == 2 {+ required = append(required, "--fail ", "--max-time 60", `download_file=$(mktemp "$config_dir/pbs-agent-download.XXXXXX")`,+ `[ -e "$installer_file" ] || [ -L "$installer_file" ]`, `--output "$download_file"`, `mv -n "$download_file" "$installer_file"`, `[ ! -e "$download_file" ]`)+ } else {+ required = append(required, "--fail-with-body ", "--max-time 15", `[ -L "$credential_file" ]`, `[ ! -f "$credential_file" ]`,+ `chmod 600 "$credential_file"`, `result_file=$(mktemp "$config_dir/pbs-response.XXXXXX")`, `--header "@$credential_file"`, `--output "$result_file"`)+ }+ for _, forbidden := range []string{"--insecure", "--location", "--config", "--trace", "--verbose", "--retry", "Authorization:", " | "} {+ if strings.Contains(block, forbidden) {+ return fmt.Errorf("PBS recipe %d contains %s", i, forbidden)+ }+ }+ if strings.Count(block, "curl ") != 1 {+ return fmt.Errorf("PBS recipe %d must make one request", i)+ }+ }+ for _, text := range required {+ if !strings.Contains(block, text) {+ return fmt.Errorf("PBS recipe %d lacks %s", i, text)+ }+ }+ }+ return nil+}++func pbsAPIGuidance(t *testing.T) [4]string {+ t.Helper()+ doc, err := os.ReadFile(repoFile("docs", "PBS.md"))+ if err != nil {+ t.Fatal(err)+ }+ blocks, err := pbsAPIBlocks(string(doc))+ if err != nil {+ t.Fatal(err)+ }+ if err := pbsAPISafety(blocks); err != nil {+ t.Fatal(err)+ }+ mirror, err := os.ReadFile(repoFile("frontend-modern", "public", "docs", "PBS.md"))+ if err != nil || string(mirror) != string(doc) {+ t.Fatal("shipped PBS guide differs from the verified recipes")+ }+ return blocks+}++func runPBSRecipe(t *testing.T, recipe, home, bin string, extraEnv ...string) (string, int) {+ t.Helper()+ ctx, cancel := context.WithTimeout(context.Background(), 25*time.Second)+ defer cancel()+ cmd := exec.CommandContext(ctx, "bash", "-c", recipe)+ cmd.Env = append(os.Environ(), "HOME="+home, "PATH="+bin+":"+os.Getenv("PATH"),+ "http_proxy=", "HTTP_PROXY=", "https_proxy=", "HTTPS_PROXY=", "ALL_PROXY=", "all_proxy=", "NO_PROXY=", "no_proxy=")+ cmd.Env = append(cmd.Env, extraEnv...)+ output, err := cmd.CombinedOutput()+ if ctx.Err() != nil {+ t.Fatal("copied PBS recipe exceeded its bounded test deadline")+ }+ if err == nil {+ return string(output), 0+ }+ failure, ok := err.(*exec.ExitError)+ if !ok {+ t.Fatal(err)+ }+ return string(output), failure.ExitCode()+}++func TestPBSAPIGuidancePreparationIsPrivateAndFailClosed(t *testing.T) {+ for index, filename := range []string{"pbs-agent-token", "pbs-header"} {+ for _, mode := range []string{"new", "existing", "config symlink", "directory symlink", "file symlink", "dangling symlink", "non-regular", "mkdir failure", "chmod failure", "touch failure", "editor failure"} {+ t.Run(filename+"/"+mode, func(t *testing.T) {+ home := t.TempDir()+ bin := filepath.Join(home, "bin")+ if err := os.Mkdir(bin, 0700); err != nil {+ t.Fatal(err)+ }+ edited := filepath.Join(home, "editor-started")+ editor := "#!/bin/sh\nprintf started > \"$EDITOR_STARTED\"\n"+ if mode == "editor failure" {+ editor += "exit 1\n"+ }+ if err := os.WriteFile(filepath.Join(bin, "vi"), []byte(editor), 0700); err != nil {+ t.Fatal(err)+ }+ dir := filepath.Join(home, ".config", "pulse")+ file := filepath.Join(dir, filename)+ if mode == "existing" || strings.Contains(mode, "file symlink") || mode == "dangling symlink" || mode == "non-regular" {+ if err := os.MkdirAll(dir, 0755); err != nil {+ t.Fatal(err)+ }+ }+ target := filepath.Join(home, "untouched")+ if strings.Contains(mode, "symlink") {+ link := file+ switch mode {+ case "file symlink":+ if err := os.WriteFile(target, []byte("synthetic-existing-secret"), 0644); err != nil {+ t.Fatal(err)+ }+ case "config symlink", "directory symlink":+ if err := os.Mkdir(target, 0755); err != nil {+ t.Fatal(err)+ }+ link = filepath.Join(home, ".config")+ if mode == "directory symlink" {+ if err := os.Mkdir(link, 0755); err != nil {+ t.Fatal(err)+ }+ link = dir+ }+ }+ if err := os.Symlink(target, link); err != nil {+ t.Fatal(err)+ }+ }+ if mode == "existing" {+ if err := os.WriteFile(file, []byte("synthetic-existing-secret"), 0644); err != nil {+ t.Fatal(err)+ }+ }+ if mode == "non-regular" {+ if err := os.Mkdir(file, 0700); err != nil {+ t.Fatal(err)+ }+ }+ if strings.HasSuffix(mode, " failure") && mode != "editor failure" {+ if err := os.WriteFile(filepath.Join(bin, strings.TrimSuffix(mode, " failure")), []byte("#!/bin/sh\nexit 1\n"), 0700); err != nil {+ t.Fatal(err)+ }+ }+ output, exit := runPBSRecipe(t, pbsAPIGuidance(t)[index], home, bin, "EDITOR_STARTED="+edited)+ _, editorErr := os.Stat(edited)+ if mode != "new" && mode != "existing" {+ if exit == 0 || (mode != "editor failure" && !os.IsNotExist(editorErr)) {+ t.Fatal("failed or unsafe preparation was accepted or reached the editor")+ }+ if strings.Contains(mode, "symlink") && mode != "dangling symlink" {+ info, err := os.Stat(target)+ wantMode := os.FileMode(0755)+ if mode == "file symlink" {+ wantMode = 0644+ content, err := os.ReadFile(target)+ if err != nil || string(content) != "synthetic-existing-secret" {+ t.Fatal("refused credential path modified its target")+ }+ }+ if err != nil || info.Mode().Perm() != wantMode {+ t.Fatal("refused path modified target permissions")+ }+ }+ } else {+ if exit != 0 || editorErr != nil {+ t.Fatalf("safe preparation failed: exit %d, %s", exit, output)+ }+ for path, permissions := range map[string]os.FileMode{dir: 0700, file: 0600} {+ info, err := os.Stat(path)+ if err != nil || info.Mode().Perm() != permissions {+ t.Fatal("credential path is not private")+ }+ }+ content, err := os.ReadFile(file)+ if err != nil || (mode == "existing" && string(content) != "synthetic-existing-secret") {+ t.Fatal("existing credential was not preserved")+ }+ }+ if strings.Contains(output, "synthetic-existing-secret") {+ t.Fatal("preparation disclosed a credential")+ }+ })+ }+ }+}++func TestPBSAPIGuidanceRejectsUnsafeRecipesAndExactParent(t *testing.T) {+ blocks := pbsAPIGuidance(t)+ for name, edit := range map[string][2]string{+ "curl config": {"curl --disable ", "curl "}, "body disclosure": {`--output "$result_file" `, ""},+ "deadline": {"--max-time 15 ", ""}, "retry": {"curl --disable ", "curl --disable --retry 2 "},+ "redirect": {"curl --disable ", "curl --disable --location "}, "TLS bypass": {"curl --disable ", "curl --disable --insecure "},+ "inline token": {`"@$credential_file"`, `'Authorization: synthetic-inline-secret'`},+ "fail open": {"set -eu", ""}, "symlink": {`[ -L "$credential_file" ]`, "false"},+ "installer overwrite": {`mv -n "$download_file"`, `mv "$download_file"`},+ } {+ t.Run(name, func(t *testing.T) {+ changed := blocks+ for i, block := range changed {+ changed[i] = strings.ReplaceAll(block, edit[0], edit[1])+ }+ if pbsAPISafety(changed) == nil {+ t.Fatal("unsafe mutation was accepted")+ }+ })+ }+ if inputs := os.Getenv("PULSE_PROOF_INPUTS"); inputs != "" {+ parent, err := os.ReadFile(filepath.Join(inputs, "pbs-parent.md"))+ if os.IsNotExist(err) {+ return // Unrelated proof inputs do not require a PBS parent.+ }+ if err != nil {+ t.Fatal(err)+ }+ old, err := pbsAPIBlocks(string(parent))+ if err != nil {+ t.Fatal(err)+ }+ if err := pbsAPISafety(old); err == nil {+ t.Fatal("unchanged exact parent passed the new safety controls")+ } else {+ t.Logf("exact parent rejected: %s", err)+ }+ }+}++// Actual curl sees hostile local defaults and peers that echo a fixture token+// and identifying data. This proves copied transport/file safety, not native+// PBS permissions, installed collection, backup recovery or agent installation.+func TestPBSAPIGuidanceCopiedRequestsKeepSecretsPrivate(t *testing.T) {+ for index, recipe := range pbsAPIGuidance(t)[2:] {+ for _, scenario := range []string{"success", "401", "403", "redirect", "wrong success status", "untrusted HTTPS", "truncated installer", "existing installer", "symlinked header"} {+ if (index == 0 && scenario == "symlinked header") || (index == 1 && strings.Contains(scenario, "installer")) {+ continue+ }+ t.Run(fmt.Sprintf("%d/%s", index, scenario), func(t *testing.T) {+ recipe := recipe+ realCurl, err := exec.LookPath("curl")+ if err != nil {+ t.Fatal("curl is required to verify copied PBS guidance")+ }+ home := t.TempDir()+ bin := filepath.Join(home, "bin")+ dir := filepath.Join(home, ".config", "pulse")+ for _, path := range []string{bin, dir} {+ if err := os.MkdirAll(path, 0700); err != nil {+ t.Fatal(err)+ }+ }+ const token = "PBSAPIToken=pulse-monitor@pbs!pulse-token:synthetic-pbs-secret"+ const body = "synthetic-pbs-secret private-datastore-name"+ header := filepath.Join(dir, "pbs-header")+ if scenario == "symlinked header" {+ target := filepath.Join(home, "outside-header")+ if err := os.WriteFile(target, []byte("Authorization: "+token+"\n"), 0644); err != nil {+ t.Fatal(err)+ }+ if err := os.Symlink(target, header); err != nil {+ t.Fatal(err)+ }+ } else if err := os.WriteFile(header, []byte("Authorization: "+token+"\n"), 0600); err != nil {+ t.Fatal(err)+ }+ installer := filepath.Join(dir, "pbs-agent-install.sh")+ if scenario == "existing installer" {+ if err := os.WriteFile(installer, []byte("original-installer"), 0600); err != nil {+ t.Fatal(err)+ }+ }+ capture := filepath.Join(home, "argv")+ trace := filepath.Join(home, "must-not-trace")+ wrapper := "#!/bin/sh\nprintf '%s\\0' \"$@\" > \"$PBS_ARGV\"\nexec \"$PBS_CURL\" \"$@\"\n"+ if err := os.WriteFile(filepath.Join(bin, "curl"), []byte(wrapper), 0700); err != nil {+ t.Fatal(err)+ }+ if err := os.WriteFile(filepath.Join(home, ".curlrc"), []byte("insecure\nlocation\ntrace = "+trace+"\n"), 0600); err != nil {+ t.Fatal(err)+ }+ requests := make(chan string, 4)+ server := httptest.NewUnstartedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {+ requests <- strings.Join([]string{r.Method, r.URL.Path, r.Header.Get("Authorization")}, "\n")+ code := 200+ switch scenario {+ case "401":+ code = 401+ case "403":+ code = 403+ case "redirect":+ w.Header().Set("Location", "/must-not-follow")+ code = 307+ case "wrong success status":+ code = 206+ case "truncated installer":+ w.Header().Set("Content-Length", "1024")+ }+ w.WriteHeader(code)+ fmt.Fprint(w, body)+ }))+ server.Config.ErrorLog = log.New(io.Discard, "", 0)+ server.StartTLS()+ t.Cleanup(server.Close)+ originalURL := "https://pulse.example.com"+ if index == 1 {+ originalURL = "https://pbs.example.com:8007"+ }+ recipe = strings.Replace(recipe, originalURL, server.URL, 1)+ if scenario != "untrusted HTTPS" {+ ca := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: server.Certificate().Raw})+ if err := os.WriteFile(filepath.Join(home, "ca.pem"), ca, 0600); err != nil {+ t.Fatal(err)+ }+ recipe = strings.Replace(recipe, "curl --disable ", `curl --disable --cacert "$HOME/ca.pem" `, 1)+ }+ output, exit := runPBSRecipe(t, recipe, home, bin, "PBS_ARGV="+capture, "PBS_CURL="+realCurl)+ wantExit := 0+ switch scenario {+ case "401", "403":+ wantExit = 22+ case "untrusted HTTPS":+ wantExit = 60+ case "truncated installer":+ wantExit = 18+ case "redirect", "wrong success status", "existing installer", "symlinked header":+ wantExit = 1+ }+ if exit != wantExit {+ t.Fatalf("copied request exit %d, want %d: %s", exit, wantExit, output)+ }+ if strings.Contains(output, "synthetic-pbs-secret") || strings.Contains(output, "private-datastore-name") {+ t.Fatal("copied request disclosed a credential or response")+ }+ if _, err := os.Stat(trace); !os.IsNotExist(err) {+ t.Fatal("curl configuration enabled tracing")+ }+ if scenario == "existing installer" || scenario == "symlinked header" {+ if _, err := os.Stat(capture); !os.IsNotExist(err) || len(requests) != 0 {+ t.Fatal("unsafe local path reached curl")+ }+ path, expected := installer, "original-installer"+ if scenario == "symlinked header" {+ path, expected = filepath.Join(home, "outside-header"), "Authorization: "+token+"\n"+ }+ content, err := os.ReadFile(path)+ if err != nil || string(content) != expected {+ t.Fatal("refused local path modified existing content")+ }+ return+ }+ argv, err := os.ReadFile(capture)+ if err != nil || strings.Contains(string(argv), "synthetic-pbs-secret") || !strings.HasPrefix(string(argv), "--disable\x00") {+ t.Fatal("curl arguments disclosed credentials or did not disable local configuration first")+ }+ if !strings.Contains(output, "HTTP ") {+ t.Fatal("request failed to expose its safe HTTP result")+ }+ if scenario == "untrusted HTTPS" {+ if len(requests) != 0 {+ t.Fatal("untrusted TLS peer received a request")+ }+ } else {+ if len(requests) != 1 {+ t.Fatal("request was missing, redirected or retried")+ }+ path, auth := "/install.sh", ""+ if index == 1 {+ path, auth = "/api2/json/admin/datastore", token+ }+ if got := <-requests; got != strings.Join([]string{"GET", path, auth}, "\n") {+ t.Fatal("copied request used the wrong method, endpoint or credential")+ }+ }+ if index == 0 {+ content, err := os.ReadFile(installer)+ if scenario == "success" {+ info, statErr := os.Stat(installer)+ if err != nil || string(content) != body || statErr != nil || info.Mode().Perm() != 0600 {+ t.Fatal("successful installer was not saved completely and privately")+ }+ } else if !os.IsNotExist(err) {+ t.Fatal("failed or redirected download became an executable installer path")+ }+ } else {+ responses, err := filepath.Glob(filepath.Join(dir, "pbs-response.??????"))+ if err != nil || len(responses) != 1 {+ t.Fatal("request did not retain one new private response")+ }+ info, err := os.Stat(responses[0])+ if err != nil || info.Mode().Perm() != 0600 {+ t.Fatal("response file is not private")+ }+ if scenario != "untrusted HTTPS" {+ content, err := os.ReadFile(responses[0])+ if err != nil || string(content) != body {+ t.Fatal("complete sensitive response was not retained locally")+ }+ }+ }+ })+ }+ }+}