Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
3 changes: 3 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 …`).
Expand Down
74 changes: 73 additions & 1 deletion DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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_<version>_linux_<arch>.tar.gz`, `SHA256SUMS` and
`pullgate_<version>.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.
39 changes: 35 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`, `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
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
Expand Down
60 changes: 59 additions & 1 deletion THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -299,7 +300,64 @@ 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. 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.

*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

Expand Down
3 changes: 3 additions & 0 deletions docs/releasing.md
Original file line number Diff line number Diff line change
Expand Up @@ -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").
Loading
Loading