filesystem

Documentation

Overview

Package filesystem provides the interface for inventory extraction plugins.

Index

• Variables
• func ExtractorErrorToFileExtractedResult(err error) stats.FileExtractedResult
• func InitWalkContext(ctx context.Context, config *Config, absScanRoots []*scalibrfs.ScanRoot) (*walkContext, error)
• func IsInterestingExecutable(api FileAPI) bool
• func Run(ctx context.Context, config *Config) ([]*extractor.Inventory, []*plugin.Status, error)
• func RunFS(ctx context.Context, config *Config, wc *walkContext) ([]*extractor.Inventory, []*plugin.Status, error)
• type Config
• type Extractor
• type FileAPI
• type ScanInput
  • func (i *ScanInput) GetRealPath() (string, error)

Variables

var (
	// ErrExtractorMemoryLimitExceeded is returned when an extractor skips a file
	// due to the extraction process exceeding a configured memory limit.
	ErrExtractorMemoryLimitExceeded = errors.New("extraction failed due to extractor exceeding the configured memory limit")
)

var (
	// ErrNotRelativeToScanRoots is returned when one of the file or directory to be retrieved or
	// skipped is not relative to any of the scan roots.
	ErrNotRelativeToScanRoots = errors.New("path not relative to any of the scan roots")
)

Functions

func ExtractorErrorToFileExtractedResult

func ExtractorErrorToFileExtractedResult(err error) stats.FileExtractedResult

ExtractorErrorToFileExtractedResult converts an error returned by an extractor to a FileExtractedResult for stats collection. Converting the error to a result minimizes the memory used for reporting stats.

func InitWalkContext

func InitWalkContext(ctx context.Context, config *Config, absScanRoots []*scalibrfs.ScanRoot) (*walkContext, error)

InitWalkContext initializes the walk context for a filesystem walk. It strips all the paths that are expected to be relative to the scan root. This function is exported for TESTS ONLY.

func IsInterestingExecutable

func IsInterestingExecutable(api FileAPI) bool

IsInterestingExecutable returns true if the specified file is an executable which may need scanning.

func Run

func Run(ctx context.Context, config *Config) ([]*extractor.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, wc *walkContext) ([]*extractor.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.

Types

type Config

type Config struct {
	Extractors []Extractor
	ScanRoots  []*scalibrfs.ScanRoot
	// 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 the ScanRoots and thus need to be
	// sub-directories of one of the ScanRoots.
	FilesToExtract []string
	// Optional: Directories that the file system walk should ignore.
	// Note that these are not relative to the ScanRoots and thus need to be
	// sub-directories of one of the ScanRoots.
	// 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: If the regex matches a glob, it will be skipped.
	SkipDirGlob glob.Glob
	// 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
	// Optional: By default, inventories stores a path relative to the scan root. If StoreAbsolutePath
	// is set, the absolute path is stored instead.
	StoreAbsolutePath bool
	// Optional: If true, print a detailed analysis of the duration of each extractor.
	PrintDurationAnalysis bool
	// Optional: If true, fail the scan if any permission errors are encountered.
	ErrorOnFSErrors bool
}

Config stores the config settings for an extraction run.

type Extractor

type Extractor interface {
	extractor.Extractor
	// FileRequired should return true if the file described by path and file info is
	// relevant for the extractor.
	// Note that the plugin doesn't traverse the filesystem itself but relies on the core
	// library for that.
	FileRequired(api FileAPI) bool
	// Extract extracts inventory data relevant for the extractor from a given file.
	Extract(ctx context.Context, input *ScanInput) ([]*extractor.Inventory, error)
}

Extractor is the filesystem-based inventory extraction plugin, used to extract inventory data from the filesystem such as OS and language packages.

type FileAPI

type FileAPI interface {
	// Stat returns the file info for the file.
	Stat() (fs.FileInfo, error)
	Path() string
}

FileAPI is the interface for accessing file information and path.

type ScanInput

type ScanInput struct {
	// FS for file access. This is rooted at Root.
	FS scalibrfs.FS
	// The path of the file to extract, relative to Root.
	Path string
	// The root directory where the extraction file walking started from.
	Root 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.

func (*ScanInput) GetRealPath

func (i *ScanInput) GetRealPath() (string, error)

GetRealPath returns the real absolute path of the file on the scanning host's filesystem. If the file is on a virtual filesystem (e.g. a remote container), it is first copied into a temporary directory on the scanning host's filesystem. It's up to the caller to delete the directory once they're done using it.