image

Documentation

Overview

Package image implements the unpacker that extracts dependency data from container images. It pulls an image by its OCI reference, or reads it from a docker-archive tarball, squashes its layers into a single filesystem, and routes that filesystem to the SystemPackages unpacker to read the installed-package databases.

Index

• Constants
• Variables
• type ExtractionMode
• type Options
• type PullHooks
• type Reference
  • func (r *Reference) DecomposableType() string
• type Unpacker
  • func NewUnpacker() *Unpacker
  • func (u *Unpacker) Extract(ctx context.Context, subject api.DecomposableSubject) ([]*sbom.NodeList, error)
  • func (u *Unpacker) RegisterDecomposer(api.Decomposer)
  • func (u *Unpacker) UnregisterDecomposer(api.Decomposer)

Constants

const SubjectType = "image"

SubjectType is the DecomposableSubject type routed to the image unpacker.

Variables

var DefaultOptions = Options{}

DefaultOptions is the zero-value configuration used by NewUnpacker.

Types

type ExtractionMode

type ExtractionMode int

ExtractionMode selects how the unpacker reads the image filesystem.

const (
	// ModeSquash flattens all layers into a single filesystem, the way a
	// container runtime presents the image, and extracts from the result.
	ModeSquash ExtractionMode = iota

	// ModePerLayer extracts from each layer individually. Not implemented
	// yet.
	ModePerLayer
)

type Options

type Options struct {
	// Mode selects squashed or per-layer extraction. Defaults to ModeSquash.
	Mode ExtractionMode

	// IncludeFiles is passed through to the system decomposers: when set,
	// every file installed by a package is emitted as a Node related to its
	// package.
	IncludeFiles bool

	// RecordLayers adds one structural node per image layer, related to
	// the image through a contains edge. Layers are identified by their
	// diff id — the digest of the uncompressed layer — and carry no
	// packages: the package inventory always reads from the squashed
	// filesystem.
	RecordLayers bool

	// Hooks receives download progress notifications, e.g. to render a
	// progress indicator. Optional.
	Hooks *PullHooks
}

Options configures the image unpacker.

type PullHooks

type PullHooks struct {
	// LayerStart fires when a layer blob starts downloading. total is the
	// compressed size in bytes, or -1 when unknown.
	LayerStart func(digest string, total int64)

	// LayerProgress fires as layer bytes arrive.
	LayerProgress func(digest string, complete, total int64)

	// LayerDone fires when a layer blob has been fully downloaded.
	LayerDone func(digest string)
}

PullHooks receives notifications while image blobs are downloaded. All callbacks are optional; nil hooks (or nil callbacks) are skipped. A text UI can register these to render download progress.

Callbacks may be invoked from concurrent goroutines (layers download in parallel) so implementations must be safe for concurrent use.

type Reference

type Reference struct {
	// Ref is the OCI reference of the image or image index.
	Ref string

	// Archive is the path to a docker-archive tarball (the `docker save`
	// format) holding the image. When set, the image is read from the
	// archive instead of pulled from a registry. Ref, when also set,
	// selects the tagged image in a multi-image archive and provides the
	// reference identity; left empty, the identity comes from the
	// archive's RepoTags, or from the image digest when it has none.
	Archive string
}

Reference is the DecomposableSubject consumed by the image unpacker: a container image addressed by an OCI reference, e.g. "alpine:3.24", "ghcr.io/org/app@sha256:..." or "registry.example.com/app:v1", or held in a docker-archive tarball on disk.

func (*Reference) DecomposableType

func (r *Reference) DecomposableType() string

DecomposableType identifies this subject as a container image, routing it to the image unpacker through the registry.

type Unpacker

type Unpacker struct {
	Options Options
}

Unpacker extracts dependency data from container images. It downloads the image, squashes its layers into the filesystem a running container would see, and reads the installed system packages out of it.

func NewUnpacker

func NewUnpacker() *Unpacker

NewUnpacker returns an image unpacker with the default options.

func (*Unpacker) Extract

func (u *Unpacker) Extract(ctx context.Context, subject api.DecomposableSubject) ([]*sbom.NodeList, error)

Extract pulls the image referenced by the subject — or reads it from the subject's archive — and returns its dependency graph: a node describing the image with the system packages found in its filesystem as descendants.

func (*Unpacker) RegisterDecomposer

func (u *Unpacker) RegisterDecomposer(api.Decomposer)

RegisterDecomposer is a no-op: the image unpacker has no decomposers of its own; it delegates to the unpackers of the subjects it discovers inside the image.

func (*Unpacker) UnregisterDecomposer

func (u *Unpacker) UnregisterDecomposer(api.Decomposer)

UnregisterDecomposer is a no-op; see RegisterDecomposer.