diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index cc7835a..6d648d5 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -1,21 +1,33 @@ name: Release # Fires when a version tag is pushed (e.g. `v0.4.0`). Cross-compiles static -# binaries (CGO_ENABLED=0; the SQLite driver is pure Go), writes SHA-256 -# checksums, and publishes them as a GitHub Release with generated notes. +# binaries (CGO_ENABLED=0; the SQLite driver is pure Go) and writes a CycloneDX +# SBOM and SHA-256 checksums in one job; a second job, which runs no build or +# test code, attests build provenance and the SBOM for every archive (keyless, +# through Sigstore with its OIDC token) and publishes them as a GitHub Release +# with generated notes. # The tag is the single source of the version: it is stamped into the binary # with -ldflags, so `codeshot --version` can never disagree with the release. +# Verify a download: `gh attestation verify --repo inth3shadows/codeshot +# --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml +# --source-ref refs/tags/`. on: push: tags: - "v*" -permissions: - contents: write # create the GitHub Release + upload assets; nothing more +permissions: {} jobs: - release: - name: Build + publish GitHub Release + # Runs the tests, the build and the SBOM tool, so it gets no signing + # permission: code here can't mint the OIDC token the attestations are + # signed with. It hands the release files to the publish job. + build: + name: Test, build + SBOM runs-on: ubuntu-latest + permissions: + contents: read + outputs: + version: ${{ steps.build.outputs.version }} steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1 with: @@ -29,8 +41,19 @@ jobs: run: sudo apt-get update && sudo apt-get install -y graphviz && go test ./... - name: Cross-compile + id: build run: | version="${GITHUB_REF_NAME#v}" + # A release tag is v (no leading zeros, optional pre-release): + # anything else would name the archives one way and give the SBOM a + # pseudo-version. + num='(0|[1-9][0-9]*)' + pre='(0|[1-9][0-9]*|[0-9]*[A-Za-z-][0-9A-Za-z-]*)' + if ! [[ "$version" =~ ^$num\.$num\.$num(-$pre(\.$pre)*)?$ ]]; then + echo "::error::tag ${GITHUB_REF_NAME} is not v..[-
]"
+            exit 1
+          fi
+          echo "version=${version}" >> "$GITHUB_OUTPUT"
           mkdir -p dist
           for target in linux/amd64 linux/arm64 darwin/amd64 darwin/arm64 windows/amd64 windows/arm64; do
             os="${target%/*}"; arch="${target#*/}"
@@ -47,9 +70,80 @@ jobs:
               tar -C dist -czf "dist/$name.tar.gz" "$name"
             fi
           done
-          (cd dist && sha256sum *.tar.gz *.zip > checksums.txt)
+          # One SBOM for the module (all six builds share its dependencies),
+          # pinned through the Go checksum database. The tag checkout gives it
+          # the version.
+          # -std lists the Go standard library compiled into every binary.
+          go run github.com/CycloneDX/cyclonedx-gomod/cmd/cyclonedx-gomod@v1.12.0 \
+            mod -licenses -std -json -output "dist/codeshot_${version}.cdx.json"
+          (cd dist && sha256sum *.tar.gz *.zip *.cdx.json > checksums.txt)
+
+      - name: Hand the release files to the publish job
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: release-files
+          path: |
+            dist/*.tar.gz
+            dist/*.zip
+            dist/*.cdx.json
+            dist/checksums.txt
+          if-no-files-found: error
+          retention-days: 7 # long enough to re-run publish on its own
+
+  # Signs and publishes; runs no build, test or third-party build code.
+  publish:
+    name: Attest + publish GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # create the GitHub Release + upload assets
+      id-token: write # the OIDC token Sigstore signs the attestations with
+      attestations: write # store the provenance and SBOM attestations
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-files
+          path: dist
+      # The build job could add or swap files; only the expected release files,
+      # listed in checksums.txt and nothing else, get attested and published.
+      - name: Check the release files are exactly the expected ones
+        env:
+          VERSION: ${{ needs.build.outputs.version }}
+        run: |
+          cd dist
+          expected=$(
+            for t in linux_amd64 linux_arm64 darwin_amd64 darwin_arm64; do echo "codeshot_${VERSION}_${t}.tar.gz"; done
+            for t in windows_amd64 windows_arm64; do echo "codeshot_${VERSION}_${t}.zip"; done
+            echo "codeshot_${VERSION}.cdx.json"
+          )
+          expected=$(echo "$expected" | LC_ALL=C sort)
+          listed=$(awk '{ sub(/^\*/, "", $2); print $2 }' checksums.txt | LC_ALL=C sort)
+          present=$(ls -1A | grep -vx 'checksums.txt' | LC_ALL=C sort)
+          if [ "$listed" != "$expected" ] || [ "$present" != "$expected" ]; then
+            echo "::error::the release files are not exactly the expected seven"
+            diff <(echo "$expected") <(echo "$listed") || true
+            diff <(echo "$expected") <(echo "$present") || true
+            exit 1
+          fi
+          sha256sum -c checksums.txt
+
+      # Provenance for every archive and the SBOM, in one attestation over the
+      # checksums file; then the SBOM, attested for the archives it describes.
+      # actions/attest directly: attest-build-provenance and attest-sbom are
+      # wrappers around it, and attest-sbom is deprecated.
+      - name: Attest build provenance
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-checksums: dist/checksums.txt
+      - name: Attest the SBOM
+        uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
+        with:
+          subject-path: |
+            dist/*.tar.gz
+            dist/*.zip
+          sbom-path: dist/codeshot_${{ needs.build.outputs.version }}.cdx.json
 
       - name: Publish GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
-        run: gh release create "${GITHUB_REF_NAME}" dist/*.tar.gz dist/*.zip dist/checksums.txt --generate-notes --title "${GITHUB_REF_NAME}"
+        run: gh release create "${GITHUB_REF_NAME}" dist/*.tar.gz dist/*.zip dist/*.cdx.json dist/checksums.txt --repo "${GITHUB_REPOSITORY}" --generate-notes --title "${GITHUB_REF_NAME}"
diff --git a/README.md b/README.md
index 8335103..e3c84c6 100644
--- a/README.md
+++ b/README.md
@@ -58,12 +58,30 @@ Generated diagrams are easy; trusted ones aren't. Tools like madge, pyan and go-
 
 ## Install
 
-Download a binary for your platform from [Releases](https://github.com/inth3shadows/codeshot/releases) (checksums in `checksums.txt`), or build from source with Go 1.26+:
+Download a binary for your platform from [Releases](https://github.com/inth3shadows/codeshot/releases), or build from source with Go 1.26+:
 
 ```bash
 go install github.com/inth3shadows/codeshot/cmd/codeshot@latest
 ```
 
+From v0.5.0 on, every release archive comes with a signed record of the workflow run that built it ([build provenance](https://slsa.dev/provenance/), keyless through Sigstore) and a [CycloneDX](https://cyclonedx.org/) SBOM, `codeshot_.cdx.json`, attested for the same archives. To check a download with the [GitHub CLI](https://cli.github.com/):
+
+```bash
+sha256sum -c checksums.txt --ignore-missing   # download intact (Linux; macOS: shasum -a 256 -c ...)
+gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \
+  --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/v0.5.0
+gh attestation verify codeshot_0.5.0_linux_amd64.tar.gz --repo inth3shadows/codeshot \
+  --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/v0.5.0 \
+  --predicate-type https://cyclonedx.org/bom    # the SBOM attestation
+```
+
+The checksum line only shows the download is intact: `checksums.txt` comes from
+the same release and isn't signed itself. The attestation is the proof of
+origin. `--signer-workflow` and `--source-ref` require it to come from
+`release.yml` running for that tag, not from any other workflow in the repo;
+they trust whatever `release.yml` was at the tagged commit, so they are as
+strong as the protection on `v*` tags.
+
 Codeshot is a single static binary; it needs no Node of its own. `codeshot --version` prints the release version for release binaries and `go install ...@vX.Y.Z`, and `dev` for any other build.
 
 **Requirements:**
diff --git a/TECHNICAL.md b/TECHNICAL.md
index 529a78b..3b66942 100644
--- a/TECHNICAL.md
+++ b/TECHNICAL.md
@@ -263,7 +263,7 @@ codeshot BuildDot --path . --format svg --out docs/BuildDot-callgraph.svg --embe
 codeshot --architecture --path . --max-symbols 5000 --group-depth 2 --rules .codeshot.yaml --format mermaid --embed README.md
 ```
 
-CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git  && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes `checksums.txt`, and publishes them as a GitHub Release.
+CI (`.github/workflows/ci.yml`) has three jobs. `test` runs `gofmt`, `go vet`, `go test ./...` (no codegraph, so the end-to-end tests self-skip) and golangci-lint v2.15.0. `test-npm-codegraph` runs `go test ./...` again with npm codegraph 1.6.0 installed and this repo indexed, so the end-to-end tests run; a weekly scheduled run swaps in unpinned `@latest`, to catch an upstream release that changes the output codeshot parses or the index schema `--architecture` reads. `diagrams` is a separate blocking job: it builds codegraph from the inth3shadows/codegraph fork at tag `v1.6.2-em.44` (commit `d9d138de`, pinned by SHA since tags are mutable, WASM-only — upstream 1.6.2 plus the fork's narrow patches), builds a fresh index and `codeshot`, and runs the three diagram commands above with `--check`, one step each so a PR learns of every stale diagram in one run, so a PR that changes the call graph without regenerating the committed SVGs and README's Mermaid block fails. The committed diagrams must be regenerated with that same build, from a fresh clone (a reused index can miss edges a fresh `init` finds). With Node 22 for every step (codegraph refuses Node 25+), build the commit CI pins in a directory outside this repo, so `init` doesn't index it: `git init cg && git -C cg fetch --depth 1 https://github.com/inth3shadows/codegraph.git  && git -C cg checkout FETCH_HEAD && (cd cg && npm ci && npm run build)`. Put a `codegraph` on `PATH` that runs `CODEGRAPH_KERNEL=0 node /dist/bin/codegraph.js "$@"` (CI writes the same wrapper), then in a fresh clone of this repo run `codegraph init .` and the three diagram commands above without `--check`. Pushing a `v*` tag runs `.github/workflows/release.yml` in two jobs. `build` (`contents: read` only) refuses a tag that isn't `v` (no leading zeros; an optional pre-release), runs the tests, cross-compiles six static binaries (linux, darwin and windows, amd64 and arm64; `CGO_ENABLED=0`) with the version stamped in by `-ldflags`, writes one CycloneDX SBOM of the module including the Go standard library (`cyclonedx-gomod` v1.12.0 `mod -licenses -std` through `go run`, so the Go checksum database pins it; the tag checkout gives it the version) and `checksums.txt` over the archives and the SBOM, and uploads them as a one-day artifact. `publish` (`contents`, `id-token` and `attestations: write`) runs no build, test or third-party build code: it downloads the files, checks them against `checksums.txt`, refuses unless `checksums.txt` lists, and the artifact holds, exactly the seven expected files for the version (six archives and the SBOM), attests build provenance for them and the SBOM for the six archives (`actions/attest` v4.2.2 both times, SHA-pinned; `attest-build-provenance` and the deprecated `attest-sbom` are wrappers around it), and publishes the GitHub Release. Splitting the jobs keeps the OIDC token away from the tests and the SBOM tool's dependencies, which could otherwise mint it and attest any file as built here; a compromised build job can still change the bytes of the seven files it hands over, which no signing step can tell apart from a real build. The artifact is kept seven days, so `publish` can be re-run on its own. The attestations are keyless: Sigstore signs them with that token, and the workflow grants nothing at the top level. `gh attestation verify  --repo inth3shadows/codeshot --signer-workflow inth3shadows/codeshot/.github/workflows/release.yml --source-ref refs/tags/` checks a download; it trusts whatever `release.yml` was at the tagged commit, so it is as strong as the protection on `v*` tags. Cosign `sign-blob` and a GPG key were rejected: the attestation already carries a Sigstore signature, and a long-lived key would need storing and rotating.
 
 There is no service to restart, no rollback beyond installing a prior release or git ref, and no other services, logs, or scheduled jobs to maintain — see [README.md](README.md#install) for the install command itself.