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"`
	Repositories   []Repository                  `yaml:"repositories,omitempty"`
	Images         []Image                       `yaml:"images,omitempty"`
	Hosts          []Host                        `yaml:"hosts,omitempty"`
	Infrastructure []Infrastructure              `yaml:"infrastructure,omitempty"`
	Controllers    map[string]ControllerSettings `yaml:"controllers,omitempty"`
}

type Config struct {
	Controllers map[string]ControllerSettings `yaml:"controllers,omitempty"`
	// Reports are the report formats to render on a scan (e.g. json, sarif, markdown, html).
	// Publishers deliver every rendered report to a destination.
	Reports []ReportConfig `yaml:"reports,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"`
	// 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"`
	// 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 []string `yaml:"allowEffects,omitempty"`
}

type ControllerSettings map[string]any

type Criticality 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 {
	// Controls sets a per-control severity threshold, overriding --fail-on for that control
	// only. Values are severity bands: critical, high, medium, low.
	//
	// 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.
	//
	// 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.
	FailOnPriority string `yaml:"failOnPriority,omitempty"`
}

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 {
	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

	// 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"`
}

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

type Release struct {
	Name    string `yaml:"name"`
	Version string `yaml:"version"`
	Stage   string `yaml:"stage,omitempty"`
}

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"`
}

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
}

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"`
}