Skip to content

Verify Click-Dog releases

Click-Dog releases provide two related checks:

  1. SHA-256 binds the downloaded archive or script to checksums.txt.
  2. A keyless cosign signature authenticates checksums.txt as output from Click-Dog's public GitHub Actions release workflow.

The standard installer always verifies a downloaded binary archive's SHA-256. When cosign is available, it also authenticates the checksum manifest. If cosign is absent, it warns and continues after the checksum matches. If an installed cosign fails or times out, installation stops instead of silently downgrading to checksum-only verification.

cosign is recommended, not required for the standard installation. Install and configure it using Sigstore's official Cosign documentation. Keyless verification needs outbound HTTPS to rekor.sigstore.dev and fulcio.sigstore.dev.

Authenticate install.sh before sudo

The two-line quick start downloads install.sh over HTTPS and then runs it as root. Use this stricter procedure when you must authenticate the bootstrap script itself before granting it root privileges.

It pins all four files to one release, authenticates checksums.txt, then checks the exact install.sh hash. It does not execute the installer:

(
  set -euo pipefail

  LATEST_URL="$(curl -fsSL -o /dev/null -w '%{url_effective}' \
    https://github.com/coltconsulting/click-dog/releases/latest)"
  VERSION="${LATEST_URL##*/v}"
  BASE="https://github.com/coltconsulting/click-dog/releases/download/v${VERSION}"

  curl -fsSL "${BASE}/install.sh" -o install.sh
  curl -fsSL "${BASE}/checksums.txt" -o checksums.txt
  curl -fsSL "${BASE}/checksums.txt.sig" -o checksums.txt.sig
  curl -fsSL "${BASE}/checksums.txt.pem" -o checksums.txt.pem

  cosign verify-blob \
    --certificate checksums.txt.pem \
    --signature checksums.txt.sig \
    --certificate-identity-regexp '^https://github\.com/coltconsulting/click-dog/\.github/workflows/release\.yml@refs/tags/v.+$' \
    --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
    checksums.txt

  if ! awk '$2 == "install.sh" { print; matches++ } END { exit(matches == 1 ? 0 : 1) }' \
      checksums.txt > install.sh.sha256; then
    echo "install.sh is missing from checksums.txt or appears more than once" >&2
    exit 1
  fi

  if command -v sha256sum >/dev/null 2>&1; then
    sha256sum -c install.sh.sha256
  elif command -v shasum >/dev/null 2>&1; then
    shasum -a 256 -c install.sh.sha256
  else
    echo "sha256sum or shasum is required" >&2
    exit 1
  fi
)

Only after both verification commands exit zero should you run:

sudo bash install.sh

Reading the script can help you understand it, but source review is not a cryptographic integrity check.

Automatic archive verification

install.sh, click-dog self-update, and the Ansible playbook use the same release chain when they download an official archive:

  • resolve one public release
  • download its archive and checksums.txt
  • authenticate checksums.txt when cosign is available
  • require the exact archive SHA-256 from that manifest
  • smoke-test the extracted binary before installing it

No GitHub token is required because the repository and release assets are public. GITHUB_TOKEN or GH_TOKEN is optional and can help hosts that share GitHub's unauthenticated API rate limit.

If cosign is installed but verification fails, fix the signature or Sigstore connectivity problem. To deliberately accept checksum-only verification, rerun with --dangerously-ignore-cosign. That override never skips the archive SHA-256 check.

Verifying releases manually

Use this procedure when downloading a Linux release archive directly. It requires cosign, plus sha256sum or an equivalent SHA-256 tool:

LATEST_URL="$(curl -fsSL -o /dev/null -w '%{url_effective}' \
  https://github.com/coltconsulting/click-dog/releases/latest)" || exit 1
VERSION="${LATEST_URL##*/v}"
BASE="https://github.com/coltconsulting/click-dog/releases/download/v${VERSION}"

curl -fsSL -O "${BASE}/click-dog_${VERSION}_linux_amd64.tar.gz"
curl -fsSL -O "${BASE}/checksums.txt"
curl -fsSL -O "${BASE}/checksums.txt.sig"
curl -fsSL -O "${BASE}/checksums.txt.pem"

cosign verify-blob \
  --certificate checksums.txt.pem \
  --signature checksums.txt.sig \
  --certificate-identity-regexp '^https://github\.com/coltconsulting/click-dog/\.github/workflows/release\.yml@refs/tags/v.+$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  checksums.txt

sha256sum -c checksums.txt --ignore-missing

Both commands must exit zero before extracting or running the binary. A signature failure means the manifest is not authenticated as an output from the Click-Dog release workflow.

Verify a container image

Container images at ghcr.io/coltconsulting/click-dog are signed with the same release-workflow identity. Resolve a release version, then verify the exact image tag:

LATEST_URL="$(curl -fsSL -o /dev/null -w '%{url_effective}' \
  https://github.com/coltconsulting/click-dog/releases/latest)" || exit 1
VERSION="${LATEST_URL##*/v}"

cosign verify ghcr.io/coltconsulting/click-dog:${VERSION} \
  --certificate-identity-regexp '^https://github\.com/coltconsulting/click-dog/\.github/workflows/release\.yml@refs/tags/v.+$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com'

Use the bare version in the image tag (26.08.2, not v26.08.2).

Air-gapped environments

Verify and extract on an internet-connected machine, then transfer the verified binary into the restricted network. The verification host needs access to GitHub, Rekor, and Fulcio.

# First run the complete manual verification above. Then extract the archive
# using the same VERSION value and transfer the resulting binary.
tar -xzf "click-dog_${VERSION}_linux_amd64.tar.gz"
scp click-dog bastion:/tmp/click-dog
scp deploy/install.sh bastion:/tmp/install.sh
ssh bastion 'sudo bash /tmp/install.sh install -c collector:4317 -b /tmp/click-dog --systemd'

The -b path treats the supplied binary as already verified and skips release download and automatic verification. For a fleet, pass the verified binary to Ansible as click_dog_local_binary=/path/to/click-dog; see Ansible.

Proxies and restricted egress

The installer accepts -x for release downloads, and standard proxy variables also work:

sudo bash install.sh install -c collector:4317 -x http://proxy.corp:3128 --systemd

# or
export HTTPS_PROXY=http://proxy.corp:3128

When cosign is available, blocking Rekor or Fulcio makes verification fail closed after its bounded timeout. Either allow those hosts, verify on a connected machine and supply the resulting binary, or make the weaker checksum-only choice explicit with --dangerously-ignore-cosign.