Documentation
¶
Overview ¶
Package vex implements Red Hat specific interpretation of VEX documents.
Index ¶
- Constants
- func CompileFixedInVersionCEL(expr string) (cel.Program, error)
- func EvalFixedInVersionCEL(prog cel.Program, p *packageurl.PackageURL, defaultVersion string) (string, error)
- type Factory
- type FactoryConfig
- type Parser
- type ParserOption
- type Updater
- func (u *Updater) Configure(ctx context.Context, f driver.ConfigUnmarshaler, c *http.Client) error
- func (u *Updater) DeltaParse(ctx context.Context, contents io.ReadCloser) ([]*claircore.Vulnerability, []string, error)
- func (u *Updater) Fetch(ctx context.Context, hint driver.Fingerprint) (io.ReadCloser, driver.Fingerprint, error)
- func (u *Updater) Name() string
- func (u *Updater) Parse(_ context.Context, _ io.ReadCloser) ([]*claircore.Vulnerability, error)
- type UpdaterConfig
- Bugs
Constants ¶
const ( // BaseURL is the base url for the Red Hat VEX security data. // //doc:url updater BaseURL = "https://security.access.redhat.com/data/csaf/v2/vex-feed/" )
Variables ¶
This section is empty.
Functions ¶
func CompileFixedInVersionCEL ¶ added in v1.6.0
CompileFixedInVersionCEL compiles a CEL expression that evaluates to a string.
The expression may use these variables:
- type (string): PURL type (oci, rpm, etc.)
- namespace (string): PURL namespace
- name (string): PURL name
- version (string): PURL version field
- qualifiers (map[string]string): PURL qualifiers
- fixed_in (string): default FixedInVersion from stock extraction
The environment includes the CEL strings extension (startsWith, substring, split etc.) and bindings to be able to set variables.
An empty expression returns a nil program. Production expressions are supplied by callers if desired.
func EvalFixedInVersionCEL ¶ added in v1.6.0
func EvalFixedInVersionCEL(prog cel.Program, p *packageurl.PackageURL, defaultVersion string) (string, error)
EvalFixedInVersionCEL evaluates a compiled FixedInVersion CEL program.
Types ¶
type Factory ¶
type Factory struct {
// contains filtered or unexported fields
}
Factory creates an Updater to process all of the Red Hat VEX data.
[Configure] must be called before [UpdaterSet].
func (*Factory) UpdaterSet ¶
UpdaterSet constructs one Updater
type FactoryConfig ¶
type FactoryConfig struct {
// URL indicates the base URL for the VEX.
//
// Must include the trailing slash.
URL string `json:"url" yaml:"url"`
// CompressedFileTimeout sets the timeout for downloading the compressed VEX file.
CompressedFileTimeout claircore.Duration `json:"compressed_file_timeout" yaml:"compressed_file_timeout"`
// IgnoreKernelPackages skips all RPM names with a "kernel" prefix, including
// the allowlisted packages that may appear in containers (kernel, kernel-core,
// etc.). This restores the historical skip-all-kernel behaviour and is intended
// as a last-resort opt-out when the extra vulnerability rows are unacceptable.
//
// Defaults to false. Toggling this forces a full archive re-ingest.
IgnoreKernelPackages bool `json:"ignore_kernel_packages" yaml:"ignore_kernel_packages"`
// FixedInVersionCEL is a CEL expression that must evaluate to a string and may
// rewrite the stock FixedInVersion extracted from a PURL. Empty means stock
// extraction only. Production expressions are defined by embedders.
// Changing this value forces a full archive re-ingest.
//
// Configured on the Factory and copied to the Updater by [Factory.UpdaterSet].
//
// Available variables: type, namespace, name, version, qualifiers, fixed_in.
// The CEL strings and bindings extensions are enabled (for example
// startsWith, substring, split, cel.bind). Use [CompileFixedInVersionCEL]
// and [EvalFixedInVersionCEL] to enable testing of expressions on client side.
FixedInVersionCEL string `json:"fixed_in_version_cel" yaml:"fixed_in_version_cel"`
}
FactoryConfig is the configuration honored by the Factory.
The URL is where the updater expects the VEX data to be published (and must end with a slash).
type Parser ¶ added in v1.5.53
type Parser struct {
// contains filtered or unexported fields
}
Parser parses individual RHEL CSAF/VEX documents into claircore vulnerabilities.
It maintains internal caches for claircore objects (Repositories, Packages) that are derived from CPE and product tree data. These caches avoid redundant allocations when the same CPE or product appears across multiple CSAF documents. The CSAF documents themselves are not cached - each document is parsed independently.
Reusing the same Parser instance across multiple documents is more efficient than creating a new one for each document.
func NewParser ¶ added in v1.5.53
func NewParser(opts ...ParserOption) *Parser
NewParser creates a new Parser with initialised caches.
The default base URL is BaseURL. Callers that ingest a different feed should pass WithBaseURL.
func (*Parser) Parse ¶ added in v1.5.53
Parse parses a single RHEL CSAF/VEX document and returns claircore vulnerabilities. The Parser's internal caches for claircore objects are reused, so parsing multiple documents avoids redundant allocations for shared CPEs and repositories.
A Parser is not safe for concurrent use.
type ParserOption ¶ added in v1.5.53
type ParserOption func(*Parser)
ParserOption is a functional option for Parser.
func WithBaseURL ¶ added in v1.6.0
func WithBaseURL(u *url.URL) ParserOption
WithBaseURL sets the VEX feed base URL used to construct a document self-link when a CSAF document omits document.references. The URL must include a trailing slash, as with BaseURL.
func WithFixedInVersionCEL ¶ added in v1.6.0
func WithFixedInVersionCEL(expr string) (ParserOption, error)
WithFixedInVersionCEL compiles expr and installs it as the FixedInVersion rewrite program. See FactoryConfig.FixedInVersionCEL for the CEL variables.
func WithIgnoreKernelPackages ¶ added in v1.6.0
func WithIgnoreKernelPackages() ParserOption
WithIgnoreKernelPackages makes the parser skip all packages whose name has a "kernel" prefix, including allowlisted ones. See FactoryConfig.IgnoreKernelPackages.
func WithProductIDInLinks ¶ added in v1.5.53
func WithProductIDInLinks() ParserOption
WithProductIDInLinks makes the parser embed the VEX product ID as a URL fragment on the self-link of each produced claircore.Vulnerability.
When the CSAF document has no self reference, the link is constructed from the parser's base URL and the document tracking ID. Some feeds (for example the Red Hat beta VEX feed) omit document.references.
This is intended for use in acceptance tests, where the product ID is needed to correlate matcher results back to expected fixture entries.
type Updater ¶
type Updater struct {
// contains filtered or unexported fields
}
Updater is responsible from reading VEX data served at the URL and creating vulnerabilities.
func (*Updater) DeltaParse ¶
func (u *Updater) DeltaParse(ctx context.Context, contents io.ReadCloser) ([]*claircore.Vulnerability, []string, error)
DeltaParse implements driver.DeltaUpdater.
func (*Updater) Fetch ¶
func (u *Updater) Fetch(ctx context.Context, hint driver.Fingerprint) (io.ReadCloser, driver.Fingerprint, error)
Fetch pulls data down from the Red Hat VEX endpoints. The order of operations is:
- Check if we need to process the entire archive of data. If yes: - Make a request to discover the latest archive endpoint. - Make a HEAD request to archive endpoint to get the last-modified header. - Save the last-modified time in the fingerprint's requestTime.
- Process the changes.csv file, requesting and appending the entries that changed since the fingerprint's requestTime.
- Process the deletions.csv file, processing the entries that changed since the fingerprint's requestTime.
- If we need to process entire archive, request the archive data and append the entries that have not been changed or deleted.
This helps to ensure that we only persist one copy of an advisory in the worst possible case. In most cases, after the initial load, the number of processed files should be very small.
func (*Updater) Parse ¶
func (u *Updater) Parse(_ context.Context, _ io.ReadCloser) ([]*claircore.Vulnerability, error)
Parse implements driver.Updater.
type UpdaterConfig ¶
type UpdaterConfig struct {
// URL overrides any discovered URL for the JSON file.
URL string `json:"url" yaml:"url"`
// IgnoreKernelPackages is documented on [FactoryConfig].
IgnoreKernelPackages bool `json:"ignore_kernel_packages" yaml:"ignore_kernel_packages"`
}
UpdaterConfig is the configuration for the updater.
Notes ¶
Bugs ¶
The RHBZ space is somewhat arbitrary. Might be worth doing a little survey of what references are used in the VEX data.
Source Files