ecosystem

type Component struct {
	// Ecosystem is the OSV ecosystem string ("Go", "Debian:12", "PyPI").
	Ecosystem string

	// Release narrows a bare-family Ecosystem to one product release, and is
	// empty unless the ecosystem needs it. Only SUSE does today: its query has
	// to be the bare family to match anything, so the product an advisory
	// applies to can only be checked after the fact. See osv.Ref.Release.
	Release string

	// Name is the package name *as OSV keys it*. For deb and rpm that is the
	// source package, not the binary package the database lists — getting this
	// backwards produces both false negatives and false positives, so plugins
	// map it during inventory rather than leaving it to the orchestrator.
	Name string

	// AltNames are further names to query OSV under, beyond Name.
	//
	// This exists because "which name does the advisory database key this
	// package on" has no consistent answer, even within one package format.
	// Debian and Alpine file against the source package, Red Hat and AlmaLinux
	// against the binary package, and Rocky Linux -- a rebuild of Red Hat --
	// against the source package like its upstream does not. Querying both
	// costs one extra entry in a batch request; picking the wrong single name
	// reports a vulnerable package as clean.
	//
	// The advisories from every name are merged into one set, so an advisory
	// filed under both names produces one finding, not two.
	AltNames []string

	// Version is the version string OSV can compare.
	Version string

	// PURL is the package URL. It is the stable identity in output and the key
	// a future vendor-VEX layer will match statements on.
	PURL string

	// Locations are the paths inside the target this component occupies or is
	// linked into. In Go image mode these are the binaries linking the module,
	// which is what lets the Go plugin keep its existing per-binary output
	// shape without a special case: one component per (module, version), one
	// finding per (binary, advisory).
	Locations []string

	// Extra is plugin-private state carried from inventory to analysis — a
	// loaded symbol table, the file list a package owns. The orchestrator never
	// inspects it.
	Extra any
}

type EcosystemResult struct {
	ID string `json:"id"`
	// Ecosystems are the concrete OSV ecosystem strings that were detected
	// ("Debian:12"), not the families the plugin supports.
	Ecosystems []string `json:"ecosystems,omitempty"`
	// Components is how many the inventory phase found.
	Components int `json:"components"`
	// Error is set when the plugin could not complete. Findings for this
	// ecosystem are then absent, not empty.
	Error string `json:"error,omitempty"`
}

type Evidence struct {
	// Origin names what produced the observation: "pclntab", "govulncheck",
	// "pkgdb-inventory", "elf-needed-closure", "llm-mined", "vendor-vex".
	Origin string `json:"origin"`

	// Detail is a short statement of what was observed.
	Detail string `json:"detail"`

	// Blocking marks a taint: something that prevents concluding the component
	// is unaffected. A taint never sets a status by itself — it stops the
	// analysis from reaching a not_affected one, and says why in the output.
	Blocking bool `json:"blocking,omitempty"`
}

type Finding struct {
	// Ecosystem is the plugin that produced this finding ("golang", "os").
	// Plugins do not set it -- the orchestrator stamps every finding with the
	// analyzer it came from, so no plugin can forget to and no plugin can
	// claim to be another.
	Ecosystem string `json:"ecosystem,omitempty"`

	// ID is the advisory, under the id the caller asked about. Same value as
	// CVE.
	ID string `json:"id"`
	// Package is the component's name in its ecosystem's terms: a Go module
	// path, an OS source package. Same value as Module.
	Package string `json:"package"`
	// Location is the path inside the target the finding is about, empty when
	// the finding is about the whole target. Same value as Binary.
	Location string `json:"location,omitempty"`
	// PURL is the component's package URL, and the key the vendor-VEX layer
	// matches statements on. Plugins set this one; nothing else can.
	PURL string `json:"purl,omitempty"`

	// Product is the purl of the shipped artifact this finding was found in --
	// the scanned image, or a Go binary's main module. It is the other half of
	// a VEX lookup: a hub keys its documents by product and names components
	// like PURL inside them.
	//
	// Plugins do not set it. The orchestrator stamps the image product on every
	// finding, and a plugin that knows a narrower artifact overrides it.
	Product string `json:"product,omitempty"`

	Binary      string   `json:"binary,omitempty"`
	Module      string   `json:"module"`
	Version     string   `json:"version"`
	CVE         string   `json:"cve"`
	GoID        string   `json:"go_id,omitempty"`
	Packages    []string `json:"packages,omitempty"`
	Granularity string   `json:"granularity,omitempty"` // package | module

	// Upstream is the CVEs this advisory says its patch fixes, when it is a
	// bundle of more than one. Distro advisories routinely are: SUSE-SU-2026
	// :0312-1 addresses eight, RHSA-2024:2447 seven, and neither id names a
	// CVE anywhere.
	//
	// Plugins do not set it; the orchestrator fills it from the OSV record.
	// Empty is the ordinary case and means the advisory is about one thing,
	// which the row already names.
	Upstream []string `json:"upstream,omitempty"`

	// FixedVersion is the version the advisory's patch lands in for this
	// finding's package, when the OSV record publishes one. It is the
	// report's one actionable field: what to upgrade to.
	//
	// Plugins do not set it; the orchestrator fills it from the OSV record's
	// affected ranges, joined on Package. Empty means no fix was published --
	// a real and common state that the renderer shows as "no fix", not as a
	// blank cell, because the two mean opposite things.
	//
	// Emitted even when empty, and that is the whole point. "" is the "no fix"
	// answer, so omitting it would drop the fact a JSON consumer most needs --
	// the flaw is acknowledged and no patch has shipped -- and leave it
	// indistinguishable from a scan run before this field existed. The text
	// report goes to the trouble of printing "no fix" rather than a blank for
	// exactly this reason; omitempty would have undone that for every
	// non-human reader. Same rule as known_exploited.
	FixedVersion string `json:"fixed_version"`

	// FixedVersions is every version the advisory published a fix in, set only
	// when there is more than one and FixedVersion is therefore a choice rather
	// than the only answer.
	//
	// A vendor maintaining several branches fixes them all: GO-2022-0623 names
	// Vault 1.5.9, 1.6.5 and 1.7.2. Those are alternatives, and the one to
	// install depends on the branch you are on, so the report shows the target
	// it picked and the ones it did not. Omitted in the ordinary single-fix
	// case, where it would only repeat FixedVersion -- unlike that field, an
	// absence here has no second meaning to lose.
	FixedVersions []string `json:"fixed_versions,omitempty"`

	// Stripped is a pointer because it is a Go-only fact with three states: a
	// binary with symbols, a binary without, and an OS package that is not a
	// binary at all. A plain bool would report every deb in the image as
	// unstripped.
	Stripped *bool `json:"stripped,omitempty"`

	// Severity is the advisory's rating, in the vocabulary of internal/cvss,
	// and CVSS is the v3 base vector it was computed from when the record
	// published one. Plugins do not set these: the orchestrator fills them
	// from advisories it has already fetched, for the same reason it stamps
	// Ecosystem, so no plugin can forget to.
	//
	// Empty means no advisory data was resolved for the finding at all, which
	// is not the same as UNKNOWN -- that is a record which was read and
	// published no rating.
	Severity string `json:"severity,omitempty"`
	CVSS     string `json:"cvss,omitempty"`

	Status        Status       `json:"status"`
	Method        string       `json:"method,omitempty"`
	Justification string       `json:"justification,omitempty"`
	Reason        string       `json:"reason,omitempty"` // for undetermined
	LLM           *llm.Verdict `json:"llm,omitempty"`
	Evidence      []Evidence   `json:"evidence,omitempty"`

	// VEX is a published vendor statement covering this finding, when a
	// --vexhub was given and one matched. It never changes Status: the verdict
	// above is what local evidence concluded, and stays comparable between a
	// run with a hub and a run without one.
	VEX *VEXStatement `json:"vex,omitempty"`

	// Priority is exploitation evidence -- an EPSS score, a KEV listing --
	// attached by --triage. Like VEX it never changes Status: whether anyone is
	// exploiting a vulnerability elsewhere says nothing about whether the code
	// is present here, which is the only question this tool answers.
	//
	// Nil means --triage was off. Non-nil with Scored false means the flag was
	// on and this finding could not be looked up, which is a different fact and
	// must not be allowed to look like a low score.
	Priority *triage.Priority `json:"priority,omitempty"`

	// Reachability is how the plugin's deterministic layer characterized a
	// genuinely-affected component, in its own words ("linked (symbols
	// retained; reachability not asserted)"). It exists so the orchestrator can
	// build an LLM prompt without knowing anything ecosystem-specific, and is
	// not serialized.
	Reachability string `json:"-"`
}

type HintConsumer interface {
	WantsHints() bool
}

type ImageAnalyzer interface {
	Plugin

	// DetectImage reports whether this plugin applies to img at all. A plugin
	// that does not apply is skipped silently; an error means detection itself
	// failed and must be surfaced, never treated as "does not apply".
	DetectImage(ctx context.Context, img *target.Image) (bool, error)

	// InventoryImage lists the components present, restricted to subjects when
	// any are given.
	//
	// Returning an empty inventory means "nothing is installed". A plugin that
	// found a package database it could not read must return an error instead:
	// an empty inventory renders as "no vulnerable packages", which is the
	// worst possible failure mode for a tool whose output becomes an
	// attestation.
	InventoryImage(ctx context.Context, img *target.Image, subjects []Subject) ([]Component, error)

	// AnalyzeImage decides each work item. Findings must carry no LLM verdict;
	// the orchestrator adds that.
	AnalyzeImage(ctx context.Context, img *target.Image, items []WorkItem) ([]Finding, error)
}

type InventorySourceAnalyzer interface {
	Plugin

	// DetectSource reports whether this plugin applies to src.
	DetectSource(ctx context.Context, src *target.Source) (bool, error)

	// InventorySource lists the components the checkout declares, restricted
	// to subjects when any are given. The same rule as InventoryImage applies:
	// a lock file that was found and could not be parsed is an error, never an
	// empty inventory.
	InventorySource(ctx context.Context, src *target.Source, subjects []Subject) ([]Component, error)

	// AnalyzeSource decides each work item. Findings must carry no LLM verdict.
	AnalyzeSource(ctx context.Context, src *target.Source, items []WorkItem) ([]Finding, error)
}

type Plugin interface {
	// ID is the stable selector used by --ecosystem and printed in output
	// ("golang", "os", "pypi").
	ID() string

	// Ecosystems lists the OSV ecosystem strings this plugin can produce
	// components for. Distro ecosystems are versioned at detect time
	// ("Debian:12"), so the OS plugin returns the unversioned families it
	// understands ("Debian", "Alpine") and callers match on prefix.
	Ecosystems() []string
}

type Registry struct {
	// contains filtered or unexported fields
}

type Request struct {
	ID       string
	Advisory *osv.Advisory

	// Hints are the mined identifiers for this advisory, or nil. See
	// WorkItem.Hints for what a plugin owes them.
	Hints *llm.Hints
}

type SourceAnalyzer interface {
	Plugin

	// DetectSource reports whether this plugin applies to src.
	DetectSource(ctx context.Context, src *target.Source) (bool, error)

	// AnalyzeSource decides the requested ids against src. An empty requested
	// list means "every advisory that applies".
	AnalyzeSource(ctx context.Context, src *target.Source, subjects []Subject, requested []string) ([]Finding, error)
}

type Status string

type Subject struct {
	// Ecosystem restricts the subject to one plugin ("golang", "os"). Empty
	// matches any plugin, which is how a bare `--package openssl` resolves
	// against whatever inventory turns out to contain it.
	Ecosystem string
	// Name is the package or module name as given, or "" for "everything".
	Name string
	// PURL is set instead of Name when the user gave a full package URL.
	PURL string
	// Raw is exactly what the user typed, for error messages.
	Raw string
}

type VEXHubResult struct {
	URL string `json:"url"`
	// Author is whoever signed the documents actually read from this hub.
	Author string `json:"author,omitempty"`
	// Products is how many artifacts the hub indexes, and Matched how many
	// findings it spoke to.
	Products int `json:"products,omitempty"`
	Matched  int `json:"matched"`
	// Error is why the hub contributed nothing. Unlike an ecosystem error it
	// does not make the whole run incomplete: see the comment on vexOverlay.
	Error string `json:"error,omitempty"`
}

type VEXStatement struct {
	// Status is OpenVEX's, not vexscan's: not_affected, affected, fixed,
	// under_investigation. It is deliberately a different vocabulary from
	// Finding.Status so the two can never be confused in the JSON.
	Status          string `json:"status"`
	Justification   string `json:"justification,omitempty"`
	ImpactStatement string `json:"impact_statement,omitempty"`
	ActionStatement string `json:"action_statement,omitempty"`

	Author    string `json:"author,omitempty"`
	Timestamp string `json:"timestamp,omitempty"`
	// Product is the artifact purl the statement was filed under, and Hub the
	// --vexhub it came from.
	Product string `json:"product,omitempty"`
	Hub     string `json:"hub,omitempty"`
	// Match records how the statement's component purl differed from the
	// finding's, when it did. Empty means they agreed exactly.
	Match string `json:"match,omitempty"`
}

type WorkItem struct {
	Component Component

	// Advisories are what the orchestrator resolved, keyed by every id each
	// advisory is known by, so a plugin can look up a CVE, GHSA or GO id
	// interchangeably.
	Advisories map[string]*osv.Advisory

	// Requested are the ids the user explicitly asked about; empty means "every
	// advisory that applies".
	Requested []string

	// Targeted says the user named this component, rather than it arriving from
	// an enumeration of everything installed.
	//
	// It decides what happens to a requested id this component has no advisory
	// for. Named, the user asked about this package and is owed an answer, so
	// the id reports undetermined; a --cves scan that silently dropped the ids
	// it could not map would read as "not affected". Enumerated, the same
	// answer repeated across four hundred packages is noise that buries the one
	// package the id actually landed on. An id that lands on nothing at all is
	// the orchestrator's to report, because it is the only thing that can see
	// the whole image at once.
	Targeted bool

	// Hints are the identifiers an LLM claimed each advisory's text names,
	// keyed by the advisory's canonical id. Present only under
	// --mine-advisories, and nil the rest of the time.
	//
	// Nothing here is a fact. A plugin must validate a hint against something
	// it can observe in the artifact before letting it support a
	// not_affected-flavored status, and an unvalidatable hint must be inert:
	// it is indistinguishable from an invented one. The validation lives in
	// the plugins because they are what hold the evidence to do it with.
	Hints map[string]*llm.Hints
}