client

Documentation

Overview

Package client provides an interface for accessing vulnerability databases, via either HTTP or local filesystem access.

The protocol is described at https://go.dev/security/vulndb/#protocol.

The expected database layout is the same for both HTTP and local databases. The database index is located at the root of the database, and contains a list of all of the vulnerable modules documented in the database and the time the most recent vulnerability was added. The index file is called index.json, and has the following format:

map[string]time.Time (DBIndex)

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.

A single client.Client can be used to access multiple vulnerability databases. When looking up vulnerable modules, each database is consulted, and results are merged together.

Index

• func EscapeModulePath(path string) (string, error)
• func UnescapeModulePath(path string) (string, error)
• type Cache
• type Client
  • func NewClient(sources []string, opts Options) (_ Client, err error)
• type DBIndex
• type Options

Functions

func EscapeModulePath

func EscapeModulePath(path string) (string, error)

EscapeModulePath should be called by cache implementations or other users of this package that want to use module paths as filesystem paths. It is like golang.org/x/mod/module, but accounts for special paths used by the vulnerability database.

func UnescapeModulePath

func UnescapeModulePath(path string) (string, error)

UnescapeModulePath should be called to convert filesystem paths into module paths. It is like golang.org/x/mod/module, but accounts for special paths used by the vulnerability database.

Types

type Cache

type Cache interface {
	// ReadIndex returns the index for the given DB along with the time it was
	// last read from the source.
	ReadIndex(dbName string) (DBIndex, time.Time, error)

	// WriteIndex stores in the index and associated time for the given DB.
	WriteIndex(dbName string, index DBIndex, t time.Time) error

	// ReadEntries returns the entries for modulePath in the named DB.
	ReadEntries(dbName, modulePath string) ([]*osv.Entry, error)

	// WriteEntries stores the entries associated with modulePath in the named
	// DB.
	WriteEntries(dbName, modulePath string, entries []*osv.Entry) error
}

A Cache caches vuln DB entries for modules. A single cache can support multiple DBs from different sources, each with a different name.

type Client

type Client interface {
	// GetByModule returns the entries that affect the given module path.
	// It returns (nil, nil) if there are none.
	GetByModule(context.Context, string) ([]*osv.Entry, error)

	// GetByID returns the entry with the given ID, or (nil, nil) if there isn't
	// one.
	GetByID(context.Context, string) (*osv.Entry, error)

	// GetByAlias returns the entries that have the given aliases, or (nil, nil)
	// if there are none.
	GetByAlias(context.Context, string) ([]*osv.Entry, error)

	// ListIDs returns the IDs of all entries in the database.
	ListIDs(context.Context) ([]string, error)

	// LastModifiedTime returns the time that the database was last modified.
	// It can be used by tools that periodically check for vulnerabilities
	// to avoid repeating work.
	LastModifiedTime(context.Context) (time.Time, error)
	// contains filtered or unexported methods
}

Client interface for fetching vulnerabilities based on module path or ID.

func NewClient

func NewClient(sources []string, opts Options) (_ Client, err error)

type DBIndex

type DBIndex map[string]time.Time

DBIndex contains a mapping of vulnerable packages to the last time a new vulnerability was added to the database.

type Options

type Options struct {
	HTTPClient *http.Client
	HTTPCache  Cache
}