plugin

type CacheKey string

type CacheVersioner interface {
	CacheVersion(ctx context.Context) string
}

type Config map[string]any

type ControlResult struct {
	Control string
	Report  sarif.Report
	Summary Summary
}

type Controller interface {
	Info() ControllerInfo
	// Plan expands a component (or the project, when comp is nil) into scan jobs.
	Plan(model saga.Model, comp *saga.Component) ([]ScanJob, error)
	// Aggregate merges and deduplicates this control's scanner outputs into one result.
	Aggregate(results []sarif.Report) (ControlResult, error)
}

type ControllerInfo struct {
	// Name is the control name, e.g. "images", "sast", "opensource".
	Name  string
	Scope Scope
	// Summary is a one-line description of what the control does, for `draugr controls`.
	Summary string
	// DefaultScanners lists the scanner(s) the control runs by default. Some controls accept
	// additional opt-in scanners (see controllers.<name>.scanners); those are discovered from
	// the registry rather than listed here.
	DefaultScanners []string
}

type Effect struct {
	Kind EffectKind
	// Detail is one line, addressed to whoever has to approve it: what will happen, in terms of
	// the target rather than the implementation.
	Detail string
}

type EffectKind string

type HostTarget struct {
	Name string
	URL  string
	Type string
}

type ImageTarget struct {
	Ref    string
	Digest string
}

type InfraTarget struct {
	Platform string
	Ref      string
	// Namespaces narrows the audit to part of the cluster. Empty means all of it.
	Namespaces []string
}

type Prewarmer interface {
	Prewarm(ctx context.Context) error
}

type RepositoryTarget struct {
	URL      string
	Revision string
	Paths    []string
}

type ScanJob struct {
	Scanner  string
	Target   Target
	Config   Config
	CacheKey CacheKey
}

type Scanner interface {
	Info() ScannerInfo
	Scan(ctx context.Context, target Target, cfg Config) (sarif.Report, error)
}

type ScannerInfo struct {
	// Name is the scanner identifier, e.g. "trivy".
	Name string
	// Binary is the external executable the scanner shells out to, e.g. "trivy". Empty for
	// scanners that need no external tool. Used by `draugr doctor` to check availability.
	Binary string
	// AlsoRequires names further executables that must be present for the scanner to work.
	//
	// Some tools shell out in turn: kube-bench's CIS policy checks are scripts that invoke
	// kubectl, so a machine with kube-bench and no kubectl fails at scan time rather than at
	// `draugr doctor`. Declaring the whole requirement is what lets the preflight check be
	// worth running.
	AlsoRequires []string
	// Version is the scanner/plugin version; it participates in the cache key.
	Version string
	// Controls are the security controls this scanner can serve, e.g. ["images"].
	Controls []string
	// TargetKinds are the target kinds this scanner accepts.
	TargetKinds []TargetKind
	// ConfigSchema is a JSON Schema for Config; it drives validation and the config wizard.
	ConfigSchema json.RawMessage
	// Effects declare what this scanner does to a target beyond reading it. Empty — the common
	// case — means it reads an artifact and nothing else.
	//
	// Draugr surfaces these before a scan runs and records them in the report afterwards, and
	// refuses to run a scanner whose effects have not been acknowledged. A scanner that omits an
	// effect it has is worse than one that overstates: the point is that nothing consequential
	// happens to a target without the operator having agreed to it.
	Effects []Effect
}

type Scope string

type Summary struct {
	Errors   int
	Warnings int
	Notes    int
}

type SurveyScope struct {
	Kind   string
	Ref    string
	Config Config
}

type Surveyor interface {
	Info() SurveyorInfo
	Survey(ctx context.Context, scope SurveyScope) (saga.Fragment, error)
}

type SurveyorInfo struct {
	// Name is the surveyor identifier, e.g. "k8s-images", "github-org-repos".
	Name string
	// Provides are the target kinds this surveyor can discover.
	Provides []TargetKind
	// ConfigSchema is a JSON Schema for the scope Config.
	ConfigSchema json.RawMessage
}

type Target interface {
	Kind() TargetKind
	Identity() string
}

type TargetKind string