README.md: updated
The contents of the README.md are updated to reflect the current
project.
Change-Id: I8461f50c4468a0f2b206a93a36e88d09b5e5f871
Reviewed-on: https://go-review.googlesource.com/c/vuln/+/360440
Trust: Julie Qiu <julie@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
diff --git a/README.md b/README.md
index 161fc5e..d5fb9fd 100644
--- a/README.md
+++ b/README.md
@@ -1,28 +1,41 @@
-# The Go Vulnerability Database `golang.org/x/vulndb`
+# Go Vulnerability Database
-This repository is a prototype of the Go Vulnerability Database.
-Read [the Draft Design](https://golang.org/design/draft-vulndb).
+[](https://pkg.go.dev/golang.org/x/vuln)
+
+This repository contains code for hosting the Go Vulnerability Database. The
+actual reports can be found at [x/vulndb](https://go.googlesource.com/vulndb).
Neither the code, nor the data, nor the existence of this repository is to be
-considered stable until an approved proposal.
+considered stable. See the
+[Draft Design](https://golang.org/design/draft-vulndb) for details on this
+project.
-**Important: vulnerability entries in this repository are represented in an
-internal, unstable format that can and will change without notice.**
+## Accessing the database
-## Consuming database entries
+The Go vulnerability database is rooted at
+`https://storage.googleapis.com/go-vulndb` and provides data as JSON. We
+recommend using
+[client.Client](https://pkg.go.dev/golang.org/x/vuln/client#Client) to read
+data from the Go vulnerability database.
-Database clients must not rely on the contents of this repository. Instead, they
-can access the tree of JSON entries rooted at
+Do not rely on the contents of the x/vulndb repository. The YAML files in that
+repository are maintained using an internal format that is subject to change
+without warning.
-https://storage.googleapis.com/go-vulndb/
+The endpoints the table below are supported. For each path:
-An `index.json` file maps module paths to last modified timestamps
-([link](https://storage.googleapis.com/go-vulndb/index.json)).
+- $base is the path portion of a Go vulnerability database URL (`https://storage.googleapis.com/go-vulndb`).
+- $module is a module path
+- $vuln is a Go vulnerabilitiy ID (for example, `GO-2021-1234`)
-For each module, a `NAME.json` file contains a list of vulnerability entries
-([example](https://storage.googleapis.com/go-vulndb/golang.org/x/crypto.json)).
+| Path | Description |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| $base/index.json | List of module paths in the database mapped to its last modified timestamp ([link](https://storage.googleapis.com/go-vulndb/index.json)). |
+| $base/$module.json | List of vulnerability entries for that module ([example](https://storage.googleapis.com/go-vulndb/golang.org/x/crypto.json)). |
+| $base/ID/index.json | List of all the vulnerability entries in the database |
+| $base/ID/$vuln.json | An individual Go vulnerability report |
-Note that this path and format are provisional and likely to change until an
+Note that these paths and format are provisional and likely to change until an
approved proposal.
## Packages
@@ -30,15 +43,15 @@
Some of these packages can probably be coalesced, but for now are easier to work
on in a more segmented fashion.
-* `osv` provides a package for generating OSV-style JSON vulnerability entries
+- `osv` provides a package for generating OSV-style JSON vulnerability entries
from a `report.Report`
-* `client` contains a client for accessing HTTP/fs based vulnerability
+- `client` contains a client for accessing HTTP/fs based vulnerability
databases, as well as a minimal caching implementation
-* `cmd/dbdiff` provides a tool for comparing two different versions of the
+- `cmd/dbdiff` provides a tool for comparing two different versions of the
vulnerability database
-* `cmd/gendb` provides a tool for converting YAML reports into JSON database
-* `cmd/linter` provides a tool for linting individual reports
-* `cmd/report2cve` provides a tool for converting YAML reports into JSON CVEs
+- `cmd/gendb` provides a tool for converting YAML reports into JSON database
+- `cmd/linter` provides a tool for linting individual reports
+- `cmd/report2cve` provides a tool for converting YAML reports into JSON CVEs
## License
