x/vuln/client: pseudo-module paths (stdlib, toolchain) need documentation

[hyangah]

The client API has hidden assumptions about the special module names used to retrieve vulnerabilities in Go standard libraries and tool chains. https://github.com/golang/vuln/blob/cbe0a6944b8b222c8d3af76d422695d0d486627b/client/client.go#L301-L308

They need to be documented.

BTW I found the use of stdlib and toolchain is not very intuitive.

• standard library module name is std in go source https://go.googlesource.com/go/+/refs/heads/master/src/go.mod#1 (and cmd for tools in src/cmd directory)
• YAML reports use std for vulnerabilities in standard libs. https://github.com/golang/vulndb/blob/00e94d784786f9fbf3b6c7f3c7e3b45f97d1f288/data/reports/GO-2021-0317.yaml#L2

[dmitshur]

CC @golang/vulndb.

[jba]

I think this should be an internal detail. How does it leak to users?

[neild]

https://go.dev/security/vuln/database documents the meaning of the OSV package field for Go vulnerabilities: The module path, except that the "std" and "cmd" modules use "stdlib" and "toolchain" instead.

I agree that this is confusing.

[hyangah]

@jba In order to use Client.GetByModule or process osv.Package correctly when interacting with the vuln.golang.org, users need to understand these.

@neild How about copy/paste the same to the "Overview" section where "module path" is explained? Currently:

Each vulnerable module is represented by an individual JSON file which contains all of the vulnerabilities in that module. The path for each module file is simply the import path of the module. For example, vulnerabilities in golang.org/x/crypto are contained in the golang.org/x/crypto.json file. The per-module JSON files contain a slice of https://pkg.go.dev/golang.org/x/vuln/osv#Entry.

My personal preference is to have details necessary for writing code using the API is accessible directly from the pkg doc instead of a separate doc.