Skip to content

Latest commit

 

History

History
482 lines (309 loc) · 13.8 KB

format.md

File metadata and controls

482 lines (309 loc) · 13.8 KB
Raw

Vulnerability Report Format & Style Guide

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.

id

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.

modules

type []module

required

Information on each Go module affected by the vulnerability.

module.module

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/...).

module.versions

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.

version.introduced

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.

version.fixed

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.

module.non_go_versions

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.

module.vulnerable_at

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.

module.vulnerable_at_requires

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]

module.packages

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.

package.package

type string

required

The import path of the vulnerable package.

package.symbols

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.

package.derived_symbols

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.

package.skip_fix

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.

summary

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.

description

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.

published

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.

last_modified

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.

cves

type []string

The Common Vulnerabilities and Exposures (CVE) ID(s) for the vulnerability.

ghsas

type []string

The GitHub Security Advisory (GHSA) IDs for the vulnerability.

credits

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.

references

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

reference.type

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.

reference.url

type string

The URL of the reference.

cve_metadata

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.

cve_metadata.id

type string

The CVE ID assigned by the Go CNA for this report.

cve_metadata.cwe

type string

The CWE most closely associated with this vulnerability, of the form "CWE-XXX: Description".

cve_metadata.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.

cve_metadata.references

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

notes

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.

source

required for new reports

Auto-generated metadata indicating the source of this report.

source.id

type string

The CVE or GHSA ID of the vulnerability used to generate this report. For original reports, this is "go-security-team".

source.created

type string

The timestamp at which the report was generated based on the indicated source.

review_status

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.

excluded

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 package main, an internal/ package only imported by package main, 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.
  • 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.

Example Reports