source

package
v0.79.0 Latest Latest
Warning

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

 Go to latest Published: Apr 21, 2023 License: Apache-2.0 Imports: 34 Imported by: 123

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

View Source 
var AllSchemes = []Scheme{
	DirectoryScheme,
	ImageScheme,
	FileScheme,
}
View Source 
var AllScopes = []Scope{
	SquashedScope,
	AllLayersScope,
}

AllScopes is a slice containing all possible scope options

Functions

func GetXid added in v0.27.0 

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

GetXid is the UID GID system info for unix

Types

type CoordinateSet added in v0.31.0 

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

func NewCoordinateSet added in v0.31.0 

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

func (*CoordinateSet) Add added in v0.31.0 

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

func (CoordinateSet) Contains added in v0.31.0 

func (s CoordinateSet) Contains(l Coordinates) bool

func (CoordinateSet) Hash added in v0.43.0 

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

func (CoordinateSet) Paths added in v0.43.0 

func (s CoordinateSet) Paths() []string

func (CoordinateSet) Remove added in v0.31.0 

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

func (CoordinateSet) ToSlice added in v0.31.0 

func (s CoordinateSet) ToSlice() []Coordinates

type Coordinates added in v0.31.0 

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 added in v0.31.0 

func (c Coordinates) ID() artifact.ID

func (Coordinates) String added in v0.31.0 

func (c Coordinates) String() string

type DeferredResolver added in v0.76.0 

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

func NewDeferredResolver added in v0.76.0 

func NewDeferredResolver(creator func() (FileResolver, error)) *DeferredResolver

func NewDeferredResolverFromSource added in v0.76.0 

func NewDeferredResolverFromSource(creator func() (Source, error)) *DeferredResolver

func (*DeferredResolver) AllLocations added in v0.76.0 

func (d *DeferredResolver) AllLocations() <-chan Location

func (*DeferredResolver) FileContentsByLocation added in v0.76.0 

func (d *DeferredResolver) FileContentsByLocation(location Location) (io.ReadCloser, error)

func (*DeferredResolver) FileMetadataByLocation added in v0.76.0 

func (d *DeferredResolver) FileMetadataByLocation(location Location) (FileMetadata, error)

func (*DeferredResolver) FilesByGlob added in v0.76.0 

func (d *DeferredResolver) FilesByGlob(patterns ...string) ([]Location, error)

func (*DeferredResolver) FilesByMIMEType added in v0.76.0 

func (d *DeferredResolver) FilesByMIMEType(types ...string) ([]Location, error)

func (*DeferredResolver) FilesByPath added in v0.76.0 

func (d *DeferredResolver) FilesByPath(paths ...string) ([]Location, error)

func (*DeferredResolver) HasPath added in v0.76.0 

func (d *DeferredResolver) HasPath(s string) bool

func (*DeferredResolver) RelativeFileByPath added in v0.76.0 

func (d *DeferredResolver) RelativeFileByPath(location Location, path string) *Location

type EmptyResolver added in v0.78.0 

type EmptyResolver struct{}

func (EmptyResolver) AllLocations added in v0.78.0 

func (e EmptyResolver) AllLocations() <-chan Location

func (EmptyResolver) FileContentsByLocation added in v0.78.0 

func (e EmptyResolver) FileContentsByLocation(_ Location) (io.ReadCloser, error)

func (EmptyResolver) FileMetadataByLocation added in v0.78.0 

func (e EmptyResolver) FileMetadataByLocation(_ Location) (FileMetadata, error)

func (EmptyResolver) FilesByGlob added in v0.78.0 

func (e EmptyResolver) FilesByGlob(_ ...string) ([]Location, error)

func (EmptyResolver) FilesByMIMEType added in v0.78.0 

func (e EmptyResolver) FilesByMIMEType(_ ...string) ([]Location, error)

func (EmptyResolver) FilesByPath added in v0.78.0 

func (e EmptyResolver) FilesByPath(_ ...string) ([]Location, error)

func (EmptyResolver) HasPath added in v0.78.0 

func (e EmptyResolver) HasPath(_ string) bool

func (EmptyResolver) RelativeFileByPath added in v0.78.0 

func (e EmptyResolver) RelativeFileByPath(_ Location, _ string) *Location

func (EmptyResolver) Write added in v0.78.0 

func (e EmptyResolver) Write(_ Location, _ io.Reader) error

type FileContentResolver added in v0.15.0 

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

FileContentResolver knows how to get file content for a given Location

type FileLocationResolver added in v0.15.0 

type FileLocationResolver interface {
	// AllLocations returns a channel of all file references from the underlying source.
	// The implementation for this may vary, however, generally the following considerations should be made:
	// - NO symlink resolution should be performed on results
	// - returns locations for any file or directory
	AllLocations() <-chan Location
}

type FileMetadata added in v0.15.0 

type FileMetadata = file.Metadata

type FileMetadataResolver added in v0.15.0 

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

type FilePathResolver added in v0.15.0 

type FilePathResolver interface {
	// HasPath indicates if the given path exists in the underlying source.
	// The implementation for this may vary, however, generally the following considerations should be made:
	// - full symlink resolution should be performed on all requests
	// - returns locations for any file or directory
	HasPath(string) bool

	// FilesByPath fetches a set of file references which have the given path (for an image, there may be multiple matches).
	// The implementation for this may vary, however, generally the following considerations should be made:
	// - full symlink resolution should be performed on all requests
	// - only returns locations to files (NOT directories)
	FilesByPath(paths ...string) ([]Location, error)

	// FilesByGlob fetches a set of file references for the given glob matches
	// The implementation for this may vary, however, generally the following considerations should be made:
	// - full symlink resolution should be performed on all requests
	// - if multiple paths to the same file are found, the best single match should be returned
	// - only returns locations to files (NOT directories)
	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 

type FileResolver interface {
	FileContentResolver
	FilePathResolver
	FileLocationResolver
	FileMetadataResolver
}

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

func NewExcludingResolver added in v0.34.0 

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 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 added in v0.40.0 

type Input struct {
	UserInput   string
	Scheme      Scheme
	ImageSource image.Source
	Location    string
	Platform    string
	Name        string
}

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 added in v0.40.0 

func ParseInput(userInput string, platform string) (*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.

func ParseInputWithName added in v0.61.0 

func ParseInputWithName(userInput string, platform, name, defaultImageSource string) (*Input, error)

ParseInputWithName generates a source Input that can be used as an argument to generate a new source from specific providers including a registry, with an explicit name.

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 {
	LocationData     `cyclonedx:""`
	LocationMetadata `cyclonedx:""`
}

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 added in v0.31.0 

func NewLocationFromCoordinates(coordinates Coordinates) Location

NewLocationFromCoordinates creates a new location for the given Coordinates.

func NewLocationFromDirectory added in v0.23.0 

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 added in v0.31.0 

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 NewVirtualLocationFromCoordinates added in v0.78.0 

func NewVirtualLocationFromCoordinates(coordinates Coordinates, virtualPath string) Location

NewVirtualLocationFromCoordinates creates a new location for the given Coordinates via a virtual path.

func NewVirtualLocationFromDirectory added in v0.39.0 

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) AccessPath added in v0.60.0 

func (l Location) AccessPath() string

func (Location) Equals added in v0.43.0 

func (l Location) Equals(other Location) bool

func (Location) String added in v0.14.0 

func (l Location) String() string

func (Location) WithAnnotation added in v0.78.0 

func (l Location) WithAnnotation(key, value string) Location

type LocationData added in v0.78.0 

type LocationData 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" json:"-"` // The path to the file which may or may not have hardlinks / symlinks
	// contains filtered or unexported fields
}

type LocationMetadata added in v0.78.0 

type LocationMetadata struct {
	Annotations map[string]string `json:"annotations,omitempty"` // Arbitrary key-value pairs that can be used to annotate a location
}

type LocationReadCloser added in v0.60.0 

type LocationReadCloser struct {
	Location
	io.ReadCloser
}

func NewLocationReadCloser added in v0.60.0 

func NewLocationReadCloser(location Location, reader io.ReadCloser) LocationReadCloser

type LocationSet added in v0.43.0 

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

func NewLocationSet added in v0.43.0 

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

func (*LocationSet) Add added in v0.43.0 

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

func (LocationSet) Contains added in v0.43.0 

func (s LocationSet) Contains(l Location) bool

func (*LocationSet) CoordinateSet added in v0.43.0 

func (s *LocationSet) CoordinateSet() CoordinateSet

func (LocationSet) Hash added in v0.43.0 

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

func (LocationSet) Remove added in v0.43.0 

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

func (LocationSet) ToSlice added in v0.43.0 

func (s LocationSet) ToSlice() []Location

type Locations added in v0.43.0 

type Locations []Location

func (Locations) Len added in v0.43.0 

func (l Locations) Len() int

func (Locations) Less added in v0.43.0 

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

func (Locations) Swap added in v0.43.0 

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

type Metadata 

type Metadata struct {
	ID            string        `hash:"ignore"` // the id generated from the parent source 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)
	Base          string        // the base path to be cataloged (directory only)
	Name          string
}

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

type MockResolver added in v0.11.1 

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 added in v0.11.1 

func NewMockResolverForPaths(paths ...string) *MockResolver

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

func NewMockResolverForPathsWithMetadata added in v0.15.0 

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

func (MockResolver) AllLocations added in v0.15.0 

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

func (MockResolver) FileContentsByLocation added in v0.11.1 

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 added in v0.15.0 

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

func (MockResolver) FilesByBasename added in v0.71.0 

func (r MockResolver) FilesByBasename(filenames ...string) ([]Location, error)

func (MockResolver) FilesByBasenameGlob added in v0.71.0 

func (r MockResolver) FilesByBasenameGlob(_ ...string) ([]Location, error)

func (MockResolver) FilesByExtension added in v0.71.0 

func (r MockResolver) FilesByExtension(extensions ...string) ([]Location, error)

func (MockResolver) FilesByGlob added in v0.11.1 

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

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

func (MockResolver) FilesByMIMEType added in v0.25.0 

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

func (MockResolver) FilesByPath added in v0.11.1 

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

FilesByPath returns all Locations that match the given paths.

func (MockResolver) HasPath added in v0.12.1 

func (r MockResolver) HasPath(path string) bool

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

func (MockResolver) RelativeFileByPath added in v0.11.1 

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

RelativeFileByPath returns a single Location for the given path.

func (MockResolver) String added in v0.11.1 

func (r MockResolver) String() string

String returns the string representation of the MockResolver.

func (MockResolver) Write added in v0.78.0 

func (r MockResolver) Write(_ Location, _ io.Reader) error

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 added in v0.39.0 

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 `hash:"ignore"` // the image object to be cataloged (image only)
	Metadata Metadata

	Exclusions []string `hash:"ignore"`
	// 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 NewFromDirectoryRoot added in v0.69.0 

func NewFromDirectoryRoot(path string) (Source, error)

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

func NewFromDirectoryRootWithName added in v0.69.0 

func NewFromDirectoryRootWithName(path string, name string) (Source, error)

NewFromDirectoryRootWithName creates a new source object tailored to catalog a given filesystem directory recursively, with an explicitly provided name.

func NewFromDirectoryWithName added in v0.61.0 

func NewFromDirectoryWithName(path string, name string) (Source, error)

NewFromDirectoryWithName creates a new source object tailored to catalog a given filesystem directory recursively, with an explicitly provided name.

func NewFromFile added in v0.30.0 

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

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

func NewFromFileWithName added in v0.61.0 

func NewFromFileWithName(path string, name string) (Source, func())

NewFromFileWithName creates a new source object tailored to catalog a file, with an explicitly provided name.

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 NewFromImageWithName added in v0.61.0 

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

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

func NewFromRegistry added in v0.40.0 

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

func (*Source) FileResolver added in v0.15.0 

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

func (*Source) ID added in v0.59.0 

func (s *Source) ID() artifact.ID

func (*Source) SetID added in v0.59.0 

func (s *Source) SetID()

type UnindexedDirectoryResolver added in v0.78.0 

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

func (UnindexedDirectoryResolver) AllLocations added in v0.78.0 

func (u UnindexedDirectoryResolver) AllLocations() <-chan Location

- NO symlink resolution should be performed on results - returns locations for any file or directory

func (UnindexedDirectoryResolver) FileContentsByLocation added in v0.78.0 

func (u UnindexedDirectoryResolver) FileContentsByLocation(location Location) (io.ReadCloser, error)

func (UnindexedDirectoryResolver) FileMetadataByLocation added in v0.78.0 

func (u UnindexedDirectoryResolver) FileMetadataByLocation(_ Location) (FileMetadata, error)

func (UnindexedDirectoryResolver) FilesByGlob added in v0.78.0 

func (u UnindexedDirectoryResolver) FilesByGlob(patterns ...string) (out []Location, _ error)

- full symlink resolution should be performed on all requests - if multiple paths to the same file are found, the best single match should be returned - only returns locations to files (NOT directories)

func (UnindexedDirectoryResolver) FilesByMIMEType added in v0.78.0 

func (u UnindexedDirectoryResolver) FilesByMIMEType(_ ...string) ([]Location, error)

func (UnindexedDirectoryResolver) FilesByPath added in v0.78.0 

func (u UnindexedDirectoryResolver) FilesByPath(paths ...string) (out []Location, _ error)

- full symlink resolution should be performed on all requests - only returns locations to files (NOT directories)

func (UnindexedDirectoryResolver) HasPath added in v0.78.0 

func (u UnindexedDirectoryResolver) HasPath(p string) bool

- full symlink resolution should be performed on all requests - returns locations for any file or directory

func (UnindexedDirectoryResolver) RelativeFileByPath added in v0.78.0 

func (u UnindexedDirectoryResolver) RelativeFileByPath(l Location, p string) *Location

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.

func (UnindexedDirectoryResolver) Write added in v0.78.0 

func (u UnindexedDirectoryResolver) Write(location Location, reader io.Reader) error

type WritableFileResolver added in v0.78.0 

type WritableFileResolver interface {
	FileResolver

	Write(location Location, reader io.Reader) error
}

func NewUnindexedDirectoryResolver added in v0.78.0 

func NewUnindexedDirectoryResolver(dir string) WritableFileResolver

func NewUnindexedDirectoryResolverFS added in v0.78.0 

func NewUnindexedDirectoryResolverFS(fs afero.Fs, dir string, base string) WritableFileResolver

func NewUnindexedDirectoryResolverRooted added in v0.78.0 

func NewUnindexedDirectoryResolverRooted(dir string, base string) WritableFileResolver

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.