sarif

type CallFrame struct {
	// Function is the function called, qualified as its language qualifies it.
	Function string `json:"function"`
	// Package is the package the function belongs to, when the analyzer reports one.
	Package string `json:"package,omitempty"`
	// Module is the module the package belongs to, when the analyzer reports one.
	Module string `json:"module,omitempty"`
	// File and Line locate the call. Relative to the module root, as the analyzer reported it.
	File string `json:"file,omitempty"`
	Line int    `json:"line,omitempty"`
}

type CallPath struct {
	// Frames are the calls making up the route, starting in this project's own code.
	Frames []CallFrame `json:"frames"`
}

type Correlation struct {
	// AlsoFoundBy is what the other scanners said about this same flaw, ordered by tool name.
	// Set on the finding that is counted, and empty on the ones that are not.
	AlsoFoundBy []Observation `json:"alsoFoundBy,omitempty"`
	// CountedUnder names the scanner whose finding this one is counted under, and is what makes
	// this finding evidence rather than a count. Empty on the finding that is counted.
	CountedUnder string `json:"countedUnder,omitempty"`
}

type Counts struct {
	Error   int
	Warning int
	Note    int
	None    int
}

type Escalation struct {
	// From is the severity before enrichment — the scanner's own rating, and the one the report
	// still displays, because it is what the scanner actually said.
	From Severity `json:"from"`
	// To is the severity the finding was *ranked* as. Enrichment feeds the priority matrix
	// rather than rewriting what the scanner reported, so this is the value the band was
	// computed from and the one that explains a P1 sitting on a "high" row.
	To Severity `json:"to"`
	// Signal names the dataset that fired: "kev" or "epss".
	Signal string `json:"signal"`
	// Detail is the specific fact, e.g. "on KEV" or "EPSS 0.87".
	Detail string `json:"detail"`
	// AsOf is the day the data was fetched, as YYYY-MM-DD. Without it the claim is "KEV said
	// so", which is not something a reader can check or reproduce.
	AsOf string `json:"asOf,omitempty"`
}

type Field struct {
	Key   string `json:"key"`
	Value string `json:"value"`
}

type Layer struct {
	// DiffID is the layer's content digest, as the image records it.
	DiffID string `json:"diffId,omitempty"`
	// Index is the layer's position from the bottom of the image, starting at 0.
	Index int `json:"index"`
	// Of is the number of layers in the image.
	Of int `json:"of,omitempty"`
	// CreatedBy is the build instruction that produced the layer, verbatim from the image's own
	// history — "RUN /bin/sh -c apt-get install …". It names the line to change, which is more
	// use than a layer digest and more honest than a guessed base image.
	CreatedBy string `json:"createdBy,omitempty"`
}

type Level string

type Location struct {
	URI       string `json:"uri,omitempty"`
	StartLine int    `json:"startLine,omitempty"`
}

type MarshalOptions struct {
	// Compact drops what only a human reads — indentation, and the rule prose relayed from
	// the scanner — while keeping the report valid SARIF.
	//
	// It exists for a consumer that is going to *act* on the report rather than read it,
	// typically an agent paying for every byte of context. Rule descriptions and remediation
	// text are the bulk of a Draugr report (61% of it, measured on this repo), and a reader
	// that can follow a link doesn't need them inlined. So helpUri survives compaction and the
	// prose doesn't: keep the pointer, drop the paragraphs.
	Compact bool
}

type Observation struct {
	// Tool is the scanner that made this observation.
	Tool string `json:"tool"`
	// RuleID is what that scanner called it, which is not always what the counted finding is
	// called — and is the id an exclusion may already be written against.
	RuleID string `json:"ruleId,omitempty"`
	// Severity and Score are that scanner's own rating, kept whether or not it agrees. The
	// report decides what is worth showing; the record does not get to be selective.
	Severity Severity `json:"severity,omitempty"`
	Score    float64  `json:"score,omitempty"`
}

type Package struct {
	// Name is the package as its ecosystem names it, e.g. "flask".
	Name string `json:"name"`
	// Version is what is installed.
	Version string `json:"version,omitempty"`
	// FixedVersion is the first release that resolves the finding. Empty when there is none —
	// which is a different and more alarming answer than "unknown", and the reason this is
	// reported rather than inferred from the absence of a fix.
	FixedVersion string `json:"fixedVersion,omitempty"`
	// PURL is the package URL, e.g. "pkg:pypi/flask@0.12.2". The one identifier that is portable
	// across ecosystems and the one every consumer of this asked for first.
	PURL string `json:"purl,omitempty"`
	// Ecosystem is the package manager the name belongs to, as the ecosystem calls itself:
	// "pip", "npm", "gem". A name alone is ambiguous — there is a `request` on npm and a
	// `requests` on PyPI, and neither is the other.
	Ecosystem string `json:"ecosystem,omitempty"`
}

type Provenance struct {
	// Tool is the scanner that produced this account.
	Tool string `json:"tool"`
	// Version is the scanner's version as the engine resolved it — the same value that goes into
	// its cache key, so the evidence and the cache cannot disagree about what ran. Empty when the
	// scanner does not report one.
	Version string `json:"version,omitempty"`
	// Fields are the scanner's own statements about the run, in the order it considers useful.
	//
	// Untyped, because the interesting ones are domain knowledge — "benchmark", "coverage",
	// "scope" — and this package is the finding currency for every scanner Draugr will ever
	// have. It should not learn what a CIS benchmark is to carry the fact that one was applied.
	Fields []Field `json:"fields,omitempty"`
}

type Reachability struct {
	// State is the verdict: reachable, unreachable, or unknown.
	State ReachabilityState `json:"state"`
	// Analyzer names the tool that decided, e.g. "govulncheck".
	Analyzer string `json:"analyzer"`
	// Method is how it decided, e.g. "call-graph". Buyers are told to reject reachability
	// claims that do not say how they were reached, and they are right to: a call graph and a
	// framework heuristic are both called reachability and are not the same evidence.
	Method string `json:"method,omitempty"`
	// Symbols are the vulnerable functions the advisory names, whether or not they are called.
	// Reported for both reachable and unreachable, because "which functions would have to be
	// called" is what makes an unreachable verdict checkable by hand.
	Symbols []string `json:"symbols,omitempty"`
	// Paths are the routes found from this project's code to the vulnerable code, each ordered
	// caller first. Empty unless State is reachable.
	Paths []CallPath `json:"paths,omitempty"`
	// RankedAs is the severity the priority band was computed from, set only when the state
	// moved it. The report still displays the scanner's own severity; this explains a P3 sitting
	// on a "high" row, the way Escalation.To explains a P1 on a "medium" one.
	RankedAs Severity `json:"rankedAs,omitempty"`
	// AsOf is the day the analysis ran, as YYYY-MM-DD. A reachability verdict describes one
	// revision of the code and stops being true when the code changes, so a claim without a date
	// is not one a reader can check.
	AsOf string `json:"asOf,omitempty"`
}

type ReachabilityState string

type Remediation string

type Report struct {
	Tool    string   `json:"tool,omitempty"`
	Results []Result `json:"results"`
	// Rules is the metadata the scanner published about the rules it applied, keyed by rule id.
	// A result names its rule; the rule is what explains it. Carrying this through is what lets
	// a reader — in a terminal, an editor, or a pull request — find out what "DS-0002" means.
	// Not every scanner publishes it, so entries may be missing.
	Rules map[string]Rule `json:"rules,omitempty"`
	// Provenance is what the scanners said about the run itself, as opposed to what they found:
	// which standard was applied, how much of it could be decided, what the scan was scoped to.
	//
	// A finding answers "what is wrong". Evidence also has to answer "what was measured, and
	// against what" — and that was not recorded anywhere, so a compliance report could not say
	// which benchmark produced it. One entry per tool run; see Provenance.
	Provenance []Provenance `json:"provenance,omitempty"`
	// Decided are the classifications this run reached a verdict on, whether or not a finding
	// resulted. A taxon here with no finding means the scanner looked and found nothing wrong.
	//
	// The distinction this exists for: a scanner that reports nothing about a control has either
	// examined it and been satisfied, or never examined it at all, and those mean opposite
	// things. Without this, a report that says "1 of 2 scanners found it" is guessing that the
	// other dissented — when far more often the other simply does not check that control.
	//
	// "Decided" rather than "examined" on purpose: a check a scanner looked at and could not
	// settle — a CIS control that requires human judgement — is not a dissent either.
	Decided []Taxon `json:"decided,omitempty"`
}

type RepositoryRef struct {
	// URL is the repository as the descriptor named it.
	URL string `json:"url"`
	// Revision is the commit that was scanned. Empty when git could not be asked.
	Revision string `json:"revision,omitempty"`
	// Uncommitted counts files in the working copy. Not part of what was scanned unless
	// WorkingTree is set, in which case they are precisely what was.
	Uncommitted int `json:"uncommitted,omitempty"`
	// WorkingTree reports that the scan read the checkout on disk rather than a commit, so the
	// result is not reproducible from the revision alone.
	WorkingTree bool `json:"workingTree,omitempty"`
}

type Result struct {
	// Tool is the scanner that produced the finding.
	Tool     string   `json:"tool,omitempty"`
	RuleID   string   `json:"ruleId"`
	Level    Level    `json:"level"`
	Message  string   `json:"message"`
	Location Location `json:"location,omitempty"`
	// Score is the finding's numeric CVSS-style severity (0–10), sourced from the SARIF
	// "security-severity" property. HasScore reports whether a score was present; without
	// one, normalized Severity falls back to Level.
	Score    float64 `json:"score,omitempty"`
	HasScore bool    `json:"-"`
	// Priority is the computed action band (P1–P4) for this finding, stamped by the engine
	// from the component's risk classification. Empty when prioritization is not configured.
	Priority string `json:"priority,omitempty"`
	// Historical marks a finding that describes a commit rather than the current tree.
	//
	// A history scan reports the path a secret had in the commit that introduced it, and after a
	// rename that path no longer exists. Unmarked, the finding reads as something already cleaned
	// up — which is exactly backwards, because a credential in history is still fetchable by
	// anyone who can clone and still needs rotating, whatever the tree looks like now.
	Historical bool `json:"historical,omitempty"`
	// PriorityFloor explains a band the component's classification alone does not account for.
	//
	// Some findings are not bounded by where the component sits. A leaked credential is valid
	// wherever it is valid — a cloud account, a registry, an artifact store — and git history is
	// often readable by more people than the service is reachable by, so an `internal` component
	// can understate who can obtain the thing. Where a control says so, the band it produces is
	// not damped below a floor.
	//
	// Set only when the floor actually raised the band, so a reader asking "why is this P2 on a
	// supporting internal component" has the answer in the report rather than in the source.
	PriorityFloor string `json:"priorityFloor,omitempty"`
	// Component names the part of the application this finding belongs to, stamped by the engine
	// from the component whose scan produced it. Empty for a project-scoped control, which has
	// no one component to attribute to.
	//
	// A location alone is ambiguous the moment a descriptor has two components: three components
	// have three go.mod files, and two can carry the same path. It is also what makes the
	// priority checkable — the band is computed from the component's declared exposure and
	// criticality, so a report showing the band without naming the component states a conclusion
	// and withholds its premise.
	Component string `json:"component,omitempty"`
	// Repository is the repository this finding was found in, for a component that has more than
	// one — or a fragment that contributed one from somewhere else.
	//
	// Paths are rewritten repository-relative so a finding can be anchored to a file, which means
	// two repositories that share a path share everything else about a finding. Without this they
	// are one finding, and the second repository's copy is discarded on the way in.
	Repository string `json:"repository,omitempty"`
	// PartialFingerprints are SARIF's own mechanism for identity across runs, keyed by name.
	//
	// Distinct from Fingerprint, and the difference is what each is for. Fingerprint deduplicates
	// *within* a run and hashes the line number to do it, which is exactly right there and useless
	// across runs: adding an import at the top of a file changes the line of every finding below
	// it. These hash what the code says rather than where it sits.
	//
	// Empty for a finding with no file and line — a vulnerable dependency is identified by its
	// package, which is already on the finding. Absent means "no content-based identity", and a
	// fabricated one would be worse than none.
	PartialFingerprints map[string]string `json:"partialFingerprints,omitempty"`
	// Package identifies the dependency a finding is about, when it is about one.
	//
	// Nil for a finding that is not: a SAST rule is about a line of code, an IaC check about a
	// resource. Set by the scanners that know, which is those reading a package manifest or an
	// image's installed set.
	Package *Package `json:"package,omitempty"`
	// Image is the container image a finding is about, for the scanners that scan one.
	//
	// It travels on the finding rather than being recovered from the component afterwards,
	// because a component may hold several images: recovering it later can only produce one
	// answer for all of them, which would be right whenever there is one image and silently
	// wrong the moment there are two.
	Image string `json:"image,omitempty"`
	// OperatingSystem is the OS whose package set contains the finding, e.g. "debian 12".
	//
	// Set only for findings in an image's OS layer, which is what distinguishes a vulnerable
	// system package from a vulnerable application dependency sitting on top of it. Empty for a
	// finding in a language ecosystem, where there is no OS answer to give.
	OperatingSystem string `json:"operatingSystem,omitempty"`
	// OSEndOfLife marks a finding whose operating system release no longer receives security
	// updates from its vendor — Trivy's EOSL, End Of Service Life.
	//
	// It changes what the finding means. On a supported release, "no fix available" is a state
	// that will end when the vendor publishes one; on a release past end of life, no fix is ever
	// coming, and upgrading the release is the only action that resolves it. That is usually the
	// highest-leverage move available, because it resolves every finding in the OS layer at once.
	OSEndOfLife bool `json:"osEndOfLife,omitempty"`
	// ProviderOperated marks a finding about a surface somebody else runs — the control plane of
	// a managed Kubernetes cluster being the case it exists for.
	//
	// Set from what the descriptor declares, never guessed: whether a cluster is managed is a
	// fact about a contract, not something visible in what a scanner reads. It is the same
	// argument that puts exposure and criticality in the descriptor.
	ProviderOperated bool `json:"providerOperated,omitempty"`
	// ImageBuiltUpstream marks a finding inside an image somebody else publishes.
	//
	// It changes the action rather than the severity. A vulnerable library in an image this team
	// builds is theirs to upgrade; the same library in an image they only run is fixed by taking
	// a newer image, and telling them to upgrade the library is advice they cannot act on.
	ImageBuiltUpstream bool `json:"imageBuiltUpstream,omitempty"`
	// Layer is the image layer the finding's package arrived in. Nil for anything that is not an
	// image finding, and for an image whose scanner did not report one.
	//
	// It is the only reliable answer to "is this mine or inherited". An image records nothing
	// about what it was built FROM — the name is not in there — so a base image cannot be named,
	// and where a multi-layer base ends is not knowable either. The layer, and the build step
	// that created it, are facts; anything further is inference and has to be labeled as such.
	Layer *Layer `json:"layer,omitempty"`
	// Suppression is set when a Saga exclusion matched this finding. A suppressed result is
	// reported but not counted: it does not reach Counts, the verdict, or the fix-first list.
	// Nil for an active finding.
	Suppression *Suppression `json:"suppression,omitempty"`
	// Escalation is set when exploitability enrichment raised this finding's severity, and says
	// which signal did it. Nil when nothing moved it.
	//
	// Suppression's twin: one records a decision to count a finding for less, this one records
	// evidence that it deserves more. Both answer the same question — a report that states a
	// conclusion and withholds its premise is a hint rather than evidence, and "critical because
	// CISA observed this being exploited, as of a date you can check" is the premise.
	Escalation *Escalation `json:"escalation,omitempty"`
	// Reachability is set when a reachability analyzer covered this finding's dependency, and
	// says whether this project's code can actually reach the vulnerable code. Nil when no
	// analyzer ran; ReachabilityUnknown when one ran but could not tell.
	//
	// Only ever set on a finding about a dependency, so it is nil wherever Package is.
	Reachability *Reachability `json:"reachability,omitempty"`
	// Correlation is set when more than one scanner reported this same flaw: on the finding that
	// is counted it names who else found it, and on the others it names the one they are counted
	// under. Nil when only one scanner reported it.
	Correlation *Correlation `json:"correlation,omitempty"`
}

type Rule struct {
	// Name is a human-readable identifier (SARIF reportingDescriptor.name), where the id
	// itself is opaque.
	Name string `json:"name,omitempty"`
	// ShortDescription is a single sentence; FullDescription is a paragraph.
	ShortDescription string `json:"shortDescription,omitempty"`
	FullDescription  string `json:"fullDescription,omitempty"`
	// Help is remediation guidance, often Markdown.
	Help string `json:"help,omitempty"`
	// HelpURI points at the rule's documentation or advisory.
	HelpURI string `json:"helpUri,omitempty"`
	// Taxa are the shared classifications this rule implements — a CIS benchmark control, a
	// CWE. Empty when the scanner claims none.
	//
	// This is what makes two tools' findings recognizable as being about the same thing, and it
	// is deliberately not the rule id. An id belongs to whoever emitted it: `draugr/cis/5.1.1`
	// and `kube-bench/cis/5.1.1` are two tools' accounts, and collapsing them into one id — as
	// they were — makes provenance unrecoverable. A taxon is the vocabulary both are speaking,
	// so the correspondence is stated rather than inferred from a string collision.
	//
	// SARIF models exactly this with `taxonomies` and `taxa`, so a consumer that has never heard
	// of Draugr can group by CIS control, and a third-party scanner can participate by emitting
	// the same references.
	Taxa []Taxon `json:"taxa,omitempty"`
}

type Severity string

type Suppression struct {
	// Kind is the SARIF suppression kind. Draugr writes "external": the decision came from the
	// Saga, not from an annotation in the source.
	Kind string `json:"kind"`
	// Justification is the reason the Saga gave. Required by Draugr even though SARIF allows
	// it to be absent.
	Justification string `json:"justification"`
	// AcceptedBy is who decided this was acceptable, when the exclusion said. Empty means the
	// suppression is unattributed — reported as such, because "who decided" is half the question
	// an auditor is asking and a blank is an answer worth seeing.
	AcceptedBy string `json:"acceptedBy,omitempty"`
	// Expires is when the acceptance lapses, as YYYY-MM-DD. Empty means it does not.
	Expires string `json:"expires,omitempty"`
	// VEXStatus is what the exclusion declared this suppression means as a claim about the
	// product: not_affected, affected, or fixed. Empty when the exclusion said nothing, which
	// is the common case and reports as affected — the reading that is never an overstatement.
	VEXStatus string `json:"vexStatus,omitempty"`
	// VEXJustification is why the product is not affected, from VEX's fixed vocabulary. Set
	// only alongside a not_affected status.
	VEXJustification string `json:"vexJustification,omitempty"`
	// Origin says who decided. Empty or "saga" is a rule in the descriptor; "vex" is a statement
	// somebody else made and this project chose to accept.
	//
	// The distinction is the whole point of reading a supplier's document rather than retyping it.
	// A `not_affected` you copied into `config.exclude` becomes indistinguishable from a decision
	// you made and are answerable for; kept apart, the report can say the analysis was theirs, and
	// an auditor can ask them rather than you.
	Origin string `json:"origin,omitempty"`
	// Author is who asserted an imported claim — the VEX document's author. Empty for a
	// descriptor rule, where AcceptedBy already answers "who decided".
	Author string `json:"author,omitempty"`
	// Asserted is when an imported claim was made, as the document wrote it. A supplier's
	// statement is made on a date they chose, and a year-old `not_affected` about a package that
	// has moved on is worth seeing as old rather than reading as current.
	Asserted string `json:"asserted,omitempty"`
	// Source is the descriptor or fragment the exclusion was written in, or the document an
	// imported claim came from. Empty when the whole descriptor is one file, where naming it
	// would be noise.
	//
	// Splitting exclusions across files is only safe if the report can still say which file
	// authorized each one — otherwise composition trades a long descriptor for an unanswerable
	// one, which is the worse of the two.
	Source string `json:"source,omitempty"`
}

type Taxon struct {
	// Taxonomy names the scheme, e.g. "CIS-Kubernetes" or "CWE".
	Taxonomy string `json:"taxonomy"`
	// ID is the identifier within it, e.g. "5.1.1" or "79".
	ID string `json:"id"`
	// Name is a short human label, when the scanner supplies one.
	Name string `json:"name,omitempty"`
	// Version is the taxonomy revision the id belongs to, e.g. "cis-1.12". A check number means
	// a different thing between benchmark revisions, so an id without one is ambiguous.
	Version string `json:"version,omitempty"`
}