syft

Documentation

Overview

Package syft is a "one-stop-shop" for helper utilities for all major functionality provided by child packages of the syft library.

Here is what the main execution path for syft does:

1. Parse a user image string to get a stereoscope image.Source object
2. Invoke all catalogers to catalog the image, adding discovered packages to a single catalog object
3. Invoke one or more encoders to output contents of the catalog

A Source object encapsulates the image object to be cataloged and the user options (catalog all layers vs. squashed layer), providing a way to inspect paths and file content within the image. The Source object, not the image object, is used throughout the main execution path. This abstraction allows for decoupling of what is cataloged (a docker image, an OCI image, a filesystem, etc) and how it is cataloged (the individual catalogers).

Similar to the cataloging process, Linux distribution identification is also performed based on what is discovered within the image.

Index

• func CreateSBOM(ctx context.Context, src source.Source, cfg *CreateSBOMConfig) (*sbom.SBOM, error)
• func GetSource(ctx context.Context, userInput string, cfg *GetSourceConfig) (source.Source, error)
• func SetBus(b *partybus.Bus)
• func SetLogger(logger logger.Logger)
• type CreateSBOMConfig
  • func DefaultCreateSBOMConfig() *CreateSBOMConfig
  • func (c *CreateSBOMConfig) Create(ctx context.Context, src source.Source) (*sbom.SBOM, error)
  • func (c *CreateSBOMConfig) WithCatalogerSelection(selection pkgcataloging.SelectionRequest) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithCatalogers(catalogerRefs ...pkgcataloging.CatalogerReference) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithDataGenerationConfig(cfg cataloging.DataGenerationConfig) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithFilesConfig(cfg filecataloging.Config) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithPackagesConfig(cfg pkgcataloging.Config) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithParallelism(p int) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithRelationshipsConfig(cfg cataloging.RelationshipsConfig) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithSearchConfig(cfg cataloging.SearchConfig) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithTool(name, version string, cfg ...any) *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithoutCatalogers() *CreateSBOMConfig
  • func (c *CreateSBOMConfig) WithoutFiles() *CreateSBOMConfig
• type GetSourceConfig
  • func DefaultGetSourceConfig() *GetSourceConfig
  • func (c *GetSourceConfig) WithAlias(alias source.Alias) *GetSourceConfig
  • func (c *GetSourceConfig) WithBasePath(basePath string) *GetSourceConfig
  • func (c *GetSourceConfig) WithDefaultImagePullSource(defaultImagePullSource string) *GetSourceConfig
  • func (c *GetSourceConfig) WithDigestAlgorithms(algorithms ...crypto.Hash) *GetSourceConfig
  • func (c *GetSourceConfig) WithExcludeConfig(excludeConfig source.ExcludeConfig) *GetSourceConfig
  • func (c *GetSourceConfig) WithPlatform(platform *image.Platform) *GetSourceConfig
  • func (c *GetSourceConfig) WithRegistryOptions(registryOptions *image.RegistryOptions) *GetSourceConfig
  • func (c *GetSourceConfig) WithSources(sources ...string) *GetSourceConfig

Functions

func CreateSBOM

func CreateSBOM(ctx context.Context, src source.Source, cfg *CreateSBOMConfig) (*sbom.SBOM, error)

CreateSBOM creates a software bill-of-materials from the given source. If the CreateSBOMConfig is nil, then default options will be used.

func GetSource

func GetSource(ctx context.Context, userInput string, cfg *GetSourceConfig) (source.Source, error)

GetSource uses all of Syft's known source providers to attempt to resolve the user input to a usable source.Source

func SetBus

func SetBus(b *partybus.Bus)

SetBus sets the event bus for all syft library bus publish events onto (in-library subscriptions are not allowed).

func SetLogger

func SetLogger(logger logger.Logger)

SetLogger sets the logger object used for all syft logging calls.

Types

type CreateSBOMConfig

type CreateSBOMConfig struct {
	// required configuration input to specify how cataloging should be performed
	Search             cataloging.SearchConfig
	Relationships      cataloging.RelationshipsConfig
	DataGeneration     cataloging.DataGenerationConfig
	Packages           pkgcataloging.Config
	Files              filecataloging.Config
	Parallelism        int
	CatalogerSelection pkgcataloging.SelectionRequest

	// audit what tool is being used to generate the SBOM
	ToolName          string
	ToolVersion       string
	ToolConfiguration interface{}
	// contains filtered or unexported fields
}

CreateSBOMConfig specifies all parameters needed for creating an SBOM.

func DefaultCreateSBOMConfig

func DefaultCreateSBOMConfig() *CreateSBOMConfig

func (*CreateSBOMConfig) Create

func (c *CreateSBOMConfig) Create(ctx context.Context, src source.Source) (*sbom.SBOM, error)

Create creates an SBOM from the given source with the current SBOM configuration.

func (*CreateSBOMConfig) WithCatalogerSelection

func (c *CreateSBOMConfig) WithCatalogerSelection(selection pkgcataloging.SelectionRequest) *CreateSBOMConfig

WithCatalogerSelection allows for adding to, removing from, or sub-selecting the final set of catalogers by name or tag.

func (*CreateSBOMConfig) WithCatalogers

func (c *CreateSBOMConfig) WithCatalogers(catalogerRefs ...pkgcataloging.CatalogerReference) *CreateSBOMConfig

WithCatalogers allows for adding user-provided catalogers to the final set of catalogers that will always be run regardless of the source type or any cataloger selections provided.

func (*CreateSBOMConfig) WithDataGenerationConfig

func (c *CreateSBOMConfig) WithDataGenerationConfig(cfg cataloging.DataGenerationConfig) *CreateSBOMConfig

WithDataGenerationConfig allows for defining what data elements that cannot be discovered from the underlying target being scanned that should be generated after package creation.

func (*CreateSBOMConfig) WithFilesConfig

func (c *CreateSBOMConfig) WithFilesConfig(cfg filecataloging.Config) *CreateSBOMConfig

WithFilesConfig allows for defining file-based cataloging parameters.

func (*CreateSBOMConfig) WithPackagesConfig

func (c *CreateSBOMConfig) WithPackagesConfig(cfg pkgcataloging.Config) *CreateSBOMConfig

WithPackagesConfig allows for defining any specific behavior for syft-implemented catalogers.

func (*CreateSBOMConfig) WithParallelism

func (c *CreateSBOMConfig) WithParallelism(p int) *CreateSBOMConfig

WithParallelism allows for setting the number of concurrent cataloging tasks that can be performed at once

func (*CreateSBOMConfig) WithRelationshipsConfig

func (c *CreateSBOMConfig) WithRelationshipsConfig(cfg cataloging.RelationshipsConfig) *CreateSBOMConfig

WithRelationshipsConfig allows for defining the specific relationships that should be captured during cataloging.

func (*CreateSBOMConfig) WithSearchConfig

func (c *CreateSBOMConfig) WithSearchConfig(cfg cataloging.SearchConfig) *CreateSBOMConfig

WithSearchConfig allows for setting the specific search configuration for cataloging.

func (*CreateSBOMConfig) WithTool

func (c *CreateSBOMConfig) WithTool(name, version string, cfg ...any) *CreateSBOMConfig

WithTool allows for setting the specific name, version, and any additional configuration that is not captured in the syft default API configuration. This could cover inputs for catalogers that were user-provided, thus, is not visible to the syft API, but would be useful to see in the SBOM output.

func (*CreateSBOMConfig) WithoutCatalogers

func (c *CreateSBOMConfig) WithoutCatalogers() *CreateSBOMConfig

WithoutCatalogers removes all catalogers from the final set of catalogers. This is useful if you want to only use user-provided catalogers (without the default syft-provided catalogers).

func (*CreateSBOMConfig) WithoutFiles

func (c *CreateSBOMConfig) WithoutFiles() *CreateSBOMConfig

WithoutFiles allows for disabling file cataloging altogether.

type GetSourceConfig

type GetSourceConfig struct {
	// SourceProviderConfig may optionally be provided to be used when constructing the default set of source providers, unused if All specified
	SourceProviderConfig *sourceproviders.Config

	// Sources is an explicit list of source names to use, in order, to attempt to locate a source
	Sources []string

	// DefaultImagePullSource will cause a particular image pull source to be used as the first pull source, followed by other pull sources
	DefaultImagePullSource string
}

func DefaultGetSourceConfig

func DefaultGetSourceConfig() *GetSourceConfig

func (*GetSourceConfig) WithAlias

func (c *GetSourceConfig) WithAlias(alias source.Alias) *GetSourceConfig

func (*GetSourceConfig) WithBasePath

func (c *GetSourceConfig) WithBasePath(basePath string) *GetSourceConfig

func (*GetSourceConfig) WithDefaultImagePullSource

func (c *GetSourceConfig) WithDefaultImagePullSource(defaultImagePullSource string) *GetSourceConfig

func (*GetSourceConfig) WithDigestAlgorithms

func (c *GetSourceConfig) WithDigestAlgorithms(algorithms ...crypto.Hash) *GetSourceConfig

func (*GetSourceConfig) WithExcludeConfig

func (c *GetSourceConfig) WithExcludeConfig(excludeConfig source.ExcludeConfig) *GetSourceConfig

func (*GetSourceConfig) WithPlatform

func (c *GetSourceConfig) WithPlatform(platform *image.Platform) *GetSourceConfig

func (*GetSourceConfig) WithRegistryOptions

func (c *GetSourceConfig) WithRegistryOptions(registryOptions *image.RegistryOptions) *GetSourceConfig

func (*GetSourceConfig) WithSources

func (c *GetSourceConfig) WithSources(sources ...string) *GetSourceConfig