The Go security team uses an internal YAML format to create vulnerability reports, which are automatically converted to OSV JSON and served to the vulnerability database at vuln.go.dev.
The YAML format is subject to change without warning and should not be relied on by external tools. (See go.dev/security/vuln/database for information on the public Go Vulnerability database API and the OSV schema.)
This page documents the fields of the internal YAML file format.
type string
required
The unique Go identifier assigned to this report.
This is automatically assigned via vulnreport create
. It should be of
the form GO-YYYY-NNNN
where YYYY
is the year the report was created,
and NNNN
is the x/vulndb issue tracker number associated with the report.
type []module
required
Information on each Go module affected by the vulnerability.
type string
required
The module path of the vulnerable module.
Use "std"
for vulnerabilities in the standard library.
Use "cmd"
for vulnerabilities in the Go tools (cmd/...
).
type []version
The version ranges in which the package is vulnerable.
If omitted, it is assumed that every version of the module is vulnerable.
Versions must be SemVer 2.0.0 versions, with no "v" or "go" prefix. Version ranges must not overlap.
Don't expend effort finding the first introduced
version unless
it's obvious.
The version ranges in announcements, CVE text, GHSAs, and so forth are frequently wrong. Always verify the fixed version from the repository history.
If the vulnerability is fixed in multiple minor versions, define sorted, non-overlapping version ranges thats describe the affected revisions. For example, for a fix in 1.17.2, 1.18.4, and 1.19.0:
- fixed: 1.17.2
- introduced: 1.18.0
fixed: 1.18.4
Note that we don't need to mention 1.19.0 in the version ranges, since it comes after 1.18.4.
type string
The version at which the vulnerability was introduced.
If this field is omitted, it is assumed that every version, from the
initial commit, up to the fixed
version is vulnerable.
type string
The version at which the vulnerability was fixed.
If this field is omitted, it is assumed that every version since the
introduced
version is vulnerable.
type string
(Optional - used only in special cases, usually for binary reports.)
The non-Go version range(s) at which the package is vulnerable.
A non-Go version range can be used to specify versions used by module maintainers that do not conform to Go's module version conventions.
An example is data/reports/GO-2024-2539.yaml, whose vulnerable versions are listed as:
versions:
- fixed: 1.1.2-0.20230830170046-f4cf4c6de017
non_go_versions:
- fixed: 4.0.0-rc2
vulnerable_at: 1.1.2-0.20230829214939-57856e474934
The GHSA for this report
lists a fixed version, 4.0.0-rc2
, which is not known to the module proxy.
To encode this, we list that version as a "non-Go" version, and put the
pseudo-version corresponding to the fix commit in the regular versions
section.
type string
The version at which the vulnerable symbols were obtained. Ideally, this is the version just prior to the fix.
In many cases, this can be inferred automatically via vulnreport fix
.
type []string
List of module@version to require when performing static analysis. It is rare that we need to specify this.
Example from GO-2021-0072:
vulnerable_at_requires:
- github.com/Sirupsen/[email protected]
type []package
required
Information on each package affected by the vulnerability.
Include every importable package containing a root vulnerable symbol.
If "internal/foo".F
is vulnerable and "foo".F
calls it, only include
the innermost (internal) package.
If a vulnerability occurs in multiple major versions of a module, include an entry for each major version.
type string
required
The import path of the vulnerable package.
type []string
The symbols affected by this vulnerability.
If included, only programs which use these symbols will be marked as vulnerable. If omitted, any program which imports this module will be marked vulnerable.
These should be the symbols initially detected or identified in the CVE or other source.
type []string
Derived symbols that are calculated from symbols
,
such as by static analysis tools like govulncheck
.
This is generated automatically by the vulnreport fix
command.
Don't edit this field manually.
Potentially, the set of derived symbols can differ with the module
version. We don't attempt to capture that level of detail. Most of the
values of derived_symbols
as of this writing were obtained from a
module version that was just prior to the version that the report
listed as fixed.
type string
A text justification for why static analysis should not be performed on this package (perhaps because it causes an error). It is rare that we need to specify this.
type string
required
A short (<=100 characters) textual description of the vulnerability,
usually of the form "PROBLEM in MODULE(s)", e.g:
summary: "Man-in-the-middle attack in golang.org/x/crypto/ssh
.
To allow for easy visual differentiation, each report must have a unique summary.
type string
required if first-party. Optional for third-party when there is an advisory link.
A textual description of the vulnerability and its impact. Should be wrapped to 80 columns. Does not use Markdown formatting.
The first paragraph should be a short, succinct description of the nature and impact of the vulnerability, ideally one line. Assume the person reading this knows what the vulnerable package does.
Use additional paragraphs to describe the issue in more detail as necessary.
Use the present tense: "This is vulnerable" rather than "this was vulnerable".
This field may be omitted for third-party reports that have an external canonical advisory linked in the references section.
type time.Time
(Handled automatically, do not edit manually)
Date the report was added to the vulnerability database. This is normally determined from the git repository history, and does not need to be set in the report YAML except when the first commit of the report YAML doesn't match the publication date.
Older reports moved from a previous location have this set.
type time.Time
(Handled automatically, do not edit manually)
Last time the report was changed. This is normally determined from the repository history, and does not need to be set in the report YAML.
type []string
The Common Vulnerabilities and Exposures (CVE) ID(s) for the vulnerability.
type []string
The GitHub Security Advisory (GHSA) IDs for the vulnerability.
type []string
The name(s) of the person/organization that discovered/reported the vulnerability.
This should be filled in for Go project reports (standard library, golang.org/x, etc.). Use the text from the golang-announce email when available.
For third-party reports, if vulnreport create
finds CVE or GHSA metadata, use
that. Also, look for a "Credits" heading on the GHSA report linked from the
GitHub issue. Otherwise, it's okay to leave this blank.
type []reference
Links to further information about the vulnerability.
Include a fix
link to the fix pull request, Gerrit code review, or commit.
No need to link both the PR and the commit.
Prefer to link to the PR or code review rather than the commit.
Don't include links to CVEs and GHSAs just because they exist. (That's what the cve/ghsa fields are for.)
DO include an advisory
link to an authoritative first-party
advisory when one exists.
If the first-party advisory is a GHSA, then link to that.
If the first-party advisory is a CVE, then link to the CVE page on
nvd.nist.gov/vuln.
Include a report
link to a first-party bug or issue when one exists.
Don't include links to random third-party issue trackers (e.g., Debian announcements). CVEs often contain a bunch of random links of dubious value; be aggressive in pruning these out.
The internal representation of a Reference
is a struct with Type
and URL
fields. For convenience, the YAML representation is a
single-element map from type to URL. For example:
references:
- fix: https://go.dev/cl/25010
- report: https://go.dev/issue/16405
type string
The type of reference, as in the OSV references field.
OSV types are upper-case, but the type in the YAML should be lower case.
Types we use:
ADVISORY
: A link to an authoritative, first-party advisory.ARTICLE
: An article or blog post about the vulnerability.REPORT
: A bug or issue tracker link.FIX
: A link to the PR/CL which fixes the vulnerability.PACKAGE
: The home page for the package. (We usually do not include this.)EVIDENCE
: A demonstration of the vulnerability. (We usually do not include this.)WEB
: Anything that doesn't fit into the above.
type string
The URL of the reference.
type cve_metadata
Information used to generate a CVE record based on this report. This should be populated only if the Go CNA assigned the CVE for this report.
type string
The CVE ID assigned by the Go CNA for this report.
type string
The CWE most closely associated with this vulnerability, of the form "CWE-XXX: Description".
type string
The description of the vulnerability to use in the CVE record. If blank, the top-level description is used.
This was used to preserve existing descriptions. For new reports, this does not need to be set.
type []string
References that should be published in the CVE record, but not the OSV record. This is used to preserve references added by the CVE program, and is rarely used.
Example: GO-2022-0476
type []string
Optional, freeform notes about the report. This field is ignored when creating OSV and CVE records, so it does not need to be polished.
It can be used to document decisions made when creating the report, outstanding issues, or anything else worth mentioning.
required for new reports
Auto-generated metadata indicating the source of this report.
type string
The CVE or GHSA ID of the vulnerability used to generate this report. For original reports, this is "go-security-team".
type string
The timestamp at which the report was generated based on the indicated source.
type string
required
The status of this report, either UNREVIEWED or REVIEWED.
Unreviewed reports are generally auto-generated or nearly so. Their details have not been verified and no attempt has been made to determine packages or symbols. These reports must have an advisory link.
Reviewed reports are reports for which we have made a good faith effort to determine correct affected versions, packages, and symbols. (In some cases it is not possible to determine all of these, which is OK). Descriptions are optional, except for reports affecting the Go standard library, toolchain or x/ repos.
type string
A reason the report is excluded from the database.
When a CVE or GHSA is evaluated and determined to be out of scope
for the Go Vulnerability Database, the reason for excluding it may
be recorded in a report. This report should include a value for the
excluded
enum (this field) as well as a list of CVEs and/or GHSAs.
Excluded reports are placed in the excluded/
directory.
Valid values are:
NOT_GO_CODE
: The vulnerability is not in a Go package, and cannot affect any Go 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 can never be imported by another module.EFFECTIVELY_PRIVATE
: While the vulnerability occurs in a Go package which can be imported by another module, the package is not intended for external use and is not likely to ever be imported outside the module in which it is defined.DEPENDENT_VULNERABILITY
: This vulnerability is a subset of another vulnerability in the database. For example, if package A contains a vulnerability, package B depends on package A, and there are separate CVEs for packages A and B, we might mark the report for B as a dependent vulnerability entirely superseded by the report for A.NOT_A_VULNERABILITY
: While a CVE or GHSA has been assigned, there is no known vulnerability associated with it.WITHDRAWN
: The source report for this vulnerability was withdrawn before a report was published in vulndb. (If a source report is withdrawn after a report is published, we withdraw the report too).LEGACY_FALSE_POSITIVE
: This is the label used for excluded reports that were marked as false positive in the initial triage process (in 2020), before we stored excluded reports in the repo. This label must not be used for any new reports.
- Standard library: GO-2021-0067
- Toolchain: GO-2021-0068
- x/ repo: GO-2020-0012
- Third-party: GO-2021-0075
- Excluded:GO-2022-0559