sealed

type Advisories struct {
	Advisories []Advisory `yaml:"advisories"`
}

type Advisory struct {
	// ID is the identifier a scanner reports: a CVE where there is one.
	ID string `yaml:"id"`
	// GHSA is the GitHub advisory identifier, for an advisory whose CVE is a separate record. The
	// Grype database then keys the advisory by it and lists ID as its related CVE, with the CVE's
	// own record beside it, the way Grype's GitHub and NVD providers store one. Grype reports the
	// GHSA with byCve off and the CVE with it on; the other databases report ID either way.
	GHSA string `yaml:"ghsa,omitempty"`
	// GoID is the Go vulnerability database's own identifier, for an advisory govulncheck reads.
	GoID string `yaml:"goID,omitempty"`
	// Ecosystem is the package ecosystem: pip, npm, go, rubygems, cargo, composer, nuget, maven,
	// or js for a library retire.js identifies by its file.
	Ecosystem string `yaml:"ecosystem"`
	// Package is the name the ecosystem gives the package.
	Package string `yaml:"package"`
	// Fixed is the first version without the vulnerability; every earlier version is affected.
	Fixed string `yaml:"fixed"`
	// Severity is CRITICAL, HIGH, MEDIUM or LOW.
	Severity string `yaml:"severity"`
	// Title is a one-line summary, written for the fixture.
	Title string `yaml:"title"`
	// Symbols maps a Go package path to the functions the vulnerability is in, which is what
	// govulncheck follows to decide whether it is reachable.
	Symbols map[string][]string `yaml:"symbols,omitempty"`
	// CWE is the weakness, which retire.js requires on every entry.
	CWE string `yaml:"cwe,omitempty"`
}

type Annotation struct {
	// File is relative to the repository, with any fixture suffix removed.
	File string
	// Line is the line the annotation is about: the first line after it that is neither blank nor
	// another annotation.
	Line int
	Rule string
	// Want is true for `ruleid:` and false for `ok:`.
	Want bool
}

type ComponentExpectation struct {
	Name string `yaml:"name"`
	// Repositories are the repository urls, relative to the descriptor.
	Repositories []string `yaml:"repositories"`
	// Paths and Ignore are the scope its repositories declare. Empty means the whole repository.
	Paths  []string `yaml:"paths"`
	Ignore []string `yaml:"ignore"`
}

type Container struct {
	// Work is the one writable directory, mounted at the same path inside. The run's HOME is
	// Work/home, so every cache and dataset Draugr reads is the one the test put there.
	Work string
	// HostHome is the invoking user's home directory, mounted read-only for the tools installed
	// under it.
	HostHome string
	// Path is the PATH inside the container.
	Path string
	// Extra are further read-only mounts, such as a GOROOT outside the directories already mounted.
	Extra []string
	// Env is added to the environment inside the container.
	Env map[string]string
	// UID and GID are who the container runs as, so what it writes belongs to the invoking user.
	UID, GID int
	// Server, when set, is the serve helper built from ./serve. Every command then runs beside
	// ServedHandler on ServedAddr, offering the files under Served and logging each request to
	// RequestLog.
	Server, Served, RequestLog string
}

type ErrorExpectation struct {
	Control string `yaml:"control"`
	// Contains is text the control's error must include.
	Contains string `yaml:"contains"`
}

type Expected struct {
	// Init is what `draugr init` writes for the repository.
	Init InitExpectation `yaml:"init"`
	// Secrets are credentials the harness writes into the repository before it is committed.
	// Each must be reported by the secrets control.
	Secrets []SecretExpectation `yaml:"secrets"`
	// Findings are every other result the scan must report, and together with the secrets and the
	// fixture's inline sast annotations, every result it may report.
	Findings []FindingExpectation `yaml:"findings"`
	// Sealed changes what the container provides and how the scan runs.
	Sealed RunOptions `yaml:"sealed"`
	// Errors are the controls that must fail to run, each with text its error must contain. Every
	// other control must run.
	Errors []ErrorExpectation `yaml:"errors"`
	// Proves names the options whose effect the findings assert, as <scanner>.<option> for a
	// scanner's option (gosec.include) or <control>.<option> for a control's own (licenses.deny).
	// Each must be set in the scenario's descriptor, and the findings must differ because of it.
	Proves []string `yaml:"proves"`
	// Requests are requests the sealed server must have received by the end of the scan, each the
	// start of a line of its log, "METHOD request-uri", for a scenario whose findings depend on
	// something a scanner fetched from it.
	Requests []string `yaml:"requests"`
	// NeverRequested are line starts no request in the log may have, "DELETE " for every delete.
	NeverRequested []string `yaml:"neverRequested"`
	// InitScan is where a scan with the descriptor init wrote departs from Findings and Errors.
	InitScan InitScanExpectation `yaml:"initScan"`
}

type FileStructure struct {
	File    string   `yaml:"file"`
	FoundBy []string `yaml:"foundBy,flow"`
}

type Finding struct {
	Control      string
	Tool         string
	Rule         string
	File         string
	Line         int
	Package      string
	Component    string
	Reachability string
	// Historical is the SARIF result's history mark: the finding comes from a commit rather than
	// the tree.
	Historical bool
	// Suppressed is who set the finding aside, as the SARIF suppression's origin names it: saga,
	// vex, tool or scanner. Empty for a finding nothing set aside.
	Suppressed string
}

type FindingExpectation struct {
	Control string `yaml:"control"`
	// Tool is the scanner that reported it, as the SARIF names it.
	Tool string `yaml:"tool"`
	Rule string `yaml:"rule"`
	// Location is file:line relative to the repository, or the file alone for a result about a
	// whole file.
	Location string `yaml:"location"`
	// Package is "ecosystem name version", for a finding about a dependency.
	Package string `yaml:"package,omitempty"`
	// Component is the component the finding was reported for. Empty matches any, which is enough
	// where one component scans the repository; two components scanning one file report it twice,
	// and only the component tells those two findings apart.
	Component string `yaml:"component,omitempty"`
	// Reachability is the verdict reachability analysis reached, where it ran.
	Reachability string `yaml:"reachability,omitempty"`
	// Historical says the finding comes from the repository's history rather than its tree, and
	// the SARIF result has to carry the mark.
	Historical bool `yaml:"historical,omitempty"`
	// Suppressed is the origin of the suppression the finding has to carry: saga, vex, tool or
	// scanner. Empty means the finding has to arrive active.
	Suppressed string `yaml:"suppressed,omitempty"`
}

type InitExpectation struct {
	// Controls are the controls it enables, in any order.
	Controls []string `yaml:"controls"`
	// Scanners are the scanners it enables inside a control beyond the control's default, as
	// control.scanner (sast.gosec, sca.retirejs), in any order. Empty means none.
	Scanners []string `yaml:"scanners"`
	// Reachability are the reachability analyzers it turns on. Empty means none.
	Reachability []string `yaml:"reachability"`
	// Specs are the API documents it proposes as a host's spec, in the hosts block it writes
	// commented out. Empty means none.
	Specs []string `yaml:"specs"`
	// Components are the components it declares.
	Components []ComponentExpectation `yaml:"components"`
	// PerDirectory is what `draugr init --per-directory` writes, for a scenario whose tree has
	// directories with their own dependency files. Unset skips that run.
	PerDirectory *InitExpectation `yaml:"perDirectory"`
}

type InitScanExpectation struct {
	// Skip is why a scan with init's descriptor is not compared, for a scenario whose descriptor
	// is the subject: options init never writes, or components declared by hand. It is logged.
	Skip string `yaml:"skip"`
	// Unreported are rules from findings that init's descriptor does not report, because they
	// need an option the hand-written descriptor sets and init leaves at its default.
	Unreported []string `yaml:"unreported"`
	// Errors replace the scenario's errors for this scan, where init enables a different set of
	// controls from the ones the scenario's failure reaches. Unset keeps the scenario's; empty
	// means every control runs. Semgrep's offline refusal is added to either, where
	// InitRefusesSemgrep says it applies.
	Errors *[]ErrorExpectation `yaml:"errors"`
}

type Normalizer struct {
	// Clear are paths to fields replaced with Cleared. "*" matches every element of an array or
	// every value of an object. Each path must match at least one field.
	Clear [][]string
	// Sort are paths to arrays sorted by their elements' JSON.
	Sort [][]string
	// Replace maps a string to what it becomes, in every string value.
	Replace map[string]string
	// AllowMissing accepts a Clear path that matches nothing. For a run where a control failed to
	// start, which leaves no scanner version and no finding for that control to clear.
	AllowMissing bool
}

type PackageStructure struct {
	Name    string `yaml:"name"`
	Version string `yaml:"version"`
	// In is the file the package was reported in, relative to the repository.
	In string `yaml:"in"`
	// FoundBy are the control/scanner pairs that reported it, sorted.
	FoundBy []string `yaml:"foundBy,flow"`
}

type RunOptions struct {
	// WithoutTool is a program removed from PATH inside the container.
	WithoutTool string `yaml:"withoutTool"`
	// FailingTool is a program replaced by one that writes FailingToolMessage and exits 2.
	FailingTool string `yaml:"failingTool"`
	// WithoutTrivyDB leaves Trivy's vulnerability database unwritten.
	WithoutTrivyDB bool `yaml:"withoutTrivyDB"`
	// GoVulnDBAge is how long before the run the local Go vulnerability database is recorded as
	// fetched, as a Go duration. Empty means at the start of the run.
	GoVulnDBAge string `yaml:"goVulnDBAge"`
	// WithoutOffline scans without --offline, for a scenario whose scanner resolves something from
	// the sealed server, which the flag would stop it asking for. The container still has no
	// network beyond its own loopback.
	WithoutOffline bool `yaml:"withoutOffline"`
}

type Scenario struct {
	// Name is the directory name, which is also the component and the repository's directory.
	Name string
	// Dir is the scenario directory.
	Dir string
	// Expected is the parsed expected.yaml.
	Expected Expected
}

type SecretExpectation struct {
	// File is where the harness writes it, relative to the repository. It is written on line 1.
	File string `yaml:"file"`
	// Rules are the rules that must report it. Empty means nothing may report it, which is how a
	// scenario writes a credential outside every component's paths and holds every component to
	// leaving it alone.
	Rules []string `yaml:"rules"`
	// Components are the components that must each report it, once per rule. Empty means one
	// report from any component, which is enough where one component scans the repository. Where
	// several share it, a secret reported under a component whose paths do not hold it is a
	// credential filed with a team that cannot rotate it, and only naming the owner catches that.
	Components []string `yaml:"components,omitempty"`
	// Removed deletes the file in a second commit, so the secret is in the repository's history
	// and not in its tree, and each report of it has to carry the history mark.
	Removed bool `yaml:"removed"`
}

type Structure struct {
	// Packages maps an ecosystem (npm, gomod, pip) to the packages found in it.
	Packages map[string][]PackageStructure `yaml:"packages,omitempty"`
	// Files are the files a result with no package was reported in: a secret, a SAST result, a
	// misconfiguration.
	Files []FileStructure `yaml:"files,omitempty"`
}