diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b967913..65b8ece 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,6 +1,12 @@ name: release -# Build, publish and sign the container image on GitHub Packages (GHCR) on a version tag. +# On a version tag: +# container - build, push and keyless-sign the image on GHCR (SBOM + provenance attached) +# artifacts - build the source archive, Next.js standalone bundle and npm SBOM; +# write SHA256SUMS, keyless-sign every file (Sigstore bundles) and +# attest SLSA v1 build provenance for them +# release - create the GitHub Release with all of the above as assets +# workflow_dispatch only runs the container job (no tag, so nothing to release). on: push: tags: ["v*"] @@ -58,6 +64,8 @@ jobs: run: | images="" for tag in ${TAGS}; do images+="${tag}@${DIGEST} "; done + # Word splitting of images is intended (one ref per tag). + # shellcheck disable=SC2086 cosign sign --yes ${images} - name: Verify the signature env: @@ -69,3 +77,177 @@ jobs: --certificate-identity "${IDENTITY}" \ --certificate-oidc-issuer https://token.actions.githubusercontent.com > /dev/null echo "Signature verified for ${IMAGE}@${DIGEST}" + + artifacts: + if: startsWith(github.ref, 'refs/tags/v') + runs-on: ubuntu-latest + timeout-minutes: 30 + permissions: + contents: read + id-token: write # keyless Sigstore signing of the release files + attestations: write # store the build provenance attestation + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 22 + cache: npm + + - run: npm ci + + - name: Build + env: + NEXT_TELEMETRY_DISABLED: "1" + run: npm run build + + # Source archive: git archive output is a pure function of the tagged + # commit (mtimes = commit time) and gzip -n drops the name/timestamp, so + # anyone can rebuild it byte for byte from the tag. + # Standalone bundle: the layout from Next's standalone deployment docs + # (.next/standalone + .next/static + public), runnable with `node server.js`, + # tarred with sorted names, fixed mtimes and numeric root ownership. + - name: Package release files + env: + TAG: ${{ github.ref_name }} + run: | + set -euo pipefail + epoch="$(git log -1 --format=%ct)" + mkdir -p dist + + git archive --format=tar --prefix="osiris-${TAG}/" HEAD \ + | gzip -n -9 > "dist/osiris-${TAG}-source.tar.gz" + + stage_root="$(mktemp -d)" + stage="${stage_root}/osiris-${TAG}" + mkdir -p "${stage}/.next" "${stage}/public" + cp -a .next/standalone/. "${stage}/" + cp -a .next/static "${stage}/.next/static" + cp -a public/. "${stage}/public/" + tar --sort=name --mtime="@${epoch}" --owner=0 --group=0 --numeric-owner \ + --format=posix --pax-option=exthdr.name=%d/PaxHeaders/%f,delete=atime,delete=ctime \ + -C "${stage_root}" -cf - "osiris-${TAG}" \ + | gzip -n -9 > "dist/osiris-${TAG}-standalone.tar.gz" + + # CycloneDX SBOM of the production npm dependency tree, generated by + # npm itself (npm sbom) from the lockfile-installed node_modules. + npm sbom --sbom-format=cyclonedx --omit=dev > "dist/osiris-${TAG}-sbom.cdx.json" + + (cd dist && sha256sum -- osiris-* > SHA256SUMS && cat SHA256SUMS) + + - uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2 + + # Keyless: each .sigstore.json bundle holds the signature, the + # short-lived Fulcio certificate (identity = this workflow at this tag) + # and the Rekor transparency-log entry. + - name: Sign release files + run: | + set -euo pipefail + files=(dist/osiris-* dist/SHA256SUMS) + for f in "${files[@]}"; do + cosign sign-blob --yes --bundle "${f}.sigstore.json" "${f}" > /dev/null + done + ls -l dist + + - name: Verify the signatures + env: + IDENTITY: https://github.com/${{ github.repository }}/.github/workflows/release.yml@${{ github.ref }} + run: | + set -euo pipefail + for bundle in dist/*.sigstore.json; do + f="${bundle%.sigstore.json}" + cosign verify-blob "${f}" --bundle "${bundle}" \ + --certificate-identity "${IDENTITY}" \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com + done + + # SLSA v1 build provenance (in-toto statement, Sigstore-signed) for every + # file listed in SHA256SUMS. It is stored in the repo's attestations + # (`gh attestation verify --repo ...`) and its bundle is also + # shipped as osiris-.intoto.jsonl so it can be verified offline and + # is recognised as provenance by OpenSSF Scorecard. A SHA-pinned action is + # used instead of slsa-github-generator, whose reusable workflow can only + # be pinned by tag (Scorecard counts that as an unpinned dependency). + - name: Attest build provenance + id: attest + uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 + with: + subject-checksums: dist/SHA256SUMS + + - name: Add and verify the provenance + env: + BUNDLE: ${{ steps.attest.outputs.bundle-path }} + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.ref_name }} + REPO: ${{ github.repository }} + run: | + set -euo pipefail + provenance="dist/osiris-${TAG}.intoto.jsonl" + cp "${BUNDLE}" "${provenance}" + for f in dist/osiris-*.tar.gz dist/osiris-*-sbom.cdx.json; do + gh attestation verify "${f}" --repo "${REPO}" --bundle "${provenance}" \ + --signer-workflow "${REPO}/.github/workflows/release.yml" \ + --source-ref "refs/tags/${TAG}" --deny-self-hosted-runners + done + + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: release-files + path: dist/ + if-no-files-found: error + retention-days: 5 + + release: + needs: [container, artifacts] + if: startsWith(github.ref, 'refs/tags/v') + runs-on: ubuntu-latest + timeout-minutes: 15 + permissions: + contents: write # create the GitHub Release and upload its assets + steps: + - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: release-files + path: dist + + # No CHANGELOG in the repo, so the notes are GitHub's generated notes + # with a verification preamble prepended. + - name: Publish the release + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ github.ref_name }} + REPO: ${{ github.repository }} + run: | + set -euo pipefail + (cd dist && sha256sum -c SHA256SUMS) + version="${TAG#v}" + cat > notes.md <.sigstore.json\`) by + \`.github/workflows/release.yml\` at \`refs/tags/${TAG}\`, and covered by SLSA + build provenance (\`osiris-${TAG}.intoto.jsonl\`). See + [DOCKER.md](https://github.com/${REPO}/blob/${TAG}/DOCKER.md#4-verifying-a-release). + + \`\`\`bash + sha256sum -c SHA256SUMS + cosign verify-blob --bundle SHA256SUMS.sigstore.json \\ + --certificate-identity 'https://github.com/${REPO}/.github/workflows/release.yml@refs/tags/${TAG}' \\ + --certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS + gh attestation verify osiris-${TAG}-standalone.tar.gz --repo ${REPO} \\ + --bundle osiris-${TAG}.intoto.jsonl \\ + --signer-workflow ${REPO}/.github/workflows/release.yml --source-ref refs/tags/${TAG} + \`\`\` + + Container image: \`ghcr.io/${REPO}:${version}\` (signed with cosign, SBOM + provenance attached). + + EOF + if gh release view "${TAG}" --repo "${REPO}" > /dev/null 2>&1; then + # Re-run of a tag whose release already exists: refresh the assets. + gh release upload "${TAG}" dist/* --repo "${REPO}" --clobber + else + gh release create "${TAG}" dist/* --repo "${REPO}" --verify-tag \ + --title "${TAG}" --notes-file notes.md --generate-notes + fi diff --git a/DOCKER.md b/DOCKER.md index db435d4..8861313 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -2,7 +2,8 @@ OSIRIS ships as a self-contained Next.js standalone build. This guide covers running it with Docker / Docker Compose, deploying it as a [CasaOS](https://casaos.io) -app, and configuring the optional API keys. +app, configuring the optional API keys, and +[verifying a signed release](#4-verifying-a-release). > **TL;DR:** OSIRIS runs fully **without any API keys**. All core feeds > (aviation, satellites, fires, earthquakes, weather, news, CVEs) use public @@ -55,7 +56,7 @@ A prebuilt multi-arch-friendly image is published to the GitHub Container Registry, so you can run OSIRIS without building anything: ```bash -docker pull ghcr.io/carbon-evolution/osiris:latest # or a pinned tag, e.g. :0.1.0 +docker pull ghcr.io/carbon-evolution/osiris:latest # or a pinned tag, e.g. :0.2.0 docker run -d --name osiris \ -p 3005:3000 --env-file .env --restart unless-stopped \ ghcr.io/carbon-evolution/osiris:latest @@ -69,13 +70,16 @@ To check that an image was built by this repository's release workflow for a given tag (install cosign first, e.g. `brew install cosign`): ```bash -cosign verify ghcr.io/carbon-evolution/osiris:0.1.0 \ - --certificate-identity https://github.com/carbon-evolution/osiris/.github/workflows/release.yml@refs/tags/v0.1.0 \ +cosign verify ghcr.io/carbon-evolution/osiris:0.2.0 \ + --certificate-identity https://github.com/carbon-evolution/osiris/.github/workflows/release.yml@refs/tags/v0.2.0 \ --certificate-oidc-issuer https://token.actions.githubusercontent.com ``` -Replace `0.1.0` / `v0.1.0` with the release you pulled. A non-zero exit means -the image was not signed by this workflow — don't run it. +Replace `0.2.0` / `v0.2.0` with the release you pulled. A non-zero exit means +the image was not signed by this workflow — don't run it. (Image signing was +added after `0.1.0`, so `0.1.0` has no signature.) The release's downloadable +files carry their own signatures and provenance — see +[Verifying a release](#4-verifying-a-release). > If the package is **private**, authenticate first with a GitHub token that > has `read:packages`: @@ -192,3 +196,101 @@ public traffic-authority feeds · Crypto (BTC) → `blockstream.info` · Crypto (ETH) → `eth.blockscout.com` ([Blockscout](https://github.com/blockscout/blockscout) open-source explorer) · OFAC SDN sanctions → [OpenSanctions](https://www.opensanctions.org) mirror (CC-BY 4.0) · Telegram OSINT → public `t.me/s/` web preview. + +--- + +## 4. Verifying a release + +Every `vX.Y.Z` tag runs [`release.yml`](.github/workflows/release.yml), which +publishes a [GitHub Release](https://github.com/carbon-evolution/osiris/releases) +with these assets (example for `v0.2.0`): + +| Asset | What it is | +|-------|------------| +| `osiris-v0.2.0-source.tar.gz` | `git archive` of the tagged commit (reproducible) | +| `osiris-v0.2.0-standalone.tar.gz` | Next.js standalone build: `.next/standalone` + `.next/static` + `public`, run with `node server.js` | +| `osiris-v0.2.0-sbom.cdx.json` | CycloneDX SBOM of the production npm dependency tree (`npm sbom`) | +| `SHA256SUMS` | SHA-256 of the three files above | +| `.sigstore.json` | Keyless [Sigstore](https://docs.sigstore.dev/) bundle (signature + certificate + Rekor entry) for each file above, including `SHA256SUMS` | +| `osiris-v0.2.0.intoto.jsonl` | [SLSA](https://slsa.dev/) v1 build provenance for the three files: the Sigstore bundle from [`actions/attest-build-provenance`](https://github.com/actions/attest-build-provenance) (also listed under the repo's [attestations](https://github.com/carbon-evolution/osiris/attestations)) | + +The signing identity is the release workflow at the tag, issued by GitHub's +OIDC provider; there are no long-lived keys. Install the tools with e.g. +`brew install cosign gh` (see the +[cosign](https://docs.sigstore.dev/cosign/system_config/installation/) and +[GitHub CLI](https://cli.github.com/) install docs). Replace `v0.2.0` / `0.2.0` +below with the release you downloaded. + +**1. Checksums** (on macOS use `shasum -a 256 -c SHA256SUMS`): + +```bash +sha256sum -c SHA256SUMS +``` + +**2. Signatures** — the checksum file, or any single file: + +```bash +cosign verify-blob --bundle SHA256SUMS.sigstore.json \ + --certificate-identity 'https://github.com/carbon-evolution/osiris/.github/workflows/release.yml@refs/tags/v0.2.0' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com \ + SHA256SUMS + +cosign verify-blob --bundle osiris-v0.2.0-standalone.tar.gz.sigstore.json \ + --certificate-identity 'https://github.com/carbon-evolution/osiris/.github/workflows/release.yml@refs/tags/v0.2.0' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com \ + osiris-v0.2.0-standalone.tar.gz +``` + +**3. SLSA provenance** — proves the file was built by this repository's +release workflow from the tagged source, on a GitHub-hosted runner: + +```bash +gh attestation verify osiris-v0.2.0-standalone.tar.gz \ + --repo carbon-evolution/osiris \ + --bundle osiris-v0.2.0.intoto.jsonl \ + --signer-workflow carbon-evolution/osiris/.github/workflows/release.yml \ + --source-ref refs/tags/v0.2.0 \ + --deny-self-hosted-runners +``` + +Drop `--bundle ...` to check against the attestation stored on GitHub instead +of the downloaded file. Repeat for `osiris-v0.2.0-source.tar.gz` and +`osiris-v0.2.0-sbom.cdx.json`. + +**4. Container image** — signature, then the attached provenance and SBOM: + +```bash +cosign verify ghcr.io/carbon-evolution/osiris:0.2.0 \ + --certificate-identity 'https://github.com/carbon-evolution/osiris/.github/workflows/release.yml@refs/tags/v0.2.0' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com + +docker buildx imagetools inspect ghcr.io/carbon-evolution/osiris:0.2.0 --format '{{ json .Provenance }}' +docker buildx imagetools inspect ghcr.io/carbon-evolution/osiris:0.2.0 --format '{{ json .SBOM }}' +``` + +Any non-zero exit means the artifact was not produced by this workflow at that +tag — don't use it. + +**Reproduce the source archive.** The tarball is `git archive` piped through +GNU `gzip -n -9`, so the uncompressed tar is identical to what you get from a +clone (and the `.tar.gz` too, on Linux with GNU gzip): + +```bash +git archive --format=tar --prefix=osiris-v0.2.0/ v0.2.0 | sha256sum +gunzip -c osiris-v0.2.0-source.tar.gz | sha256sum # same hash +``` + +### Running the standalone build (no Docker) + +The standalone bundle is built on GitHub's `ubuntu-latest` (linux-x64, glibc) +with Node 22, so native dependencies (e.g. `sharp`) are linux-x64 binaries; +on other platforms use the container image or build from source. + +```bash +tar xzf osiris-v0.2.0-standalone.tar.gz +cd osiris-v0.2.0 +PORT=3000 HOSTNAME=0.0.0.0 node server.js +``` + +Configuration is the same as for the image (environment variables, see +[section 3](#3-api-keys--data-sources)). diff --git a/README.md b/README.md index dde0039..a298639 100644 --- a/README.md +++ b/README.md @@ -352,6 +352,24 @@ Build for production: npm run build && npm start ``` +### Signed releases + +Each [GitHub Release](https://github.com/carbon-evolution/osiris/releases) +ships a source archive, a prebuilt Next.js standalone bundle (run with +`node server.js`), an npm SBOM and `SHA256SUMS`, each with a keyless Sigstore +signature (`.sigstore.json`) plus SLSA build provenance (`.intoto.jsonl`); the +container image on GHCR is signed too. Quick check: + +```bash +sha256sum -c SHA256SUMS +cosign verify-blob --bundle SHA256SUMS.sigstore.json \ + --certificate-identity 'https://github.com/carbon-evolution/osiris/.github/workflows/release.yml@refs/tags/vX.Y.Z' \ + --certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS +``` + +Full steps (provenance, image) in +[DOCKER.md → Verifying a release](DOCKER.md#4-verifying-a-release). + --- ## 💻 Configuration diff --git a/package-lock.json b/package-lock.json index 1a04503..917a255 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "osiris", - "version": "0.1.0", + "version": "0.2.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "osiris", - "version": "0.1.0", + "version": "0.2.0", "dependencies": { "@deck.gl/core": "^9.3.4", "@deck.gl/layers": "^9.3.4", diff --git a/package.json b/package.json index 4608cbb..3621bd6 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "osiris", - "version": "0.1.0", + "version": "0.2.0", "private": true, "scripts": { "dev": "next dev --webpack",