scan

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package scan scans container images layer by layer: it pulls an image, streams every file of every layer to a scan engine and works out which findings are visible in the final filesystem and which were deleted by a later layer but are still shipped with the image.

Index

Constants

View Source
const (
	// StatusPresent: the file is visible in the final image filesystem.
	StatusPresent = "present"
	// StatusDeleted: a later layer deleted the file (whiteout or opaque
	// directory), but it is still shipped with the image.
	StatusDeleted = "deleted"
	// StatusOverwritten: a later layer replaced the file or a parent
	// directory.
	StatusOverwritten = "overwritten"
)

Finding statuses.

View Source
const DefaultMaxPaths = 1_000_000

DefaultMaxPaths keeps the cache at roughly 100-150 MiB.

Variables

This section is empty.

Functions

func IsEngineError

func IsEngineError(err error) bool

IsEngineError reports whether err is (or wraps) an EngineError.

Types

type Cache

type Cache struct {
	Max      int
	MaxPaths int
	// contains filtered or unexported fields
}

Cache keeps layer results in memory, keyed by layer digest and diffID, engine and signature version and scan limits. A signature update therefore causes a rescan. The oldest entries are evicted beyond Max layers or MaxPaths paths: a layer result keeps every path of the layer for whiteout detection, so the number of paths, not layers, decides the memory use.

func NewCache

func NewCache(max int) *Cache

NewCache returns a cache holding at most max layers and DefaultMaxPaths paths.

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of cached layers.

type EngineError

type EngineError struct{ Err error }

EngineError is a failure of the scan engine itself (unreachable, timeout, protocol error), as opposed to one of the image or its registry. The operator's scan gate treats it like an outage of meles.

func (*EngineError) Error

func (e *EngineError) Error() string

func (*EngineError) Unwrap

func (e *EngineError) Unwrap() error

type Finding

type Finding struct {
	Platform  string `json:"platform"`
	Layer     int    `json:"layer"`
	DiffID    string `json:"diffID"`
	Path      string `json:"path"`
	Signature string `json:"signature"`
	// SHA256 of the file content, hex.
	SHA256 string `json:"sha256,omitempty"`
	Status string `json:"status"`
	// HiddenByLayer is the layer that deleted or replaced the file.
	HiddenByLayer int `json:"hiddenByLayer,omitempty"`
	// HiddenHow is "whiteout", "opaque" or "overwritten".
	HiddenHow string `json:"hiddenHow,omitempty"`
	CreatedBy string `json:"createdBy,omitempty"`
	// Rule describes the YARA rule behind the signature if it is one of the
	// default rules. Its author must appear wherever the finding is shown
	// (Detection Rule License).
	Rule *yararules.Info `json:"rule,omitempty"`
	// Ignored is set if an ignore rule matched: the finding does not count
	// (unless the rule expired).
	Ignored *ignore.Match `json:"ignored,omitempty"`
}

Finding is a file the engine flagged.

type LayerReport

type LayerReport struct {
	Index     int    `json:"index"`
	DiffID    string `json:"diffID"`
	Digest    string `json:"digest"`
	CreatedBy string `json:"createdBy,omitempty"`
	Files     int    `json:"files"`
	Bytes     int64  `json:"bytes"`
	Cached    bool   `json:"cached"`
}

LayerReport describes one layer of a platform image.

type Option

type Option func(*source.Options)

Option changes a single scan.

func WithAllowPrivate added in v0.2.0

func WithAllowPrivate(host string) Option

WithAllowPrivate lets this scan use private addresses for host (see source.Network), e.g. the registry of the Harbor that asked for it.

func WithInput

func WithInput(path string) Option

WithInput reads the image from a local OCI image layout or docker save archive; the reference then names the image in it, empty for the only one.

func WithInsecure

func WithInsecure() Option

WithInsecure allows a plain HTTP registry for this scan.

func WithKeychain

func WithKeychain(kc authn.Keychain) Option

WithKeychain pulls the image with kc instead of the Scanner's keychain, e.g. with the pull secrets of the pods that run it.

type PlatformReport

type PlatformReport struct {
	Platform string        `json:"platform"`
	Digest   string        `json:"digest"`
	Files    int           `json:"files"`
	Layers   []LayerReport `json:"layers"`
	Findings []Finding     `json:"findings"`
	Skipped  []SkippedFile `json:"skipped"`
}

PlatformReport is the result for one platform of an image.

type Progress

type Progress struct {
	Platform    string
	Layer       int // 1-based
	Layers      int
	FilesQueued int
}

Progress is reported while a scan runs.

type Report

type Report struct {
	// Ref is the image reference; for a local input the name of the image
	// in it, or the input path if it names none.
	Ref string `json:"ref"`
	// Input is the local OCI layout or docker save archive the image was
	// read from; empty for a registry.
	Input  string         `json:"input,omitempty"`
	Digest string         `json:"digest"`
	Engine engine.Version `json:"engine"`
	// Platform is the platform filter that was applied ("all", "host", ...).
	Platform   string           `json:"platformFilter"`
	StartedAt  time.Time        `json:"startedAt"`
	FinishedAt time.Time        `json:"finishedAt"`
	Platforms  []PlatformReport `json:"platforms"`
	// Complete is false if any file was skipped (and not ignored). A report
	// without findings then does not mean the image is clean.
	Complete bool `json:"complete"`
	// IgnoreRules is the number of ignore rules the report was checked
	// against.
	IgnoreRules int `json:"ignoreRules,omitempty"`
}

Report is the result of scanning one image reference.

func (*Report) ActiveFindings

func (r *Report) ActiveFindings() []Finding

ActiveFindings returns the findings that count: not ignored.

func (*Report) ActiveSkipped

func (r *Report) ActiveSkipped() []SkippedFile

ActiveSkipped returns the skipped files that count: not ignored.

func (*Report) ApplyIgnore

func (r *Report) ApplyIgnore(rules *ignore.Rules, now time.Time)

ApplyIgnore marks the findings and skipped files that rules ignore at now and sets Complete accordingly. Ignored entries stay in the report.

func (*Report) Files

func (r *Report) Files() int

Files returns the number of scanned files over all platforms, counting shared layers once per platform.

func (*Report) Findings

func (r *Report) Findings() []Finding

Findings returns the findings of all platforms, including ignored ones.

func (*Report) Infected

func (r *Report) Infected() bool

Infected reports whether any platform has a finding that is not ignored.

func (*Report) Skipped

func (r *Report) Skipped() []SkippedFile

Skipped returns the skipped files of all platforms, including ignored ones.

type Scanner

type Scanner struct {
	Engine engine.Engine
	Limits extract.Limits
	// Concurrency is the number of parallel engine sessions per scan.
	Concurrency int
	// Cache is optional. It is shared between scans.
	Cache  *Cache
	Source source.Options
	Logger *slog.Logger
}

Scanner scans images. It is safe for concurrent use if its Engine is.

func (*Scanner) Scan

func (s *Scanner) Scan(ctx context.Context, ref string, platforms source.PlatformFilter, progress func(Progress), opts ...Option) (*Report, error)

Scan scans the platforms of ref selected by platforms. Progress is optional. An error means the image was not fully scanned; it must never be treated as clean.

type SkippedFile

type SkippedFile struct {
	Platform string `json:"platform"`
	Layer    int    `json:"layer"`
	extract.Skipped
	// Ignored is set if an ignore rule matched.
	Ignored *ignore.Match `json:"ignored,omitempty"`
}

SkippedFile is a file that was not scanned.

Jump to

Keyboard shortcuts

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