saga

type BuiltBy string

type Classification struct {
	Exposure    Exposure
	Criticality Criticality
}

type Component struct {
	Name        string            `yaml:"name"`
	Labels      map[string]string `yaml:"labels,omitempty"`
	Exposure    Exposure          `yaml:"exposure,omitempty"`
	Criticality Criticality       `yaml:"criticality,omitempty"`
	// BuiltBy is who publishes this component's targets, unless one of them says otherwise.
	//
	// Here as well as on each target because a component that is entirely somebody else's software, a
	// vendor console, an open-source service you run from source. Otherwise needs the field written
	// on every repository and every image, and a target added later silently defaults back to `self`.
	BuiltBy        BuiltBy          `yaml:"builtBy,omitempty"`
	Repositories   []Repository     `yaml:"repositories,omitempty"`
	Images         []Image          `yaml:"images,omitempty"`
	Hosts          []Host           `yaml:"hosts,omitempty"`
	Infrastructure []Infrastructure `yaml:"infrastructure,omitempty"`
	// Controls overrides the project's per-control configuration for this component.
	Controls map[string]ControllerSettings `yaml:"controls,omitempty"`

	// Controllers is the older spelling, still read. Deprecated: write `controls`.
	Controllers map[string]ControllerSettings `yaml:"controllers,omitempty"`
	// VEX are exploitability claims somebody else made about this component, read and applied to
	// its findings.
	//
	// Scoped to the component rather than the descriptor, and that is the whole safety argument:
	// a claim is an assertion by one supplier about one artifact, and a document that could reach
	// another component's findings would turn one vendor's assurance into a suppression somewhere
	// nobody was looking.
	//
	// Note the asymmetry with `config.vex`, which is not a mistake: that describes the document
	// Draugr **writes** about your product, this lists documents Draugr **reads** about a supplier's.
	// A component does not author claims about itself.
	VEX []VEXSource `yaml:"vex,omitempty"`
}

type Config struct {
	// Controls is the per-control configuration: which of them run, and what each is told.
	//
	// Named for what a reader meets everywhere else. `draugr controls` lists them, the catalog
	// names them, every concept behind a `?` calls them controls, and `config.gate.controls`
	// seventeen lines from here already did. A controller is the Go type that plans the jobs, and
	// that word belongs in the code rather than in the file people write.
	Controls map[string]ControllerSettings `yaml:"controls,omitempty"`

	// Controllers is the older spelling, still read so no descriptor breaks.
	//
	// Deprecated: write `controls`. Folded into Controls when a descriptor loads, so nothing else
	// has to know both names.
	Controllers map[string]ControllerSettings `yaml:"controllers,omitempty"`
	// Publishers are the destinations that rendered reports are delivered to.
	Publishers []PublisherConfig `yaml:"publishers,omitempty"`
	// Gate tunes the pass/fail thresholds. Policy belongs in the descriptor rather than in a
	// flag every pipeline has to remember to pass.
	Gate *GateConfig `yaml:"gate,omitempty"`
	// Exclude suppresses findings that match, with a stated reason. Suppressed findings are still
	// reported. They just stop counting toward the verdict.
	Exclude []ExcludeRule `yaml:"exclude,omitempty"`
	// VEX names the author and product for a generated VEX document (`--report vex`). Optional;
	// without it Draugr falls back to the release, which produces a valid document rather than a
	// publishable one.
	VEX *VEXConfig `yaml:"vex,omitempty"`
	// VEXSources are exploitability claims applied to every component in the project.
	//
	// The project-wide half of `components[].vex`, for the case that is common inside one
	// organization: a platform team publishes one document covering everything they ship, and the
	// twelve projects consuming it should say so once rather than repeat a URL on every component.
	//
	// Scoping is still done by the document. A statement names the package it is about, so a
	// project-wide source excuses a finding only where the identifiers match, listing it here widens
	// which findings are *considered*, not what a given statement is allowed to claim.
	VEXSources []VEXSource `yaml:"vexSources,omitempty"`
	// SBOM turns on Software Bill of Materials generation for this project's repositories and
	// images. It is evidence rather than a control: an SBOM is an inventory, it finds nothing,
	// and it never affects the verdict.
	SBOM *SBOMConfig `yaml:"sbom,omitempty"`
	// Exploitability raises a finding's severity by real-world signals, CISA KEV and FIRST EPSS.
	// Before it is ranked, so "what to fix first" reflects what is being exploited rather than only
	// what could be.
	Exploitability *ExploitabilityConfig `yaml:"exploitability,omitempty"`
	// Reachability ranks a dependency finding down when this project's code cannot reach the
	// vulnerable part of it, so "what to fix first" reflects what the code actually calls.
	//
	// Exploitability's mirror image, and here for the same reason: both decide how findings are
	// ranked, and a decision that can move a finding across the gate belongs somewhere a team
	// reviews rather than in a list of tools to run.
	Reachability *ReachabilityConfig `yaml:"reachability,omitempty"`
	// AllowEffects acknowledges scanner effects that would otherwise stop a run, the kinds a scanner
	// declares when it does more to a target than read it ("mutate", "privilege").
	//
	// In the descriptor rather than only a flag, because it is a decision about what may be
	// done to your systems: reviewed in a pull request, and applied identically by every
	// pipeline instead of remembered by whoever wrote the workflow.
	AllowEffects EffectPermissions `yaml:"allowEffects,omitempty"`
}

type ControllerSettings map[string]any

type Criticality string

type EffectPermissions []string

type ExcludeRule struct {
	// Paths matches the finding's location. A pattern ending in "/" matches everything beneath
	// that directory; otherwise it is a glob (path.Match) against the whole location, so
	// "*.md" and "test/fixture.go" both work.
	Paths []string `yaml:"paths,omitempty"`
	// Rules matches the finding's rule id. `*` is a wildcard for any run of characters, including
	// separators. A rule id is an opaque string rather than a path, and the ids that most need
	// matching are compound (`license/GPL-3.0-only/github.com/somelib/thing`), so a wildcard that
	// stopped at `/` could not express "this license, any package". A pattern with no `*` matches
	// exactly. There is no escape for a literal `*`; no scanner emits one.
	Rules []string `yaml:"rules,omitempty"`
	// Reason is why this exclusion exists. Required.
	Reason string `yaml:"reason"`
	// AcceptedBy names who decided this finding was acceptable.
	//
	// The question an auditor asks of a suppression is not whether the scanner ran. It is who
	// decided, and when. `reason` answers why; without this the who lives in prose if it is recorded
	// at all, and a name buried in a sentence cannot be reported on. Optional, and a suppression
	// without one is reported as unattributed rather than rejected.
	AcceptedBy string `yaml:"acceptedBy,omitempty"`
	// Expires is the date this exclusion stops applying, as YYYY-MM-DD.
	//
	// An exclusion accepted "until the upstream fix lands" has nothing that brings the finding back,
	// so the temporary ones become permanent by default. Which is how a suppression mechanism decays
	// into a way of never seeing something again. Past this date the exclusion no longer suppresses
	// and the finding returns, with the report saying it lapsed rather than silently producing a
	// finding that used to be accepted.
	Expires string `yaml:"expires,omitempty"`
	// VEX states what this suppression means as a machine-readable claim about the product,
	// for `--report vex`. Optional: without it the finding is reported as `affected`, which is
	// the claim that is never an overstatement.
	VEX *VEXDecision `yaml:"vex,omitempty"`
	// Source is the file this rule was read from, set by the loader rather than by the
	// descriptor. Splitting exclusions across files is only safe if the report can still say
	// which file authorized each one, so the provenance travels with the rule.
	Source string `yaml:"-"`
}

type ExploitabilityConfig struct {
	// KEV and EPSS each name a source: a file path, "cache" to read what `draugr feeds update`
	// left without touching the network, or "auto" to fetch when the cache is missing or stale.
	// Empty leaves that signal off; either may be used without the other.
	KEV  string `yaml:"kev,omitempty"`
	EPSS string `yaml:"epss,omitempty"`
	// EPSSThreshold is the EPSS probability (0–1) at or above which a finding's severity is
	// raised one band. Zero means the CLI default.
	//
	// A pointer so "not set" and "deliberately zero" stay distinguishable: zero disables the
	// EPSS bump entirely, which is a thing someone might mean.
	EPSSThreshold *float64 `yaml:"epssThreshold,omitempty"`
	// MaxAge is how old a cached feed may be before "auto" refetches it and a scan warns that
	// it is stale. Empty means the built-in default of 24 hours, which tracks EPSS being
	// republished daily.
	//
	// Configurable because a runner deliberately pinned to a known copy of the data has a legitimate
	// reason to say "do not tell me it is old", reproducing last quarter's verdict requires last
	// quarter's feed.
	MaxAge string `yaml:"maxAge,omitempty"`
}

type Exposure string

type Fetcher interface {
	// Fetch returns a directory holding the repository at the requested revision, the commit it
	// resolved to, and a cleanup.
	Fetch(url, revision string) (dir, resolved string, cleanup func(), err error)
}

type Fragment struct {
	// Components are merged by name, a repeated name unions the two surfaces rather than replacing or
	// colliding, so a component described in two places ends up whole.
	Components []Component `yaml:"components,omitempty"`
	// Config is the subset of a Saga's config a fragment may carry.
	Config FragmentConfig `yaml:"config,omitempty"`
	// Fragments are further fragments this one pulls in, resolved relative to it.
	Fragments []FragmentRef `yaml:"fragments,omitempty"`
	// ExposureReasons explains, per component name, what topology a proposed `exposure` was read
	// from, "an Ingress routes into it", and so on.
	//
	// Never serialized: it is evidence about a proposal rather than part of the descriptor, and a
	// fragment somebody writes by hand has no use for it. It exists so a survey can put the
	// reasoning beside the value it wrote, where the value gets reviewed.
	ExposureReasons map[string]string `yaml:"-" json:"-"`
}

type FragmentConfig struct {
	// Exclude suppresses findings that match, with a stated reason. Appended to whatever the
	// descriptor and other fragments already carry.
	Exclude []ExcludeRule `yaml:"exclude,omitempty"`
}

type FragmentRef struct {
	// Path selects the fragment files. Globs are the same dialect as `paths:` and `ignore:`, `*`
	// within a segment, `**` across them, so `**/draugr.saga-fragment.yaml` collects one fragment
	// from every component in a monorepo. Relative to the file that names it, so a fragment keeps
	// working when its directory moves.
	Path string `yaml:"path"`
	// URL is a git repository to read the fragments from. Empty means the local filesystem.
	URL string `yaml:"url,omitempty"`
	// Revision is the branch, tag or commit to read. Required when URL is set, and deliberately
	// not defaulted to the repository's default branch: a fragment that tracks a moving branch is
	// a gate that changes with no commit in your own repository. The revision a run resolved to
	// is recorded in the report, so a tag that moves is visible afterwards.
	Revision string `yaml:"revision,omitempty"`
}

type GateConfig struct {
	// FailOn is the threshold that fails the build, written in either vocabulary.
	//
	// `P1` asks what band a finding landed in for the component it was found in, folding in the
	// exposure and criticality declared below. `high` asks what the scanner called the flaw on its
	// own terms. One field rather than two, so writing both is not expressible: a verdict with two
	// possible reasons cannot be read back to the rule that produced it, and a shape nobody can
	// write is a better guarantee than an error about it.
	//
	// Empty is the default, which is P1. The ranking this product computes is the one it judges
	// by, and a tool whose default gate is the number a scanner printed has its central claim
	// switched off until somebody configures it.
	FailOn string `yaml:"failOn,omitempty"`

	// Controls sets a per-control threshold, overriding FailOn for that control only.
	//
	// The same vocabulary as FailOn, because the run asks one question: a band under a severity
	// gate, or a severity under a band gate, is a second question asked of one control and puts
	// the reader back where two keys left them.
	//
	// A refinement of FailOn, so it needs one.
	//
	// This exists because one threshold cannot serve every control. License policy is owned by
	// legal and vulnerability policy by security; "fail the build on a forbidden license but
	// only warn on a medium CVE" is a reasonable position that a single global threshold makes
	// unsayable.
	Controls map[string]string `yaml:"controls,omitempty"`

	// FailOnPriority also fails the build on any finding at or above a priority band.
	//
	// Deprecated: write the band in FailOn instead, which takes either vocabulary. Still read, so
	// a descriptor that predates the merge keeps working, and refused alongside FailOn because
	// the two together are the contradiction one field exists to prevent.
	//
	// Severity rates a flaw in the abstract; priority folds in what the descriptor says about the
	// component it was found in. A team that has classified its components usually wants the gate on
	// the second, and until now could only say so with a flag. Which every pipeline has to remember,
	// and which nothing reviews.
	//
	// In the descriptor for the same reason as the rest of this block: it is a decision about
	// this application, reviewed in a pull request and applied identically by every runner. A
	// --fail-on-priority flag still overrides it, so a stricter run stays possible without
	// editing the file.
	//
	// This is the default gate. A descriptor that names nothing fails on P1, because the ranking
	// this product computes is the one it should be judged by.
	FailOnPriority string `yaml:"failOnPriority,omitempty"`
}

type GateKind int

type Host struct {
	Name string `yaml:"name"`
	URL  string `yaml:"url"`
	Type string `yaml:"type,omitempty"`
	// Auth authenticates the dynamic scan of this endpoint. Absent means probe it anonymously.
	Auth *HostAuth `yaml:"auth,omitempty"`
	// Spec drives the dynamic scan from an OpenAPI document instead of crawling.
	Spec *HostSpec `yaml:"spec,omitempty"`
}

type HostAuth struct {
	// Type is "bearer", an `Authorization: Bearer <token>` header, or "header" for a named one.
	Type string `yaml:"type"`
	// Header is the header name, required when Type is "header" (e.g. X-API-Key).
	Header string `yaml:"header,omitempty"`
	// TokenEnv names the environment variable holding the credential.
	TokenEnv string `yaml:"tokenEnv"`
}

type HostSpec struct {
	// Path is the OpenAPI or Swagger document, resolved like every other path in a
	// descriptor: relative to where Draugr runs, not to the descriptor or the repository.
	Path string `yaml:"path"`
	// Methods are the HTTP methods to exercise. Empty means GET and HEAD.
	//
	// A specification lists POST, PUT and DELETE too, and a scanner handed one will exercise them, a
	// scan of a staging API that deletes its fixtures is a scan nobody runs twice. Naming a write
	// method here is how that is accepted: explicit, per endpoint, and visible in review.
	Methods []string `yaml:"methods,omitempty"`
}

type Image struct {
	Image  string `yaml:"image"`
	Digest string `yaml:"digest,omitempty"`
	// BuiltBy says who builds this image: "self" (the default) or "upstream" for one this
	// component runs but somebody else publishes.
	//
	// It decides what the report tells a reader to do about a vulnerable package inside it. Nobody
	// running a scan can upgrade a library inside an image they do not build. The fix is a newer
	// image, or a wait for whoever publishes it. Advice they cannot take, at the top of a list called
	// "fix first", teaches them the list is not worth reading.
	//
	// Declared rather than detected, because nothing in an image says who built it. Defaults to
	// "self" so a descriptor that says nothing keeps describing its own work, which is the common
	// case for a hand-written one. A surveyed cluster is the case that needs saying.
	BuiltBy BuiltBy `yaml:"builtBy,omitempty"`
}

type Infrastructure struct {
	Kind string `yaml:"kind"`
	Ref  string `yaml:"ref,omitempty"`
	// Namespaces narrows the audit to the namespaces this component owns. Empty means the whole
	// cluster.
	//
	// On a shared cluster the cluster is not the unit anyone owns. Most of what the benchmark's
	// policies section examines is namespace-scoped, so a team owning three namespaces of eighty
	// otherwise receives seventy-seven namespaces' worth of findings it cannot act on. And a number
	// that will never reach zero is a number people stop reading.
	//
	// It also fixes what the component's risk classification means. `exposure` and `criticality`
	// describe a component, so declaring them against a whole shared cluster asserts them on
	// everybody else's workloads too.
	Namespaces []string `yaml:"namespaces,omitempty"`
	// OperatedBy says who runs this surface: "self", or "provider" for a managed service.
	//
	// It states a fact rather than a judgement, and what follows from it. That a finding about the
	// provider's half is not something this team can go and fix. Is derived rather than asserted.
	// "managed" was the obvious word and is ambiguous: managed by whom, and a managed service is
	// still yours to pay for.
	//
	// Declared rather than detected, because whether a cluster is managed is a fact about a
	// contract and not something visible in what a scanner reads. The same argument that puts
	// exposure and criticality here.
	//
	// It narrows what it excuses. On a managed cluster the provider runs the control plane, the
	// API server and etcd; RBAC, Pod Security and network policy remain the team's, and those
	// are usually the findings that matter. Marking a whole cluster as somebody else's problem
	// would hide the half that is not.
	OperatedBy OperatedBy `yaml:"operatedBy,omitempty"`
}

type Model struct {
	// Project is which project this descriptor describes, and the name a platform files its runs
	// under. Lowercase letters, digits and dashes.
	Project    string        `yaml:"project,omitempty"`
	Release    Release       `yaml:"release"`
	Config     Config        `yaml:"config,omitempty"`
	Components []Component   `yaml:"components,omitempty"`
	Fragments  []FragmentRef `yaml:"fragments,omitempty"`
	References []Reference   `yaml:"references,omitempty"`
}

type OperatedBy string

type PublisherConfig struct {
	Kind string `yaml:"kind"`
	Dir  string `yaml:"dir,omitempty"` // file: output directory

	// Reports narrows what this destination is given, and is where the two lists finally meet.
	//
	// Left out, a destination is handed every report `config.reports` renders, which is what a
	// descriptor written before this meant and still means. That cross product is almost never
	// what anybody wants: writing HTML and JSON to a directory while posting the markdown to a
	// pull request was not expressible, so every destination got all three and picked out what it
	// recognized.
	//
	// A format named here is rendered whether or not `config.reports` also names it, so a
	// descriptor that publishes and keeps no local artifacts need not declare the same format
	// twice. Rendering still happens once per distinct report, however many destinations ask for
	// it.
	Reports []ReportConfig `yaml:"reports,omitempty"`

	// github / github-pr-comment: Repo defaults to $GITHUB_REPOSITORY; the token to $GITHUB_TOKEN
	// (or TokenEnv). github: Commit/Ref default to $GITHUB_SHA / $GITHUB_REF.
	Repo     string `yaml:"repo,omitempty"`
	Commit   string `yaml:"commit,omitempty"`
	Ref      string `yaml:"ref,omitempty"`
	TokenEnv string `yaml:"tokenEnv,omitempty"` // env var holding the token; default GITHUB_TOKEN

	// github-pr-comment / azure-pr-comment: posts the markdown report as a sticky pull-request
	// comment. PR defaults to the number parsed from $GITHUB_REF (refs/pull/<n>/merge) or
	// $SYSTEM_PULLREQUEST_PULLREQUESTID; Marker identifies the sticky comment to update
	// (default a Draugr marker).
	PR     int    `yaml:"pr,omitempty"`
	Marker string `yaml:"marker,omitempty"`

	// azure-pr-comment: Org is the collection URI (default $SYSTEM_TEAMFOUNDATIONCOLLECTIONURI)
	// and Project the team project (default $SYSTEM_TEAMPROJECT). Repo defaults to
	// $BUILD_REPOSITORY_NAME and the token to $SYSTEM_ACCESSTOKEN (or TokenEnv).
	Org     string `yaml:"org,omitempty"`
	Project string `yaml:"project,omitempty"`

	// draugr-api: URL is where the server is reached, defaulting to $DRAUGR_API_URL. The token
	// comes from $DRAUGR_API_TOKEN (or TokenEnv) and never from this file, which is one people
	// commit.
	URL string `yaml:"url,omitempty"`
	// DefaultURL is what draugr.config.yaml said, carried here so a publisher can consult it last.
	// Never read from a descriptor, `yaml:"-"`, so writing it in a Saga does nothing and the schema
	// does not offer it.
	//
	// A separate field rather than filling URL, because the two sit at opposite ends of the
	// precedence chain: URL is somebody's explicit choice for this project and beats the
	// environment, while this is the organization's default and loses to it. Merging them would
	// make an ambient value indistinguishable from an intentional one.
	DefaultURL string `yaml:"-"`
}

type ReachabilityConfig struct {
	// Analyzers names the tools that decide reachability, e.g. "govulncheck". An analyzer is
	// named rather than inferred so the descriptor says which tool reached the verdict, and so
	// `draugr doctor` can tell you what to install before a scan finds out for you.
	//
	// Empty leaves reachability off, which is the same as omitting the block.
	Analyzers []string `yaml:"analyzers,omitempty"`
}

type Reference struct {
	Type string `yaml:"type"`
	Link string `yaml:"link"`
}

type Release struct {
	Version string `yaml:"version"`
}

type ReportConfig struct {
	Format string `yaml:"format"`
	// Template and TemplateFile supply the Go text/template for the "template" format (set
	// exactly one). Ignored by other formats.
	Template     string `yaml:"template,omitempty"`
	TemplateFile string `yaml:"templateFile,omitempty"`
	// Filename overrides the artifact's default output filename (used by file-based publishers).
	Filename string `yaml:"filename,omitempty"`
	// MinPriority narrows this report to findings at or above a priority band, leaving every
	// other report complete.
	//
	// Per report, because the reports answer to different readers. A SARIF upload becomes review
	// comments somebody reads on every pull request, where a few hundred findings they did not
	// cause is the reason nobody reads any of them; the JSON beside it is evidence, and evidence
	// is not something to trim.
	//
	// Narrowing an artifact is otherwise refused, and for a good reason: a file that claims to be the
	// scan and is not misleads whatever consumes it. What makes this different is that it is
	// declared, written in the descriptor, and stated inside the artifact it produced. A scope
	// somebody chose and can read back is a scope; an undeclared one is the problem.
	MinPriority string `yaml:"minPriority,omitempty"`
}

type Repository struct {
	URL      string `yaml:"url"`
	Revision string `yaml:"revision,omitempty"`
	// Paths restricts the scan to these directories. Empty scans the whole repository.
	//
	// Files at the repository root are always included regardless: manifests and the scanners' own
	// configuration live there, and a tool that cannot see go.mod or .trivyignore does not fail. It
	// reports less against a tree it did not fully understand, which is indistinguishable from a
	// clean scan.
	Paths []string `yaml:"paths,omitempty"`
	// Ignore removes matching paths from the scan, applied after Paths so it can carve out of
	// one. Gitignore-style: a trailing `/` is a directory, `*` matches within a path segment,
	// `**` across them.
	Ignore []string `yaml:"ignore,omitempty"`
	// BuiltBy says who publishes this repository: "self" (the default) or "upstream" for one this
	// component uses and somebody else maintains. Falls back to the component's own `builtBy`.
	//
	// It decides what the report tells a reader to do. A denied license in the dependency tree of a
	// repository this team does not publish is not a license they chose and not one they can swap
	// out: the answers are to stop using the component or to record an exception, and "change the
	// code" is neither. The same holds for a vulnerable dependency, a flaw in the source, and a
	// credential committed there. The declaration is about who can change the thing, which does not
	// vary by what found the problem.
	//
	// Declared rather than detected, for the reason an image's is: a git remote is not a statement
	// of ownership. Plenty of teams publish from a fork and plenty consume from one.
	//
	// It changes the action and nothing else. The finding keeps its severity and its band, a flaw in
	// somebody else's software is exactly as dangerous. And it is still counted and still reaches the
	// gate.
	BuiltBy BuiltBy `yaml:"builtBy,omitempty"`
}

type Resolved struct {
	Model   *Model
	Sources []Source
}

type SBOMConfig struct {
	// Enabled generates one SBOM per distinct repository and image in the project.
	Enabled bool `yaml:"enabled"`
	// Format is the document format. Empty means SBOMCycloneDXJSON.
	Format SBOMFormat `yaml:"format,omitempty"`
	// Scope is what each document covers: one target, the whole project, or both. Empty means
	// SBOMScopeComponent, which is the behavior a descriptor written before this field had.
	Scope SBOMScope `yaml:"scope,omitempty"`
}

type SBOMFormat string

type SBOMScope string

type Source struct {
	// Path is the file, as written in the descriptor that named it (or the root's own path).
	Path string
	// URL is the repository it came from, empty for a local file.
	URL string
	// Revision is what the descriptor asked for, and Resolved is the commit that turned out to
	// be. Both empty for a local file.
	Revision string
	Resolved string
	// Root marks the descriptor the resolution started from.
	Root bool
	// Digest is the content digest of the file, before ${{ VAR }} substitution.
	//
	// Per source rather than only over the merged result, because "which files was this assembled
	// from, and were they these ones" is the question an exclusion raises: a suppression arriving
	// from a fragment somebody cannot pin is a decision with no author.
	Digest string
}

type VEXConfig struct {
	// Author identifies who is making these statements: an organization, ideally with a way to reach
	// them ("Example Ltd <security@example.com>"). Defaults to the release name, which is a project
	// rather than a party. Enough to produce a valid document, not enough for one you would hand to
	// a customer.
	Author string `yaml:"author,omitempty"`
	// Product identifies the thing the statements are about, as an IRI. A package URL is the
	// conventional choice ("pkg:oci/example/api@sha256:…").
	//
	// Defaults to a purl built from the release name and version. Set it to whatever the SBOM
	// a consumer holds calls this product: a VEX statement is matched to a component by
	// identifier, so a document naming the product differently is one nothing will apply.
	Product string `yaml:"product,omitempty"`
}

type VEXDecision struct {
	// Status is the claim: not_affected, affected, or fixed.
	//
	// under_investigation is deliberately not accepted here. It is what an untriaged finding already
	// reports, and claiming it on a finding you have suppressed says two contradictory things. That
	// the matter is open, and that it is settled.
	Status string `yaml:"status"`
	// Justification is why the product is not affected, from VEX's fixed vocabulary. Valid only
	// with not_affected, where VEX requires either this or a prose statement; without it the
	// exclusion's `reason` is emitted as the prose form instead.
	//
	// A closed vocabulary because the whole value of the field is that a consumer can act on it
	// without reading English.
	Justification string `yaml:"justification,omitempty"`
}

type VEXRepository struct {
	// URL is the repository holding the document.
	URL string `yaml:"url"`
	// Ref is the branch, tag or commit to read. Empty takes the default branch.
	//
	// Worth pinning for a claim you are gating on: a branch moves, and a supplier revising their
	// analysis would change what your gate accepts with nothing in your descriptor having
	// changed. Either way the report records the commit actually read, so the run can be
	// reproduced after the fact even when this was left open.
	Ref string `yaml:"ref,omitempty"`
	// Path is the document's path inside the repository.
	Path string `yaml:"path"`
}

type VEXSource struct {
	// Path is a document on disk, resolved **relative to where Draugr runs**, not to the descriptor,
	// and not to the repository. That is the same rule every other path in a descriptor follows (see
	// HostSpec.Path), and stating it here is deliberate: a path whose base a reader has to guess is
	// one that works on a laptop and silently misses in CI.
	Path string `yaml:"path,omitempty"`
	// URL is a document to fetch over HTTPS. Fetched once per run and cached; the report records
	// the URL, when it was fetched and the digest of what came back, so a run stays reproducible
	// from its own evidence rather than from the network still agreeing later.
	URL string `yaml:"url,omitempty"`
	// Repository is a document inside a git repository, for a supplier who publishes VEX there
	// rather than at a stable URL.
	Repository *VEXRepository `yaml:"repository,omitempty"`
}