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 ¶
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.
const DefaultMaxPaths = 1_000_000
DefaultMaxPaths keeps the cache at roughly 100-150 MiB.
Variables ¶
This section is empty.
Functions ¶
func IsEngineError ¶
IsEngineError reports whether err is (or wraps) an EngineError.
Types ¶
type Cache ¶
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.
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 ¶
Option changes a single scan.
func WithAllowPrivate ¶ added in v0.2.0
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 ¶
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 ¶
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 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 ¶
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 ¶
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 ¶
Files returns the number of scanned files over all platforms, counting shared layers once per platform.
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.