source

package
v0.52.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 29, 2022 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package source provides an abstraction to allow a user to loosely define a data source to catalog and expose a common interface that catalogers and use explore and analyze data from the data source. All valid (cataloggable) data sources are defined within this package.

Index

Constants

View Source
const WindowsOS = "windows"

Variables

AllScopes is a slice containing all possible scope options

Functions

func GetXid

func GetXid(info os.FileInfo) (uid, gid int)

GetXid is the UID GID system info for unix

Types

type CoordinateSet

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

func NewCoordinateSet

func NewCoordinateSet(coordinates ...Coordinates) (s CoordinateSet)

func (*CoordinateSet) Add

func (s *CoordinateSet) Add(coordinates ...Coordinates)

func (CoordinateSet) Contains

func (s CoordinateSet) Contains(l Coordinates) bool

func (CoordinateSet) Hash

func (s CoordinateSet) Hash() (uint64, error)

func (CoordinateSet) Paths

func (s CoordinateSet) Paths() []string

func (CoordinateSet) Remove

func (s CoordinateSet) Remove(coordinates ...Coordinates)

func (CoordinateSet) ToSlice

func (s CoordinateSet) ToSlice() []Coordinates

type Coordinates

type Coordinates struct {
	RealPath     string `json:"path" cyclonedx:"path"`                 // The path where all path ancestors have no hardlinks / symlinks
	FileSystemID string `json:"layerID,omitempty" cyclonedx:"layerID"` // An ID representing the filesystem. For container images, this is a layer digest. For directories or a root filesystem, this is blank.
}

Coordinates contains the minimal information needed to describe how to find a file within any possible source object (e.g. image and directory sources)

func (Coordinates) ID

func (c Coordinates) ID() artifact.ID

func (Coordinates) String

func (c Coordinates) String() string

type FileContentResolver

type FileContentResolver interface {
	FileContentsByLocation(Location) (io.ReadCloser, error)
}

FileContentResolver knows how to get file content for a given Location

type FileLocationResolver

type FileLocationResolver interface {
	AllLocations() <-chan Location
}

type FileMetadata

type FileMetadata struct {
	Mode            os.FileMode
	Type            FileType
	UserID          int
	GroupID         int
	LinkDestination string
	Size            int64
	MIMEType        string
}

type FileMetadataResolver

type FileMetadataResolver interface {
	FileMetadataByLocation(Location) (FileMetadata, error)
}

type FilePathResolver

type FilePathResolver interface {
	// HasPath indicates if the given path exists in the underlying source.
	HasPath(string) bool
	// FilesByPath fetches a set of file references which have the given path (for an image, there may be multiple matches)
	FilesByPath(paths ...string) ([]Location, error)
	// FilesByGlob fetches a set of file references which the given glob matches
	FilesByGlob(patterns ...string) ([]Location, error)
	// FilesByMIMEType fetches a set of file references which the contents have been classified as one of the given MIME Types
	FilesByMIMEType(types ...string) ([]Location, error)
	// RelativeFileByPath fetches a single file at the given path relative to the layer squash of the given reference.
	// This is helpful when attempting to find a file that is in the same layer or lower as another file.
	RelativeFileByPath(_ Location, path string) *Location
}

FilePathResolver knows how to get a Location for given string paths and globs

type FileResolver

FileResolver is an interface that encompasses how to get specific file references and file contents for a generic data source.

func NewExcludingResolver

func NewExcludingResolver(delegate FileResolver, excludeFn excludeFn) FileResolver

NewExcludingResolver create a new resolver which wraps the provided delegate and excludes entries based on a provided path exclusion function

type FileType

type FileType string
const (
	RegularFile FileType = "RegularFile"
	// IrregularFile is how syft defines files that are neither regular, symbolic or directory.
	// For ref: the seven standard Unix file types are regular, directory, symbolic link,
	// FIFO special, block special, character special, and socket as defined by POSIX.
	IrregularFile   FileType = "IrregularFile"
	HardLink        FileType = "HardLink"
	SymbolicLink    FileType = "SymbolicLink"
	CharacterDevice FileType = "CharacterDevice"
	BlockDevice     FileType = "BlockDevice"
	Directory       FileType = "Directory"
	FIFONode        FileType = "FIFONode"
	Socket          FileType = "Socket"
)

type ImageMetadata

type ImageMetadata struct {
	UserInput      string          `json:"userInput"`
	ID             string          `json:"imageID"`
	ManifestDigest string          `json:"manifestDigest"`
	MediaType      string          `json:"mediaType"`
	Tags           []string        `json:"tags"`
	Size           int64           `json:"imageSize"`
	Layers         []LayerMetadata `json:"layers"`
	RawManifest    []byte          `json:"manifest"`
	RawConfig      []byte          `json:"config"`
	RepoDigests    []string        `json:"repoDigests"`
	Architecture   string          `json:"architecture"`
	Variant        string          `json:"architectureVariant,omitempty"`
	OS             string          `json:"os"`
}

ImageMetadata represents all static metadata that defines what a container image is. This is useful to later describe "what" was cataloged without needing the more complicated stereoscope Image objects or FileResolver objects.

func NewImageMetadata

func NewImageMetadata(img *image.Image, userInput string) ImageMetadata

NewImageMetadata creates a new ImageMetadata object populated from the given stereoscope Image object and user configuration.

type Input

type Input struct {
	UserInput   string
	Scheme      Scheme
	ImageSource image.Source
	Location    string
	Platform    string
	// contains filtered or unexported fields
}

Input is an object that captures the detected user input regarding source location, scheme, and provider type. It acts as a struct input for some source constructors.

func ParseInput

func ParseInput(userInput string, platform string, detectAvailableImageSources bool) (*Input, error)

ParseInput generates a source Input that can be used as an argument to generate a new source from specific providers including a registry.

type LayerMetadata

type LayerMetadata struct {
	MediaType string `json:"mediaType"`
	Digest    string `json:"digest"`
	Size      int64  `json:"size"`
}

LayerMetadata represents all static metadata that defines what a container image layer is.

type Location

type Location struct {
	Coordinates `cyclonedx:""` // Empty string here means there is no intermediate property name, e.g. syft:locations:0:path without "coordinates"
	// note: it is IMPORTANT to ignore anything but the coordinates for a Location when considering the ID (hash value)
	// since the coordinates are the minimally correct ID for a location (symlinks should not come into play)
	VirtualPath string `hash:"ignore"` // The path to the file which may or may not have hardlinks / symlinks
	// contains filtered or unexported fields
}

Location represents a path relative to a particular filesystem resolved to a specific file.Reference. This struct is used as a key in content fetching to uniquely identify a file relative to a request (the VirtualPath).

func NewLocation

func NewLocation(realPath string) Location

NewLocation creates a new Location representing a path without denoting a filesystem or FileCatalog reference.

func NewLocationFromCoordinates

func NewLocationFromCoordinates(coordinates Coordinates) Location

NewLocationFromCoordinates creates a new location for the given Coordinates.

func NewLocationFromDirectory

func NewLocationFromDirectory(responsePath string, ref file.Reference) Location

NewLocationFromDirectory creates a new Location representing the given path (extracted from the ref) relative to the given directory.

func NewLocationFromImage

func NewLocationFromImage(virtualPath string, ref file.Reference, img *image.Image) Location

NewLocationFromImage creates a new Location representing the given path (extracted from the ref) relative to the given image.

func NewVirtualLocation

func NewVirtualLocation(realPath, virtualPath string) Location

NewVirtualLocation creates a new location for a path accessed by a virtual path (a path with a symlink or hardlink somewhere in the path)

func NewVirtualLocationFromDirectory

func NewVirtualLocationFromDirectory(responsePath, virtualResponsePath string, ref file.Reference) Location

NewVirtualLocationFromDirectory creates a new Location representing the given path (extracted from the ref) relative to the given directory with a separate virtual access path.

func (Location) Equals

func (l Location) Equals(other Location) bool

func (Location) String

func (l Location) String() string

type LocationSet

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

func NewLocationSet

func NewLocationSet(locations ...Location) (s LocationSet)

func (*LocationSet) Add

func (s *LocationSet) Add(locations ...Location)

func (LocationSet) Contains

func (s LocationSet) Contains(l Location) bool

func (*LocationSet) CoordinateSet

func (s *LocationSet) CoordinateSet() CoordinateSet

func (LocationSet) Hash

func (s LocationSet) Hash() (uint64, error)

func (LocationSet) Remove

func (s LocationSet) Remove(locations ...Location)

func (LocationSet) ToSlice

func (s LocationSet) ToSlice() []Location

type Locations

type Locations []Location

func (Locations) Len

func (l Locations) Len() int

func (Locations) Less

func (l Locations) Less(i, j int) bool

func (Locations) Swap

func (l Locations) Swap(i, j int)

type Metadata

type Metadata struct {
	Scheme        Scheme        // the source data scheme type (directory or image)
	ImageMetadata ImageMetadata // all image info (image only)
	Path          string        // the root path to be cataloged (directory only)
}

Metadata represents any static source data that helps describe "what" was cataloged.

type MockResolver

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

MockResolver implements the FileResolver interface and is intended for use *only in test code*. It provides an implementation that can resolve local filesystem paths using only a provided discrete list of file paths, which are typically paths to test fixtures.

func NewMockResolverForPaths

func NewMockResolverForPaths(paths ...string) *MockResolver

NewMockResolverForPaths creates a new MockResolver, where the only resolvable files are those specified by the supplied paths.

func NewMockResolverForPathsWithMetadata

func NewMockResolverForPathsWithMetadata(metadata map[Location]FileMetadata) *MockResolver

func (MockResolver) AllLocations

func (r MockResolver) AllLocations() <-chan Location

func (MockResolver) FileContentsByLocation

func (r MockResolver) FileContentsByLocation(location Location) (io.ReadCloser, error)

FileContentsByLocation fetches file contents for a single location. If the path does not exist, an error is returned.

func (MockResolver) FileMetadataByLocation

func (r MockResolver) FileMetadataByLocation(l Location) (FileMetadata, error)

func (MockResolver) FilesByGlob

func (r MockResolver) FilesByGlob(patterns ...string) ([]Location, error)

FilesByGlob returns all Locations that match the given path glob pattern.

func (MockResolver) FilesByMIMEType

func (r MockResolver) FilesByMIMEType(types ...string) ([]Location, error)

func (MockResolver) FilesByPath

func (r MockResolver) FilesByPath(paths ...string) ([]Location, error)

FilesByPath returns all Locations that match the given paths.

func (MockResolver) HasPath

func (r MockResolver) HasPath(path string) bool

HasPath indicates if the given path exists in the underlying source.

func (MockResolver) RelativeFileByPath

func (r MockResolver) RelativeFileByPath(_ Location, path string) *Location

RelativeFileByPath returns a single Location for the given path.

func (MockResolver) String

func (r MockResolver) String() string

String returns the string representation of the MockResolver.

type Scheme

type Scheme string

Scheme represents the optional prefixed string at the beginning of a user request (e.g. "docker:").

const (
	// UnknownScheme is the default scheme
	UnknownScheme Scheme = "UnknownScheme"
	// DirectoryScheme indicates the source being cataloged is a directory on the root filesystem
	DirectoryScheme Scheme = "DirectoryScheme"
	// ImageScheme indicates the source being cataloged is a container image
	ImageScheme Scheme = "ImageScheme"
	// FileScheme indicates the source being cataloged is a single file
	FileScheme Scheme = "FileScheme"
)

func DetectScheme

func DetectScheme(fs afero.Fs, imageDetector sourceDetector, userInput string) (Scheme, image.Source, string, error)

type Scope

type Scope string

Scope indicates "how" or from "which perspectives" the source object should be cataloged from.

const (
	// UnknownScope is the default scope
	UnknownScope Scope = "UnknownScope"
	// SquashedScope indicates to only catalog content visible from the squashed filesystem representation (what can be seen only within the container at runtime)
	SquashedScope Scope = "Squashed"
	// AllLayersScope indicates to catalog content on all layers, irregardless if it is visible from the container at runtime.
	AllLayersScope Scope = "AllLayers"
)

func ParseScope

func ParseScope(userStr string) Scope

ParseScope returns a scope as indicated from the given string.

func (Scope) String

func (o Scope) String() string

type Source

type Source struct {
	Image    *image.Image // the image object to be cataloged (image only)
	Metadata Metadata

	Exclusions []string
	// contains filtered or unexported fields
}

Source is an object that captures the data source to be cataloged, configuration, and a specific resolver used in cataloging (based on the data source and configuration)

func New

func New(in Input, registryOptions *image.RegistryOptions, exclusions []string) (*Source, func(), error)

New produces a Source based on userInput like dir: or image:tag

func NewFromDirectory

func NewFromDirectory(path string) (Source, error)

NewFromDirectory creates a new source object tailored to catalog a given filesystem directory recursively.

func NewFromFile

func NewFromFile(path string) (Source, func())

NewFromFile creates a new source object tailored to catalog a file.

func NewFromImage

func NewFromImage(img *image.Image, userImageStr string) (Source, error)

NewFromImage creates a new source object tailored to catalog a given container image, relative to the option given (e.g. all-layers, squashed, etc)

func NewFromRegistry

func NewFromRegistry(in Input, registryOptions *image.RegistryOptions, exclusions []string) (*Source, func(), error)

func (*Source) FileResolver

func (s *Source) FileResolver(scope Scope) (FileResolver, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL