Inspecting the Source of Go Modules: Bridging the Gap Between Verification and Convenience

Go's module integrity system stands as one of the most robust package management solutions in the programming language ecosystem. The Go Checksum Database ensures that every Go client worldwide receives identical source code for any given module version, creating an immutable record that persists indefinitely. This system functions remarkably well despite Go modules' decentralized nature, where packages can be fetched directly from their origin using import paths. For instance, retrieving version 1.2.3 of github.com/example/mod involves cloning the git repository and exporting the v1.2.3 tag, a process that GOPROXY=direct can force.

The Checksum Database operates by storing the cryptographic hash of a module version upon its first use across the ecosystem, then providing that identical checksum to every subsequent Go client. This mechanism creates a powerful safeguard: if someone were to force-push a git tag or if a code host attempted to serve different versions to different clients, the go tool would detect the mismatch and abort the fetch operation. This approach proves vastly more practical than requiring module authors to manage cryptographic keys while delivering comparable security levels, since authors themselves can verify that the Checksum Database entry matches their developed code.

Furthermore, the Checksum Database functions as a transparency log, preventing even its operator—Google—from falsifying or concealing entries. This architectural choice ensures that the system remains trustworthy even if the central authority becomes compromised.

However, a critical vulnerability emerges whenever developers read code directly from code hosts. The code displayed at URLs like https://github.com/example/mod/blob/v1.2.3/exp.go carries no guarantee of authenticity. GitHub permits force-pushing git tags and has even built its recommended GitHub Actions workflows upon mutable tags. This weakness was exploited last year in a classic typosquatting attack where malicious code was published in a fake BoltDB module, followed by force-pushing innocent code to GitHub. Some observers mistakenly attributed this to exploiting the Go Modules Mirror's cache, but the real issue lies in the GitHub web interface's lack of verification, which fails to display the authentic (and in that case, malicious) source code that actual Go tooling uses.

The solution for local module review involves commands like cd $(go mod download -json filippo.io/[email protected] | jq -r .Dir), which fetches the correct source code. Development is underway for a go mod verify -tag command that will verify local git repository contents against the Go Checksum Database, enabling module authors to confirm that Checksum Database entries accurately reflect their code.

Despite these solutions, pkg.go.dev continues linking to unverified code hosts, and the convenience of pkg.go.dev source links remains appealing. Russ Cox previously created a simple service for viewing Go module source at go-mod-viewer.appspot.com. Building upon this foundation, pkg.geomys.dev emerges as a new service offering similar functionality with enhanced features including optional syntax highlighting, line and line range linking, multiple font choices, automatic dark mode support, and integrated file tree and module versions browsing.

Users can access this service manually by replacing "go.dev" with "geomys.dev" in any pkg.go.dev URL. Additionally, companion browser extensions for Chrome and Firefox automatically replace code host links in pkg.go.dev pages with links to pkg.geomys.dev, streamlining the verification process.

The service operates by making HTTP Range requests directly to module version zip files and decompressing them in the browser, eliminating the need to download entire archives. Once proxy.golang.org resolves its CORS configuration issues, the service will function without requiring any Geomys backend infrastructure. Currently, it trusts the Google Modules Proxy to serve correct zip files without verifying transparency log proofs. Plans exist to implement optional proof checking once CORS issues are resolved, including support for third-party gossip mechanisms.

Unfortunately, proof checking requires downloading the entire module version zip archive to compute the dirhash, which the Checksum Database includes (and which appears in go.sum files). This trade-off between verification and efficiency presents an ongoing challenge in the ecosystem.

The development of these tools reflects broader concerns about Go module security. While GOPROXY=direct might seem appealing for direct access, configuring GOPROXY=proxy.golang.org actually proves more secure by removing the direct fallback and reducing the attack surface associated with running git clone on potentially adversarial repositories. Regardless of whether code is fetched directly or through a proxy, the sumdb authentication ensures consistent, verified contents—or an error if verification fails.

These developments underscore the ongoing evolution of Go's module ecosystem, where the tension between convenience and security continues to drive innovation. As the ecosystem matures, tools like pkg.geomys.dev represent important steps toward making verified code inspection accessible to all developers, not just those comfortable with command-line operations and cryptographic verification procedures.