| name | go-sumdb-verify |
| description | Verify Go module checksums against the public checksum database (sumdb): GOSUMDB, sum.golang.org, go.sum integrity, go mod verify, tiled hashes, and GONOSUMDB/GOPRIVATE exceptions. Use when sumdb, GOSUMDB, go.sum mismatch, SECURITY ERROR checksum, go mod verify, sum.golang.org, notary.google.com, GONOSUMDB, or module hash verification fail in CI.
|
Go Sumdb Verify
Own checksum-database (sumdb) verification for Go modules: when the
toolchain consults GOSUMDB, how go.sum relates to sumdb tiles, diagnosing
hash mismatches, and safe private-module exceptions. Prefer the repo’s proxy
and CI env. Hand tidy/replace/MVS to go-module-hygiene; multi-ecosystem pins
to dependency-pinning-strategies.
When To Use
go.sum SECURITY ERROR, unexpected hash, or sumdb lookup failure- Configuring or reviewing
GOSUMDB, GONOSUMDB, GOPRIVATE
- CI fails on
go mod verify, sumdb network errors, or offline builds
- Auditing whether checksums are enforced vs silently skipped (
off)
- Keywords: sum.golang.org, notary, checksum database, module hash, h1:,
tile, note key, sumdb protocol, go.sum drift, proxy vs sumdb
Do not use as primary for: tidy/replace/MVS → go-module-hygiene;
govulncheck → go-govulncheck-workflow; multi-lang locks →
dependency-pinning-strategies; SBOM → sbom-and-supply-chain; style →
go-style-conventions.
Repo Config First
Repository and org module-fetch policy outrank defaults below.
go.mod / go.sum: committed together; no hand-edited hashes- Env / CI:
GOPROXY, GOSUMDB, GONOSUMDB, GOPRIVATE
- Private path globs: real VCS prefixes only (not over-broad
*)
- Air-gapped / offline: vendor, module cache mirrors, sumdb access
- Corporate proxy: serves sumdb vs needs
direct/org mirror
- Neighbors:
go.work, -mod=readonly/vendor, Makefile targets
Precedence: Follow the repo. Flag GOSUMDB=off, empty sumdb, or
GONOSUMDB=* that disables verification for public modules without a written
exception.
Workflow
1. Mental model
| Piece | Role |
|---|
go.sum | Local module version content hashes (h1:…) |
GOSUMDB | Checksum DB + public key (default sum.golang.org) |
| Sumdb | Global notary; clients verify signed tiles |
GOPROXY | Download path; not a substitute for sumdb |
GONOSUMDB / GOPRIVATE | Path prefixes that skip sumdb (often proxy too) |
Proxy delivers modules; sumdb authenticates public-module hashes. Never
treat “downloaded successfully” as “hash verified.”
2. Inventory verification posture
go env GOSUMDB GOPROXY GONOSUMDB GOPRIVATE
go mod verify
- Record default vs overridden
GOSUMDB (name + key if custom).
- Justify each
GONOSUMDB/GOPRIVATE glob; keep public paths verified.
- Align CI and developer machines on the same policy.
- Offline/vendor builds must still match committed
go.sum.
3. Local and CI verify
go mod download && go mod verify && go list -m all
go mod verify checks cache against go.sum (and sumdb when enabled).
Fail closed in CI on any mismatch.- After upgrades: tidy /
go get, re-verify; commit go.mod + go.sum
together. Never hand-edit h1: lines.
- Prefer
-mod=readonly (or vendor) in release jobs so sums cannot rewrite
silently during build.
4. Diagnose common failures
| Symptom | Likely cause | Action |
|---|
| SECURITY ERROR / hash mismatch | Tamper, bad cache, sum drift | Diff go.sum; clear bad cache; re-download; do not delete sums blindly |
| Sumdb unreachable | Network, firewall, bad GOSUMDB | Fix path or org mirror; avoid default off |
| Private module sumdb miss | Path not in private globs | Precise GOPRIVATE/GONOSUMDB |
| Local OK, CI fails | Divergent env or dirty cache | Align go env; pin Go; full go.sum |
| Vendor drift | Stale vendor/ | Refresh with repo step; re-verify |
If mismatch persists across clean cache + trusted proxy + sumdb, treat as a
supply-chain incident: stop the bad version, pin known-good, escalate.
5. Exceptions and evidence
GOSUMDB=off: break-glass/labs only; never default CI for public deps.GONOSUMDB: private modules only; review globs in PR like code.- Custom sumdb: document endpoint, key, ownership; test key rotation.
- Air-gap: cache or vendor + locked
go.sum; still run go mod verify.
- Record redacted
go env, commands, failing module@version, sumdb consulted
or not, and fix. Graph debt → go-module-hygiene; SBOM →
sbom-and-supply-chain. Redact tokens from proxy/VCS debug logs.
Routing
| Situation | Primary | Helper |
|---|
| sumdb, GOSUMDB, go mod verify, hash SECURITY ERROR | This skill | — |
| tidy, replace, MVS, retract, private path layout | go-module-hygiene | this for sum policy |
| govulncheck / Go vulndb CI gate | go-govulncheck-workflow | after sums verify |
| Cross-lang lockfile pin strategy | dependency-pinning-strategies | this for Go sums |
| SBOM / provenance inventory | sbom-and-supply-chain | this for hash evidence |
| Registry namespace confusion | dependency-confusion | this for sumdb checks |
| CI job layout / caches | ci-cd-pipeline-patterns | this for verify step |
| Implementation quality | code-quality-standards | always on CI/scripts |
Keep this skill primary until verification env, go.sum, and CI verify
behavior are correct; then hand graph or vuln work to neighbors.
Output Checklist
