[WORK IN PROGRESS]
This document is a quick guide our new (evolving) process for handling vulnerability issue triage in the x/vulndb issue tracker.
For the original documentation, which is somewhat outdated, see our old triage docs.
If you haven't already, follow the one-time-setup process.
Sync the vulndb repo, re-install vulnreport and switch to a fresh branch, e.g.:
$ cd vulndb $ git sync $ go install ./cmd/vulnreport $ git checkout -b reports
Auto-triage the outstanding issues by running
$ vulnreport triage
See vulnreport triage
for more info and options for this command.
All triaged reports (label: triaged
) will need a report, except for duplicates. For all reports marked possible duplicate
, determine if the label is correct.
possible duplicate
label with the duplicate
label, add a comment exactly of the form “Duplicate of #NNN” where #NNN is number of the issue this is a duplicate of, and close the issue.possible duplicate
label and ensure the triaged
label is present.For all reports marked possibly not Go
, determine if the label is correct by investigating the report to see if the vulnerability affects Go code.
possibly not Go
label with the excluded:NOT_GO_CODE
label.possibly not Go
label and ensure the triaged
label is present.Once labeled, you can create excluded reports for these using the vulnreport create-excluded
command (See the old docs for usage).
Note: the excluded labels NOT_IMPORTABLE and EFFECTIVELY_PRIVATE are being deprecated. The labels NOT_A_VULNERABILITY and DEPENDENT_VULNERABILITY are still acceptable, but it is also OK to just create an unreviewed report for these types of vulns.
All remaining open issues marked triaged
now need standard reports.
Issues marked high priority
need a REVIEWED report, and issues without a priority label need an UNREVIEWED report. To create a report for issue #NNN, run:
$ vulnreport create NNN
The command knows whether to create a reviewed or unreviewed report based on the issue's label. (To override this decision, use flag -status=UNREVIEWED
or -status=REVIEWED
.)
Edit the report if needed. For reviewed reports, this follows the standard process. For unreviewed reports, only edit the report if it has lint/fix errors (which will be populated in the notes section).
Fix the report and add derived files:
$ vulnreport fix NNN
If fix
fails, edit the report until it succeeds.
Commit the report:
$ vulnreport commit NNN
Mail the CL and add a team member as a reviewer.
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).
From the repo root, run go install ./cmd/vulnreport
to install the latest version of vulnreport tool.
There are 4 types of issues on our tracker:
The vast majority of issues are of the first type, and this document focuses on handling these.
vulnreport
commandsvulnreport triage
Standard usage:
$ vulnreport triage
This command looks at all untriaged issues to find and label:
high priority
) - issues that affect modules with >= 100 importerspossible duplicate
) - issues that may be duplicates of another issue because they share a CVE/GHSApossibly Not Go
) - issues that possibly do not affect Go at all. This is applied to modules for which more than 20% of current reports are marked excluded: NOT_GO_CODE
.Arguments:
The vulnreport triage
command also accepts arguments, e.g. vulnreport triage 123
to triage issue #123, but the duplicate search only works properly when applied to all open issues.
Flags:
-dry
: don't apply labels to issues-f
: force re-triage of issues labeled triaged