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"`
	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"`
	// Details is the detector's own record of the finding, kept whole.
	Details any `json:"details,omitempty"`
}

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" or "warning".
	Level 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 as a system root
	Timeout     time.Duration // host: connect timeout
}

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 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"`
	Findings []Finding     `json:"findings"`
	Skipped  []source.Skip `json:"skipped"`
	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
}

type TargetKind string

type Verdict string