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 ¶
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 Coverage ¶
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 ¶
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).
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
}
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
func ResolveDefaultScope ¶
ResolveDefaultScope picks the default scope: staged when the index is non-empty, else full with the caller printing the note (cli-spec §5).