presets

type ExceptionVerdict struct {
	// State is one of the four constants above.
	State string

	// Reason states why, for every state — an entry the report leaves in place
	// has to say what it is waiting for, or the file goes quiet again.
	Reason string

	// StillOn names the catalogue repository that still carries the CVE, which
	// is the repository the entry has to be re-filed against. Set for carry-over
	// alone, so a verdict never implies a repository it did not find the finding
	// on.
	StillOn string

	// FixedIn carries the fix the scanners reported for this CVE, when there is
	// one. An exception must never be written for a vulnerability that is fixed
	// upstream — that is image freshness, not a decision — so an entry that
	// turns out to have a fix is named as such rather than silently renewed.
	FixedIn string
}

type Finding struct {
	// ID is the identifier the scanner reported: a CVE, or a GHSA where the
	// scanner knows the advisory but not the CVE it maps to.
	ID string

	// Severity is HIGH or CRITICAL; the callers filter before constructing one.
	Severity string

	// Package names the installed package the finding is against, as the
	// scanner spells it.
	Package string

	// PackageType is the ecosystem the package comes from — `gobinary` /
	// `go-module` for a Go binary's embedded module list, `debian` / `deb` /
	// `apk` / `rpm` for an OS package.
	PackageType string

	// FixedIn is the version that fixes it, empty when no fix exists at any
	// version. Trivy calls it `FixedVersion`, Grype `fix.versions`.
	FixedIn string

	// EPSS is the probability of exploitation in the next 30 days, 0 when the
	// scanner reported none. Grype carries it, Trivy does not. It is reported,
	// never thresholded: it tells a human where to look first.
	EPSS float64

	// KEV records that CISA lists the vulnerability as actively exploited.
	// Measured zero on this catalogue, which is exactly why the field is
	// reported rather than acted on automatically.
	KEV bool
}

type Option struct {
	Type        string `yaml:"type" toml:"type"`                 // string, bool, int, array
	Default     any    `yaml:"default" toml:"default"`           // Default value
	Description string `yaml:"description" toml:"description"`   // Help text
	EnvVar      string `yaml:"env_var" toml:"env_var"`           // Maps to environment variable
	CommandFlag string `yaml:"command_flag" toml:"command_flag"` // Maps to command flag
}

type OptionTOML struct {
	Type        string      `toml:"type"`
	Default     interface{} `toml:"default"`
	Description string      `toml:"description"`
	CommandFlag string      `toml:"command_flag"`
	EnvVar      string      `toml:"env_var"`
}

type Preset struct {
	Name          string            `yaml:"name" toml:"name"`
	Phase         string            `yaml:"phase" toml:"phase"`
	Image         string            `yaml:"image" toml:"image"`
	Description   string            `yaml:"description,omitempty" toml:"description,omitempty"` // Usage notes and constraints, shown by `preset info`
	Hardened      bool              `yaml:"hardened,omitempty" toml:"hardened,omitempty"`       // Uses Docker Hardened Image (dhi.io)
	Command       string            `yaml:"command" toml:"command"`
	Entrypoint    []string          `yaml:"entrypoint" toml:"entrypoint"`
	Workdir       string            `yaml:"workdir" toml:"workdir"`
	Volumes       []string          `yaml:"volumes" toml:"volumes"`
	Env           map[string]string `yaml:"env" toml:"env"`
	ConfigFiles   []string          `yaml:"config_files" toml:"config_files"`
	Options       map[string]Option `yaml:"options" toml:"options"`
	RequireCI     bool              `yaml:"require_ci" toml:"require_ci"`                       // Requires CI environment
	LocalBehavior string            `yaml:"local_behavior" toml:"local_behavior"`               // draft, no-push, dry-run, disabled
	Privileged    bool              `yaml:"privileged,omitempty" toml:"privileged,omitempty"`   // Requires root privileges (skip user mapping)
	PullPolicy    string            `yaml:"pull_policy,omitempty" toml:"pull_policy,omitempty"` // always, if-not-present, never (default: env-based)
	Timeout       string            `yaml:"timeout,omitempty" toml:"timeout,omitempty"`         // duration string (e.g., "5m", "45m"), default: 30m
}

type PresetTOML struct {
	Name          string                `toml:"name"`
	Phase         string                `toml:"phase"`
	Image         string                `toml:"image"`
	Description   string                `toml:"description"`
	Hardened      bool                  `toml:"hardened"`
	Command       string                `toml:"command"`
	Entrypoint    []string              `toml:"entrypoint"`
	Workdir       string                `toml:"workdir"`
	Volumes       []string              `toml:"volumes"`
	Env           map[string]string     `toml:"env"`
	ConfigFiles   []string              `toml:"config_files"`
	Options       map[string]OptionTOML `toml:"options"`
	RequireCI     bool                  `toml:"require_ci"`
	LocalBehavior string                `toml:"local_behavior"`
	Privileged    bool                  `toml:"privileged"`
	PullPolicy    string                `toml:"pull_policy"`
	Timeout       string                `toml:"timeout"`
}

type PresetsFile struct {
	Presets map[string]PresetTOML `toml:"presets"`
}

type PromotionDecision struct {
	// Promote reports whether the candidate may replace the running image.
	Promote bool

	// Reason states why. Always set, for promotions as much as for holds — a
	// candidate held for another week has to say so somewhere, or the policy
	// silently swallows it.
	Reason string

	// WaivedFor names the vulnerabilities that bought the candidate its way
	// past the cooldown. Empty when no waiver was needed, so a promotion never
	// claims a waiver that did nothing.
	WaivedFor []string

	// AgeDays is how long the candidate has been public, in whole days. Nil
	// when the registry gave no date.
	AgeDays *int
}

type ScanDecision struct {
	// Promote reports whether the findings leave the candidate promotable.
	Promote bool

	// Reason states why — for a pass as much as for a hold. A candidate the
	// scan gate holds has to say so somewhere, or the promotion silently
	// swallows it, which is the failure mode #247 was about in the first place.
	Reason string

	// Introduces names the findings that blocked the promotion: on the
	// candidate, on neither the running image's record nor the candidate's own,
	// and therefore new. Empty on a pass, so a promotion never implies findings
	// it does not have.
	Introduces []string
}

type Triage struct {
	// Carried is every distinct HIGH/CRITICAL finding the scanners reported.
	// It is the number the baseline was missing: publishing only Accepted is
	// how the file came to read "0 accepted findings" on a catalogue carrying
	// 596.
	Carried int

	// Fixable is fixed upstream: image freshness, never exception territory.
	Fixable int

	// GoStdlib and KernelHeaders are the two exempt classes.
	GoStdlib      int
	KernelHeaders int

	// Actionable is what is left: no fix at any version, and reachable enough
	// to be worth an argument. The only population an exception is the right
	// instrument for.
	Actionable int

	// KEV names the findings CISA lists as actively exploited, and TopEPSS is
	// the highest exploitation probability seen. Both are reported for a human
	// to read; neither gates anything.
	KEV     []string
	TopEPSS float64
}