golang/vulndb: the infrastructure behind Go vulnerability reports

A mirror of infrastructure, not a library to import

The repository description says it plainly: this is a mirror, and the content is the infrastructure and internal reports that create the Go Vulnerability Database at vuln.go.dev. The Go Reference badge points at pkg.go.dev for the module path golang.org/x/vulndb, so the code is published as a Go module, which is what makes the mirror usable as a Go dependency at all.

But the README warns against reading it as a normal x/ module. The packages here are internal to the Go Security Team and its needs, some may be modified arbitrarily or even disappear altogether, and the code in this repository is not subject to the Go 1 Compatibility Promise. That last sentence is the load bearing one, because the compatibility promise is what makes the rest of golang.org/x safe to depend on.

So the intended users are the Go Security Team itself, contributors who want to see how entries are produced, and operators who want to mirror the data rather than pull it from the public endpoint. If you are looking for a way to check your own code for known vulnerabilities, the answer is govulncheck, and the README points you to go.dev/security/vuln for the wider vulnerability management system, and to a privacy policy for govulncheck at vuln.go.dev/privacy.

The last push to the repository was on 2026-10-21, and it publishes no GitHub releases, which is consistent with a repository whose artefacts are a live database rather than a versioned package.

The compatibility promise deliberately does not apply

It is worth sitting with the README's warning, because it is unusual to see a Go module opt out of stability in its own README.

The reasoning is straightforward once stated. This code exists to serve the Go Security Team's needs, not to serve as a public API. A tool that reads, validates and publishes vulnerability reports has requirements that change as the reporting process changes, and the team does not want to be constrained by a promise to keep a package's shape stable. The words may be modified arbitrarily, and some may disappear altogether, are an unusually clear statement of that.

The practical consequence for an adopter is that you cannot upgrade this module the way you upgrade anything else. There is no semver contract to lean on, so a change in behaviour can arrive with a change in a dependency, and the module is published with a fairly specific toolchain requirement, which we will come to.

The other thing the README does is to be explicit about where the supported surface lives. The go.dev security documentation is the place to read about the vulnerability management system, the issue chooser is where you report a public vulnerability in the Go ecosystem or give feedback on the project itself, and the privacy policy is published separately for govulncheck. This repository is the machinery behind those services, and the documentation tells you where to go for each question.

Two licences in one tree: BSD-style code, CC-BY-4.0 entries

The licence section is where the split between the tooling and the data becomes concrete, and it is a distinction that is easy to get wrong if you only read the badge.

Unless otherwise noted, the Go source files are distributed under the BSD-style license found in the LICENSE file. The database entries are distributed under the terms of the CC-BY-4.0 license, with a pointer to go.dev/security/vuln/database for information on how to access those entries. There is also a PATENTS file in the repository root, which is the standard patent grant that accompanies the Go source licence.

Those are different obligations and they matter for different reasons. The Go sources are ordinary permissive code, so if you vendor or modify a tool from this repository, keeping the notice is the requirement. The database entries are licensed under a Creative Commons attribution licence, which is the right choice for a data set that people are expected to reuse and redistribute, and it means attribution and licence terms travel with the data rather than with a code licence.

For a security team that wants to mirror the data, the practical consequence is that mirroring the entries and mirroring the tooling are governed by different terms. A team that takes a copy of the entries to run scans against an internal module proxy is in the CC-BY-4.0 case, and a team that wants to run the validation tooling itself is in the BSD-style case.

The README points at the database documentation for how to access the entries, which is where the access and reuse instructions live.

The go.mod file describes the whole publishing pipeline

The module file is unusually readable, and it tells you more about the architecture than any documentation would.

The module is golang.org/x/vulndb, it declares go 1.26.0, and it carries a godebug default of go1.26.2 together with a toolchain directive of go1.26.2. The comment explains why in detail. The module had already started using godebug setting values from Go 1.26.2 in an earlier change, before the go directive was lowered to 1.25.0, and the setting was kept to avoid going back to the 1.25 godebug values unnecessarily. The comment also warns that using a go1.26.2 or newer toolchain is required, because otherwise the go command fails with a default=go1.26.2 too new error. The toolchain directive makes that requirement explicit.

The dependency list is the interesting part, because it maps the pipeline:

module golang.org/x/vulndb

go 1.26.0

godebug default=go1.26.2

toolchain go1.26.2

Cloud Google libraries for Firestore, Secret Manager and error reporting say the entries live in a document store and that secrets are managed elsewhere. The OpenTelemetry exporter and propagator packages, and the jba metrics packages, say the pipeline is instrumented and that its behaviour is measured. github.com/google/go-github/v89 and the GitHub v4 client say reports are pulled from and pushed to GitHub issues, github.com/go-git and go-billy say repository content is read through a git implementation, and the generative AI Go client says some part of the workflow involves a model. github.com/lib/pq is the PostgreSQL driver, and the google/safehtml and jba/templatecheck packages say that untrusted input is sanitised and that templates are checked.

Two of those deserve a second look. The secret manager dependency implies that credentials for the publishing process are not stored in the repository, and the generative AI client dependency implies that some part of the pipeline is model-assisted, which raises a question about who reviews the output.

cmd, internal, report and the data directory

The top level layout shows how the work is split, and the names carry most of the meaning.

The cmd directory holds the command line entry points, internal holds the packages that are not part of any public surface, which is where the bulk of the implementation lives given the README's warning about internal packages. The report directory is where the internal reports are kept, and the data directory holds the data the tooling operates on.

Around those sit the operational pieces. The deploy directory and the terraform directory together describe how the service is deployed, and the webconfig directory holds the web service configuration for the public front end. The devtools directory holds the developer tooling, and the doc directory holds the documentation that is published alongside the site.

The test files are at the root rather than in a test directory, which is the convention this project uses: all_test.go and tools_test.go sit alongside the packages they cover, and checks.bash is the shell entry point for the checks. The CI configuration lives in the .github directory.

Two files outside the Go tree are worth noticing. CONTRIBUTING.md is the route for contributing to the database itself, and PATENTS is the patent grant that accompanies the source licence.

What the layout makes clear is the scale of the operation. This is not a small tool that runs against a repository of text files. It is a service with a database, a deployment footprint described in Terraform, a web front end, a public issue intake path, and instrumentation for its own behaviour.

Reporting, feedback and the state of the tree

The reporting path is the part of the README that most directly affects you if you find a vulnerability in the Go ecosystem itself. The link goes to an issue chooser on the project, described as the place to report a public vulnerability in the Go ecosystem or to give feedback about the project. A chooser rather than a plain new issue form, which suggests the process asks you to classify what you are submitting before you write it.

The privacy policy is published separately, for govulncheck, and it lives at vuln.go.dev/privacy rather than in this repository. That separation is a signal about the architecture: the tool that scans your code has a privacy policy of its own because it runs against your source tree, while the database that backs it does not.

On maintenance, the numbers are healthy. The repository is not archived, the last push was on 2026-10-21, and the module is pinned to a current Go release with an explicit toolchain directive. There are no GitHub releases, which is the right shape for a continuously updated database, and the CHANGELOG is not in the tree, so the commit history and the issue tracker are the change record.

The one thing to keep in mind when you evaluate this project is the README's own framing. The repository is the Go Security Team's working infrastructure, mirrored so that it is inspectable and reusable. It is not a stable library, and the licence split plus the compatibility exemption together tell you exactly how much of a promise you are getting.

Editorial conclusion

Adopt golang/vulndb if you contribute to the Go vulnerability database, run a mirror of it, or want to understand how the entries behind govulncheck are produced, since the repository is the authoritative source for the process rather than for a client library. Do not import its packages into your own product, because the README states the code is not subject to the Go 1 Compatibility Promise and that packages may be changed or removed without notice. Verify first the licence position for your use, since the Go sources are BSD-style while the database entries are CC-BY-4.0 and the two have different obligations, and check the current Go toolchain requirement, since the module pins a godebug default and a toolchain directive that the go command refuses to run against anything older.

Frequently asked questions

Official sources

1. golang/vulndb on GitHub
2. Issues
3. README