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
184 changes: 183 additions & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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*"]
Expand Down Expand Up @@ -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:
Expand All @@ -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 <file>.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 <file> --repo ...`) and its bundle is also
# shipped as osiris-<tag>.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 <<EOF
## Verify this release

Every file is signed keylessly with Sigstore (\`<file>.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
114 changes: 108 additions & 6 deletions DOCKER.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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`:
Expand Down Expand Up @@ -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/<channel>` 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 |
| `<file>.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)).
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "osiris",
"version": "0.1.0",
"version": "0.2.0",
"private": true,
"scripts": {
"dev": "next dev --webpack",
Expand Down
Loading