Back to Go Vulnerability Management

Overview

The Go vulnerability database (https://vuln.go.dev)serves Go vulnerability information in theOpen Source Vulnerability (OSV) schema.

You can also browse vulnerabilities in the database atpkg.go.dev/vuln.

Do not rely on the contents of the x/vulndb Git repository. The YAML files in thatrepository are maintained using an internal format that may changewithout warning.

Contributing

We would love for all Go package maintainers tocontributeinformation about public vulnerabilities in their own projects,andupdate existing information about vulnerabilitiesin their Go packages.

We aim to make reporting a low friction process,so feel free tosend us your suggestions.

Pleasedo not use the forms above to report a vulnerability in the Gostandard library or sub-repositories.Instead, follow the process atgo.dev/security/policyfor vulnerabilities about the Go project.

API

The canonical Go vulnerability database,https://vuln.go.dev,is an HTTP server that can respond to GET requests for the endpoints specified below.

The endpoints have no query parameters, and no specific headers are required.Because of this, even a site serving from a fixed file system (including afile:// URL)can implement this API.

Each endpoint returns a JSON-encoded response, in either uncompressed(if requested as.json) or gzipped form (if requested as.json.gz).

The endpoints are:

• /index/db.json[.gz]

  Returns metadata about the database:

  {  // The latest time the database should be considered  // to have been modified, as an RFC3339-formatted UTC  // timestamp ending in "Z".  "modified": string}

  Note that the modified timeshould not be compared to wall clock time,e.g. for purposes of cache invalidation, as there may a delay in makingdatabase modifications live.

  See/index/db.json for a live example.

• /index/modules.json[.gz]

  Returns a list containing metadata about each module in the database:

  [ {  // The module path.  "path": string,  // The vulnerabilities that affect this module.  "vulns":    [ {      // The vulnerability ID.      "id": string,      // The latest time the vulnerability should be considered      // to have been modified, as an RFC3339-formatted UTC      // timestamp ending in "Z".      "modified": string,      // (Optional) The module version (in SemVer 2.0.0 format)      // that contains the latest fix for the vulnerability.      // If unknown or unavailable, this should be omitted.      "fixed": string,    } ]} ]

  See/index/modules.json for a live example.

• /index/vulns.json[.gz]

  Returns a list containing metadata about each vulnerability in the database:

   [ {     // The vulnerability ID.     "id": string,     // The latest time the vulnerability should be considered     // to have been modified, as an RFC3339-formatted UTC     // timestamp ending in "Z".     "modified": string,     // A list of IDs of the same vulnerability in other databases.     "aliases": [ string ] } ]

  See/index/vulns.json for a live example.

• /ID/$id.json[.gz]

  Returns the individual report for the vulnerability with ID$id,in OSV format (described below inSchema).

  See/ID/GO-2022-0191.jsonfor a live example.

Bulk download

To make it easier to download the entire Go vulnerability database,a zip file containing all the index and OSV files is available atvuln.go.dev/vulndb.zip.

Usage ingovulncheck

By default,govulncheck uses the canonical Go vulnerability database atvuln.go.dev.

The command can be configured to contact a different vulnerability database using the-db flag,which accepts a vulnerability database URL with protocolhttp://,https://, orfile://.

To work correctly withgovulncheck, the vulnerability database specified must implement the API described above. Thegovulncheck command uses compressed “.json.gz” endpoints when reading from an http(s) source, and the “.json” endpoints when reading from a file source.

Legacy API

The canonical database contains some additional endpoints that are part of a legacy API.We plan to remove support for these endpoints soon. If you are relying on the legacy APIand need additional time to migrate,please let us know.

Schema

Reports use theOpen Source Vulnerability (OSV) schema.The Go vulnerability database assigns the following meanings to the fields:

id

The id field is a unique identifier for the vulnerability entry. It is a stringof the format GO-<YEAR>-<ENTRYID>.

affected

Theaffected field is aJSON array containing objects that describes the module versions that containthe vulnerability.

affected[].package

Theaffected[].packagefield is a JSON object identifying the affectedmodule. The object has tworequired fields:

• ecosystem: this will always be “Go”
• name: this is the Go module path
  • Importable packages in the standard library will have the namestdlib.
  • The go command will have the nametoolchain.

affected[].ecosystem_specific

Theaffected[].ecosystem_specificfield is a JSON object with additional information about the vulnerability,which is used by Go’s vulnerability detection tools.

For now, ecosystem specific will always be an object with a single field,imports.

affected[].ecosystem_specific.imports

Theaffected[].ecosystem_specific.imports field is a JSON array containingthe packages and symbols affected by the vulnerability. Each object in thearray will have these two fields:

• path: a string with the import path of the package containing the vulnerability
• symbols: a string array with the names of the symbols (function or method) that contains the vulnerability
• goos: a string array with the execution operating system where the symbols appear, if known
• goarch: a string array with the architecture where the symbols appear, if known

database_specific

Thedatabase_specific field contains custom fields specific to the Go vulnerability database.

database_specific.url

Thedatabase_specific.url field is a string representing the fully-qualifiedURL of the Go vulnerability report, e.g, “https://pkg.go.dev/vuln/GO-2023-1621".

database_specific.review_status

Thedatabase_specific.review_status field is a string representing the reviewstatus of the vulnerability report. If not present, the report should beconsideredREVIEWED. The possible values are:

• UNREVIEWED: The report was automatically generated based on another source, such asa CVE or GHSA. Its data may be limited and has not been verified by the Go team.
• REVIEWED: The report originated from the Go team, or was generated based on an external source.A member of the Go team has reviewed the report, and where appropriate, added additional data.

For information on other fields in the schema, refer to theOSV spec.

Note on Versions

Our tooling attempts to automatically map modules and versions insource advisories to canonical Go modules and versions, in accordance withstandardGo module version numbers. Tools likegovulncheck are designed to rely on these standard versions to determinewhether a Go project is affected by a vulnerability in a dependency or not.

In some cases, such as when a Go project uses its own versioning scheme,the mapping to standard Go versions can fail. When this happens, the Govulnerability database report may conservatively list all Go versions asaffected. This ensures that tools such asgovulncheck do not fail to reportvulnerabilities due to unrecognized version ranges (false negatives).However, conservatively listing all versions as affected may cause tools toincorrectly report a fixed version of a module as containing the vulnerability(false positives).

If you believegovulncheck is incorrectly reporting (or failing to report) avulnerability, pleasesuggest an editto the vulnerability report and we will review it.

Examples

All vulnerabilities in the Go vulnerability database use the OSV schemadescribed above.

See the links below for examples of different Go vulnerabilities:

• Go standard library vulnerability (GO-2022-0191):JSON,HTML
• Go toolchain vulnerability (GO-2022-0189):JSON,HTML
• Vulnerability in Go module (GO-2020-0015):JSON,HTML

Excluded Reports

The reports in the Go vulnerability database are collected from differentsources and curated by the Go Security team. We may come across a vulnerability advisory(for example, a CVE or GHSA) and choose to exclude it for a variety of reasons.In these cases, a minimal report will be created in the x/vulndb repository,underx/vulndb/data/excluded.

Reports may be excluded for these reasons:

• NOT_GO_CODE: The vulnerability is not in a Go package,but it was marked as a security advisory for the Go ecosystem by another source.This vulnerability cannot affect anyGo packages. (For example, a vulnerability in a C++ library.)
• NOT_IMPORTABLE: The vulnerability occurs in packagemain, aninternal/package only imported by packagemain, or some other location which cannever be imported by another module.
• EFFECTIVELY_PRIVATE: While the vulnerability occurs in a Go package whichcan be imported by another module, the package is not intended for externaluse and is not likely to ever be imported outside the module in which it isdefined.
• DEPENDENT_VULNERABILITY: This vulnerability is a subset of anothervulnerability in the database. For example, if package A contains avulnerability, package B depends on package A, and there are separate CVE IDsfor packages A and B, we might mark the report for B as a dependentvulnerability entirely superseded by the report for A.
• NOT_A_VULNERABILITY: While a CVE ID or GHSA has been assigned, there is noknown vulnerability associated with it.
• WITHDRAWN: The vulnerability has been withdrawn by its source.

At the moment, excluded reports are not served viavuln.go.dev API. However, if you havea specific use case and it would be helpful to have access to this informationthrough the API,please let us know.