cvecatalog

Documentation

Overview

Package cvecatalog implements a catalog of contain Ubuntu kernels fixed CVEs which provides quick lookup for arbitrary Ubuntu kernel packages.

The package supports a few formats (like OSV bucket ZIP archive, or Canonical `.tar.xz` archive).

Note that this is meant to be a generic package and that is why it has no relation/reference to the Livepatch server internals. However, the package provides methods to allow Livepatch server to transfer a catalog over the wire.

Index

• func NormalizeCVEID(cve string) string
• func ValidateCVEData(data CVEData) error
• type ABI
• type ABIList
  • func NewABIList() *ABIList
  • func (l *ABIList) AddFixedCVEToABI(abi uint64, cveData CVEData) error
  • func (l *ABIList) GetFixedCVEs(abi uint64) []CVEData
• type Bucket
  • func BucketFromPackageName(packageName string) (Bucket, uint64, error)
  • func BucketFromString(s string) (Bucket, error)
  • func (k *Bucket) Series() string
  • func (k *Bucket) String() string
• type CVE
• type CVEData
• type Catalog
  • func NewCatalog() *Catalog
  • func ProcessZIP(data []byte) (*Catalog, error)
  • func ReadXZ(reader io.Reader) (*Catalog, error)
  • func ReadZIP(reader io.Reader) (*Catalog, error)
  • func (c *Catalog) AddCVEFile(cve CVE) error
  • func (c *Catalog) ComputeDigest() (string, error)
  • func (c *Catalog) Find(packageName string) ([]CVEData, error)
  • func (c *Catalog) GetBucketABIList(bucket Bucket) (*ABIList, error)
  • func (c *Catalog) GetBuckets() []Bucket
  • func (c *Catalog) SetBucketABIList(bucket Bucket, abis *ABIList)

Functions

func NormalizeCVEID

func NormalizeCVEID(cve string) string

NormalizeCVEID is a helper function to normalize CVE names/IDs into a stable casing and format. A well formatted CVE name is like `UBUNTU-CVE-2024-99999`.

Note that, at the client side, CVE names/IDs extracted from the patch files look like `cve-2024-9999` (i.e., missing the `UBUNTU-` prefix and also all in small caps). Sometimes the extracted CVE IDs also include information on other systems, such as Launchpad making the IDs look like cve-2025-123;LP 98. This function handles such cases.

func ValidateCVEData

func ValidateCVEData(data CVEData) error

ValidateCVEData performs comprehensive validation on a CVEData structure. It validates CVE ID and USN formats.

Types

type ABI

type ABI struct {
	ABI uint64

	// NewlyFixedCVEs is the set of CVEs that are newly fixed in the ABI version
	// denoted by the `ABI` field. This means, it does not include those CVEs
	// fixed in earlier ABI versions.
	//
	// To get the list of all fixed CVEs (including earlier versions) you should
	// use the `GetFixedCVEs` method.
	NewlyFixedCVEs map[string]CVEData
}

ABI represents a specific ABI version and the CVEs fixed in them.

type ABIList

type ABIList struct {

	// List is the ordered slice of ABIs and CVEs fixed in them.
	List []ABI
	// contains filtered or unexported fields
}

ABIList contains a list of ABI versions and CVEs fixed in each ABI for a bucket/group.

func NewABIList

func NewABIList() *ABIList

NewABIList creates a new ABIList instance.

func (*ABIList) AddFixedCVEToABI

func (l *ABIList) AddFixedCVEToABI(abi uint64, cveData CVEData) error

func (*ABIList) GetFixedCVEs

func (l *ABIList) GetFixedCVEs(abi uint64) []CVEData

GetFixedCVEs returns a sorted slice of all CVEs fixed in the given ABI version, including those fixed in earlier ABI versions.

type Bucket

type Bucket struct {
	Major   int
	Minor   int
	Patch   int
	Flavour string
}

Bucket represents a bucket/group key identified by a kernel version and a flavour (e.g., `6.8.0-generic` or `5.8.0-aws`).

func BucketFromPackageName

func BucketFromPackageName(packageName string) (Bucket, uint64, error)

BucketFromPackageName extracts a bucket from a package name string and returns the bucket object and the ABI number.

func BucketFromString

func BucketFromString(s string) (Bucket, error)

BucketFromString returns a bucket from the given string representation.

func (*Bucket) Series

func (k *Bucket) Series() string

Series returns the kernel series as a string; e.g. "6.8.0".

func (*Bucket) String

func (k *Bucket) String() string

String returns a string representation of the bucket; e.g., "6.8.0-generic"

type CVE

type CVE struct {
	SchemaVersion string `json:"schema_version"`

	ID       string   `json:"id"`
	Aliases  []string `json:"aliases"`
	Affected []struct {
		Package struct {
			Ecosystem string `json:"ecosystem"`
			Name      string `json:"name"`
		} `json:"package"`
		Ranges []struct {
			Type   string `json:"type"`
			Events []struct {
				Introduced string `json:"introduced"`
				Fixed      string `json:"fixed"`
			} `json:"events"`
		} `json:"ranges"`
		Versions          []string `json:"versions"`
		EcosystemSpecific struct {
			Binaries []struct {
				BinaryName    string `json:"binary_name"`
				BinaryVersion string `json:"binary_version"`
			} `json:"binaries"`
		} `json:"ecosystem_specific"`
	} `json:"affected"`
	Published string   `json:"published"`
	Modified  string   `json:"modified"`
	Related   []string `json:"related"`
}

CVE models a CVE file. For simplicity this type is used as a DTO and a model at the same time.

Fields that we are not interested in them are commented out.

type CVEData

type CVEData struct {
	ID string `json:"ID"`
	// Published is the date when the CVE was published.
	Published string `json:"Published"`
	// Modified is the date when the CVE was last modified.
	Modified string `json:"Modified"`
	// RelatedUSNs is the list of USNs related to the CVE
	RelatedUSNs []string `json:"RelatedUSNs"`
}

CVEData represents the CVE data structure as it is stored in the catalog.

type Catalog

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog represents a data structure of fixed CVEs information, capable of looking up for Ubuntu kernel package names and resolving the list of CVEs fixed in them.

func NewCatalog

func NewCatalog() *Catalog

NewCatalog creates an empty catalog.

func ProcessZIP

func ProcessZIP(data []byte) (*Catalog, error)

ProcessZIP processes ZIP data from a byte slice and returns a fixed CVEs catalog. This is more memory-efficient than ReadZIP when the data is already in memory, as it avoids an additional io.ReadAll() call.

Only CVE files that start with "UBUNTU-CVE-" and end with ".json" will be processed. Any files not matching these criteria will be ignored.

Returns a fixed CVEs catalog.

func ReadXZ

func ReadXZ(reader io.Reader) (*Catalog, error)

ReadXZ reads from the given `.tar.xz` stream of OSV CVE data and returns a fixed CVEs catalog.

The CVE files in the archive must be organised under the `osv/cve/` prefix, and they must be in JSON format. Any files not matching these criteria will be ignored.

Returns a fixed CVEs catalog.

The caller is responsible for closing the provided stream.

func ReadZIP

func ReadZIP(reader io.Reader) (*Catalog, error)

ReadZIP reads from the given `.zip` stream of OSV CVE data and returns a fixed CVEs catalog.

Only CVE files that start with "UBUNTU-CVE-" and end with ".json" will be processed. Any files not matching these criteria will be ignored.

Returns a fixed CVEs catalog.

The caller is responsible for closing the provided stream.

func (*Catalog) AddCVEFile

func (c *Catalog) AddCVEFile(cve CVE) error

AddCVEFile adds a CVE file entry to the catalog.

func (*Catalog) ComputeDigest

func (c *Catalog) ComputeDigest() (string, error)

ComputeDigest returns a base64 digest out of the data stored in the catalog.

The returned digest is guaranteed to be stable regarding the ordering of elements in the internal maps/slices.

func (*Catalog) Find

func (c *Catalog) Find(packageName string) ([]CVEData, error)

Find returns the list of CVEs fixed in the given Ubuntu kernel package name.

Note that the returned slice also contains CVEs from all earlier ABI versions.

If the package name is not explicitly listed in the underlying data set, this method will return the list of CVEs fixed in the highest version prior to the given package.

func (*Catalog) GetBucketABIList

func (c *Catalog) GetBucketABIList(bucket Bucket) (*ABIList, error)

GetBucketABIList returns the ABI list of the given bucket. If the bucket was not found, it returns an error.

func (*Catalog) GetBuckets

func (c *Catalog) GetBuckets() []Bucket

GetBuckets returns a stably-ordered list of buckets in the catalog.

func (*Catalog) SetBucketABIList

func (c *Catalog) SetBucketABIList(bucket Bucket, abis *ABIList)

SetBucketABIList sets the ABI list for the given bucket.