engine

type CVEResult struct {
	ID      string  `json:"id"`
	Verdict Verdict `json:"verdict"`
	Reason  string  `json:"reason,omitempty"`
}

type Detector interface {
	Manifest() Manifest
	// Load parses and checks the detector's embedded data. An error means the
	// data contradicts itself and the engine refuses to run.
	Load() error
	// NewScan starts a scan of one filesystem or image target.
	NewScan(kind TargetKind) Scan
}

type File struct {
	Path       string
	Data       []byte
	Executable bool
	// Member is true for a file found inside an archive or package.
	Member bool
}

type Finding struct {
	Detector string  `json:"detector"`
	Kind     string  `json:"kind"`
	Path     string  `json:"path"`
	Line     int     `json:"line,omitempty"` // for findings in source files
	Verdict  Verdict `json:"verdict"`
	Reason   string  `json:"reason,omitempty"`
	// Message is the exact fact, in words.
	Message string `json:"message"`
	// Method says how it was found (pem, pkcs12, go-buildinfo, elf-strings...).
	Method string `json:"method,omitempty"`
	// Facts are short checkable values (hashes, versions), also written to SARIF.
	Facts map[string]string `json:"facts,omitempty"`
	CVEs  []CVEResult       `json:"cves,omitempty"`
	Fix   string            `json:"fix,omitempty"`
	// Severity, when set, overrides the kind's SARIF level for this finding:
	// critical and high are errors, medium and low warnings.
	Severity string `json:"severity,omitempty"`
	// Details is the detector's own record of the finding, kept whole.
	Details any `json:"details,omitempty"`
}

type Fixer interface {
	Fix(ctx context.Context, dirs []string, opts Options, stdout, stderr io.Writer) int
}

type Kind struct {
	ID    string // stable, used in SARIF rule IDs as "<detector>/<kind>"
	Title string
	// Level is the SARIF level for a vulnerable finding: "error", "warning" or
	// "note" (something to look at that is not itself a vulnerability).
	Level string
	// Description explains the kind in a sentence or two (SARIF fullDescription).
	Description string
	// SecuritySeverity is the CVSS-style score code scanners sort by ("9.2").
	SecuritySeverity string
	CWEs             []string
}

type Manifest struct {
	ID         string
	Title      string
	CVEs       []string
	Advisories []string // URLs; the first is the SARIF help link
	Disclosed  string   // YYYY-MM-DD
	Targets    []TargetKind
	Kinds      []Kind
	Tags       []string
	// Archives asks the engine to unpack archives and packages (jar, whl, deb,
	// rpm, compressed files, PyInstaller executables) and hand every member to
	// Visit as "outer!/inner".
	Archives bool
	// Data identifies the detector's knowledge snapshot, for the report.
	Data string
}

type Options struct {
	MaxFileSize int64
	Platform    string // image platform, e.g. linux/amd64
	AsRoot      bool   // fs: treat the directory itself as a system root
	// SystemRoot (fs) is the directory holding the system the scanned path
	// belongs to, "/" by default. Paths are reported inside it, and detectors
	// can read its package databases even when only a subdirectory is walked.
	SystemRoot string
	Timeout    time.Duration // host: connect timeout; repo: registry timeout per request
	// Repository scans and fixes.
	Offline    bool     // no registry lookups
	PublicOnly bool     // contact only public registry addresses
	Platforms  []string // the platforms that are built; empty means every platform
	DryRun     bool     // fix: print changes without writing them
}

type Prober interface {
	// Probe connects to addr and returns the name it resolved to, how many items
	// it checked (certificates, responses) and what it found.
	Probe(ctx context.Context, addr string, timeout time.Duration) (target string, checked int, findings []Finding, err error)
}

type Reader interface {
	Wants(path string, head []byte, executable bool) bool
}

type RepoScanner interface {
	ScanRepo(ctx context.Context, dir string, opts Options) *Target
}

type Scan interface {
	Visit(f File) []Skip
	Finish(ctx TargetContext) []Finding
}

type Skip struct {
	Path   string
	Reason string
	// contains filtered or unexported fields
}

type Target struct {
	Name     string        `json:"target"`
	Type     TargetKind    `json:"type"`
	Digest   string        `json:"digest,omitempty"`
	Platform string        `json:"platform,omitempty"`
	Root     string        `json:"root,omitempty"` // filesystem scans: SARIF paths are relative to it
	Files    int           `json:"files_scanned"`  // regular files examined
	Read     int           `json:"files_read"`     // of those, read in full and checked
	Findings []Finding     `json:"findings"`
	Skipped  []source.Skip `json:"skipped"`
	// Problems are things a detector could not read fully (a damaged package
	// database), which weaken its verdicts without stopping the scan.
	Problems []string `json:"problems,omitempty"`
	// Annotations are facts about the whole target (its OS release).
	Annotations map[string]any `json:"annotations,omitempty"`
	// Incomplete says why the scan could not finish (a registry failed).
	Incomplete string `json:"incomplete,omitempty"`
	Error      string `json:"error,omitempty"`
}

type TargetContext interface {
	Kind() TargetKind
	// Exists reports whether a regular file at that absolute path was scanned.
	Exists(path string) bool
	// Env is the image configuration's environment ("KEY=value"), nil otherwise.
	Env() []string
	// Aliases returns every path that names the same file as p (symlinks, hard
	// links), p included.
	Aliases(p string) []string
	// Links returns every symlink (path -> target as written) and hard link
	// (path -> path it names) seen in the walk, for detectors that resolve
	// them their own way.
	Links() (symlinks, hardlinks map[string]string)
	// SystemRoot is the OS path of the system root when a directory below it
	// was scanned, so a detector can read the root's package databases. It is
	// empty for images and for walks that start at the root.
	SystemRoot() string
	// Problem records something read only partly (a damaged package database).
	Problem(msg string)
	// Annotate records a fact about the whole target, such as its OS release.
	Annotate(key string, v any)
}

type TargetKind string

type Verdict string