Add THIRD_PARTY_NOTICES.md and tooling to generate it

[abrarshivani]

Summary

Adds THIRD_PARTY_NOTICES.md, a single file carrying the license of every Go dependency behind the released artifacts, and tools/generate-notices which produces it. make notices regenerates it, make notices-check verifies it is current, and a CI job runs that check on every build.

Note for reviewers

~98% of this diff is generated output and does not need reading. Of 28,570 added lines, 27,875 are machine-produced: THIRD_PARTY_NOTICES.md is the tool's output, and tools/go.sum comes from go mod tidy.

The hand-written change is 695 lines across 8 files:

File	Lines	What it is
tools/generate-notices	503	The main thing to review. The generator: named functions behind a main(), ~75 lines of it comments.
.github/workflows/release-third-party-notices.yaml	94	Attaches the notices file to the GitHub Release
.github/workflows/notices-check.yaml	62	CI job: regenerate and diff
Makefile	19	notices and notices-check targets
tools/go.mod	7	Pins go-licenses v2.0.1
.github/workflows/ci.yaml	6	Calls the new job
.gitignore	3	Ignores /.licenses-cache, the generator's scratch tree
tools/tools.go	1	go-licenses import so install-tools builds it

Generated — skim or skip	Lines
THIRD_PARTY_NOTICES.md	27,778
tools/go.sum	97

If you only read one thing, read tools/generate-notices. To spot-check the output, the two index tables at the top of THIRD_PARTY_NOTICES.md are the summary; everything below them is verbatim license text.

How THIRD_PARTY_NOTICES.md is generated

Prerequisites: Go (version from versions.mk) and go-licenses, which make install-tools puts in ./bin from the pin in tools/go.mod. The main module is vendored, so the runtime pass needs no network; the toolchain pass resolves from the module cache and will download on a cold one.

make notices          # regenerate
make notices-check    # regenerate and fail if the committed file differs

What tools/generate-notices does, in order:

1. Checks prerequisites — finds go and go-licenses, preferring ./bin/go-licenses over $PATH so the pinned version is the one that runs.
2. Verifies the platform matrix — reads DOCKER_BUILD_PLATFORM_OPTIONS from multi-arch.mk and fails if the script's PLATFORMS array has drifted from the platforms the image is actually released for.
3. Collects runtime licenses, once per platform. For each of linux/amd64 and linux/arm64, with GOFLAGS=-mod=vendor and CGO_ENABLED=0: runs go-licenses save to copy every license file into .licenses-cache, and go-licenses csv to record the classifications. Results are unioned across platforms. Only the local module is passed to --ignore — go-licenses excludes the standard library itself, and --ignore matches raw string prefixes, so anything shorter and more generic silently drops real dependencies.
4. Collects build toolchain licenses the same way, from tools/go.mod, over four platforms including darwin. The tool list is read out of tools/tools.go rather than duplicated, so it cannot drift from what make install-tools builds.
5. Collapses the rows. Sorts whole lines to get a total order, then joins every distinct license for a package rather than keeping one, so dual- and multi-licensed dependencies report all of them.
6. Attaches module versions — maps each package to its providing module by longest-prefix match against vendor/modules.txt, giving the exact module@version.
7. Composes the document — header, an index table per surface, then each dependency's license text verbatim, fenced with a backtick run long enough to survive licenses that are themselves Markdown.

7 writes to a temp file and moves it into place, so an interrupted run cannot leave a truncated committed file.

Output is deterministic: LC_ALL=C sorting and the platform union make it byte-identical regardless of which machine runs it — verified by generating on macOS and in a Linux container and comparing sha256.

To add a dependency, nothing special is needed — change go.mod, run go mod vendor, then make notices and commit the result. CI fails the PR if you forget.

Scope

This document covers Go dependencies. It does not inventory the non-Go contents of the released image — the packages inherited from the base image, the BusyBox tree, the CUDA sample, or the CUDA compatibility libraries. Base image dependencies are covered by that image's own compliance process, and the remaining components are handled through separate flows, including any source-distribution obligations they carry. The generated file states this in its header rather than claiming to cover everything shipped.

How the file is shipped

The notices file is not copied into the runtime image, so image size is unchanged. It is published as a GitHub Release asset instead: release-third-party-notices.yaml triggers on release: published, checks out the tagged commit and uploads the committed file, failing if it is missing or empty. Nothing is regenerated at release time — notices-check already proves the committed file matches the tree. The workflow follows release-image-list.yaml, which attaches a generated artifact the same way. It also accepts workflow_dispatch with a tag, for backfilling an existing release.

Attaching to the image in the registry was considered and deferred, and the workflow records why. nvcr.io does not implement the OCI 1.1 referrers API — GET /v2/nvidia/gpu-operator/referrers/<digest> returns {"code":"UNSUPPORTED"}. The repository does carry per-digest artifacts through the cosign tag scheme (240 sha256-<digest>.{sig,sbom,vex} tags, including SPDX SBOMs), but those are attached by the downstream publishing pipeline, not by anything in this repository. Binding notices to an image digest is therefore a request to that pipeline rather than a change here, and worth revisiting once we know whether OSRB wants digest-bound license texts alongside the existing SBOM.

Why a wrapper instead of go-licenses directly

go-licenses resolves the dependency graph for a single platform, the host's. Build-tagged sources pull in different transitive dependencies per platform, so running it once gives a file that is both incomplete — missing everything the non-host platforms bring in — and dependent on who ran it, which would make any freshness check flap between a macOS laptop and a Linux runner.

tools/generate-notices runs it once per target, unions the results, and sorts deterministically so the output is byte-identical on any host. The runtime matrix is the image platforms from multi-arch.mk, and a guard fails the run if the array and the makefile drift apart. The toolchain matrix additionally covers darwin, since those binaries get built on developer machines as well as in CI.

Correctness details worth review

Multi-licensed dependencies report every license. go-licenses emits one row per recognized license. Collapsing on the package field kept exactly one: filepath-securejoin showed as BSD-3-Clause with its MPL-2.0 disclosure dropped, and klauspost/compress, sigs.k8s.io/yaml and sigs.k8s.io/json each lost two. Which row survived was also unstable — sort -u with a key compares only that key, so BSD sort keeps whichever came first in input order while GNU sort applies a whole-line tiebreak, so macOS and Linux could disagree. Sorting whole lines first gives a total order, and licenses are now joined rather than discarded.

Vendored dependencies are identified by module@version. In vendor mode go-licenses reports a URL into this repository at HEAD, which stops describing released content once main advances and names our vendor copy rather than upstream. vendor/modules.txt has the exact version behind every vendored package, so entries carry that instead. All 124 resolve.

Scope of the runtime scan

Scoped to ./cmd/... rather than ./.... That is exactly the set make cmds builds — CMDS is a wildcard over ./cmd/*, and the Dockerfile builds the image by running make cmds — so it tracks the build definition rather than a hand-maintained list. Measured against ./..., the only difference is github.com/onsi/ginkgo/v2 and github.com/onsi/gomega/format from the e2e suite, which is never shipped.

It errs the other way on gpuop-cfg: that command is scanned even though it is a build/CI helper not copied into the image. Attributing slightly more than is redistributed is the safe direction.

CI

The notices-check job is wired into ci.yaml and runs on every build, with no changed-paths filter.

A filter was tried and removed. The runtime inventory is the import closure of ./cmd/..., so it changes when ordinary .go files change their imports, not only when go.mod or vendor/ move — a filter keyed on dependency manifests passes green while the committed file goes stale, and the failure then surfaces on main instead of on the PR that caused it. Its base computation was also broken: git fetch --depth=1 on an already-full clone writes .git/shallow, after which git merge-base finds no common ancestor and the step dies with exit 128. A gate that can silently pass is worth less than the runner minutes it saves.

This job has now run on real CI and passed (1m18s), which also confirms the generated file reproduces byte-identically on the Linux runner from a file generated on macOS.

make notices-check also fails if the file is untracked, since git diff reports nothing for an untracked path and the gate would otherwise pass silently.

Testing

Current output: 124 runtime packages, 74 build toolchain packages, 1.44 MB. (Index rows are per package; one module can own several.)

• Cross-host reproducibility, proven not assumed. The generator was run under golang:1.26.5 (GNU coreutils, gawk) and on macOS (BSD userland), and the two outputs compared: identical sha256. This is the property the whole multi-platform design rests on, and it is now verified rather than caveated. Two consecutive runs on each host are also byte-identical.
• Completeness against independent ground truth. The runtime index was compared against the dependency set derived separately via go list -deps ./cmd/... for both released platforms, mapped to license-owning directories: 124 expected, 124 present, 0 missing, 0 extra.
• Every index row has a matching license-text section; zero Unknown licenses, zero "License text unavailable", zero unresolved module versions.
• Multi-licensed dependencies verified against the actual license files, including filepath-securejoin (BSD-3-Clause / MPL-2.0), klauspost/compress, sigs.k8s.io/yaml, sigs.k8s.io/json.
• make notices-check passes against the committed file, and was observed failing correctly when the file was stale and when it is untracked.
• Error paths exercised: missing input file, and a deliberately drifted multi-arch.mk (platform matrix guard) — both exit 1 with actionable messages.
• shellcheck clean on the generator; actionlint and yamllint clean on both workflows.
• New guards exercised directly: a replace directive in vendor/modules.txt (uses the replacement), a filesystem replace (fails loudly), and an unreadable module list (fails loudly rather than labelling every row unknown).

Bugs found and fixed during review

Three defects were found by review and testing after the initial version, all now fixed and verified:

1. 18 runtime modules and 14 toolchain modules had no attribution at all — including google.golang.org/protobuf, all nine golang.org/x/*, go.uber.org/zap and gopkg.in/yaml.v3. The stdlib ignore list was built with go list std | cut -d/ -f1, which yields the bare token go (from go/ast, go/build). go-licenses matches --ignore with strings.HasPrefix on the import path rather than by path segment, so go silently swallowed every module whose path starts with those two letters. The list was never needed — go-licenses already excludes the standard library itself — so it is gone. Runtime went 106 → 124.
2. The output differed between Linux and macOS on 664 lines. In lic[pkg] = (pkg in lic) ? ... : ..., mawk instantiates the assignment target before evaluating the right-hand side, so the separator was prepended to a value that did not exist yet and every license read " / BSD-3-Clause". mawk is /usr/bin/awk on stock Debian and Ubuntu; BSD awk and gawk both behave the other way, which is why it never showed up locally. This would have failed notices-check on the first CI run.
3. Two locale- and awk-dependent failures that produce a wrong file while exiting 0. The license-filename match lacked LC_ALL=C, so under a Turkish locale LICENSE stops matching and the document silently collapses from 1.4 MB to 57 KB of "License text unavailable". The fence-width grep lacked -a, so a license containing a NUL byte would produce a fence whose width depends on the grep version and the path length. Neither triggers on today's dependency set; both are one token to fix.
4. replace directives in vendor/modules.txt were misattributed to the original module path and version rather than the code actually vendored, and an unreadable module list labelled every entry unknown without failing.
5. The CI path filter could pass green while the file went stale. The runtime inventory is the import closure of ./cmd/..., so it changes when ordinary .go files change imports — which the filter did not watch. Its base computation was also broken: git fetch --depth=1 on an already-full clone writes .git/shallow, after which git merge-base finds no common ancestor and the step dies with exit 128; and it diffed against main even for cherry-pick PRs targeting release-*. The filter is removed and the check now runs on every build.