This document explains how we handle vulnerability issue triage in the x/vulndb issue tracker.
All vulnerabilities in the Go vulnerability database are currently stored as a YAML file in the data/reports or data/excluded directory.
For a detailed explanation of the report format and style guide, see doc/format.md.
Any open issue should be in one of the following states:
Maintainers of the Go vulndb move issues from one state to another. The intent behind these explicit states is to describe the (minimum) next steps required to bring the issue to resolution.
The issue has been filed by the vulndb worker or an external reporter.
The issue will have the title:
x/vulndb: potential Go vuln in <module/package>: <CVE ID and or GHSA ID>.
To transition from this state, do one of the following:
NeedsInvestigation, and discuss the issue with the team.
excluded: REASON, and use the
vulnreport create-excluded command to create a CL.
NeedsReport, and use the
vulnreport tool to assist in creating a CL.
excluded: OUT_OF_SCOPE and close the issue.
duplicate and close the issue.
This state is used when it is not clear how to proceed. (Otherwise, an issue can move straight to one of the other states.)
Make a plan to discuss the issue with the team to determine a course of action.
The issue has been confirmed to be an in-scope Go vulnerability, and a report needs to be added to
excluded: REASON where REASON is one of the possible excluded reasons.
The issue represents a reported vulnerability, but is not in scope for the main
data/reports folder. An “excluded” report needs to be added to
excluded: OUT_OF_SCOPE or
The issue is out of scope for both the
data/excluded folders. For example, it is an issue mistakenly posted to the tracker (
excluded: OUT_OF_SCOPE) or a duplicate (
duplicate) of another issue.
The issue can be closed without further action.
Clone the x/vulndb repository:
git clone https://go.googlesource.com/vulndb.
Get a GitHub access token with scope
repo: public_repo (follow instructions for “personal access token (classic)”).
Store the token in a file, e.g.,
~/.github-token, and run:
export VULN_GITHUB_ACCESS_TOKEN=`cat ~/.github-token` (you can also store this command in a
~/.bashrc file or similar).
go install ./cmd/vulnreport to install the latest version of vulnreport tool
vulnreport create <GitHub issue number>. The
vulnreport tool will create a YAML report template for the CVE or GHSA at the specified GitHub issue number. This command works for both regular reports and excluded reports. It also accepts multiple Github issue numbers (space separated), and Github issue ranges (e.g.,
vulnreport fix <GitHub issue number>. This will lint the report, add exported symbols, and convert the YAML to OSV.
vulnreport commit <GitHub issue number>. This will create a git commit containing the new files with a standard commit message. Commits are to the local git repository. The
vulnreport commit command also accepts multiple space-separated issue numbers, and will create a separate commit for each report.
vulnreport fix <GitHub issue number> before re-mailing to update the OSV and make sure the report is still valid.
vulnreport create-excluded. This will batch create YAML reports for all issues with the
excluded: REASON label. If there is an error creating any given report, the skipped issue number will be printed to stdout and that issue will have to be created manually with
vulnreport create <Github issue number>. (see steps 2-4 above for more information). Additionally,
create-excluded will automatically create a single commit for all successful reports.
Sometimes an issue describes a vulnerability that we already have a report for. The worker doesn't always detect this automatically, so it is a good idea to grep the
/data directory of this repo for the module path and read the report to see if the vulns are the same.
If the issue is indeed a duplicate:
duplicate to the issue.
data/reports, and add the duplicate IDs to the
ghsas section, as appropriate. Running
vulnreport fix can sometimes find the IDs automatically. (If the duplicate IDs are already present, close the GH issue.)
vulnreport -up commit NNN to update generated files and create a commit. Edit the generated commit message so that it includes the words “add aliases”. You can also add “Fixes #DDDD” (the number of the duplicate issue) to the commit message, or close it manually.
When adding a vulnerability report about the standard library, ensure that the references section follows this format:
references: - report: https://go.dev/issue/<#> - fix: https://go.dev/cl/<#> - web: https://groups.google.com/g/golang-announce/c/<XXX>/<YYY>
You can find these links in the golang-announce@ email for the security release fixing this vulnerability.
Report: The Github issue will be listed in the golang-announce@ email.
Fix: The PR will be a go.dev/cl/<#> link, found as a gopherbot comment on the issue for the vulnerability.
Web: The golang-announce email link.
Occasionally, we will receive new information about a Go vulnerability and want to update the existing report.
In that case, reopen the issue for the report to discuss the change, rather than create a new issue.
vulnreport -up commit NNN can be used to create a more sensible commit message when committing an updated report.
This section describes frequent issues that come up when triaging vulndb reports.
vulnreport fix fails with an error message like
/email@example.com/foo.go:1:2: could not import C (no metadata for C)
a frequent cause is the local machine missing
C library headers causing typechecking of cgo packages to fail. The easiest workaround is to use a machine with the development headers installed or to install them.
Commonly missing packages include: