database

Documentation

Overview

Package database provides functionality for reading, writing, and validating Go vulnerability databases according to the v1 schema.

Index

• func IsIndexEndpoint(filename string) bool
• func Unzip(src, dst string) error
• func ValidateDeploy(newPath, oldPath string) (err error)
• func WriteJSON(filename string, value any, indent bool) (err error)
• type DBMeta
• type Database
  • func FromRepo(ctx context.Context, repo *git.Repository) (_ *Database, err error)
  • func Load(path string) (_ *Database, err error)
  • func New(entries ...osv.Entry) (*Database, error)
  • func RawLoad(vulnsPath string) (_ *Database, err error)
  • func (db *Database) Add(entries ...osv.Entry) error
  • func (db *Database) Write(dir string) error
  • func (db *Database) WriteZip(filename string) error
• type Module
• type ModuleVuln
• type ModulesIndex
  • func (m ModulesIndex) MarshalJSON() ([]byte, error)
  • func (m *ModulesIndex) UnmarshalJSON(data []byte) error
• type Vuln
• type VulnsIndex
  • func (v VulnsIndex) MarshalJSON() ([]byte, error)
  • func (v *VulnsIndex) UnmarshalJSON(data []byte) error

Functions

func IsIndexEndpoint

func IsIndexEndpoint(filename string) bool

func Unzip

func Unzip(src, dst string) error

Unzip unzips the zip file in src and writes it to the directory dst.

func ValidateDeploy

func ValidateDeploy(newPath, oldPath string) (err error)

ValidateDeploy checks that the database in newPath is a valid database, and that the database in newPath can be safely deployed on top of the database in oldPath.

func WriteJSON

func WriteJSON(filename string, value any, indent bool) (err error)

Types

type DBMeta

type DBMeta struct {
	// Modified is the time the database was last modified, calculated
	// as the most recent time any single OSV entry was modified.
	Modified osv.Time `json:"modified"`
}

DBMeta contains metadata about the database itself.

type Database

type Database struct {
	// DB represents the index/db.json endpoint.
	DB DBMeta
	// Modules represents the index/modules.json endpoint.
	Modules ModulesIndex
	// Vulns represents the index/vulns.json endpoint.
	Vulns VulnsIndex
	// Entries represents the ID/GO-YYYY-XXXX.json endpoints.
	Entries []osv.Entry
}

Database represents a Go Vulnerability Database in the v1 schema.

func FromRepo

func FromRepo(ctx context.Context, repo *git.Repository) (_ *Database, err error)

FromRepo creates a new Database based on the contents of the "data/osv" folder in the given repo.

It reads each OSV file, marshals it into a struct, updates the modified and published times based on the time of latest and first CL to modify the file, and stores the struct in the Database).

The result is an in-memory vulnerability database that can be written to files via Database.Write.

The repo must contain a "data/osv" folder with files in OSV JSON format with filenames of the form GO-YYYY-XXXX.json.

Does not modify the repo.

func Load

func Load(path string) (_ *Database, err error)

Load loads a database assuming that path contains a full, valid database following the v1 specification.

It errors if:

• any required files are missing or invalid
• any unexpected files are found in the index/ or ID/ folders (with the exception that ID/index.json, from the legacy spec, is ignored)

Any files present in the top level directory are ignored.

func New

func New(entries ...osv.Entry) (*Database, error)

New creates a new database from the given entries. Errors if there are multiple entries with the same ID.

func RawLoad

func RawLoad(vulnsPath string) (_ *Database, err error)

RawLoad loads a database assuming that vulnsPath contains ".json" files representing OSV entries. It errors if any of the files cannot be unmarshaled into osv.Entry. It does not require any database indexes or gzipped files to be present, Directories and non-JSON files are ignored. Also, to accommodate the legacy spec, the file "index.json" is ignored if present.

func (*Database) Add

func (db *Database) Add(entries ...osv.Entry) error

Add adds new entries to a database, erroring if any of the entries is already in the database.

func (*Database) Write

func (db *Database) Write(dir string) error

func (*Database) WriteZip

func (db *Database) WriteZip(filename string) error

WriteZip writes the database to filename as a zip file.

type Module

type Module struct {
	// Path is the module path.
	Path string `json:"path"`
	// Vulns is a list of vulnerabilities that affect this module.
	Vulns []ModuleVuln `json:"vulns"`
}

Module contains metadata about a Go module that has one or more vulnerabilities in the database.

type ModuleVuln

type ModuleVuln struct {
	// ID is a unique identifier for the vulnerability.
	// The Go vulnerability database issues IDs of the form
	// GO-<YEAR>-<ENTRYID>.
	ID string `json:"id"`
	// Modified is the time the vuln was last modified.
	Modified osv.Time `json:"modified"`
	// Fixed is the latest version that introduces a fix for the
	// vulnerability, in SemVer 2.0.0 format, with no leading "v" prefix.
	// (This is technically the earliest version V such that the
	// vulnerability does not occur in any version later than V.)
	//
	// This field can be used to determine if a version is definitely
	// not affected by a vulnerability (if the version is greater than
	// or equal to the fixed version), but the full OSV entry must
	// be downloaded to determine if a version less than the fixed
	// version is affected.
	//
	// This field is optional, and should be empty if there is no
	// known fixed version.
	//
	// Example:
	// Suppose a vulnerability is present in all versions
	// up to (not including) version 1.5.0, is re-introduced in version
	// 2.0.0, and fixed again in version 2.4.0. The "Fixed" version
	// would be 2.4.0.
	// The fixed version tells us that any version greater than or equal
	// to 2.4.0 is not affected, but we would need to look at the OSV
	// entry to determine if any version less than 2.4.0 was affected.
	Fixed string `json:"fixed,omitempty"`
}

ModuleVuln contains metadata about a vulnerability that affects a certain module (as used by the ModulesIndex).

type ModulesIndex

type ModulesIndex map[string]*Module

ModulesIndex is a map from module paths to module metadata. It marshals into and unmarshals from the format published in index/modules.json, which is a JSON array of objects.

func (ModulesIndex) MarshalJSON

func (m ModulesIndex) MarshalJSON() ([]byte, error)

func (*ModulesIndex) UnmarshalJSON

func (m *ModulesIndex) UnmarshalJSON(data []byte) error

type Vuln

type Vuln struct {
	// ID is a unique identifier for the vulnerability.
	// The Go vulnerability database issues IDs of the form
	// GO-<YEAR>-<ENTRYID>.
	ID string `json:"id"`
	// Modified is the time the vulnerability was last modified.
	Modified osv.Time `json:"modified"`
	// Aliases is a list of IDs for the same vulnerability in other
	// databases.
	Aliases []string `json:"aliases,omitempty"`
}

Vuln contains metadata about a vulnerability in the database, as used by the VulnsIndex.

type VulnsIndex

type VulnsIndex map[string]*Vuln

VulnsIndex is a map from vulnerability IDs to vulnerability metadata. It marshals into and unmarshals from the format published in index/vulns.json, which is a JSON array of objects.

func (VulnsIndex) MarshalJSON

func (v VulnsIndex) MarshalJSON() ([]byte, error)

func (*VulnsIndex) UnmarshalJSON

func (v *VulnsIndex) UnmarshalJSON(data []byte) error