The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
release signing: accept sqv, harden the apt key steps, fix stale comments
Claudee4bedbec7bae
diff --git a/cli/beacon/internal/endpoint/selfupdate/apply.go b/cli/beacon/internal/endpoint/selfupdate/apply.goindex 540e4e7f..23cdb744 100644--- a/cli/beacon/internal/endpoint/selfupdate/apply.go+++ b/cli/beacon/internal/endpoint/selfupdate/apply.go@@ -223,8 +223,8 @@ func (a *Applier) installPackage(ctx context.Context, pkg Package, result ApplyR// SHA-256 verification above still applies on every platform and is not optional. The trust// root that leaves is HTTPS plus the release checksum -- which is the same trust root the// user relied on to obtain the package they are updating, so this is parity with the install- // path rather than a downgrade. Once a release key is pinned, Linux also requires the- // package in a checksums.txt signed by Beacon's release key.+ // path rather than a downgrade. On Linux, Beacon's release key is pinned, so the package must+ // also be listed in a checksums.txt signed by that key (verified with gpgv or sqv).switch {case runtime.GOOS == "linux" && len(releaseKeyFingerprints) > 0 && !a.AllowInsecureTest:result.Verification = "sha256+gpg"diff --git a/cli/beacon/internal/endpoint/selfupdate/linuxsig.go b/cli/beacon/internal/endpoint/selfupdate/linuxsig.goindex 6fd6c6e3..1dc9996d 100644--- a/cli/beacon/internal/endpoint/selfupdate/linuxsig.go+++ b/cli/beacon/internal/endpoint/selfupdate/linuxsig.go@@ -13,11 +13,11 @@ import ()// pinnedReleaseKeys holds the OpenPGP fingerprints, one per line, of the keys allowed to sign a-// release's checksums.txt; two only while a key is rotated. It is empty until Beacon has a Linux-// release key, and while it is, a Linux update is verified against the manifest's SHA-256 only.-// Once set, a .deb or .rpm is installed only if a checksums.txt signed by one of these keys lists-// it. The release copy of packaging/linux/install.sh is stamped from the same file, so pinning a-// key is a change to release-key.fingerprint alone.+// release's checksums.txt; two only while a key is rotated. It pins Beacon's Linux release key, so+// a .deb or .rpm is installed only if a checksums.txt signed by one of these keys lists it, on top+// of the manifest's SHA-256. The release copy of packaging/linux/install.sh is stamped from the+// same file, so changing the pinned key is a change to release-key.fingerprint alone (published in+// docs/platforms/linux.mdx#release-signing).////go:embed release-key.fingerprintvar pinnedReleaseKeys string@@ -83,37 +83,76 @@ func (a *Applier) fetchSignedChecksums(ctx context.Context, base, dir string) erreturn fmt.Errorf("download %s: %w", f, err)}}- // Status is read from stdout alone, because stderr repeats the key's user ID and the release- // supplies the key.- var stderr strings.Builder- cmd := exec.CommandContext(ctx, "gpgv", "--homedir", dir, "--keyring", filepath.Join(dir, releaseKeyAsset),- "--status-fd", "1", filepath.Join(dir, "checksums.txt.sig"), filepath.Join(dir, "checksums.txt"))- cmd.Stderr = &stderr- out, err := cmd.Output()+ signers, err := goodSignatures(ctx, dir)if err != nil {- var exit *exec.ExitError- msg := fmt.Sprintf("checksums.txt signature does not verify: %v: %s", err, strings.TrimSpace(stderr.String()))- if errors.As(err, &exit) {- return &signatureMismatchError{msg: msg}- }- return errors.New(msg)+ return err}- if !validSigFrom(string(out), releaseKeyFingerprints) {+ if !signedByPinnedKey(signers, releaseKeyFingerprints) {return fmt.Errorf("checksums.txt is not signed by a Beacon release key (%s)", strings.Join(releaseKeyFingerprints, ", "))}return nil}-// validSigFrom reports whether gpgv's status output has a good signature whose primary key is one-// of fingerprints. VALIDSIG ends with the primary key's fingerprint, so a signing subkey counts.-func validSigFrom(status string, fingerprints []string) bool {+// signatureVerifiers are the programs that can check checksums.txt.sig, in order of preference:+// gpgv on most systems, and sqv (Sequoia) where it replaces gpgv, as on Debian trixie-based images.+var signatureVerifiers = []string{"gpgv", "sqv"}++// goodSignatures verifies dir/checksums.txt.sig over dir/checksums.txt with the release key in dir+// and returns the primary-key fingerprint of each good signature. A signature that does not verify+// is a *signatureMismatchError, the one failure a second fetch can fix.+func goodSignatures(ctx context.Context, dir string) ([]string, error) {+ sig, sums, key := filepath.Join(dir, "checksums.txt.sig"), filepath.Join(dir, "checksums.txt"), filepath.Join(dir, releaseKeyAsset)+ for _, verifier := range signatureVerifiers {+ path, err := exec.LookPath(verifier)+ if err != nil {+ continue+ }+ var cmd *exec.Cmd+ if verifier == "gpgv" {+ // Status is read from stdout alone, because stderr repeats the key's user ID and the+ // release supplies the key.+ cmd = exec.CommandContext(ctx, path, "--homedir", dir, "--keyring", key, "--status-fd", "1", sig, sums)+ } else {+ // sqv prints the fingerprint of each good signature's key on stdout.+ cmd = exec.CommandContext(ctx, path, "--keyring", key, sig, sums)+ }+ var stderr strings.Builder+ cmd.Stderr = &stderr+ out, err := cmd.Output()+ if err != nil {+ var exit *exec.ExitError+ msg := fmt.Sprintf("checksums.txt signature does not verify (%s): %v: %s", verifier, err, strings.TrimSpace(stderr.String()))+ if errors.As(err, &exit) {+ return nil, &signatureMismatchError{msg: msg}+ }+ return nil, errors.New(msg)+ }+ if verifier == "gpgv" {+ return validSigFingerprints(string(out)), nil+ }+ return strings.Fields(string(out)), nil+ }+ return nil, fmt.Errorf("verifying the release signature needs gpgv or sqv; install gpgv (apt-get install gpgv, dnf install gnupg2) and retry")+}++// validSigFingerprints returns the last field of each VALIDSIG line in gpgv's status output, the+// signature's primary-key fingerprint, so a signing subkey counts.+func validSigFingerprints(status string) []string {+ var fprs []stringfor _, line := range strings.Split(status, "\n") {f := strings.Fields(line)- if len(f) < 3 || f[0] != "[GNUPG:]" || f[1] != "VALIDSIG" {- continue+ if len(f) >= 3 && f[0] == "[GNUPG:]" && f[1] == "VALIDSIG" {+ fprs = append(fprs, f[len(f)-1])}- for _, fpr := range fingerprints {- if strings.EqualFold(f[len(f)-1], fpr) {+ }+ return fprs+}++// signedByPinnedKey reports whether any good signature's fingerprint is one of the pinned ones.+func signedByPinnedKey(signers, pinned []string) bool {+ for _, s := range signers {+ for _, fpr := range pinned {+ if strings.EqualFold(s, fpr) {return true}}diff --git a/cli/beacon/internal/endpoint/selfupdate/linuxsig_test.go b/cli/beacon/internal/endpoint/selfupdate/linuxsig_test.goindex c3d1c877..b189b51e 100644--- a/cli/beacon/internal/endpoint/selfupdate/linuxsig_test.go+++ b/cli/beacon/internal/endpoint/selfupdate/linuxsig_test.go@@ -20,13 +20,37 @@ import (// testdata/signed-release is a release signed by a throwaway test key with this fingerprint.const testReleaseKeyFingerprint = "492264C703AE4B306CF804C9E0F25BE9BE03411C"+// TestVerifyReleaseSignature runs once per supported verifier, each alone, so both gpgv and the+// sqv fallback are checked wherever they are installed.func TestVerifyReleaseSignature(t *testing.T) {if runtime.GOOS != "linux" {t.Skip("release signatures are verified on Linux only")}- if _, err := exec.LookPath("gpgv"); err != nil {- t.Skip("gpgv is not installed")+ for _, verifier := range []string{"gpgv", "sqv"} {+ t.Run(verifier, func(t *testing.T) {+ if _, err := exec.LookPath(verifier); err != nil {+ t.Skipf("%s is not installed", verifier)+ }+ old := signatureVerifiers+ signatureVerifiers = []string{verifier}+ t.Cleanup(func() { signatureVerifiers = old })+ testVerifyReleaseSignature(t)+ })+ }+}++// A host with neither verifier gets an error that names what to install, not an exec failure.+func TestVerifyReleaseSignatureWithoutVerifier(t *testing.T) {+ old := signatureVerifiers+ signatureVerifiers = []string{"beacon-test-no-such-verifier"}+ t.Cleanup(func() { signatureVerifiers = old })+ _, err := goodSignatures(context.Background(), t.TempDir())+ if err == nil || !strings.Contains(err.Error(), "needs gpgv or sqv") {+ t.Fatalf("goodSignatures error = %v, want one naming gpgv or sqv", err)}+}++func testVerifyReleaseSignature(t *testing.T) {tampered := false// staleChecksums makes the next N checksums.txt downloads come from a different upload than// the signature, as a client sees while finalize replaces the pair.diff --git a/docs/platforms/linux.mdx b/docs/platforms/linux.mdxindex 884660f9..be6d4f2f 100644--- a/docs/platforms/linux.mdx+++ b/docs/platforms/linux.mdx@@ -45,19 +45,23 @@ APT reads a local package as its unprivileged `_apt` user. If the `.deb` sits so### From the apt repository (Debian, Ubuntu)-Beacon also publishes a signed apt repository at `https://apt.beacon.sh`, so `apt` installs the package and brings later releases in with your other updates. Download the repository key and check that it is Beacon's release key before you trust it. The second command must print `07BEA34ED6A411F4C066D98322F94195DCDC8F45` (see [Release signing](#release-signing)):--```bash title="Fetch and check the repository key"-curl -fsSL https://apt.beacon.sh/beacon-archive-keyring.gpg -o /tmp/beacon-archive-keyring.gpg-gpg --show-keys --with-colons /tmp/beacon-archive-keyring.gpg | awk -F: '$1 == "fpr" { print $10 }'-```--Then add the repository and install:+Beacon also publishes a signed apt repository at `https://apt.beacon.sh`, so `apt` installs the package and brings later releases in with your other updates. This block downloads the repository key into a private temporary directory, stops unless it is Beacon's release key (`07BEA34ED6A411F4C066D98322F94195DCDC8F45`, see [Release signing](#release-signing)), then adds the repository and installs. It needs `gpg` to read the key:```bash title="Add the repository and install"-sudo install -m 0644 /tmp/beacon-archive-keyring.gpg /usr/share/keyrings/beacon-archive-keyring.gpg-echo "deb [signed-by=/usr/share/keyrings/beacon-archive-keyring.gpg] https://apt.beacon.sh stable main" | sudo tee /etc/apt/sources.list.d/beacon.list-sudo apt update && sudo apt install beacon+(+ set -euo pipefail+ FPR=07BEA34ED6A411F4C066D98322F94195DCDC8F45+ DIR="$(mktemp -d)"+ trap 'rm -rf "$DIR"' EXIT+ curl -fsSL https://apt.beacon.sh/beacon-archive-keyring.gpg -o "$DIR/beacon-archive-keyring.gpg"+ GOT="$(GNUPGHOME="$DIR" gpg --batch --show-keys --with-colons "$DIR/beacon-archive-keyring.gpg" |+ awk -F: '$1 == "pub" { want = 1; next } want && $1 == "fpr" { print $10; want = 0 }')"+ [ "$GOT" = "$FPR" ] || { echo "unexpected repository key: ${GOT:-none}" >&2; exit 1; }+ sudo install -m 0644 "$DIR/beacon-archive-keyring.gpg" /usr/share/keyrings/beacon-archive-keyring.gpg+ echo "deb [signed-by=/usr/share/keyrings/beacon-archive-keyring.gpg] https://apt.beacon.sh stable main" |+ sudo tee /etc/apt/sources.list.d/beacon.list >/dev/null+ sudo apt update && sudo apt install beacon+)````apt` refuses the repository's index unless that key signed it, and checks every package against the index. The package is the same `.deb` the release publishes, so the install sets up the system service exactly as above, and `sudo apt upgrade` updates it. The repository starts at 1.3.57; for an older release, use the installer with `BEACON_VERSION` or the manual steps.@@ -286,7 +290,7 @@ sudo beacon endpoint update --checksudo beacon endpoint update --apply```-`--apply` downloads the release package for your platform, verifies its SHA-256, installs it with `dpkg` or `rpm`, restarts the collector, and rolls back if the new version fails its health check. Verification is checksum-over-HTTPS from GitHub Releases, the same trust root you used to download the package in the first place. macOS additionally verifies Apple notarization. On Linux, builds after 1.3.57 pin the release key (see [Release signing](#release-signing)), so the package must also be listed in a `checksums.txt` signed by that key, which needs `gpgv`. `beacon endpoint update` reports which verification it performed (`sha256`, `sha256+gpg` or `sha256+notarization`) rather than implying more.+`--apply` downloads the release package for your platform, verifies its SHA-256, installs it with `dpkg` or `rpm`, restarts the collector, and rolls back if the new version fails its health check. Verification is checksum-over-HTTPS from GitHub Releases, the same trust root you used to download the package in the first place. macOS additionally verifies Apple notarization. On Linux, builds after 1.3.57 pin the release key (see [Release signing](#release-signing)), so the package must also be listed in a `checksums.txt` signed by that key, which needs `gpgv` or `sqv`. `beacon endpoint update` reports which verification it performed (`sha256`, `sha256+gpg` or `sha256+notarization`) rather than implying more.## Release signingdiff --git a/docs/sharing/api-key.mdx b/docs/sharing/api-key.mdxindex 73255417..bc43a152 100644--- a/docs/sharing/api-key.mdx+++ b/docs/sharing/api-key.mdx@@ -114,7 +114,7 @@ Install Beacon in the image and pass the keys in at run time:```dockerfile title="Dockerfile"FROM node:22-slim-RUN apt-get update -qq && apt-get install -y -qq curl ca-certificates \+RUN apt-get update -qq && apt-get install -y -qq curl ca-certificates gpgv \&& curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bashWORKDIR /appCOPY . .diff --git a/packaging/linux/install.sh b/packaging/linux/install.shindex fab722d8..7b7b0521 100755--- a/packaging/linux/install.sh+++ b/packaging/linux/install.sh@@ -81,27 +81,41 @@ curl -fsSL "${base}/${package}" -o "${tmp}/${package}"curl -fsSL "${base}/checksums.txt" -o "${tmp}/checksums.txt"if [[ -n "$release_key_fingerprints" ]]; then- command -v gpgv >/dev/null 2>&1 || fail "gpgv is needed to verify the release signature; install gpgv or gnupg and rerun."+ # gpgv on most systems; sqv (Sequoia) where it replaces gpgv, as on Debian trixie-based images.+ if command -v gpgv >/dev/null 2>&1; then+ verifier=gpgv+ elif command -v sqv >/dev/null 2>&1; then+ verifier=sqv+ else+ fail "gpgv or sqv is needed to verify the release signature; install gpgv (apt-get install gpgv, dnf install gnupg2) and rerun."+ ficurl -fsSL "${base}/checksums.txt.sig" -o "${tmp}/checksums.txt.sig" || fail "${tag} has no checksums.txt.sig."curl -fsSL "${base}/beacon-release-key.gpg" -o "${tmp}/beacon-release-key.gpg" || fail "${tag} has no beacon-release-key.gpg."mkdir -m 0700 "${tmp}/gnupg"+ # Prints the primary-key fingerprint of each good signature, one per line, and fails when the+ # signature does not verify.verify_checksums() {- gpgv --homedir "${tmp}/gnupg" --keyring "${tmp}/beacon-release-key.gpg" --status-fd 1 \- "${tmp}/checksums.txt.sig" "${tmp}/checksums.txt" 2>/dev/null+ if [[ "$verifier" == gpgv ]]; then+ gpgv --homedir "${tmp}/gnupg" --keyring "${tmp}/beacon-release-key.gpg" --status-fd 1 \+ "${tmp}/checksums.txt.sig" "${tmp}/checksums.txt" 2>/dev/null |+ awk '$1 == "[GNUPG:]" && $2 == "VALIDSIG" { print $NF }'+ return "${PIPESTATUS[0]}"+ fi+ sqv --keyring "${tmp}/beacon-release-key.gpg" "${tmp}/checksums.txt.sig" "${tmp}/checksums.txt" 2>/dev/null}# The release's finalize job replaces checksums.txt and its signature after the release is public,# one asset at a time, so a download in those few seconds can pair files from different uploads.# Fetch both once more before giving up.- if ! status="$(verify_checksums)"; then+ if ! signers="$(verify_checksums)"; thensleep 5curl -fsSL "${base}/checksums.txt" -o "${tmp}/checksums.txt" || fail "${tag} has no checksums.txt."curl -fsSL "${base}/checksums.txt.sig" -o "${tmp}/checksums.txt.sig" || fail "${tag} has no checksums.txt.sig."- status="$(verify_checksums)" || fail "checksums.txt signature does not verify."+ signers="$(verify_checksums)" || fail "checksums.txt signature does not verify."fi# The key file comes from the release too, so only the pinned fingerprint makes it Beacon's.awk -v fprs="$release_key_fingerprints" 'BEGIN { n = split(toupper(fprs), pinned, ",") }- $1 == "[GNUPG:]" && $2 == "VALIDSIG" { for (i = 1; i <= n; i++) if (toupper($NF) == pinned[i]) ok = 1 }- END { exit !ok }' <<<"$status" ||+ { for (i = 1; i <= n; i++) if (toupper($1) == pinned[i]) ok = 1 }+ END { exit !ok }' <<<"$signers" ||fail "checksums.txt is not signed by a Beacon release key (${release_key_fingerprints})."fi