From 9305567fb45452b52bee1187579ad047c1297f86 Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:46:23 +0200 Subject: [PATCH 1/2] feat: install.sh that installs or updates pullgate from a checked release Refs #7 Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 20 +- AGENTS.md | 3 + DESIGN.md | 74 +- README.md | 39 +- THREAT-MODEL.md | 58 +- docs/releasing.md | 3 + install.sh | 695 +++++++++++++++++++ install_linux_test.go | 1421 ++++++++++++++++++++++++++++++++++++++ 8 files changed, 2306 insertions(+), 7 deletions(-) create mode 100644 install.sh create mode 100644 install_linux_test.go diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index af433a7..7c83e59 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -45,7 +45,8 @@ jobs: fi - run: go vet ./... # The tests need git. GitHub sets CI=true, and then a test fails - # instead of skips when git is missing. + # instead of skips when git is missing. The tests of install.sh + # (install_linux_test.go) run it against a fake release. - run: git --version - run: go test -race ./... - name: Build static binaries @@ -97,6 +98,23 @@ jobs: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false + - name: shellcheck install.sh + # A fixed release of ShellCheck, checked by its SHA-256. Dependabot + # does not update it. Update it by hand: the version and the SHA-256 + # of shellcheck-VERSION.linux.x86_64.tar.xz together. + env: + SHELLCHECK_VERSION: v0.11.0 + SHELLCHECK_SHA256: 8c3be12b05d5c177a04c29e3c78ce89ac86f1595681cab149b65b97c4e227198 + run: | + set -euo pipefail + dir="${RUNNER_TEMP}/shellcheck" + mkdir -p "$dir" + curl --proto '=https' --tlsv1.2 -fsSL --retry 3 -o "$dir/shellcheck.tar.xz" \ + "https://github.com/koalaman/shellcheck/releases/download/${SHELLCHECK_VERSION}/shellcheck-${SHELLCHECK_VERSION}.linux.x86_64.tar.xz" + echo "${SHELLCHECK_SHA256} $dir/shellcheck.tar.xz" | sha256sum --strict -c - + tar -xJf "$dir/shellcheck.tar.xz" -C "$dir" + "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --version + "$dir/shellcheck-${SHELLCHECK_VERSION}/shellcheck" --shell=sh install.sh - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 with: go-version-file: go.mod diff --git a/AGENTS.md b/AGENTS.md index 3171651..7aaddc6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,6 +27,9 @@ change code. They are the rules the code must follow. - `internal/gate/` - `run`, `apply` and `status` (DESIGN.md sections 7, 9, 10, 13). - `contrib/` - example systemd units and example configs. +- `install.sh` - installs or updates a release on a host, after its checks + (DESIGN.md section 16). Its tests are `install_linux_test.go`, at the + root. CI runs a pinned ShellCheck on it. - `test/e2e/` - the end-to-end test. Build tag `e2e`. - `docs/releasing.md` - how releases are made and checked. Only the owner merges a release pull request (`chore(main): release …`). diff --git a/DESIGN.md b/DESIGN.md index bbdbbea..1ef9968 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -568,8 +568,80 @@ bare repo with two commits, runs `pullgate run`, the listener against the fake Telegram server, a tap, `pullgate apply`, and checks that the second commit was applied. +The tests of `install.sh` (`install_linux_test.go`, at the root) run the +script with `/bin/sh` against a fake release: a fake `curl`, `uname`, `gh` +and `pullgate`. They never use the network. They show that the script +installs nothing when a check fails (section 16), and that it installs when +all checks pass. CI also runs a pinned ShellCheck on the script. + ## 15. Not in version 0.1 -- Self-update of pullgate. +- Self-update of pullgate. `install.sh` updates it only when root runs + the script (section 16). - Signed commits (`git verify-commit`). - A web UI. + +## 16. The install script + +`install.sh`, at the root of the repo, installs a release, or updates one. +It is a POSIX `sh` script. Root runs it on the host itself: + +```sh +sh install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall] +``` + +All the work is in functions. Only the last line starts `main`, so a +download that stops in the middle runs nothing. The steps: + +1. Clean the environment: remove `TAR_OPTIONS`, `GZIP`, `CURL_HOME`, the + `SSL_CERT_*`, `OPENSSL_*` and `LD_*` variables, `GCONV_PATH`, + `GLIBC_TUNABLES`, `GODEBUG`, `CDPATH`, `IFS` and more (the list and the + reasons are in `clean_env` of the script). Set `LC_ALL=C`. As root, set + `PATH=/usr/sbin:/usr/bin:/sbin:/bin`. pullgate and gh run with a time + limit (`timeout`): 60 seconds, and 300 seconds for + `gh attestation verify`. curl has its own limit. +2. Read the arguments. `--version` must be `X.Y.Z`. A wrong argument + exits with 64. +3. Check the platform: Linux on amd64 or arm64 only. +4. Check the paths: only root may change the bin directory + (default `/usr/local/bin`), each directory above it, the old binary and + the `--gh` file. The old binary `DIR/pullgate` must be a regular file or + missing, never a link. A directory that others can write may pass only + above the checked path, and only with the sticky bit (as `/tmp`). +5. Make a temporary directory with `mktemp -d` in `TMPDIR` (default + `/tmp`). Check `TMPDIR`, each directory above it, and the new directory. +6. Ask the GitHub API for the newest release, or for the release of + `--version`. Its tag must be `vX.Y.Z` of that version. +7. Run the old binary with `version`. The same version: nothing to do, + exit 0, unless `--reinstall`. A newer installed version: nothing to do, + unless `--version` asks for the older one; then it says that this is a + downgrade. An unknown version (`pullgate dev`, no output, or it does not + run): fail, unless `--reinstall`. +8. Download `pullgate__linux_.tar.gz`, `SHA256SUMS` and + `pullgate_.sigstore.json`. Every download uses + `curl -q --proto '=https' --tlsv1.2` and has a size limit: 1 MiB for the + API answer, `SHA256SUMS` and the bundle; 64 MiB for a tarball. +9. `SHA256SUMS` must have exactly one line for the tarball, and the SHA-256 + must match. +10. Get gh: the `--gh` file (gh 2.93.0 or newer), or gh 2.102.0, downloaded + and checked against the SHA-256 for this CPU that is written in the + script. gh runs with no token and an empty config. +11. Run `gh attestation verify` on the tarball with the bundle, + `--repo code6x/pullgate`, `--cert-identity + https://github.com/code6x/pullgate/.github/workflows/release.yml@refs/heads/main` + and `--deny-self-hosted-runners`. +12. Take only `pullgate` out of the tarball. Run `pullgate version` from the + temporary directory. It must print `pullgate X.Y.Z` of the version + asked for, and nothing else. +13. Copy it into the bin directory under a new name, mode 0755, owner + root. Run `pullgate version` there again. Write it to the disk + (`sync`), then rename it over the old binary. The rename is atomic: a + new process gets the old file or the new one. +14. Print what to restart. The script restarts nothing. + `pullgate-listen.service` runs the old binary until it is restarted. + The timers and path units start a new process each time, so they get + the new binary at their next start. + +A trap removes the temporary directory and a new file that was not renamed +yet, at every exit. A failure exits with 1, and its last line says that +nothing was installed. What the script trusts: THREAT-MODEL.md, T17. diff --git a/README.md b/README.md index e551696..3ade16c 100644 --- a/README.md +++ b/README.md @@ -41,17 +41,48 @@ path unit ─> pullgate apply NAME (root) ## Install -Download a release and check it as [docs/releasing.md](docs/releasing.md) -says (section "Verify a download"), or build it with Go 1.26 or newer: +pullgate runs on Linux, on amd64 or arm64. There are three ways to get the +binary. + +**With the install script** (as root, on the host itself). Download the +script, read it, then run it: + +```sh +curl --proto '=https' --tlsv1.2 -fsSL -o /root/install.sh https://raw.githubusercontent.com/code6x/pullgate/main/install.sh +less /root/install.sh +sh /root/install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall] +``` + +It installs the newest release, or the one of `--version`, as +`/usr/local/bin/pullgate` (or `DIR/pullgate`). It installs nothing unless +every check passes: the SHA-256 in `SHA256SUMS`, the build attestation of +the release (with `gh attestation verify`), and the version that the new +binary prints. It needs `curl`, `tar`, `gzip` and GNU coreutils. Without +`--gh`, it downloads a pinned gh and checks its SHA-256. It replaces the old +binary only in the last step, and restarts nothing: it prints what to +restart. Run it again to update. `--reinstall` installs the same version +again, or replaces a build of unknown version. Exit codes: 0 done or nothing +to do, 1 failure (nothing was installed), 64 wrong usage. To get the +script of one release, put its tag (`vX.Y.Z`) in the URL instead of `main`. +To start it with a clean environment, run it as +`env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin sh /root/install.sh`. What it does and +what it trusts: [DESIGN.md](DESIGN.md) section 16 and +[THREAT-MODEL.md](THREAT-MODEL.md) T17. + +**By hand.** Download a release and check it as +[docs/releasing.md](docs/releasing.md) says (section "Verify a download"). +Then, as root: `install -m 0755 pullgate /usr/local/bin/pullgate`. + +**From the source**, with Go 1.26 or newer. Then install it as above: ```sh CGO_ENABLED=0 go build -trimpath -o pullgate ./cmd/pullgate ``` -Then, as root: +Then, as root, make the users and the directories, and copy the units from +[contrib/systemd/](contrib/systemd/): ```sh -install -m 0755 pullgate /usr/local/bin/pullgate useradd --system --no-create-home --shell /usr/sbin/nologin pullgate # One check user per instance, never the listener user: useradd --system --no-create-home --shell /usr/sbin/nologin pullgate-check-config-repo diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index c8fbfe5..94cad07 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -39,6 +39,7 @@ on the host, out of reach of the repo. | the network | Not trusted. SSH with a pinned host key protects the fetch. | | other local users | Not trusted. | | the `apply` and `health` commands | Trusted: the owner wrote them. They run as root on the approved tree. | +| GitHub, the release workflow on `main`, and the gh that `install.sh` pins | Trusted to build and serve the release that `install.sh` installs (T16, T17). | ## 4. What pullgate promises @@ -299,7 +300,62 @@ move one, releases are immutable, and the `release` environment needs the owner's approval. The build job is read-only and checks that the tag is the commit of the run. Each tarball has a SHA-256 in `SHA256SUMS` and a build provenance attestation tied to `release.yml` on `main`. Check both before -you install (docs/releasing.md, "Verify a download"). +you install (docs/releasing.md, "Verify a download"), or let `install.sh` +check them (T17). + +### T17. A bad install path + +*Attack.* `install.sh` runs as root and puts a binary that root runs later. +An attacker tries to make it install a file that the release workflow did +not build, or an older build under a newer name. Or a local user changes a +file or a directory that the script uses while it runs. Or the +environment of root changes what `tar`, `curl` or `gh` do. + +*What the script trusts.* + +- **GitHub**: to serve the release files and the answer of its API over + HTTPS, and to run the release workflow on its own runners. +- **The release workflow identity**: only + `https://github.com/code6x/pullgate/.github/workflows/release.yml@refs/heads/main`, + on a runner that GitHub hosts, may have built the tarball. Sigstore's + public trusted root says whether the attestation is valid. +- **The pinned gh**: gh 2.102.0, checked against a SHA-256 for each CPU that + is written in the script. Or a gh that the owner gives with `--gh`: it + must be 2.93.0 or newer, and only root may change it. +- **The script itself**: the owner downloads it over HTTPS and reads it + before running it. +- **The host**: root, and the programs in `/usr/sbin:/usr/bin:/sbin:/bin`. + +*Defense.* (DESIGN.md section 16.) The script installs nothing unless every +check passes: exactly one line in `SHA256SUMS` for the tarball, and its +SHA-256 matches; `gh attestation verify` with the bundle of the release, +`--repo code6x/pullgate`, the identity above and +`--deny-self-hosted-runners`; the new binary prints `pullgate X.Y.Z` of the +version asked for. The attestation proves which workflow built a file, not +its version, so the version check stops an older build under a newer name. +The new binary runs only after the attestation passed. Every download has +a size limit, uses HTTPS only with TLS 1.2 or newer, and reads no +`.curlrc`. The script removes a list of variables that change `tar`, +`gzip`, `curl`, OpenSSL, gh, name lookups, libc and the dynamic loader, sets +`LC_ALL=C`, and as root uses a fixed `PATH`. pullgate and gh run with a time +limit (`timeout`), and curl has its own. It writes the new file to the disk before the rename. gh runs with no token and an empty config. Only root may +change the bin directory, the old binary, `TMPDIR`, the new temporary +directory and the `--gh` file, and each directory above them. The old +binary must be a regular file, never a link. The new file replaces the old +one by a rename in the same directory, as the last step. + +*What is left.* Whoever controls the release workflow on `main` (T16), or +GitHub itself, can ship a binary that passes. The script cannot check +itself: a changed copy of `install.sh` can do anything, so read it before +you run it. The list of removed variables is a block list: a variable that +is not on it, or one that acts before the first line runs (such as +`SHELLOPTS` when `sh` is bash), still reaches the programs. Who controls +root's environment controls root already; to be sure, start the script +with `env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin sh install.sh`. The proxy +variables stay on purpose: TLS and the attestation protect what comes +through a proxy. The old binary runs once, as root, to print its version; only +root can change it, so this gives nothing new to an attacker. The script +restarts nothing. ## 6. Out of scope diff --git a/docs/releasing.md b/docs/releasing.md index a01e1c2..55553f4 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -88,3 +88,6 @@ gh attestation verify "pullgate_${VERSION}_linux_${ARCH}.tar.gz" \ ``` Both checks must say OK before you install the binary. + +`install.sh` makes the same checks, and checks the version of the new +binary too (README.md, section "Install"). diff --git a/install.sh b/install.sh new file mode 100644 index 0000000..e6b0f20 --- /dev/null +++ b/install.sh @@ -0,0 +1,695 @@ +#!/bin/sh +# install.sh installs pullgate from a release on GitHub, or updates it. +# +# Run it as root on the host itself. README.md (section "Install") shows +# how to get and run it, DESIGN.md (section 16) says what it does, and +# THREAT-MODEL.md (T17) says what it trusts. +# +# sh install.sh [--version X.Y.Z] [--bin-dir DIR] [--gh PATH] [--reinstall] +# +# It installs nothing unless every check passes: +# - only root can change the bin directory, the old file, the temporary +# directory and the gh of --gh (when the script does not run as root, +# the user who runs it may too); +# - the release has the tag vX.Y.Z of the version; +# - the SHA-256 of the tarball is the one in SHA256SUMS of the release; +# - gh attestation verify, with the bundle file of the release, says that +# the release workflow of code6x/pullgate on main built the tarball, on +# a runner that GitHub hosts; +# - the new pullgate says that it is the version asked for. The +# attestation proves which workflow built a file, not its version, so +# this check stops an older build that was published under a newer +# name. +# +# All the work is in functions, and only the last line starts it. So if a +# download stops in the middle, nothing runs. +# +# Exit codes: 0 done or nothing to do, 1 failure, 64 wrong usage. + +set -eu + +# The gh that checks the attestation when --gh is not given, and the +# SHA-256 of its tarball for each CPU. The SHA-256s are the lines of +# gh_2.102.0_checksums.txt of that release, and both tarballs passed +# "gh attestation verify --repo cli/cli" on 2026-10-17. Change the version +# and both SHA-256s together, and check them in the same way. +gh_version=2.102.0 +gh_sha256_amd64=bb766f710eef8ede859c18578c72c327597cd4c8a85b06001b1f3843c6019386 +gh_sha256_arm64=7862c86c72f43df3a2d93ddde6f473285b4e2af61b494849846827e513ef6484 + +# The oldest gh that --gh may name. Older versions have known bugs in +# gh attestation verify (GHSA-fgw4-v983-mgp8, GHSA-8xvp-7hj6-mcj9). Newer +# advisories (GHSA-mm27-mwq9-fr5g, GHSA-wjmr-j3rp-mh2g, GHSA-4mq3-hpgx-9cx8) +# are about --signer-repo, --signer-workflow and --source-ref only, which +# this script does not use. +gh_min_version=2.93.0 + +repo=code6x/pullgate + +# Only the release workflow on main may have built the tarball. This is +# the identity of docs/releasing.md, "Verify a download". +cert_identity=https://github.com/code6x/pullgate/.github/workflows/release.yml@refs/heads/main + +# As root, the script runs only the programs of these directories. +root_path=/usr/sbin:/usr/bin:/sbin:/bin + +# Time limits, in seconds, of the programs that the script runs, other +# than curl (it has its own). timeout sends TERM, and KILL 10 seconds +# later. +max_run=60 # pullgate version, gh --version +max_verify=300 # gh attestation verify: it gets the trusted root of Sigstore online + +# Size limits of the downloads, in bytes. An older curl checks only the +# size that the server announces. +max_small=1048576 # 1 MiB: the answer of the API, SHA256SUMS, the bundle +max_big=67108864 # 64 MiB: the tarballs of pullgate and of gh + +usage() { + cat <&2 + exit 1 +} + +# usage_error prints the usage, and the last line says why the usage is +# wrong. It exits with 64. +usage_error() { + usage >&2 + printf 'pullgate: %s (exit 64)\n' "$*" >&2 + exit 64 +} + +# cleanup removes the temporary directory and a new file that was not +# renamed yet. It runs at every exit, also after a failure. It must return +# 0: under set -e, a failed trap would change the exit code. +cleanup() { + if [ -n "$tmp_target" ]; then + rm -f "$tmp_target" || : + fi + if [ -n "$tmp" ]; then + rm -rf "$tmp" || : + fi + return 0 +} + +# clean_env removes the variables that change what the programs of the +# script do in a way that is not safe here, sets LC_ALL=C, and sets uid. +# As root, PATH becomes root_path, so that only the programs of the system +# run. The variables: +# - TAR_OPTIONS: options for tar, such as --to-command or +# --checkpoint-action=exec, which run commands as root; +# - GZIP: options for gzip; +# - POSIXLY_CORRECT: changes how the GNU programs read their arguments; +# - CURL_HOME: where curl finds .curlrc (download gives curl -q too); +# - CURL_CA_BUNDLE, SSL_CERT_FILE, SSL_CERT_DIR: the TLS certificates +# that curl and gh trust; +# - SSLKEYLOGFILE: a file that curl writes the TLS keys to; +# - OPENSSL_CONF, OPENSSL_MODULES, OPENSSL_ENGINES: the config of +# OpenSSL, which curl reads at its start, and the places of the +# modules it loads. A config can name any library to load as a +# provider; +# - LD_PRELOAD, LD_LIBRARY_PATH, LD_AUDIT, GCONV_PATH: code that each +# program loads; +# - LD_DEBUG, LD_DEBUG_OUTPUT, LD_PROFILE, LD_PROFILE_OUTPUT, +# GLIBC_TUNABLES, MALLOC_TRACE, MALLOC_CHECK_, MALLOC_PERTURB_: files +# that the loader and libc write as root, and how they work; +# - HOSTALIASES, RES_OPTIONS, LOCALDOMAIN: how names are looked up; +# - GODEBUG: how gh, a Go program, works (for example its TLS); +# - GH_DEBUG, GH_PAGER, PAGER, GH_BROWSER, BROWSER: what gh prints and +# runs; +# - CDPATH and IFS: how cd finds a directory and how the shell splits +# words. +# The proxy variables (https_proxy and the others) stay: some hosts need a +# proxy, and TLS and the attestation protect what comes through it. +# Variables that act before the first line runs (for example SHELLOPTS +# when sh is bash) cannot be removed here. To start with a clean +# environment, run: env -i PATH=$root_path sh install.sh +clean_env() { + unset TAR_OPTIONS GZIP POSIXLY_CORRECT CURL_HOME CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR \ + SSLKEYLOGFILE OPENSSL_CONF OPENSSL_MODULES OPENSSL_ENGINES \ + LD_PRELOAD LD_LIBRARY_PATH LD_AUDIT GCONV_PATH \ + LD_DEBUG LD_DEBUG_OUTPUT LD_PROFILE LD_PROFILE_OUTPUT GLIBC_TUNABLES MALLOC_TRACE MALLOC_CHECK_ MALLOC_PERTURB_ \ + HOSTALIASES RES_OPTIONS LOCALDOMAIN GODEBUG GH_DEBUG GH_PAGER PAGER GH_BROWSER BROWSER CDPATH IFS + LC_ALL=C + export LC_ALL + uid=$( + PATH=$root_path + export PATH + id -u + ) || die "cannot run id -u; check that $root_path has the program id" + case $uid in + '' | *[!0-9]*) die "id -u does not print a user ID; check the program id in $root_path" ;; + esac + owners=root + if [ "$uid" = 0 ]; then + PATH=$root_path + export PATH + else + owners="root or user $uid" + fi +} + +# is_number reports whether $1 is a number of at most 9 digits, without a +# leading zero. +is_number() { + case $1 in + 0) return 0 ;; + '' | 0* | *[!0-9]* | ??????????*) return 1 ;; + esac + return 0 +} + +# is_version reports whether $1 is a version X.Y.Z: three numbers, and +# nothing else. +is_version() { + case $1 in + *.*.*.* | *[!0-9.]*) return 1 ;; + *.*.*) ;; + *) return 1 ;; + esac + v_rest=${1#*.} + is_number "${1%%.*}" && is_number "${v_rest%%.*}" && is_number "${v_rest#*.}" +} + +# compare_versions sets cmp to -1, 0 or 1 when the version $1 is older +# than, the same as, or newer than the version $2. Both must pass +# is_version, so each part is a small number. +compare_versions() { + cmp_a=$1 + cmp_b=$2 + cmp=0 + for _ in 1 2 3; do + if [ "${cmp_a%%.*}" -lt "${cmp_b%%.*}" ]; then + cmp=-1 + return 0 + fi + if [ "${cmp_a%%.*}" -gt "${cmp_b%%.*}" ]; then + cmp=1 + return 0 + fi + cmp_a=${cmp_a#*.} + cmp_b=${cmp_b#*.} + done +} + +# real_dir sets real to the path of the directory $1 without links, . or +# .. in it. The script then uses this path, so a link that someone changes +# later does not matter. +real_dir() { + real=$(cd -P -- "$1" && pwd -P) || die "cannot find the directory $1; check the path" +} + +# check_entry checks that only $owners can change the path $1: its owner +# must be one of them, and group and others must not be able to write to +# it. With $2 "shared", a directory may let them write when it has the +# sticky bit, as /tmp does: then they cannot rename or remove what is not +# theirs in it. +check_entry() { + ce_stat=$(stat -c '%u %a' "$1") || die "cannot read the owner and the mode of $1; check that it exists and that stat works" + ce_owner=${ce_stat%% *} + ce_mode=${ce_stat#* } + case $ce_owner$ce_mode in + '' | *[!0-9]*) die "cannot read the owner and the mode of $1; check that stat is GNU stat" ;; + esac + if [ "$ce_owner" != 0 ] && [ "$ce_owner" != "$uid" ]; then + die "$1 is owned by user $ce_owner; it must be owned by $owners (fix it with chown, or use another path)" + fi + if [ "$((0$ce_mode & 022))" != 0 ]; then + if [ "$2" != shared ] || [ ! -d "$1" ] || [ "$((0$ce_mode & 01000))" = 0 ]; then + die "group or others can write to $1; only $owners may (fix it with chmod go-w, or use another path)" + fi + fi +} + +# check_tree checks the absolute path $1 as check_entry does, with $2, and +# each directory above it, up to /, as shared. $1 must have no link, . or +# .. in it (real_dir). +check_tree() { + ct_path=$1 + check_entry "$ct_path" "$2" + while [ "$ct_path" != / ]; do + ct_path=${ct_path%/*} + if [ -z "$ct_path" ]; then + ct_path=/ + fi + check_entry "$ct_path" shared + done +} + +# parse_args reads the arguments into want_version, bin_dir, gh and +# reinstall. +parse_args() { + while [ "$#" -gt 0 ]; do + case $1 in + --version) + if [ "$#" -lt 2 ]; then + usage_error "--version needs a version, such as 0.2.0" + fi + if ! is_version "$2"; then + usage_error "--version must be X.Y.Z, such as 0.2.0" + fi + want_version=$2 + shift 2 + ;; + --bin-dir) + if [ "$#" -lt 2 ]; then + usage_error "--bin-dir needs a directory" + fi + bin_dir=$2 + shift 2 + ;; + --gh) + if [ "$#" -lt 2 ]; then + usage_error "--gh needs the path of gh" + fi + gh=$2 + shift 2 + ;; + --reinstall) + reinstall=1 + shift + ;; + --help | -h) + usage + exit 0 + ;; + *) + usage_error "unknown argument: $1" + ;; + esac + done + case $bin_dir in + /*) ;; + *) usage_error "--bin-dir must be an absolute path" ;; + esac + case $gh in + '' | /*) ;; + *) usage_error "--gh must be an absolute path" ;; + esac +} + +# check_platform checks that this is Linux on amd64 or arm64. +check_platform() { + os=$(uname -s) || die "cannot run uname -s; check that $root_path has the program uname" + if [ "$os" != Linux ]; then + die "pullgate runs on Linux only, and this is $os; run this on a Linux host" + fi + machine=$(uname -m) || die "cannot run uname -m; check that $root_path has the program uname" + case $machine in + x86_64 | amd64) + arch=amd64 + gh_sha256=$gh_sha256_amd64 + ;; + aarch64 | arm64) + arch=arm64 + gh_sha256=$gh_sha256_arm64 + ;; + *) + die "pullgate has releases for amd64 and arm64 only, and this machine is $machine; build it from the source (README.md, section Install)" + ;; + esac +} + +# check_paths checks, before anything is downloaded, the places that the +# script runs programs from and writes to: the bin directory, the old +# file, and the gh of --gh. The script runs the old file and the gh, and +# as root it must not run a file that another user can change. A link as +# the old file or as the gh is refused: name the file itself. +check_paths() { + if [ ! -d "$bin_dir" ]; then + die "$bin_dir is not a directory; make it, or give another --bin-dir" + fi + real_dir "$bin_dir" + bin_dir=$real + check_tree "$bin_dir" own + if [ ! -w "$bin_dir" ]; then + die "cannot write to $bin_dir; run this as root" + fi + target=$bin_dir/pullgate + if [ -L "$target" ]; then + die "$target is a link; the script replaces only a file (remove the link, or give another --bin-dir)" + fi + if [ -e "$target" ]; then + if [ ! -f "$target" ]; then + die "$target is not a file; remove it, or give another --bin-dir" + fi + check_entry "$target" own + fi + if [ -n "$gh" ]; then + if [ -L "$gh" ] || [ ! -f "$gh" ] || [ ! -x "$gh" ]; then + die "--gh $gh is not a program file; name the file itself, not a link" + fi + gh_dir=${gh%/*} + real_dir "${gh_dir:-/}" + gh=${real%/}/${gh##*/} + check_tree "$gh" own + fi +} + +# make_tmp makes the private temporary directory in TMPDIR, or /tmp. +# TMPDIR, and each directory above it, must be safe as check_tree says: +# else another user could swap a checked file in it for another one. The +# new directory itself must have the owner and mode 0700 that mktemp +# gives. The trap of main removes it. +make_tmp() { + real_dir "${TMPDIR:-/tmp}" + tmp_parent=$real + check_tree "$tmp_parent" shared + tmp=$(mktemp -d "$tmp_parent/pullgate-install.XXXXXXXX") || + die "cannot make a temporary directory in $tmp_parent; set TMPDIR to a directory that only root can write, such as /root" + check_entry "$tmp" own + tmp_fix="set TMPDIR to a directory that only root can write and where programs can run, such as /root" + mkdir "$tmp/home" "$tmp/gh" "$tmp/new" || die "cannot make directories in $tmp; check the free space in $tmp_parent" +} + +# download gets the URL $1 into the file $2, at most $3 bytes: HTTPS only, +# also after a redirect, with TLS 1.2 or newer, with retries and a time +# limit. An HTTP error is a failure. -q comes first, so curl reads no +# .curlrc. +download() { + curl -q --proto '=https' --proto-redir '=https' --tlsv1.2 --fail --silent --show-error --location \ + --retry 3 --connect-timeout 30 --max-time 600 --max-filesize "$3" --output "$2" "$1" /dev/null) || installed_out= + installed=${installed_out#pullgate } + if [ "pullgate $installed" != "$installed_out" ] || ! is_version "$installed"; then + installed= + fi + fi + if [ -z "$installed" ]; then + if [ -z "$reinstall" ]; then + die "$target has an unknown version (a build from the source, or it does not run); to replace it with pullgate $version, run this again with --reinstall" + fi + say "$target has an unknown version. pullgate $version will replace it, as --reinstall asks." + return 0 + fi + compare_versions "$version" "$installed" + case $cmp in + 0) + if [ -z "$reinstall" ]; then + say "$target says that it is pullgate $version already. Nothing to do." + say "This did not check the installed file. To replace it with a checked copy, run this again with --reinstall." + exit 0 + fi + say "Installing pullgate $version again as $target, as --reinstall asks." + ;; + 1) + say "Updating $target from pullgate $installed to pullgate $version." + ;; + *) + if [ -z "$want_version" ]; then + say "$target says that it is pullgate $installed, which is newer than $version, the newest release. Nothing to do." + say "This did not check the installed file. To install $version anyway, run this again with --version $version." + exit 0 + fi + say "This is a downgrade: replacing pullgate $installed with the older pullgate $version, as --version asks." + ;; + esac +} + +# download_release gets the tarball for this machine, SHA256SUMS and the +# bundle of the build attestation. +download_release() { + tarball=pullgate_${version}_linux_${arch}.tar.gz + bundle=pullgate_${version}.sigstore.json + base=https://github.com/$repo/releases/download/v$version + say "Downloading $tarball, SHA256SUMS and $bundle." + download "$base/$tarball" "$tmp/$tarball" "$max_big" || die "cannot download $base/$tarball; check the network and try again" + download "$base/SHA256SUMS" "$tmp/SHA256SUMS" "$max_small" || die "cannot download $base/SHA256SUMS; check the network and try again" + download "$base/$bundle" "$tmp/$bundle" "$max_small" || die "cannot download $base/$bundle; check the network and try again" +} + +# check_sha256 checks the SHA-256 of the tarball against its own line in +# SHA256SUMS. There must be exactly one such line. It finds a broken +# download early. It proves nothing about who built the file: whoever can +# publish a release can publish its SHA256SUMS too. The attestation proves +# that. +check_sha256() { + want= + while read -r line_sum line_name || [ -n "$line_sum" ]; do + if [ "$line_name" = "$tarball" ] || [ "$line_name" = "*$tarball" ]; then + if [ -n "$want" ]; then + die "SHA256SUMS of the release has more than one line for $tarball; do not use this release, and report it at https://github.com/$repo/issues" + fi + want=$line_sum + fi + done <"$tmp/SHA256SUMS" + if [ -z "$want" ]; then + die "SHA256SUMS of the release has no line for $tarball; do not use this release, and report it at https://github.com/$repo/issues" + fi + sha256_of "$tmp/$tarball" + if [ "$file_sha256" != "$want" ]; then + die "the SHA-256 of $tarball is not the one in SHA256SUMS; the download is broken or changed, try again later" + fi +} + +# get_gh sets gh to the gh that checks the attestation: the one of --gh, +# which check_paths checked, or gh $gh_version, downloaded and checked +# against the SHA-256 in this script. It must be $gh_min_version or newer: +# the first line of gh --version must be "gh version X.Y.Z", then a space +# or nothing, so a version such as 2.93.0-rc.1 does not count. +get_gh() { + gh_hint=" (check that $gh runs here and is gh $gh_min_version or newer)" + if [ -z "$gh" ]; then + gh_hint=" (if programs cannot run in $tmp_parent, use --gh, or $tmp_fix)" + gh_tarball=gh_${gh_version}_linux_${arch}.tar.gz + say "Downloading gh $gh_version to check the attestation." + download "https://github.com/cli/cli/releases/download/v$gh_version/$gh_tarball" "$tmp/$gh_tarball" "$max_big" || + die "cannot download $gh_tarball; check the network, or give a gh with --gh" + sha256_of "$tmp/$gh_tarball" + if [ "$file_sha256" != "$gh_sha256" ]; then + die "the SHA-256 of $gh_tarball is not the one in this script; give a gh with --gh" + fi + tar --no-same-owner -xzf "$tmp/$gh_tarball" -C "$tmp/gh" "gh_${gh_version}_linux_${arch}/bin/gh" /dev/null || sync || die "cannot write $tmp_target to the disk; check the disk" + mv -f "$tmp_target" "$target" || die "cannot rename the new file to $target; check that $bin_dir is not read-only" + tmp_target= + sync -- "$bin_dir" 2>/dev/null || sync || : +} + +# print_restart prints what the new file says, and what to restart. It +# restarts nothing. +print_restart() { + if done_out=$(limited "$max_run" "$target" version >"$FAKE_LOGS/curl" +out= +max= +url= +while [ "$#" -gt 0 ]; do + case $1 in + --output) + out=$2 + shift + ;; + --max-filesize) + max=$2 + shift + ;; + esac + url=$1 + shift +done +case $url in +https://*) ;; +*) + echo "fake curl: not HTTPS: $url" >&2 + exit 1 + ;; +esac +file=$FAKE_WEB/${url#https://} +if [ ! -f "$file" ]; then + echo "curl: (22) The requested URL returned error: 404" >&2 + exit 22 +fi +if [ -n "$max" ] && [ "$(wc -c <"$file")" -gt "$max" ]; then + echo "curl: (63) Maximum file size exceeded" >&2 + exit 63 +fi +cp "$file" "$out" +` + +const fakeUname = `#!/bin/sh +# A fake uname: the system and the CPU of the test. +case $1 in +-s) echo "${FAKE_UNAME_S:-Linux}" ;; +-m) echo "${FAKE_UNAME_M:-x86_64}" ;; +*) exit 1 ;; +esac +` + +const fakeGh = `#!/bin/sh +# A fake gh. It writes down each call, one a line, its own path, and the +# environment of each kind of call. For --version, it prints the version +# $FAKE_GH_VERSION, or exits with $FAKE_GH_VERSION_EXIT. For attestation +# verify, it writes down its arguments, keeps a copy of the file and of the +# bundle to check, and exits with $FAKE_GH_EXIT. With $FAKE_GH_WAIT, it +# makes that file instead, and waits. +printf '%s\n' "$*" >>"$FAKE_LOGS/gh" +printf '%s\n' "$0" >"$FAKE_LOGS/gh-path" +env >"$FAKE_LOGS/gh-env-$1" +if [ "$1" = --version ]; then + if [ -n "${FAKE_GH_VERSION_EXIT:-}" ]; then + exit "$FAKE_GH_VERSION_EXIT" + fi + echo "gh version ${FAKE_GH_VERSION:-2.102.0} (2026-09-30)" + echo "https://github.com/cli/cli/releases/tag/v${FAKE_GH_VERSION:-2.102.0}" + exit 0 +fi +printf '%s\n' "$@" >"$FAKE_LOGS/gh-args" +cp "$3" "$FAKE_LOGS/gh-file" || exit 2 +cp "$5" "$FAKE_LOGS/gh-bundle" || exit 2 +if [ -n "${FAKE_GH_WAIT:-}" ]; then + : >"$FAKE_GH_WAIT" + exec sleep 60 +fi +exit "${FAKE_GH_EXIT:-0}" +` + +// fakePullgate returns a fake pullgate. "pullgate version" prints the +// lines. The note tells copies apart, such as the CPU of a tarball. Each +// run writes the note to $FAKE_LOGS/pullgate-runs, and the note and the +// directory of the file to $FAKE_LOGS/pullgate-dirs, so a test can see +// which copies ran, and where. +func fakePullgate(note string, lines ...string) []byte { + return fmt.Appendf(nil, "#!/bin/sh\n# A fake pullgate (%s).\necho '%s' >>\"$FAKE_LOGS/pullgate-runs\"\n"+ + "echo \"%s ${0%%/*}\" >>\"$FAKE_LOGS/pullgate-dirs\"\n"+ + "if [ \"$1\" = version ]; then\n\tprintf '%%s\\n' '%s'\nfi\n", + note, note, note, strings.Join(lines, "' '")) +} + +// failingPullgate is a fake pullgate that does not run. +var failingPullgate = []byte("#!/bin/sh\necho 'cannot run' >&2\nexit 1\n") + +// says returns the fake pullgate of each CPU of a release, for +// installer.release. +func says(lines ...string) func(arch string) []byte { + return func(arch string) []byte { return fakePullgate(arch, lines...) } +} + +// tarFile is a file in a tarball of tarGz. +type tarFile struct { + name string + mode int64 + data []byte +} + +// tarGz returns a tar.gz file with these files. +func tarGz(t *testing.T, files ...tarFile) []byte { + t.Helper() + var buf bytes.Buffer + gz := gzip.NewWriter(&buf) + tw := tar.NewWriter(gz) + for _, f := range files { + hdr := &tar.Header{Name: f.name, Mode: f.mode, Size: int64(len(f.data)), ModTime: time.Unix(1_760_000_000, 0)} + if err := tw.WriteHeader(hdr); err != nil { + t.Fatal(err) + } + if _, err := tw.Write(f.data); err != nil { + t.Fatal(err) + } + } + if err := tw.Close(); err != nil { + t.Fatal(err) + } + if err := gz.Close(); err != nil { + t.Fatal(err) + } + return buf.Bytes() +} + +// installer runs install.sh against fakes. +type installer struct { + t *testing.T + dir string // the working directory of the script + script string // the path of the script + web string // the files of the fake GitHub + bin string // the directory of --bin-dir + tmp string // TMPDIR of the script: it must be empty after each run + logs string // what the fake programs write down + fakes string // the fake curl and uname, first in PATH + gh string // the fake gh, for --gh + binArg string // the value of --bin-dir, if it is not bin + env []string // more environment for the script +} + +func newInstaller(t *testing.T) *installer { + t.Helper() + if os.Geteuid() == 0 { + t.Skip("as root, install.sh runs only the programs of the system, not the fakes of the test") + } + for _, name := range []string{"sed", "tar", "gzip", "sha256sum", "install", "mktemp", "id", "stat", "cp", "env", "wc", "sleep", "timeout", "sync"} { + if _, err := exec.LookPath(name); err != nil { + skipOrFail(t, "%s is not installed", name) + } + } + script, err := filepath.Abs("install.sh") + if err != nil { + t.Fatal(err) + } + // The script refuses a directory that group or others can write to. + // Under a umask such as 002, t.TempDir is one. + dir := privateDir(t) + in := &installer{ + t: t, + dir: dir, + script: script, + web: filepath.Join(dir, "web"), + bin: filepath.Join(dir, "bin"), + tmp: filepath.Join(dir, "tmp"), + logs: filepath.Join(dir, "logs"), + fakes: filepath.Join(dir, "fakes"), + gh: filepath.Join(dir, "gh"), + } + for _, d := range []string{in.web, in.bin, in.tmp, in.logs, in.fakes} { + mkdir(t, d, 0o700) + } + writeFile(t, filepath.Join(in.fakes, "curl"), []byte(fakeCurl), 0o700) + writeFile(t, filepath.Join(in.fakes, "uname"), []byte(fakeUname), 0o700) + writeFile(t, in.gh, []byte(fakeGh), 0o700) + if exec.CommandContext(t.Context(), filepath.Join(in.fakes, "uname"), "-s").Run() != nil { + skipOrFail(t, "a program in the temporary directory %s cannot run", dir) + } + return in +} + +// privateDir returns a new temporary directory with mode 0700, by its path +// without links: the script prints such paths. +func privateDir(t *testing.T) string { + t.Helper() + dir, err := filepath.EvalSymlinks(t.TempDir()) + if err != nil { + t.Fatal(err) + } + if err := os.Chmod(dir, 0o700); err != nil { + t.Fatal(err) + } + return dir +} + +// mkdir makes the directory path with exactly mode. +func mkdir(t *testing.T, path string, mode os.FileMode) { + t.Helper() + if err := os.Mkdir(path, 0o700); err != nil { + t.Fatal(err) + } + if err := os.Chmod(path, mode); err != nil { + t.Fatal(err) + } +} + +// releaseJSON is the answer of the fake GitHub API for a release, in the +// form of the real one. +func releaseJSON(tag string) []byte { + return fmt.Appendf(nil, "{\n \"url\": \"https://api.github.com/repos/code6x/pullgate/releases/1\",\n"+ + " \"tag_name\": %q,\n \"name\": %q,\n \"draft\": false\n}\n", tag, tag) +} + +// latest makes tag the newest release on the fake GitHub API. +func (in *installer) latest(tag string) { + in.serve(latestPath, releaseJSON(tag)) +} + +// release puts a release on the fake GitHub: its answer of the API, for +// each CPU a tarball with pullgate, LICENSE and README.md, and SHA256SUMS +// and the bundle. pullgate returns the file pullgate of each CPU. +func (in *installer) release(version string, pullgate func(arch string) []byte) { + in.serve(tagPath+version, releaseJSON("v"+version)) + var sums strings.Builder + for _, arch := range []string{"amd64", "arm64"} { + name := "pullgate_" + version + "_linux_" + arch + ".tar.gz" + data := tarGz(in.t, + tarFile{"pullgate", 0o755, pullgate(arch)}, + tarFile{"LICENSE", 0o644, []byte("a made-up license\n")}, + tarFile{"README.md", 0o644, []byte("# a made-up readme\n")}) + in.serve(releasePath+version+"/"+name, data) + fmt.Fprintf(&sums, "%x %s\n", sha256.Sum256(data), name) + } + in.serve(releasePath+version+"/SHA256SUMS", []byte(sums.String())) + in.serve(releasePath+version+"/pullgate_"+version+".sigstore.json", []byte(bundle(version))) +} + +// bundle is the made-up bundle of a release. +func bundle(version string) string { + return `{"mediaType": "application/vnd.dev.sigstore.bundle.v0.3+json", "release": "` + version + `"}` + "\n" +} + +// ghRelease puts a tarball of gh 2.102.0 for amd64 on the fake GitHub, +// with the fake gh in it. It returns the SHA-256 of the tarball, in hex. +func (in *installer) ghRelease() string { + data := tarGz(in.t, + tarFile{"gh_2.102.0_linux_amd64/LICENSE", 0o644, []byte("a made-up license\n")}, + tarFile{"gh_2.102.0_linux_amd64/bin/gh", 0o755, []byte(fakeGh)}) + in.serve(ghPath+"2.102.0/gh_2.102.0_linux_amd64.tar.gz", data) + return fmt.Sprintf("%x", sha256.Sum256(data)) +} + +// serve puts a file at https://path on the fake GitHub. +func (in *installer) serve(path string, data []byte) { + in.t.Helper() + file := filepath.Join(in.web, filepath.FromSlash(path)) + if err := os.MkdirAll(filepath.Dir(file), 0o700); err != nil { + in.t.Fatal(err) + } + writeFile(in.t, file, data, 0o600) +} + +// unserve removes the file at https://path from the fake GitHub. +func (in *installer) unserve(path string) { + in.t.Helper() + if err := os.Remove(filepath.Join(in.web, filepath.FromSlash(path))); err != nil { + in.t.Fatal(err) + } +} + +// installed makes data the installed pullgate. +func (in *installer) installed(data []byte) { + writeFile(in.t, filepath.Join(in.bin, "pullgate"), data, 0o755) +} + +// result is the end of a run of the script. +type result struct { + code int + stdout, stderr string +} + +// run runs the script with the arguments. +func (in *installer) run(args ...string) result { + in.t.Helper() + return runCmd(in.t, in.command(args...)) +} + +// runCmd runs cmd, and returns its exit code and output. +func runCmd(t *testing.T, cmd *exec.Cmd) result { + t.Helper() + var stdout, stderr bytes.Buffer + cmd.Stdout, cmd.Stderr = &stdout, &stderr + err := cmd.Run() + var exit *exec.ExitError + if err != nil && !errors.As(err, &exit) { + t.Fatalf("cannot run %s: %v", cmd.Path, err) + } + return result{cmd.ProcessState.ExitCode(), stdout.String(), stderr.String()} +} + +// command returns the command that runs the script with --bin-dir of the +// test and then args, with stdin from /dev/null. A --bin-dir in args +// comes later, so it counts. +func (in *installer) command(args ...string) *exec.Cmd { + bin := in.bin + if in.binArg != "" { + bin = in.binArg + } + cmd := exec.CommandContext(in.t.Context(), "/bin/sh", append([]string{in.script, "--bin-dir", bin}, args...)...) + cmd.Dir = in.dir + cmd.Env = append([]string{ + "PATH=" + in.fakes + string(os.PathListSeparator) + os.Getenv("PATH"), + "HOME=" + in.dir, + "TMPDIR=" + in.tmp, + "FAKE_WEB=" + in.web, + "FAKE_LOGS=" + in.logs, + }, in.env...) + return cmd +} + +// files returns the mode and the content of each file in dir, by name: a +// link has its target, and a directory or another kind of file has only +// its mode. +func files(t *testing.T, dir string) map[string]string { + t.Helper() + entries, err := os.ReadDir(dir) + if err != nil { + t.Fatal(err) + } + got := map[string]string{} + for _, e := range entries { + info, err := e.Info() + if err != nil { + t.Fatal(err) + } + path := filepath.Join(dir, e.Name()) + got[e.Name()] = info.Mode().String() + switch { + case info.Mode().IsRegular(): + got[e.Name()] += " " + string(readFile(t, path)) + case info.Mode()&fs.ModeSymlink != 0: + target, err := os.Readlink(path) + if err != nil { + t.Fatal(err) + } + got[e.Name()] += " -> " + target + } + } + return got +} + +// checkTmpGone checks that the temporary directory of the script is gone. +func (in *installer) checkTmpGone() { + in.t.Helper() + if left := files(in.t, in.tmp); len(left) != 0 { + in.t.Errorf("the temporary directory is still there: %v", slices.Sorted(maps.Keys(left))) + } +} + +// checkFailed checks a run that must fail with code and a last line that +// holds want, and that it changed nothing in the bin directory. +func (in *installer) checkFailed(r result, code int, want string, before map[string]string) { + in.t.Helper() + end := " (exit " + strconv.Itoa(code) + ")\n" + if code == 1 { + end = "; nothing was installed" + end + } + last := lastLine(r.stderr) + if r.code != code || !strings.HasPrefix(last, "pullgate: ") || !strings.Contains(last, want) || !strings.HasSuffix(last, end) { + in.t.Errorf("exit code %d, last line %q; want %d and a line with %q and %q\nstdout:\n%s\nstderr:\n%s", + r.code, last, code, want, end, r.stdout, r.stderr) + } + if after := files(in.t, in.bin); !maps.Equal(after, before) { + in.t.Errorf("the bin directory changed: %v, before %v", slices.Sorted(maps.Keys(after)), slices.Sorted(maps.Keys(before))) + } + in.checkTmpGone() +} + +// curlCalls returns the arguments of each call of curl. +func (in *installer) curlCalls() [][]string { + in.t.Helper() + var calls [][]string + for _, line := range in.log("curl") { + calls = append(calls, strings.Fields(line)) + } + return calls +} + +// urls returns the URL of each call of curl, in order. +func (in *installer) urls() []string { + in.t.Helper() + var urls []string + for _, call := range in.curlCalls() { + urls = append(urls, call[len(call)-1]) + } + return urls +} + +// log returns the lines that a fake wrote to the log name, or none. +func (in *installer) log(name string) []string { + in.t.Helper() + data, err := os.ReadFile(filepath.Join(in.logs, name)) + if errors.Is(err, fs.ErrNotExist) { + return nil + } + if err != nil { + in.t.Fatal(err) + } + return strings.Split(strings.TrimSuffix(string(data), "\n"), "\n") +} + +// ghChecked reports whether gh attestation verify ran. +func (in *installer) ghChecked() bool { + return in.log("gh-args") != nil +} + +// releaseURLs are the URLs of the files of a release, for amd64. +func releaseURLs(version string) []string { + base := "https://" + releasePath + version + "/" + return []string{base + "pullgate_" + version + "_linux_amd64.tar.gz", base + "SHA256SUMS", base + "pullgate_" + version + ".sigstore.json"} +} + +const latestURL = "https://" + latestPath + +// tagURL is the URL of the API for the release of version. +func tagURL(version string) string { return "https://" + tagPath + version } + +// TestInstall installs a release where no pullgate is, when every check +// passes, and checks how the script ran curl, gh and the new pullgate. +func TestInstall(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + // Tokens, a host and other places for the config of gh: none of them + // may reach gh. + token := "made-up-token-" + rand.Text() + for _, name := range tokenVars { + in.env = append(in.env, name+"="+token) + } + in.env = append(in.env, "GH_CONFIG_DIR=/nonexistent/gh", "XDG_CONFIG_HOME=/nonexistent/config", + "XDG_CACHE_HOME=/nonexistent/cache", "XDG_DATA_HOME=/nonexistent/data", "XDG_STATE_HOME=/nonexistent/state") + // Variables that change what the programs do: the script removes + // them. Through TAR_OPTIONS, tar would run a command. + ran := filepath.Join(in.dir, "tar-ran-a-command") + in.env = append(in.env, "TAR_OPTIONS=--checkpoint=1 --checkpoint-action=exec=touch "+ran, "LC_ALL=de_DE.UTF-8") + for _, name := range unsafeVars { + in.env = append(in.env, name+"=/nonexistent/made-up") + } + + r := in.run("--gh", in.gh) + if r.code != 0 { + t.Fatalf("exit code %d\nstdout:\n%s\nstderr:\n%s", r.code, r.stdout, r.stderr) + } + // Only pullgate of amd64 is in the bin directory, with mode 0755. + want := map[string]string{"pullgate": "-rwxr-xr-x " + string(fakePullgate("amd64", "pullgate 0.2.0"))} + if got := files(t, in.bin); !maps.Equal(got, want) { + t.Errorf("the bin directory holds %q, want %q", got, want) + } + in.checkTmpGone() + for _, s := range []string{"Installing pullgate 0.2.0 as " + in.bin + "/pullgate.", "version says: pullgate 0.2.0", + "This script restarts nothing.", "systemctl restart pullgate-listen.service", "pullgate-run@NAME.timer", + "pullgate-apply@NAME.path"} { + if !strings.Contains(r.stdout, s) { + t.Errorf("stdout does not say %q:\n%s", s, r.stdout) + } + } + if _, err := os.Lstat(ran); err == nil { + t.Error("tar ran the command of TAR_OPTIONS") + } + + // curl: the newest release, then the files of the release, each with + // no .curlrc, over HTTPS only, with TLS 1.2 or newer, failing on an + // HTTP error, with retries, a time limit and a size limit. + wantURLs := append([]string{latestURL}, releaseURLs("0.2.0")...) + if got := in.urls(); !slices.Equal(got, wantURLs) { + t.Errorf("curl got the URLs\n%q\nwant\n%q", got, wantURLs) + } + for i, call := range in.curlCalls() { + if call[0] != "-q" { + t.Errorf("a call of curl does not start with -q, so curl reads .curlrc: %q", call) + } + limit := maxSmall + if strings.HasSuffix(call[len(call)-1], ".tar.gz") { + limit = maxBig + } + for _, want := range [][]string{{"--proto", "=https"}, {"--proto-redir", "=https"}, {"--tlsv1.2"}, {"--fail"}, + {"--retry", "3"}, {"--max-time", "600"}, {"--max-filesize", limit}} { + if !slices.ContainsFunc(windows(call, len(want)), func(w []string) bool { return slices.Equal(w, want) }) { + t.Errorf("call %d of curl has no %q: %q", i, want, call) + } + } + } + + // gh: its version, then the check with the identity of + // docs/releasing.md, of the file that the script downloaded. + if got, want := in.log("gh"), []string{"--version", "attestation verify"}; len(got) != 2 || got[0] != want[0] || !strings.HasPrefix(got[1], want[1]) { + t.Fatalf("calls of gh: %q, want --version and then attestation verify", got) + } + args := in.log("gh-args") + if len(args) < 3 { + t.Fatalf("gh got %q", args) + } + tmp := filepath.Dir(args[2]) // the temporary directory of the script + if filepath.Dir(tmp) != in.tmp || !strings.HasPrefix(filepath.Base(tmp), "pullgate-install.") { + t.Errorf("gh checked %s, not a file in a new directory in TMPDIR %s", args[2], in.tmp) + } + wantArgs := []string{"attestation", "verify", filepath.Join(tmp, "pullgate_0.2.0_linux_amd64.tar.gz"), + "--bundle", filepath.Join(tmp, "pullgate_0.2.0.sigstore.json"), + "--repo", "code6x/pullgate", "--cert-identity", certIdentity, "--deny-self-hosted-runners"} + if !slices.Equal(args, wantArgs) { + t.Errorf("gh got the arguments\n%q\nwant\n%q", args, wantArgs) + } + served := readFile(t, filepath.Join(in.web, releasePath+"0.2.0", "pullgate_0.2.0_linux_amd64.tar.gz")) + if checked := readFile(t, filepath.Join(in.logs, "gh-file")); !bytes.Equal(checked, served) { + t.Error("gh checked another file than the tarball of the release") + } + if checked := readFile(t, filepath.Join(in.logs, "gh-bundle")); string(checked) != bundle("0.2.0") { + t.Errorf("gh checked with the bundle %q, want %q", checked, bundle("0.2.0")) + } + + // The new pullgate ran first from the temporary directory, then as the + // new file in the bin directory before the rename, and then as the + // installed file. + wantDirs := []string{"amd64 " + filepath.Join(tmp, "new"), "amd64 " + in.bin, "amd64 " + in.bin} + if got := in.log("pullgate-dirs"); !slices.Equal(got, wantDirs) { + t.Errorf("the new pullgate ran in\n%q\nwant\n%q", got, wantDirs) + } + + // The environment of gh, for both calls: no token and no host, its + // home, config and XDG directories in the temporary directory, no + // update notices, prompts or telemetry, LC_ALL=C, and none of the + // unsafe variables. + for _, call := range []string{"--version", "attestation"} { + env := readEnv(t, filepath.Join(in.logs, "gh-env-"+call)) + for _, name := range append(slices.Clone(tokenVars), append([]string{"TAR_OPTIONS"}, unsafeVars...)...) { + if v, ok := env[name]; ok { + t.Errorf("gh %s got %s (%d bytes)", call, name, len(v)) + } + } + for name, value := range env { + if strings.Contains(value, token) { + t.Errorf("gh %s got the token in %s", call, name) + } + } + if env["HOME"] != filepath.Join(tmp, "home") { + t.Errorf("gh %s got HOME=%q, want %q", call, env["HOME"], filepath.Join(tmp, "home")) + } + for _, name := range []string{"GH_CONFIG_DIR", "XDG_CONFIG_HOME", "XDG_CACHE_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME"} { + if !strings.HasPrefix(env[name], tmp+"/") { + t.Errorf("gh %s got %s=%q, want a directory in %s", call, name, env[name], tmp) + } + } + for name, want := range map[string]string{"GH_NO_UPDATE_NOTIFIER": "1", "GH_NO_EXTENSION_UPDATE_NOTIFIER": "1", + "GH_PROMPT_DISABLED": "1", "GH_TELEMETRY": "false", "LC_ALL": "C"} { + if env[name] != want { + t.Errorf("gh %s got %s=%q, want %q", call, name, env[name], want) + } + } + } +} + +// TestInstallReplaces replaces an installed pullgate: an older version, +// one whose version is not known with --reinstall, the same one with +// --reinstall, and with --version an older one (a downgrade). It also +// installs with paths that the script takes as safe. +func TestInstallReplaces(t *testing.T) { + all := append([]string{latestURL}, releaseURLs("0.2.0")...) + for _, tt := range []struct { + name string + installed []byte // the pullgate that is installed before + setup func(in *installer) // more changes before the run + args []string // after --gh + arch string // the CPU of the tarball that must be installed + say string // a part of stdout + urls []string // what curl gets + }{ + {name: "an older version", installed: fakePullgate("installed", "pullgate 0.1.0"), arch: "amd64", + say: "Updating BIN/pullgate from pullgate 0.1.0 to pullgate 0.2.0.", urls: all}, + {name: "a build from the source, with --reinstall", installed: fakePullgate("installed", "pullgate dev"), + args: []string{"--reinstall"}, arch: "amd64", + say: "BIN/pullgate has an unknown version. pullgate 0.2.0 will replace it, as --reinstall asks.", urls: all}, + {name: "a file that prints nothing, with --reinstall", installed: []byte("#!/bin/sh\n"), + args: []string{"--reinstall"}, arch: "amd64", say: "has an unknown version", urls: all}, + {name: "a file that does not run, with --reinstall", installed: failingPullgate, + args: []string{"--reinstall"}, arch: "amd64", say: "has an unknown version", urls: all}, + {name: "the same version, with --reinstall", installed: fakePullgate("installed", "pullgate 0.2.0"), + args: []string{"--reinstall"}, arch: "amd64", + say: "Installing pullgate 0.2.0 again as BIN/pullgate, as --reinstall asks.", urls: all}, + {name: "a downgrade, with --version", installed: fakePullgate("installed", "pullgate 0.3.0"), + args: []string{"--version", "0.2.0"}, arch: "amd64", + say: "This is a downgrade: replacing pullgate 0.3.0 with the older pullgate 0.2.0, as --version asks.", + urls: append([]string{tagURL("0.2.0")}, releaseURLs("0.2.0")...)}, + {name: "on arm64", setup: env("FAKE_UNAME_M=aarch64"), arch: "arm64", say: "Installing pullgate 0.2.0", + urls: []string{latestURL, "https://" + releasePath + "0.2.0/pullgate_0.2.0_linux_arm64.tar.gz", + "https://" + releasePath + "0.2.0/SHA256SUMS", "https://" + releasePath + "0.2.0/pullgate_0.2.0.sigstore.json"}}, + {name: "on amd64, when uname -m says amd64", setup: env("FAKE_UNAME_M=amd64"), arch: "amd64", + say: "Installing pullgate 0.2.0", urls: all}, + {name: "with gh 2.93.0, the oldest that counts", setup: env("FAKE_GH_VERSION=2.93.0"), arch: "amd64", + say: "with gh 2.93.0.", urls: all}, + // A directory with the sticky bit, as /tmp, may let others write. + {name: "a TMPDIR with the sticky bit", setup: func(in *installer) { + in.tmp = filepath.Join(in.dir, "shared-tmp") + mkdir(in.t, in.tmp, 0o777|os.ModeSticky) + }, arch: "amd64", say: "Installing pullgate 0.2.0", urls: all}, + {name: "a bin directory in a directory with the sticky bit", setup: func(in *installer) { + mkdir(in.t, filepath.Join(in.dir, "shared"), 0o777|os.ModeSticky) + in.bin = filepath.Join(in.dir, "shared", "bin") + mkdir(in.t, in.bin, 0o755) + }, arch: "amd64", say: "Installing pullgate 0.2.0", urls: all}, + // A link in the path of the bin directory is followed once, and the + // script uses the real path from then on. + {name: "a bin directory behind a link", setup: func(in *installer) { + in.binArg = filepath.Join(in.dir, "bin-link") + if err := os.Symlink(in.bin, in.binArg); err != nil { + in.t.Fatal(err) + } + }, arch: "amd64", say: "Installing pullgate 0.2.0 as BIN/pullgate.", urls: all}, + } { + t.Run(tt.name, func(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + if tt.installed != nil { + in.installed(tt.installed) + } + if tt.setup != nil { + tt.setup(in) + } + r := in.run(append([]string{"--gh", in.gh}, tt.args...)...) + if r.code != 0 { + t.Fatalf("exit code %d\nstdout:\n%s\nstderr:\n%s", r.code, r.stdout, r.stderr) + } + want := map[string]string{"pullgate": "-rwxr-xr-x " + string(fakePullgate(tt.arch, "pullgate 0.2.0"))} + if got := files(t, in.bin); !maps.Equal(got, want) { + t.Errorf("the bin directory holds %q, want %q", got, want) + } + if say := strings.ReplaceAll(tt.say, "BIN", in.bin); !strings.Contains(r.stdout, say) { + t.Errorf("stdout does not say %q:\n%s", say, r.stdout) + } + if got := in.urls(); !slices.Equal(got, tt.urls) { + t.Errorf("curl got the URLs\n%q\nwant\n%q", got, tt.urls) + } + in.checkTmpGone() + }) + } +} + +// TestInstallNothingToDo: the version is installed already, or the +// installed one is newer and --version does not ask for the older one. +// The script exits with 0, downloads no file of the release and changes +// nothing. It says that it did not check the installed file. +func TestInstallNothingToDo(t *testing.T) { + for _, tt := range []struct { + name string + installed string + args []string + say string + urls []string + }{ + {"same version, the newest release", "0.2.0", nil, "BIN/pullgate says that it is pullgate 0.2.0 already. Nothing to do.\n" + + "This did not check the installed file. To replace it with a checked copy, run this again with --reinstall.", + []string{latestURL}}, + {"same version, with --version", "0.2.0", []string{"--version", "0.2.0"}, "says that it is pullgate 0.2.0 already", + []string{tagURL("0.2.0")}}, + {"a newer version", "0.3.0", nil, + "BIN/pullgate says that it is pullgate 0.3.0, which is newer than 0.2.0, the newest release. Nothing to do.\n" + + "This did not check the installed file. To install 0.2.0 anyway, run this again with --version 0.2.0.", + []string{latestURL}}, + {"a newer version in the second number", "0.10.0", nil, "which is newer than 0.2.0", []string{latestURL}}, + {"a newer version in the first number", "1.0.0", nil, "which is newer than 0.2.0", []string{latestURL}}, + {"a newer version, with --reinstall", "0.3.0", []string{"--reinstall"}, "which is newer than 0.2.0", []string{latestURL}}, + } { + t.Run(tt.name, func(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + in.installed(fakePullgate("installed", "pullgate "+tt.installed)) + before := files(t, in.bin) + r := in.run(append([]string{"--gh", in.gh}, tt.args...)...) + if r.code != 0 || r.stderr != "" { + t.Errorf("exit code %d, stderr %q; want 0 and nothing", r.code, r.stderr) + } + if say := strings.ReplaceAll(tt.say, "BIN", in.bin); !strings.Contains(r.stdout, say) { + t.Errorf("stdout does not say %q:\n%s", say, r.stdout) + } + if got := in.urls(); !slices.Equal(got, tt.urls) { + t.Errorf("curl got the URLs %q, want %q", got, tt.urls) + } + if in.ghChecked() { + t.Error("gh checked an attestation") + } + if after := files(t, in.bin); !maps.Equal(after, before) { + t.Errorf("the bin directory changed") + } + in.checkTmpGone() + }) + } +} + +// TestInstallDenies: each failed check stops the script with exit code 1 +// and a last line that says why and that nothing was installed. The old +// pullgate stays, and no new file is left next to it. +func TestInstallDenies(t *testing.T) { + const tarball = "pullgate_0.2.0_linux_amd64.tar.gz" + sums := func(lines ...string) func(in *installer) { + return func(in *installer) { + in.serve(releasePath+"0.2.0/SHA256SUMS", []byte(strings.Join(lines, ""))) + } + } + sumOf := func(in *installer, arch string) string { + data := readFile(in.t, filepath.Join(in.web, releasePath+"0.2.0", "pullgate_0.2.0_linux_"+arch+".tar.gz")) + return fmt.Sprintf("%x", sha256.Sum256(data)) + } + for _, tt := range []struct { + name string + installed []byte // the installed pullgate; nil: pullgate 0.1.0 + setup func(in *installer) // after the newest release 0.2.0 is on the fake GitHub + args []string // nil: --gh with the fake gh + want string // a part of the last line + checked bool // whether gh attestation verify ran + noCurl bool // whether the script must stop before any download + noRun bool // whether the script must run no pullgate and no gh + }{ + // The platform. + {name: "platform not supported", setup: env("FAKE_UNAME_S=Darwin"), noCurl: true, + want: "pullgate runs on Linux only, and this is Darwin"}, + {name: "cpu not supported", setup: env("FAKE_UNAME_M=riscv64"), noCurl: true, + want: "amd64 and arm64 only, and this machine is riscv64"}, + {name: "cpu armv7 not supported", setup: env("FAKE_UNAME_M=armv7l"), noCurl: true, + want: "amd64 and arm64 only, and this machine is armv7l"}, + + // The paths that the script runs programs from and writes to. + {name: "no bin directory", args: []string{"--bin-dir", "/nonexistent/bin"}, noCurl: true, noRun: true, + want: "/nonexistent/bin is not a directory"}, + {name: "bin directory not writable", setup: func(in *installer) { chmod(in.t, in.bin, 0o500) }, + noCurl: true, noRun: true, want: "cannot write to BIN; run this as root"}, + {name: "bin directory writable by others", setup: func(in *installer) { chmod(in.t, in.bin, 0o777) }, + noCurl: true, noRun: true, want: "group or others can write to BIN; only root or user"}, + {name: "bin directory writable by group", setup: func(in *installer) { chmod(in.t, in.bin, 0o770) }, + noCurl: true, noRun: true, want: "group or others can write to BIN;"}, + {name: "bin directory with the sticky bit", setup: func(in *installer) { chmod(in.t, in.bin, 0o777|os.ModeSticky) }, + noCurl: true, noRun: true, want: "group or others can write to BIN;"}, + {name: "bin directory in a directory writable by others", setup: func(in *installer) { + open := filepath.Join(in.dir, "open") + mkdir(in.t, open, 0o777) + in.bin = filepath.Join(open, "bin") + mkdir(in.t, in.bin, 0o700) + in.installed(fakePullgate("installed", "pullgate 0.1.0")) + }, noCurl: true, noRun: true, want: "group or others can write to DIR/open;"}, + {name: "target writable by others", setup: func(in *installer) { chmod(in.t, filepath.Join(in.bin, "pullgate"), 0o777) }, + noCurl: true, noRun: true, want: "group or others can write to BIN/pullgate;"}, + {name: "target is a symlink", setup: func(in *installer) { + mkdir(in.t, filepath.Join(in.dir, "elsewhere"), 0o700) + writeFile(in.t, filepath.Join(in.dir, "elsewhere", "pullgate"), fakePullgate("elsewhere", "pullgate 0.1.0"), 0o755) + replace(in.t, filepath.Join(in.bin, "pullgate"), func(path string) error { + return os.Symlink(filepath.Join(in.dir, "elsewhere", "pullgate"), path) + }) + }, noCurl: true, noRun: true, want: "BIN/pullgate is a link; the script replaces only a file"}, + {name: "target is a directory", setup: func(in *installer) { + replace(in.t, filepath.Join(in.bin, "pullgate"), func(path string) error { return os.Mkdir(path, 0o700) }) + }, noCurl: true, noRun: true, want: "BIN/pullgate is not a file"}, + {name: "target is a pipe", setup: func(in *installer) { + replace(in.t, filepath.Join(in.bin, "pullgate"), func(path string) error { return syscall.Mkfifo(path, 0o600) }) + }, noCurl: true, noRun: true, want: "BIN/pullgate is not a file"}, + {name: "TMPDIR writable by others", setup: func(in *installer) { + in.tmp = filepath.Join(in.dir, "open-tmp") + mkdir(in.t, in.tmp, 0o777) + }, noCurl: true, noRun: true, want: "group or others can write to DIR/open-tmp;"}, + {name: "TMPDIR in a directory writable by others", setup: func(in *installer) { + mkdir(in.t, filepath.Join(in.dir, "open"), 0o777) + in.tmp = filepath.Join(in.dir, "open", "tmp") + mkdir(in.t, in.tmp, 0o700) + }, noCurl: true, noRun: true, want: "group or others can write to DIR/open;"}, + {name: "no TMPDIR", setup: env("TMPDIR=/nonexistent/tmp"), noCurl: true, noRun: true, + want: "cannot find the directory /nonexistent/tmp"}, + {name: "gh writable by others", setup: func(in *installer) { chmod(in.t, in.gh, 0o777) }, + noCurl: true, noRun: true, want: "group or others can write to DIR/gh;"}, + {name: "gh in a directory writable by others", setup: func(in *installer) { + mkdir(in.t, filepath.Join(in.dir, "open"), 0o777) + in.gh = filepath.Join(in.dir, "open", "gh") + writeFile(in.t, in.gh, []byte(fakeGh), 0o700) + }, noCurl: true, noRun: true, want: "group or others can write to DIR/open;"}, + {name: "gh is a symlink", setup: func(in *installer) { + link := filepath.Join(in.dir, "gh-link") + if err := os.Symlink(in.gh, link); err != nil { + in.t.Fatal(err) + } + in.gh = link + }, noCurl: true, noRun: true, want: "--gh DIR/gh-link is not a program file; name the file itself, not a link"}, + {name: "gh missing", args: []string{"--gh", "/nonexistent/gh"}, noCurl: true, noRun: true, + want: "--gh /nonexistent/gh is not a program file"}, + {name: "gh not a program", setup: func(in *installer) { chmod(in.t, in.gh, 0o600) }, + noCurl: true, noRun: true, want: "--gh DIR/gh is not a program file"}, + + // The installed version. + {name: "installed version unknown", installed: fakePullgate("installed", "pullgate dev"), + want: "BIN/pullgate has an unknown version (a build from the source, or it does not run); " + + "to replace it with pullgate 0.2.0, run this again with --reinstall"}, + {name: "installed version prints nothing", installed: []byte("#!/bin/sh\n"), want: "has an unknown version"}, + {name: "installed file does not run", installed: failingPullgate, want: "has an unknown version"}, + + // The release and its files. + {name: "no answer from the API", setup: func(in *installer) { in.unserve(latestPath) }, + want: "cannot ask GitHub for the newest release"}, + {name: "API answer too big", setup: func(in *installer) { + in.serve(latestPath, bytes.Repeat([]byte(" "), 1<<20+1)) + }, want: "cannot ask GitHub for the newest release"}, + {name: "no release for --version", args: []string{"--version", "0.9.0"}, + want: "cannot get the release v0.9.0 from GitHub"}, + {name: "release tag does not match --version", setup: func(in *installer) { + in.serve(tagPath+"0.2.0", releaseJSON("v0.2.1")) + }, args: []string{"--version", "0.2.0"}, want: "GitHub names the release v0.2.0 as v0.2.1"}, + {name: "tag without v", setup: latest("0.2.0"), want: "GitHub does not name the release in the form vX.Y.Z"}, + {name: "tag with two numbers", setup: latest("v0.2"), want: "in the form vX.Y.Z"}, + {name: "tag with four numbers", setup: latest("v0.2.0.1"), want: "in the form vX.Y.Z"}, + {name: "tag with a leading zero", setup: latest("v0.02.0"), want: "in the form vX.Y.Z"}, + {name: "tag of a pre-release", setup: latest("v0.2.0-rc.1"), want: "in the form vX.Y.Z"}, + {name: "tag with a long number", setup: latest("v0.2.1234567890"), want: "in the form vX.Y.Z"}, + {name: "tag with a space", setup: latest("v0.2.0 "), want: "in the form vX.Y.Z"}, + {name: "two tags", setup: func(in *installer) { + in.serve(latestPath, []byte("{\n \"tag_name\": \"v0.2.0\",\n \"tag_name\": \"v0.3.0\"\n}\n")) + }, want: "in the form vX.Y.Z"}, + {name: "no tag", setup: func(in *installer) { + in.serve(latestPath, []byte("{\n \"name\": \"v0.2.0\"\n}\n")) + }, want: "in the form vX.Y.Z"}, + {name: "no tarball", setup: func(in *installer) { in.unserve(releasePath + "0.2.0/" + tarball) }, + want: "cannot download https://" + releasePath + "0.2.0/" + tarball}, + {name: "no SHA256SUMS", setup: func(in *installer) { in.unserve(releasePath + "0.2.0/SHA256SUMS") }, + want: "cannot download https://" + releasePath + "0.2.0/SHA256SUMS"}, + {name: "SHA256SUMS too big", setup: func(in *installer) { + sums(sumOf(in, "amd64")+" "+tarball+"\n", strings.Repeat("#", 1<<20))(in) + }, want: "cannot download https://" + releasePath + "0.2.0/SHA256SUMS"}, + {name: "no bundle", setup: func(in *installer) { in.unserve(releasePath + "0.2.0/pullgate_0.2.0.sigstore.json") }, + want: "cannot download https://" + releasePath + "0.2.0/pullgate_0.2.0.sigstore.json"}, + {name: "wrong sha256", setup: func(in *installer) { + sums(sumOf(in, "arm64")+" "+tarball+"\n", sumOf(in, "arm64")+" pullgate_0.2.0_linux_arm64.tar.gz\n")(in) + }, want: "the SHA-256 of " + tarball + " is not the one in SHA256SUMS"}, + {name: "SHA256SUMS has no line for the tarball", setup: func(in *installer) { + sums(sumOf(in, "arm64") + " pullgate_0.2.0_linux_arm64.tar.gz\n")(in) + }, want: "SHA256SUMS of the release has no line for " + tarball}, + {name: "SHA256SUMS has a line for a longer name only", setup: func(in *installer) { + sums(sumOf(in, "amd64") + " " + tarball + ".old\n")(in) + }, want: "SHA256SUMS of the release has no line for " + tarball}, + {name: "SHA256SUMS has two lines for the tarball", setup: func(in *installer) { + sums(sumOf(in, "amd64")+" "+tarball+"\n", sumOf(in, "amd64")+" *"+tarball+"\n")(in) + }, want: "SHA256SUMS of the release has more than one line for " + tarball}, + + // gh and the attestation. + {name: "attestation fails", setup: env("FAKE_GH_EXIT=1"), checked: true, + want: "gh attestation verify failed or ran longer than 300 seconds, so it is not proven that the release workflow built " + tarball + "; read the output of gh above"}, + {name: "gh too old", setup: env("FAKE_GH_VERSION=2.92.0"), want: " is gh 2.92.0; it must be gh 2.93.0 or newer"}, + {name: "gh pre-release", setup: env("FAKE_GH_VERSION=2.93.0-rc.1"), want: "cannot tell the version of "}, + {name: "gh version with more", setup: env("FAKE_GH_VERSION=2.102.0+ds1"), want: "cannot tell the version of "}, + {name: "gh with no version", setup: env("FAKE_GH_VERSION=DEV"), want: "cannot tell the version of "}, + {name: "gh --version fails", setup: env("FAKE_GH_VERSION_EXIT=1"), want: "/gh --version (check that "}, + {name: "downloaded gh with another sha256", setup: func(in *installer) { in.ghRelease() }, args: []string{}, + want: "the SHA-256 of gh_2.102.0_linux_amd64.tar.gz is not the one in this script"}, + {name: "no gh to download", args: []string{}, want: "cannot download gh_2.102.0_linux_amd64.tar.gz"}, + + // The new pullgate. The attestation proves which workflow built a + // file, not which version it is. A release 0.3.0 with an attested + // build of 0.2.0 passes the checksum and the attestation, and must + // still fail. + {name: "binary reports another version", setup: rel(says("pullgate 0.1.0")), checked: true, + want: "the new pullgate does not say that it is pullgate 0.2.0"}, + {name: "attested older build under a newer name", setup: func(in *installer) { + in.latest("v0.3.0") + in.release("0.3.0", says("pullgate 0.2.0")) + }, checked: true, want: "the new pullgate does not say that it is pullgate 0.3.0"}, + {name: "binary prints more than its version", setup: rel(says("pullgate 0.2.0", "pullgate 0.3.0")), checked: true, + want: "the new pullgate does not say that it is pullgate 0.2.0"}, + {name: "binary prints a v", setup: rel(says("pullgate v0.2.0")), checked: true, + want: "the new pullgate does not say that it is pullgate 0.2.0"}, + {name: "binary does not run", setup: rel(func(string) []byte { return failingPullgate }), checked: true, + want: "the new pullgate does not run, or runs longer than 60 seconds (if programs cannot run in "}, + {name: "tarball without pullgate", setup: func(in *installer) { + data := tarGz(in.t, tarFile{"LICENSE", 0o644, []byte("a made-up license\n")}) + in.serve(releasePath+"0.2.0/"+tarball, data) + sums(fmt.Sprintf("%x %s\n", sha256.Sum256(data), tarball))(in) + }, checked: true, want: "cannot take pullgate out of " + tarball}, + } { + t.Run(tt.name, func(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + installed := tt.installed + if installed == nil { + installed = fakePullgate("installed", "pullgate 0.1.0") + } + in.installed(installed) + if tt.setup != nil { + tt.setup(in) + } + args := tt.args + if args == nil { + args = []string{"--gh", in.gh} + } else if len(args) > 0 && args[0] == "--version" { + args = append([]string{"--gh", in.gh}, args...) + } + before := files(t, in.bin) + r := in.run(args...) + want := strings.NewReplacer("BIN", in.bin, "DIR", in.dir).Replace(tt.want) + in.checkFailed(r, 1, want, before) + if in.ghChecked() != tt.checked { + t.Errorf("gh attestation verify ran: %v, want %v", in.ghChecked(), tt.checked) + } + if urls := in.urls(); tt.noCurl && len(urls) != 0 { + t.Errorf("curl got %q, want no call", urls) + } + if runs := append(in.log("pullgate-runs"), in.log("gh")...); tt.noRun && len(runs) != 0 { + t.Errorf("the script ran a pullgate or a gh: %q", runs) + } + // The new pullgate runs only after the attestation passed. + if ranNew := slices.ContainsFunc(in.log("pullgate-runs"), func(s string) bool { return s == "amd64" }); ranNew && !tt.checked { + t.Error("the new pullgate ran, but the attestation was not checked") + } + }) + } +} + +// TestInstallRunsNoNewFileBeforeTheCheck: when the attestation fails, the +// new pullgate never runs, not even for its version. +func TestInstallRunsNoNewFileBeforeTheCheck(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + in.installed(fakePullgate("installed", "pullgate 0.1.0")) + in.env = append(in.env, "FAKE_GH_EXIT=1") + before := files(t, in.bin) + r := in.run("--gh", in.gh) + in.checkFailed(r, 1, "gh attestation verify failed", before) + // Only the installed pullgate ran, for its version. + if runs := in.log("pullgate-runs"); !slices.Equal(runs, []string{"installed"}) { + t.Errorf("these copies of pullgate ran: %q, want only the installed one", runs) + } +} + +// env returns a setup that adds the variables to the environment of the +// script. +func env(vars ...string) func(in *installer) { + return func(in *installer) { in.env = append(in.env, vars...) } +} + +// latest returns a setup that makes tag the newest release. +func latest(tag string) func(in *installer) { + return func(in *installer) { in.latest(tag) } +} + +// rel returns a setup that makes the release 0.2.0 again, with these +// files pullgate. +func rel(pullgate func(arch string) []byte) func(in *installer) { + return func(in *installer) { in.release("0.2.0", pullgate) } +} + +// chmod sets the mode of path, and sets it back to 0700 at the end of the +// test, so that the temporary directory can be removed. +func chmod(t *testing.T, path string, mode os.FileMode) { + t.Helper() + if err := os.Chmod(path, mode); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(path, 0o700) }) +} + +// replace removes the file path and makes something else there with +// create. +func replace(t *testing.T, path string, create func(path string) error) { + t.Helper() + if err := os.Remove(path); err != nil { + t.Fatal(err) + } + if err := create(path); err != nil { + t.Fatal(err) + } +} + +// TestInstallUsage: wrong arguments stop the script with exit code 64, +// before it downloads anything. +func TestInstallUsage(t *testing.T) { + for _, tt := range []struct { + args []string + want string + }{ + {[]string{"--bogus"}, "unknown argument: --bogus"}, + {[]string{"0.2.0"}, "unknown argument: 0.2.0"}, + {[]string{"--version=0.2.0"}, "unknown argument: --version=0.2.0"}, + {[]string{"--reinstall=yes"}, "unknown argument: --reinstall=yes"}, + {[]string{"--version"}, "--version needs a version, such as 0.2.0"}, + {[]string{"--version", "0.2"}, "--version must be X.Y.Z, such as 0.2.0"}, + {[]string{"--version", "v0.2.0"}, "--version must be X.Y.Z"}, + {[]string{"--version", "0.2.0.1"}, "--version must be X.Y.Z"}, + {[]string{"--version", "0.2.0-rc.1"}, "--version must be X.Y.Z"}, + {[]string{"--version", "00.2.0"}, "--version must be X.Y.Z"}, + {[]string{"--version", "0.-2.0"}, "--version must be X.Y.Z"}, + {[]string{"--version", ""}, "--version must be X.Y.Z"}, + {[]string{"--version", "--bin-dir"}, "--version must be X.Y.Z"}, + {[]string{"--bin-dir"}, "--bin-dir needs a directory"}, + {[]string{"--bin-dir", "bin"}, "--bin-dir must be an absolute path"}, + {[]string{"--gh"}, "--gh needs the path of gh"}, + {[]string{"--gh", "gh"}, "--gh must be an absolute path"}, + } { + t.Run(strings.Join(tt.args, " "), func(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + in.installed(fakePullgate("installed", "pullgate 0.1.0")) + before := files(t, in.bin) + r := in.run(tt.args...) + in.checkFailed(r, 64, tt.want, before) + if !strings.HasPrefix(r.stderr, "Usage: sh install.sh ") || r.stdout != "" { + t.Errorf("stdout %q, stderr %q; want the usage on stderr", r.stdout, r.stderr) + } + if urls := in.urls(); len(urls) != 0 { + t.Errorf("curl got %q", urls) + } + }) + } + for _, help := range []string{"--help", "-h"} { + in := newInstaller(t) + r := in.run(help) + if r.code != 0 || !strings.HasPrefix(r.stdout, "Usage: sh install.sh ") || !strings.Contains(r.stdout, "--reinstall") || r.stderr != "" { + t.Errorf("%s: exit code %d, stdout %q, stderr %q; want 0 and the usage on stdout", help, r.code, r.stdout, r.stderr) + } + } +} + +// TestInstallDownloadsGh runs a copy of the script whose SHA-256 of gh is +// the one of a fake gh: the script downloads the tarball of gh, checks it, +// takes gh out of it and checks the attestation with it. +func TestInstallDownloadsGh(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + sum := in.ghRelease() + script := string(readFile(t, in.script)) + pin := regexp.MustCompile(`(?m)^gh_sha256_amd64=[0-9a-f]{64}$`) + if n := len(pin.FindAllString(script, -1)); n != 1 { + t.Fatalf("install.sh has %d lines gh_sha256_amd64=, want 1", n) + } + in.script = filepath.Join(in.dir, "install-with-fake-gh.sh") + writeFile(t, in.script, []byte(pin.ReplaceAllString(script, "gh_sha256_amd64="+sum)), 0o600) + + r := in.run() + if r.code != 0 { + t.Fatalf("exit code %d\nstdout:\n%s\nstderr:\n%s", r.code, r.stdout, r.stderr) + } + want := append([]string{latestURL}, releaseURLs("0.2.0")...) + want = append(want, "https://"+ghPath+"2.102.0/gh_2.102.0_linux_amd64.tar.gz") + if got := in.urls(); !slices.Equal(got, want) { + t.Errorf("curl got the URLs\n%q\nwant\n%q", got, want) + } + if last := in.curlCalls()[len(want)-1]; !slices.Contains(last, maxBig) { + t.Errorf("the download of gh has no size limit %s: %q", maxBig, last) + } + // The gh that ran is the one from the tarball, in the temporary + // directory. + args := in.log("gh-args") + if !in.ghChecked() || len(args) < 3 { + t.Fatalf("gh attestation verify did not run: %q", args) + } + tmp := filepath.Dir(args[2]) + if got, want := in.log("gh-path"), filepath.Join(tmp, "gh", "gh_2.102.0_linux_amd64", "bin", "gh"); len(got) != 1 || got[0] != want { + t.Errorf("the gh that ran is %q, want %s", got, want) + } + if got := files(t, in.bin); got["pullgate"] != "-rwxr-xr-x "+string(fakePullgate("amd64", "pullgate 0.2.0")) { + t.Errorf("the bin directory holds %q", got) + } + in.checkTmpGone() +} + +// TestInstallStopsOnSIGTERM sends SIGTERM to the script and its programs, +// as Ctrl-C does with SIGINT, while gh checks the attestation. The script +// exits with 1, installs nothing, and removes its temporary directory. +func TestInstallStopsOnSIGTERM(t *testing.T) { + in := newInstaller(t) + in.latest("v0.2.0") + in.release("0.2.0", says("pullgate 0.2.0")) + in.installed(fakePullgate("installed", "pullgate 0.1.0")) + before := files(t, in.bin) + marker := filepath.Join(in.dir, "gh-waits") + in.env = append(in.env, "FAKE_GH_WAIT="+marker) + cmd := in.command("--gh", in.gh) + cmd.SysProcAttr = &syscall.SysProcAttr{Setpgid: true} + var stdout, stderr bytes.Buffer + cmd.Stdout, cmd.Stderr = &stdout, &stderr + if err := cmd.Start(); err != nil { + t.Fatal(err) + } + done := make(chan error, 1) + go func() { done <- cmd.Wait() }() + deadline := time.Now().Add(20 * time.Second) + for { + if _, err := os.Stat(marker); err == nil { + break + } + select { + case err := <-done: + t.Fatalf("the script ended before gh waited: %v\nstdout:\n%s\nstderr:\n%s", err, stdout.String(), stderr.String()) + case <-time.After(10 * time.Millisecond): + } + if time.Now().After(deadline) { + t.Fatal("gh did not start to wait") + } + } + if err := syscall.Kill(-cmd.Process.Pid, syscall.SIGTERM); err != nil { + t.Fatal(err) + } + select { + case <-done: + case <-time.After(20 * time.Second): + _ = syscall.Kill(-cmd.Process.Pid, syscall.SIGKILL) + t.Fatal("the script did not stop on SIGTERM") + } + if code := cmd.ProcessState.ExitCode(); code != 1 { + t.Errorf("exit code %d, want 1\nstderr:\n%s", code, stderr.String()) + } + if after := files(t, in.bin); !maps.Equal(after, before) { + t.Errorf("the bin directory changed") + } + in.checkTmpGone() +} + +// functions writes install.sh without its last line, which starts main, +// into dir, so that a test can load its functions with ".". It returns the +// path of the copy. +func functions(t *testing.T, dir string) string { + t.Helper() + body, ok := strings.CutSuffix(string(readFile(t, "install.sh")), "\nmain \"$@\"\n") + if !ok { + t.Fatal(`install.sh does not end with the line main "$@"`) + } + path := filepath.Join(dir, "functions.sh") + writeFile(t, path, []byte(body+"\n"), 0o600) + return path +} + +// runFunctions runs code with /bin/sh, after it loaded the functions of +// install.sh, with the environment env. +func runFunctions(t *testing.T, lib string, env []string, code string) result { + t.Helper() + cmd := exec.CommandContext(t.Context(), "/bin/sh", "-c", ". \"$0\"\n"+code, lib) + cmd.Env = env + return runCmd(t, cmd) +} + +// TestInstallChecksAsRoot runs the checks of the paths as the script runs +// them as root, with uid 0: then only root may own a path. A test cannot +// make files of root, so it checks that its own files are refused, and +// that the directories of the system pass. +func TestInstallChecksAsRoot(t *testing.T) { + if os.Geteuid() == 0 { + t.Skip("the test needs files that root does not own") + } + dir := privateDir(t) + lib := functions(t, dir) + own := filepath.Join(dir, "own") + writeFile(t, own, []byte("#!/bin/sh\n"), 0o755) + env := []string{"PATH=" + os.Getenv("PATH")} + asRoot := "uid=0\nowners=root\n" + for _, tt := range []struct { + code string + want string // a part of the last line + }{ + {"check_tree " + own + " own", "pullgate: " + own + " is owned by user " + strconv.Itoa(os.Geteuid()) + + "; it must be owned by root (fix it with chown, or use another path); nothing was installed (exit 1)\n"}, + {"check_tree " + dir + " shared", "it must be owned by root"}, + {"check_entry /tmp own", "pullgate: group or others can write to /tmp; only root may (fix it with chmod go-w, or use another path); nothing was installed (exit 1)\n"}, + } { + r := runFunctions(t, lib, env, asRoot+tt.code) + if r.code != 1 || !strings.Contains(lastLine(r.stderr), tt.want) { + t.Errorf("%s: exit code %d, stderr %q; want 1 and %q", tt.code, r.code, r.stderr, tt.want) + } + } + // The directories of the system: root owns them, and only /tmp, with + // the sticky bit, lets others write. + for _, code := range []string{"check_tree /usr/bin own", "check_tree /tmp shared", "check_tree / own"} { + path := strings.Fields(code)[1] + if info, err := os.Lstat(path); err != nil || !info.IsDir() || info.Sys().(*syscall.Stat_t).Uid != 0 { + skipOrFail(t, "%s is not a directory of root", path) + } + if r := runFunctions(t, lib, env, asRoot+code); r.code != 0 { + t.Errorf("%s: exit code %d, stderr %q; want 0", code, r.code, r.stderr) + } + } +} + +// TestInstallCleansTheEnvironment runs clean_env of the script. It removes +// the variables that change what the programs of the script do, and sets +// LC_ALL=C. As root (a fake id says 0), it also sets the fixed PATH, which +// here is a directory of the test. +func TestInstallCleansTheEnvironment(t *testing.T) { + dir := privateDir(t) + lib := functions(t, dir) + all := append(append([]string{"TAR_OPTIONS"}, loaderVars...), unsafeVars...) + env := []string{"PATH=" + os.Getenv("PATH"), "LC_ALL=de_DE.UTF-8", "IFS=x"} + for _, name := range all { + env = append(env, name+"=/nonexistent/made-up") + } + show := `printf '%s|%s|' "$uid" "$owners"; printf '%s|' "$LC_ALL" "${IFS-unset}"` + for _, name := range all { + show += `; printf '%s|' "${` + name + `-unset}"` + } + wantVars := "C|unset|" + strings.Repeat("unset|", len(all)) + + // As this user: PATH stays. + r := runFunctions(t, lib, env, "clean_env\n"+show+`; printf '%s' "$PATH"`) + uid := strconv.Itoa(os.Geteuid()) + if want := uid + "|root or user " + uid + "|" + wantVars + os.Getenv("PATH"); r.code != 0 || r.stdout != want { + t.Errorf("as user %s: exit code %d, stdout %q, stderr %q; want %q", uid, r.code, r.stdout, r.stderr, want) + } + + // As root: PATH is root_path. + fakeRoot := filepath.Join(dir, "root-bin") + mkdir(t, fakeRoot, 0o700) + writeFile(t, filepath.Join(fakeRoot, "id"), []byte("#!/bin/sh\necho 0\n"), 0o700) + r = runFunctions(t, lib, env, "root_path="+fakeRoot+"\nclean_env\n"+show+`; printf '%s' "$PATH"`) + if want := "0|root|" + wantVars + fakeRoot; r.code != 0 || r.stdout != want { + t.Errorf("as root: exit code %d, stdout %q, stderr %q; want %q", r.code, r.stdout, r.stderr, want) + } + // The real script uses the directories of the system. + if !strings.Contains(string(readFile(t, "install.sh")), "\nroot_path=/usr/sbin:/usr/bin:/sbin:/bin\n") { + t.Error("install.sh does not set root_path=/usr/sbin:/usr/bin:/sbin:/bin") + } +} + +// TestInstallChecksTheUserID: clean_env stops when id -u fails, or prints +// something that is not a user ID. +func TestInstallChecksTheUserID(t *testing.T) { + dir := privateDir(t) + lib := functions(t, dir) + for i, tt := range []struct { + id string // the fake id + want string + }{ + {"echo root", "id -u does not print a user ID; check the program id in ROOT"}, + {"echo 0x0", "id -u does not print a user ID; check the program id in ROOT"}, + {"echo ' 0'", "id -u does not print a user ID; check the program id in ROOT"}, + {"echo -1", "id -u does not print a user ID; check the program id in ROOT"}, + {"true", "id -u does not print a user ID; check the program id in ROOT"}, + {"exit 1", "cannot run id -u; check that ROOT has the program id"}, + } { + fakes := filepath.Join(dir, "fakes"+strconv.Itoa(i)) + mkdir(t, fakes, 0o700) + writeFile(t, filepath.Join(fakes, "id"), []byte("#!/bin/sh\n"+tt.id+"\n"), 0o700) + r := runFunctions(t, lib, []string{"PATH=" + os.Getenv("PATH")}, "root_path="+fakes+"\nclean_env\necho passed") + if want := "pullgate: " + strings.ReplaceAll(tt.want, "ROOT", fakes) + "; nothing was installed (exit 1)\n"; r.code != 1 || lastLine(r.stderr) != want || r.stdout != "" { + t.Errorf("id that runs %q: exit code %d, stdout %q, stderr %q; want 1 and %q", tt.id, r.code, r.stdout, r.stderr, want) + } + } +} + +// TestPinnedGh: the gh that the script downloads is 2.93.0 or newer, and +// the script has a SHA-256 for each CPU. +func TestPinnedGh(t *testing.T) { + script := string(readFile(t, "install.sh")) + value := func(name, pattern string) string { + m := regexp.MustCompile(`(?m)^`+name+`=(`+pattern+`)$`).FindAllStringSubmatch(script, -1) + if len(m) != 1 { + t.Fatalf("install.sh has %d lines %s=%s, want 1", len(m), name, pattern) + } + return m[0][1] + } + num := `(0|[1-9][0-9]*)` + version := value("gh_version", num+`\.`+num+`\.`+num) + if minVersion := value("gh_min_version", num+`\.`+num+`\.`+num); minVersion != "2.93.0" { + t.Errorf("gh_min_version is %s, want 2.93.0", minVersion) + } + var parts [3]int + for i, s := range strings.Split(version, ".") { + parts[i], _ = strconv.Atoi(s) + } + if parts[0] < 2 || (parts[0] == 2 && parts[1] < 93) { + t.Errorf("the pinned gh is %s, want 2.93.0 or newer", version) + } + if value("gh_sha256_amd64", "[0-9a-f]{64}") == value("gh_sha256_arm64", "[0-9a-f]{64}") { + t.Error("gh has the same SHA-256 for amd64 and arm64") + } +} + +// skipOrFail skips the test, or fails it when the CI environment variable +// is set: CI has every program that the tests need. +func skipOrFail(t *testing.T, format string, args ...any) { + t.Helper() + if os.Getenv("CI") != "" { + t.Fatalf("CI is set, so this test must run, but: "+format, args...) + } + t.Skipf(format, args...) +} + +// writeFile writes data to path with mode. It holds syscall.ForkLock while +// the file is open, so that no child process that starts at that time +// gets a copy of the descriptor: then running the file would fail with +// "text file busy" (go.dev/issue/22315). +func writeFile(t *testing.T, path string, data []byte, mode os.FileMode) { + t.Helper() + syscall.ForkLock.RLock() + err := os.WriteFile(path, data, 0o600) + syscall.ForkLock.RUnlock() + if err != nil { + t.Fatal(err) + } + if err := os.Chmod(path, mode); err != nil { + t.Fatal(err) + } +} + +func readFile(t *testing.T, path string) []byte { + t.Helper() + data, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + return data +} + +// readEnv reads the output of env into a map. +func readEnv(t *testing.T, path string) map[string]string { + t.Helper() + env := map[string]string{} + for line := range strings.Lines(string(readFile(t, path))) { + if name, value, ok := strings.Cut(strings.TrimSuffix(line, "\n"), "="); ok { + env[name] = value + } + } + return env +} + +// lastLine returns the last line of s, with its newline. +func lastLine(s string) string { + body := strings.TrimSuffix(s, "\n") + return s[strings.LastIndex(body, "\n")+1:] +} + +// windows returns each run of n elements of s. +func windows(s []string, n int) [][]string { + var w [][]string + for i := 0; i+n <= len(s); i++ { + w = append(w, s[i:i+n]) + } + return w +} From ab1674522b6eca3b2750d76c7f3e206ecf049231 Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Thu, 12 Nov 2026 19:52:32 +0200 Subject: [PATCH 2/2] fix: review findings of install.sh A signal says in the last line whether the new file was installed; an early check for GNU timeout; tests fail instead of skip as root in CI; docs: sed is needed, the sticky-bit exception in T17. Co-Authored-By: Claude Opus 5.5 --- README.md | 2 +- THREAT-MODEL.md | 4 +++- install.sh | 29 ++++++++++++++++++++++++++++- install_linux_test.go | 7 +++++-- 4 files changed, 37 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 3ade16c..86ae644 100644 --- a/README.md +++ b/README.md @@ -57,7 +57,7 @@ It installs the newest release, or the one of `--version`, as `/usr/local/bin/pullgate` (or `DIR/pullgate`). It installs nothing unless every check passes: the SHA-256 in `SHA256SUMS`, the build attestation of the release (with `gh attestation verify`), and the version that the new -binary prints. It needs `curl`, `tar`, `gzip` and GNU coreutils. Without +binary prints. It needs `curl`, `tar`, `gzip`, `sed` and GNU coreutils. Without `--gh`, it downloads a pinned gh and checks its SHA-256. It replaces the old binary only in the last step, and restarts nothing: it prints what to restart. Run it again to update. `--reinstall` installs the same version diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index 94cad07..1df3225 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -340,7 +340,9 @@ a size limit, uses HTTPS only with TLS 1.2 or newer, and reads no `LC_ALL=C`, and as root uses a fixed `PATH`. pullgate and gh run with a time limit (`timeout`), and curl has its own. It writes the new file to the disk before the rename. gh runs with no token and an empty config. Only root may change the bin directory, the old binary, `TMPDIR`, the new temporary -directory and the `--gh` file, and each directory above them. The old +directory and the `--gh` file, and each directory above them. A directory +above them that others can write is accepted only with the sticky bit, as +`/tmp` has. The old binary must be a regular file, never a link. The new file replaces the old one by a rename in the same directory, as the last step. diff --git a/install.sh b/install.sh index e6b0f20..9bd0c87 100644 --- a/install.sh +++ b/install.sh @@ -122,6 +122,28 @@ cleanup() { return 0 } +# on_signal ends the script after a signal. Its last line says whether the +# new file was already in place. +on_signal() { + if [ -n "$renamed" ]; then + printf 'pullgate: stopped by a signal after the new file was installed as %s; run %s version to check it (exit 1)\n' "$target" "$target" >&2 + exit 1 + fi + if [ -n "$renaming" ]; then + printf 'pullgate: stopped by a signal during the rename; the new file may be installed as %s; run %s version to check it (exit 1)\n' "$target" "$target" >&2 + exit 1 + fi + die "stopped by a signal; run the script again" +} + +# check_tools stops early when timeout is not the one of GNU coreutils +# (busybox timeout has no --foreground). Later errors would else point the +# wrong way, for example to an unknown installed version. +check_tools() { + timeout --foreground 10 true >/dev/null 2>&1 || + die "timeout --foreground does not work; install GNU coreutils and run the script again" +} + # clean_env removes the variables that change what the programs of the # script do in a way that is not safe here, sets LC_ALL=C, and sets uid. # As root, PATH becomes root_path, so that only the programs of the system @@ -644,8 +666,10 @@ install_new() { # loss cannot leave an empty file under the old name. sync with a file # needs coreutils 8.24 or newer; else sync writes all files. sync -- "$tmp_target" 2>/dev/null || sync || die "cannot write $tmp_target to the disk; check the disk" + renaming=1 mv -f "$tmp_target" "$target" || die "cannot rename the new file to $target; check that $bin_dir is not read-only" tmp_target= + renamed=1 sync -- "$bin_dir" 2>/dev/null || sync || : } @@ -672,13 +696,16 @@ main() { reinstall= tmp= tmp_target= + renaming= + renamed= trap cleanup EXIT # A signal ends the script through exit, so the EXIT trap runs too. - trap 'exit 1' HUP INT PIPE TERM + trap on_signal HUP INT PIPE TERM clean_env parse_args "$@" check_platform + check_tools check_paths make_tmp choose_version diff --git a/install_linux_test.go b/install_linux_test.go index e4a3837..7ee3975 100644 --- a/install_linux_test.go +++ b/install_linux_test.go @@ -222,7 +222,7 @@ type installer struct { func newInstaller(t *testing.T) *installer { t.Helper() if os.Geteuid() == 0 { - t.Skip("as root, install.sh runs only the programs of the system, not the fakes of the test") + skipOrFail(t, "as root, install.sh runs only the programs of the system, not the fakes of the test") } for _, name := range []string{"sed", "tar", "gzip", "sha256sum", "install", "mktemp", "id", "stat", "cp", "env", "wc", "sleep", "timeout", "sync"} { if _, err := exec.LookPath(name); err != nil { @@ -1194,6 +1194,9 @@ func TestInstallStopsOnSIGTERM(t *testing.T) { if code := cmd.ProcessState.ExitCode(); code != 1 { t.Errorf("exit code %d, want 1\nstderr:\n%s", code, stderr.String()) } + if want := "pullgate: stopped by a signal; run the script again; nothing was installed (exit 1)"; lastLine(stderr.String()) != want+"\n" && lastLine(stderr.String()) != want { + t.Errorf("last line %q, want %q", lastLine(stderr.String()), want) + } if after := files(t, in.bin); !maps.Equal(after, before) { t.Errorf("the bin directory changed") } @@ -1229,7 +1232,7 @@ func runFunctions(t *testing.T, lib string, env []string, code string) result { // that the directories of the system pass. func TestInstallChecksAsRoot(t *testing.T) { if os.Geteuid() == 0 { - t.Skip("the test needs files that root does not own") + skipOrFail(t, "the test needs files that root does not own") } dir := privateDir(t) lib := functions(t, dir)