extractor

Documentation

Overview

Package extractor provides the interface for inventory extraction plugins.

Index

• type Config
• type Inventory
  • func Run(ctx context.Context, config *Config) ([]*Inventory, []*plugin.Status, error)
  • func RunFS(ctx context.Context, config *Config) ([]*Inventory, []*plugin.Status, error)
• type InventoryExtractor
• type ScanInput

Types

type Config

type Config struct {
	Extractors []InventoryExtractor
	ScanRoot   string
	FS         fs.FS
	// Optional: Individual files to extract inventory from. If specified, the
	// extractors will only look at these files during the filesystem traversal.
	// Note that these are not relative to ScanRoot and thus need to be in
	// sub-directories of ScanRoot.
	FilesToExtract []string
	// Optional: Directories that the file system walk should ignore.
	// Note that these are not relative to ScanRoot and thus need to be
	// sub-directories of ScanRoot.
	// TODO(b/279413691): Also skip local paths, e.g. "Skip all .git dirs"
	DirsToSkip []string
	// Optional: If the regex matches a directory, it will be skipped.
	SkipDirRegex *regexp.Regexp
	// Optional: stats allows to enter a metric hook. If left nil, no metrics will be recorded.
	Stats stats.Collector
	// Optional: Whether to read symlinks.
	ReadSymlinks bool
	// Optional: Limit for visited inodes. If 0, no limit is applied.
	MaxInodes int
}

Config stores the config settings for an extraction run.

type Inventory

type Inventory struct {
	// A human-readable name representation of the package. Note that this field
	// should only be used for things like logging as different packages can have
	// multiple different types of names (e.g. .deb packages have a source name
	// and a binary name), in which case we arbitrarily pick one of them to use here.
	// In cases when the exact name type used is important (e.g. when matching
	// against vuln feeds) you should use the specific name field from the Metadata.
	Name string
	// The version of this package.
	Version string

	// Paths or source of files related to the package.
	Locations []string
	// The name of the InventoryExtractor that found this software instance. Set by the core library.
	Extractor string
	// The additional data found in the package.
	Metadata any
}

Inventory is an instance of a software package or library found by the extractor.

func Run

func Run(ctx context.Context, config *Config) ([]*Inventory, []*plugin.Status, error)

Run runs the specified extractors and returns their extraction results, as well as info about whether the plugin runs completed successfully.

func RunFS

func RunFS(ctx context.Context, config *Config) ([]*Inventory, []*plugin.Status, error)

RunFS runs the specified extractors and returns their extraction results, as well as info about whether the plugin runs completed successfully. scanRoot is the location of fsys. This method is for testing, use Run() to avoid confusion with scanRoot vs fsys.

type InventoryExtractor

type InventoryExtractor interface {
	plugin.Plugin
	// FileRequired should return true if the file described by path and mode is
	// relevant for the extractor.
	// Note that the plugin doesn't traverse the filesystem itself but relies on the core
	// library for that.
	FileRequired(path string, mode fs.FileMode) bool
	// Extract extracts inventory data relevant for the extractor from a given file.
	Extract(ctx context.Context, input *ScanInput) ([]*Inventory, error)
	// ToPURL converts an inventory created by this extractor into a PURL.
	ToPURL(i *Inventory) (*purl.PackageURL, error)
	// ToCPEs converts an inventory created by this extractor into CPEs, if supported.
	ToCPEs(i *Inventory) ([]string, error)
}

InventoryExtractor is the interface extraction plugin, used to extract inventory data such as OS and language packages.

type ScanInput

type ScanInput struct {
	// The path of the file to extract, relative to ScanRoot.
	Path string
	// The root directory where the extraction file walking started from.
	ScanRoot string
	Info     fs.FileInfo
	// A reader for accessing contents of the file.
	// Note that the file is closed by the core library, not the plugin.
	Reader io.Reader
}

ScanInput describes one file to extract from.