scan

package
v0.2.6 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package scan orchestrates one scan: scope resolution and staging inside the engine container, scanner invocation contracts, SARIF projection, and the delta fold against state (cli-spec §§6–8). Scanner exec runs outside the artefact lock; only the fold+append+rewrite critical section holds it (§14).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func TierScanners

func TierScanners(scope Scope, deep, checkov bool) []string

TierScanners implements the scope→scanner table (cli-spec §6): the fast tier is gitleaks+trivy; --full and --deep add opengrep. checkov joins the filesystem tier only where the repository opts in (scanners.checkov), on every scope it applies to, so coverage claims stay honest (spec §5.2). There is no --fast and no --no-deep – --full already asks for everything. The image scope has no filesystem tier: its only scanner, trivy-image, is run by the image phase itself.

Types

type Counts

type Counts struct {
	Confirmed                         int
	ConfirmedHigh, ConfirmedLow       int
	Critical, High, Medium, Low, Info int
	Dismissed, Suppressed, Baseline   int
	Dev                               int // open/confirmed rows in dev dependency chains
}

type Coverage

type Coverage struct {
	Scanners []string
	AllPaths bool
	Paths    map[string]bool
}

Coverage describes what a scan actually looked at — remediation proof (spec §3.1: absence from a scan that did not cover the file, or did not run the scanner that found it, is not remediation).

type DB added in v0.2.3

type DB struct {
	Digest    string `json:"digest,omitempty"`
	UpdatedAt string `json:"updatedAt,omitempty"` // RFC3339 advisories date
	Source    string `json:"source"`              // managed | baked
}

DB records one advisory artifact's live identity at scan time (PR B): what the scanners actually matched against. Digest is empty and Source "baked" before the first update-db swap (engineclient.ReadDBInfo is the source of this).

type FoldResult

type FoldResult struct {
	Events   []events.Event
	Findings []*store.Finding
}

FoldResult is the delta of one scan: events to append (in append order — detected/remediated first, surfaced last) and the replacement findings list.

func Fold

func Fold(state *store.State, merged []*projection.MergedFinding, cov Coverage, o Options, now time.Time) (*FoldResult, error)

Fold merges scan results against state per cli-spec §8.3. New fingerprints get one detected event per location, so a rebuild reproduces state exactly; baseline fingerprints' detections predate the log's first scan and emit nothing. Surfaced events carry one entry per actionable finding shown — `cavet log --fingerprint` reconstructs presentation history (cli-spec §16.16).

type LastScan

type LastScan struct {
	Scope    string        `json:"scope"`
	Scanners []string      `json:"scanners"`
	Phase    string        `json:"phase"`
	Engine   string        `json:"engine"`
	At       string        `json:"at"`
	DB       map[string]DB `json:"db,omitempty"`
}

LastScan is the coverage header the posture view shows: the scanners, phase, and engine of the most recent scan (cli-spec §5 bare). Derived, scan-written, not log-reconstructable — the last_seen family (artefacts §6.4, deviation cli-spec §16.18). DB joins the per-scan advisory identity keyed by artifact name ("vuln"; the java DB stays state-level, nothing in the scan path consumes it).

func ReadLastScan

func ReadLastScan(s *store.Store) (*LastScan, error)

ReadLastScan returns the stored coverage header, or nil before any scan.

type Options

type Options struct {
	Scope   Scope
	DiffRef string
	Images  []config.ImageEntry // configured Dockerfiles plus build targets (scan.container_images)
	Deep    bool
	Checkov bool // scanners.checkov: the opt-in second IaC scanner joins the filesystem tier
	DevDeps bool // scanners.dev-deps: include dev dependency chains in the trivy fs scan
	// Timeout is the trivy scan budget as a Go duration string ("90m"),
	// resolved by the CLI (scan.timeout under the --timeout flag); empty
	// leaves trivy's own built-in default. Passed verbatim: trivy parses Go
	// durations.
	Timeout string
	Actor   events.Actor
	Phase   events.Phase
	Context events.SurfaceContext
	Engine  string // engine ref recorded on every event (artefacts §2.1)
	// VulnDB is the live vuln DB identity this scan runs against, read once
	// after EnsureRunning (engineclient.ReadDBInfo). Zero value (failed or
	// skipped read) records nothing: findings keep their old shape.
	VulnDB engineclient.DBInfo
}

type Result

type Result struct {
	NothingStaged bool
	ScopeLabel    string
	Scanners      []string
	Phase         events.Phase
	Rows          []Row
	Counts        Counts
	DismissedIDs  []string // display ids of dismissed findings, for next hints
	Items         int      // open items after this scan's fold
	DevIncluded   bool     // scanners.dev-deps was on for this scan
}

func Run

func Run(ctx context.Context, s *store.Store, r Runner, o Options) (*Result, error)

Run performs one scan end to end.

type Row

type Row struct {
	FP         string
	DisplayID  string
	Sev        string
	Rule       string
	Path       string
	Line       int
	Desc       string
	Confidence string
	Secret     bool
	Dev        bool
}

Row is one confirmed-or-open finding for the result table. Confidence is the verdict confidence (high|low) when triaged; Secret drives state-derived next hints.

type Runner

type Runner interface {
	Exec(ctx context.Context, cmd []string) (engineclient.ExecResult, error)
	CopyOut(ctx context.Context, containerPath string) ([]byte, error)
	NextScanDir() string
	BuildImage(ctx context.Context, dockerfilePath, contextDir, tag, target string, output io.Writer) error
	SaveImage(ctx context.Context, ref, destPath string) error
	CopyToContainer(ctx context.Context, srcPath, dstPath string) error
	RemoveImage(ctx context.Context, ref string) error
}

Runner is the engine seam: engineclient.Client satisfies it; tests fake it. The image methods are the Task-1 host-side plumbing the image phase drives.

type Scope

type Scope int
const (
	ScopeStaged Scope = iota
	ScopeDiff
	ScopeFull
	ScopeImage
)

func ResolveDefaultScope

func ResolveDefaultScope(ctx context.Context, r Runner) (Scope, error)

ResolveDefaultScope picks the default scope: staged when the index is non-empty, else full with the caller printing the note (cli-spec §5).

func (Scope) String

func (s Scope) String() string

Jump to

Keyboard shortcuts

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