diff options
| -rw-r--r-- | design/draft-vulndb.md | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/design/draft-vulndb.md b/design/draft-vulndb.md new file mode 100644 index 0000000..586f6d8 --- /dev/null +++ b/design/draft-vulndb.md @@ -0,0 +1,145 @@ +# Design Draft: Go Vulnerability Database + +Authors: Roland Shoemaker, Filippo Valsorda + +[golang.org/design/draft-vulndb](https://golang.org/design/draft-vulndb) + +This is a Draft Design, not a formal Go proposal, since it is a +large change that is still flexible. +The goal of circulating this draft design is to collect feedback +to shape an intended eventual proposal. + +## Goal + +We want to provide a low-noise, reliable way for Go developers to +be alerted of known security vulnerabilities that affect their +applications. + +We aim to build a first-party, curated, consistent database of +security vulnerabilities open to community submissions, and +static analysis tooling to surface only the vulnerabilities that +are likely to affect an application, minimizing false positives. + +## The database + +The vulnerability database will provide entries for known +vulnerabilities in importable (non-main) Go packages in public +modules. + +**Curated dataset.** +The database will be actively maintained by the Go Security team, +and will provide consistent metadata and uniform analysis of the +tracked vulnerabilities, with a focus on enabling not just +detection, but also precise impact assessment. + +**Basic metadata.** +Entries will include a database-specific unique identifier for +the vulnerability, affected package and version ranges, a coarse +severity grade, and `GOOS`/`GOARCH` if applicable. +If missing, we will also assign a CVE number. + +**Targeting metadata.** +Each database entry will include metadata sufficient to enable +detection of impacted downstream applications with low false +positives. +For example, it will include affected symbols (functions, +methods, types, variables…) so that unaffected consumers can be +identified with static analysis. + +**Web pages.** +Each vulnerability will link to a web page with the description +of the vulnerability, remediation instructions, and additional +links. + +**Source of truth.** +The database will be maintained as a public git repository, +similar to other Go repositories. +The database entries will be available via a stable protocol (see +“The protocol”). +The contents of the repository itself will be in an internal +format which can change without notice. + +**Triage process.** +Candidate entries will be sourced from existing streams (such as +the CVE database, and security mailing lists) as well as +community submissions. +Both will be processed by the team to ensure consistent metadata +and analysis. +*We want to specifically encourage maintainers to report +vulnerabilities in their own modules.* + +**Not a disclosure process.** +Note that the goal of this database is tracking known, public +vulnerabilities, not coordinating the disclosure of new findings. + +## The protocol + +The vulnerability database will be served through a simple, +stable HTTPS and JSON-based protocol. +Vulnerabilities will be grouped by module, and an index file will +list the modules with known vulnerabilities and the last time +each entry has been updated. + +The protocol will be designed to be served as a collection of +static files, and cacheable by simple HTTP proxies. +The index allows downloading and hosting a full mirror of the +database to avoid leaking module usage information. + +Multiple databases can be fetched in parallel, and their entries +are combined, enabling private and commercial databases. +We’ll aim to use an interoperable format. + +## The tooling + +The primary consumer of the database and the protocol will be a +Go tool, tentatively `go audit`, which will analyze a module and +report what vulnerabilities it’s affected by. + +The tool will analyze what vulnerabilities are likely to affect +the current module not only based on the versions of the +dependencies, but also based on the packages and code paths that +are reachable from a configured set of entry points (functions +and methods). + +The precision of this analysis will be configurable. +When available, the tool will provide sample traces of how the +vulnerable code is reachable, to aid in assessing impact and +remediation. + +The tool accepts a list of packages and reports the +vulnerabilities that affect them (considering as entry points the +`main` and `init` functions for main packages, and exported +functions and methods for non-main packages). + +The tool will also support a `-json` output mode, to integrate +reports in other tools, processes such as CI, and UIs, like how +golang.org/x/tools/go/packages tools use `go list -json`. + +### Integrations + +Besides direct invocations on the CLI and in CI, we want to make +vulnerability entries and audit reports widely available. +The details of each integration involve some open questions. + +**vscode-go** will surface reports for vulnerabilities affecting +the workspace and offer easy version bumps. +*Open question*: can vscode-go invoke `go audit`, or do we need a +tighter integration into `gopls`? + +**pkg.go.dev** will show vulnerabilities in the displayed +package, and possibly vulnerabilities in its dependencies. +*Open question*: if we analyze transitive dependencies, what +versions should we consider? + +At **runtime**, programs will be able to query reports affecting +the dependencies they were built with through `debug.BuildInfo`. +*Open question*: how should applications handle the fact that +runtime reports will have higher false positives due to lack of +source code access? + +In the future, we'll also consider integration into other `go` +tool commands, like `go get` and/or `go test`. + +Finally, we hope the entries in the database will flow into other +existing systems that provide vulnerability tracking, with their +own integrations. |