Go teams drown in dependency alerts that do not apply to them, while the controls that actually protect Go builds, the checksum database and the module proxy chain, are quietly switched off by one environment variable. Go is unusual among language ecosystems: the toolchain ships with a curated vulnerability database, a scanner that checks whether your code calls the vulnerable function, and a global transparent log that makes every public module version tamper-evident. Used well, these cut alert noise and make dependency tampering detectable. Misconfigured, they leave private modules unverified and let a proxy serve whatever it likes. This guide is for Go developers, platform engineers and application security teams who run Go services in production. It covers govulncheck in CI, the Go vulnerability database, GOPROXY, GOSUMDB, GOPRIVATE and their relatives, and how to fit them into a vulnerability management programme. Language-level secure coding is in the Go Secure Coding Guide.
Key takeaways
- Reachability is the default. govulncheck runs at symbol level unless told otherwise, so it reports a vulnerability only when your code has a call path to the affected function, which removes most false alarms from module-level scanners.
- The checksum database is your tamper alarm. sum.golang.org is a transparent log of go.sum hashes; any module matched by GOPRIVATE or GONOSUMDB, or any build with GOSUMDB=off, is accepted without that check.
- Comma and pipe in GOPROXY are not cosmetic. A comma falls back only on 404 or 410, a pipe falls back on any error, which decides whether a gatekeeping proxy can actually block a module.
- JSON and SARIF output never fail a build. govulncheck exits 0 with -format json, sarif or openvex, so pipelines that switch format for reporting must gate on the results themselves.
- Binary scans see what is deployed. -mode binary checks the build configuration actually shipped, but without call stacks, so pair it with source scans rather than replacing them.
How Go's supply chain model differs
The Go team's description of its supply chain design (Go Blog, "How Go Mitigates Supply Chain Attacks") sets out properties that change how you manage risk compared with npm or PyPI:
- go.mod is the lock: the main module's go.mod fully determines dependency versions. Since Go 1.16 build commands run with
-mod=readonlyby default and fail if go.mod needs changing, so only explicitgo getorgo mod tidymoves versions, and those changes go through review. - Minimal version selection: transitive dependencies resolve to the versions their parents declare, not the newest. A malicious new release affects nobody until someone deliberately upgrades.
- go.sum hashes: each dependency's zip and go.mod hashes are recorded. A mismatch is a security error and the file is not installed in the module cache.
- No install hooks: fetching or building a module does not run its code at install time, unlike npm postinstall scripts. Package
initfunctions still run when the program starts, so this limits spread rather than removing risk. - No registry accounts: module paths point at version control, so there is no central publishing account to steal. The trade-off is that control of the repository or the domain behind a vanity import path is control of the module.
The practical result: Go vulnerability management is less about blocking surprise installs and more about knowing which reachable vulnerable code you ship, and making sure every module you build was verified against a hash you trust.
The Go vulnerability database
The Go vulnerability database at vuln.go.dev is fed by a pipeline that collects reports from the NVD, the GitHub Advisory Database and Go package maintainers. The Go Security team reviews and curates entries, and the team is a CVE Numbering Authority. Entries are published in the OSV format and browsable at pkg.go.dev/vuln.
| Field or endpoint | What it gives you | Why it matters |
|---|---|---|
ID GO-YYYY-NNNN | Go-specific identifier, with CVE and GHSA IDs in aliases | Correlate govulncheck findings with SCA and ticketing tools that key on CVE |
affected[].ecosystem_specific.imports | Package path, vulnerable symbols, optional goos and goarch | The data that makes symbol-level reachability possible; a Windows-only flaw need not block a Linux build |
affected[].package.name | Module path, or stdlib, or toolchain | Standard library flaws are fixed by upgrading Go itself, not a dependency |
database_specific.review_status | REVIEWED or UNREVIEWED (auto-generated from a CVE or GHSA) | Unreviewed entries may lack symbol data, so reachability is less precise |
/index/modules.json, /index/vulns.json, /ID/$id.json, vulndb.zip | Static API and bulk download | Mirror the database for air-gapped builds and point govulncheck at it with -db |
The Go team deliberately does not assign severity labels, arguing that impact depends on how the code is used. Your programme therefore has to supply its own prioritisation, using reachability, exposure and asset criticality. The documentation also notes that reports which cannot map a project's versions to Go versions may mark all versions affected, which avoids false negatives at the cost of some false positives.
govulncheck in practice
Install with go install golang.org/x/vuln/cmd/govulncheck@latest and run govulncheck ./... from the module root. It analyses the code using the Go version found on the PATH, so the scanner's view of standard library vulnerabilities depends on the toolchain in your CI image.
Modes, scan levels and output
| Setting | Values (default first) | When to use it |
|---|---|---|
-mode | source, binary, extract | Source in pull requests; binary for release artefacts and images; extract to produce a small blob from a binary for later scanning where shipping the binary is impractical |
-scan | symbol, package, module | Symbol for gating; package or module for an inventory view of everything imported, for example during audits or SBOM reconciliation |
-format | text, json, sarif, openvex | SARIF for code scanning dashboards; OpenVEX to publish "not affected" statements for unreachable findings; JSON for custom gates |
-show | traces, verbose, color, version (text output only) | traces prints the full call stack, which is what a developer needs to fix or justify a finding |
-test, -tags | Off by default; source mode only | Scan every build tag combination you ship, for example -tags=linux,prod; include tests if test helpers are built into tools |
-db | https://vuln.go.dev | Point at an internal mirror that implements the Go vulnerability database specification |
Exit codes and CI gating
In text mode govulncheck exits 0 when nothing is found and non-zero when vulnerabilities affect the code, which makes it a simple build gate. With -json, -format sarif or -format openvex it always exits 0. A common pattern is two steps: a text-mode run that gates the merge, and a SARIF run that uploads results to the code scanning dashboard. The Go team publishes a govulncheck GitHub Action, and the scanner also runs in the VS Code Go extension so developers see findings before they push.
Known limitations to plan around
- Reflection and unsafe: calls made through
reflectare invisible to static analysis, andunsafecan cause false negatives. Code that dispatches handlers by reflection (some RPC and plugin frameworks) needs a package-level scan as a backstop. - Interfaces and function pointers: analysed conservatively, which can produce false positives or odd call stacks.
- Binary mode: no call graphs, and code linked but unreachable may be reported. Binaries built with Go versions before 1.18 only get standard library findings; binaries without symbol information are reported against every dependency module.
- No suppression: findings cannot be silenced in the tool yet (tracked in Go issue 61211). Record accepted risk outside the scanner, or publish OpenVEX statements, and review them on a schedule.
- Privacy: requests to vuln.go.dev contain only module paths already known to the database, not your code, which is usually acceptable even for private repositories.
Module proxies, the checksum database and private modules
By default the go command downloads modules from the public mirror and verifies them against the public checksum database. go env on a default install shows GOPROXY=https://proxy.golang.org,direct and GOSUMDB=sum.golang.org.
The checksum database is a transparent log (a Merkle tree backed by Trillian) of go.sum line hashes. Because independent auditors can check it has not been rewritten, it lets you use an untrusted proxy: the proxy cannot serve different bytes for a public version without the mismatch being detected, and a version's content cannot change even if the author later moves the tag.
| Variable | Effect | Security note |
|---|---|---|
GOPROXY | Ordered list of proxy URLs, direct (fetch from VCS) or off | Comma: fall through only on 404/410. Pipe: fall through on any error. Use a comma after a gatekeeping proxy so a 403 for an unapproved module stops the build. |
GOSUMDB | Checksum database name, optional key and URL; off disables it | With off, hashes for modules not already in go.sum are accepted unverified. Never set it globally in CI. |
GOPRIVATE | Comma-separated globs of private module path prefixes | Sets the defaults for GONOPROXY and GONOSUMDB. Keep patterns narrow, for example *.corp.example.com, not a bare domain that also hosts public code. |
GONOPROXY / GONOSUMDB | Override GOPRIVATE for the proxy and checksum decisions separately | With an internal proxy serving private modules, set GONOPROXY=none so private modules still go through it. |
GOINSECURE | Allows HTTP fetch and redirects for matching paths | Does not disable checksum validation, but exposes import path resolution to tampering. Should be empty in production builds. |
GOVCS | Which version control tools may be used for which paths | Default allows only git and hg for public servers and any VCS for private ones, because Bazaar, Fossil and Subversion are less scrutinised as clients of untrusted servers. |
GOFLAGS | Default flags for go commands | A -mod=mod here lets builds rewrite go.mod and go.sum silently; check CI images for it. |
Choosing a proxy architecture
- Small teams, public dependencies only: the defaults are sound. Commit go.sum, keep GOSUMDB on and do not set GOPRIVATE.
- Private modules, no internal proxy: set GOPRIVATE to the narrowest pattern that covers them and fetch direct from your VCS with authenticated access. Accept that those modules have only go.sum as their integrity record, so protect the repositories and branch rules.
- Regulated or large estates: run an internal proxy as the single egress for modules, with
GOPROXY=https://goproxy.corp.example.comandGONOPROXY=none, keep the public checksum database enabled for public modules, and have the proxy refuse modules not on an approved list. Mirror vuln.go.dev for govulncheck. - Air-gapped builds: vendor dependencies (
go mod vendor) or pre-populate the internal proxy, and set GOSUMDB to a reachable mirror or rely on a committed go.sum, documenting the decision.
Two module cache details matter in incident response. go mod verify checks that files in the local module cache still match the hashes recorded when they were downloaded, which detects tampering on a build host after the fact. And the public mirror may keep serving a version even after the author deletes its tag; the correct response to a bad release is a new version with a retract directive, which hides the bad versions from @latest and upgrades. See the Private Package Repository and Proxy Guide for proxy design across ecosystems.
Building the programme: phased rollout
- Baseline: run
govulncheck ./...andgovulncheck -scan module ./...on every repository. The gap between the two counts is the noise reachability removes; publish it to win developer support. - Fix the toolchain first: standard library findings are fixed by moving to the latest Go minor release. The Go team ships security fixes in point releases and pre-announces them on golang-announce, so subscribe and schedule upgrades.
- Audit module configuration: grep CI images, Dockerfiles and developer bootstrap scripts for
GOSUMDB=off,GONOSUMDB,GOINSECURE,GOFLAGS=-mod=modand broad GOPRIVATE patterns. Remove or narrow each one. - Gate in report mode: add govulncheck in text mode as a non-blocking job for two to four weeks, triage findings with
-show traces, then make it blocking for new reachable findings. - Scan what ships: run
govulncheck -mode binaryagainst release binaries and container images, so a build with different tags or a stale base image is caught. - Rollback: if the gate blocks an urgent release, allow a time-boxed exception recorded with the GO ID, the reason (for example no fix available and code path disabled) and an owner, rather than disabling the job.
Detection, measurement and framework mapping
What to monitor
- Checksum errors: "SECURITY ERROR" checksum mismatches in build logs are a potential tampering signal, not a flaky build. Alert on them and investigate the proxy and origin.
- go.sum churn: pull requests that change go.sum without a corresponding go.mod change, or add many new modules, deserve review.
- Proxy denials: 403 responses from an internal gatekeeping proxy show attempted use of unapproved modules, including typosquats.
- Configuration drift: scheduled checks of
go envon build agents for the variables in the table above.
Metrics
- Reachable (symbol-level) vulnerabilities open per service, and median days to fix against your remediation window.
- Percentage of services on a supported Go release with the latest point release.
- Percentage of repositories with govulncheck gating merges and binary scans on release.
- Number of build environments with GOSUMDB disabled or GONOSUMDB broader than the private namespace (target zero).
- Ratio of module-level to symbol-level findings, as evidence of reduced triage load.
Framework mapping
| Go control | NIST SP 800-53 Rev 5 | NIST CSF 2.0 | OWASP ASVS 5.0 / ATT&CK |
|---|---|---|---|
| govulncheck in CI and on binaries | RA-5 Vulnerability Monitoring and Scanning, SI-2 Flaw Remediation | ID.RA-01 | V15.1.1, V15.2.1 |
| go.mod and go.sum inventory, SBOM | CM-8 System Component Inventory | ID.RA-01 | V15.1.2 |
| Checksum database, go.sum verification | SR-4 Provenance, SR-11 Component Authenticity | PR.PS-06 | V15.2.4; counters T1195.001 Compromise Software Dependencies and Development Tools |
| Internal proxy with approved module list | SR-3 Supply Chain Controls and Processes | GV.SC-05 | V15.2.4 |
Common failure patterns
- GOSUMDB=off as a fix for private module errors: the quick workaround for "verifying module: not found" disables verification for every module, public ones included. The right fix is a narrow GOPRIVATE or GONOSUMDB pattern.
- Gating on SARIF exit codes: a pipeline switched to
-format sariffor dashboards stops failing builds, because that format always exits 0. Keep a text-mode gate or parse the output. - Scanning with the wrong toolchain: govulncheck uses the Go on the PATH, so a CI image with an old Go reports different standard library findings from the toolchain that built production. Pin the same version, or scan the binary.
- Treating module-level scanner output as the backlog: teams that import every CVE from a generic SCA tool spend weeks on unreachable code. Use symbol-level results to prioritise, and module-level results only for inventory.
- Deleting a bad tag instead of retracting: the mirror may keep serving the version. Publish a new release with a
retractdirective. - Trusting a vanity import path without owning it: whoever controls the domain behind a custom import path controls where go fetches from. Protect those domains and their DNS like signing keys. The Malicious Package and Dependency Confusion Guide covers lookalike module names.
Practitioner checklist
- govulncheck runs at symbol level on every pull request in text mode and blocks new reachable findings.
- Release binaries and images are scanned with
-mode binary, and SARIF or OpenVEX output feeds the security dashboard. - Go is on the latest point release of a supported minor version, and someone owns golang-announce.
- go.mod and go.sum are committed and reviewed; CI runs with the default
-mod=readonlyand no-mod=modin GOFLAGS. - GOSUMDB is on everywhere; GOPRIVATE and GONOSUMDB are limited to the private namespace.
- GOINSECURE is empty in build environments, and GOVCS is left at its default or tightened.
- An internal proxy, if used, is the only module egress and refuses unapproved modules with a 403 after a comma in GOPROXY.
- Accepted vulnerability risks are recorded with GO ID, rationale, owner and review date.
- Checksum mismatches in build logs raise a security alert.
Standards and references
- Go: Go Vulnerability Management
- Go: govulncheck command documentation
- Go: Go Vulnerability Database
- Go: Go Modules Reference
- Go: Security Best Practices for Go Developers
- Go Blog: How Go Mitigates Supply Chain Attacks
- Go: Go Module Mirror, Index and Checksum Database
- NIST: SP 800-53 Rev. 5 Security and Privacy Controls
Related NHI Mgmt Group resources: Go Secure Coding Guide · Private Package Repository and Proxy Guide · Software Supply Chain Security Guide · SBOM Guide · Package Registry Security Comparison Guide