skald

Documentation

Overview

Package skald renders scan results and verdicts into evidence: a JSON summary and merged SARIF. A skald is the poet who records deeds — here, the record of a scan.

Index

• Constants
• func MergedSARIF(run engine.Result) sarif.Report
• func MinPriorityOfReport(rep sarif.Report) (string, bool)
• func MinPriorityProvenance(band string) (sarif.Provenance, bool)
• func RenderJSON(w io.Writer, release saga.Release, run engine.Result, verdict norn.Result, ...) error
• func RenderJSONWith(w io.Writer, release saga.Release, run engine.Result, verdict norn.Result, ...) error
• func RenderJSONWithFeeds(w io.Writer, release saga.Release, run engine.Result, verdict norn.Result, ...) error
• func ScopeOfReport(rep sarif.Report) (string, bool)
• func ScopeProvenance(scope engine.Scope) (sarif.Provenance, bool)
• func WriteSARIF(w io.Writer, run engine.Result) error
• func WriteSARIFNarrowed(w io.Writer, run engine.Result, band string, opts sarif.MarshalOptions) error
• func WriteSARIFWith(w io.Writer, run engine.Result, opts sarif.MarshalOptions) error
• type FeedProvenance

Constants

const MinPriorityProvenanceTool = "draugr/min-priority"

MinPriorityProvenanceTool is the provenance entry a priority-narrowed report stamps on its SARIF.

const ScopeProvenanceTool = "draugr/scope"

ScopeProvenanceTool is the provenance entry a scoped run stamps on its SARIF.

Functions

func MergedSARIF

func MergedSARIF(run engine.Result) sarif.Report

MergedSARIF combines all controls' reports into one SARIF report.

func MinPriorityOfReport

func MinPriorityOfReport(rep sarif.Report) (string, bool)

MinPriorityOfReport reports the band a loaded report was narrowed to, and whether it was narrowed at all. The inverse of MinPriorityProvenance, for a consumer reading a file somebody else wrote.

func MinPriorityProvenance

func MinPriorityProvenance(band string) (sarif.Provenance, bool)

MinPriorityProvenance renders a declared priority band as a SARIF provenance entry, and reports whether there was one to render.

The same carrier and the same reason as a scope: a run states what it left out, not only what it found. And the same hazard if it does not — a narrowed file and a complete one are indistinguishable to anything that reloads them, so `draugr diff` would read every finding below the band as fixed.

func RenderJSON

func RenderJSON(w io.Writer, release saga.Release, run engine.Result, verdict norn.Result, minPriority string) error

RenderJSON writes a JSON evidence summary combining the run result and the verdict. Controls are emitted in name order for stable output. When minPriority is non-empty (e.g. "P2"), a ranked `findings` list of findings at or above that band is included; priority counts are always included when the run was prioritized.

func RenderJSONWith

func RenderJSONWith(w io.Writer, release saga.Release, run engine.Result, verdict norn.Result, minPriority string, opts sarif.MarshalOptions) error

RenderJSONWith is RenderJSON with marshalling options; Compact drops the indentation.

func RenderJSONWithFeeds

func RenderJSONWithFeeds(w io.Writer, release saga.Release, run engine.Result, verdict norn.Result, minPriority string, feeds []FeedProvenance, opts sarif.MarshalOptions) error

RenderJSONWithFeeds is RenderJSONWith plus the exploitability datasets the run used.

func ScopeOfReport

func ScopeOfReport(rep sarif.Report) (string, bool)

ScopeOfReport describes what a loaded report was scoped to, and reports whether it was scoped at all. The inverse of ScopeProvenance, for a consumer reading a file somebody else wrote.

func ScopeProvenance

func ScopeProvenance(scope engine.Scope) (sarif.Provenance, bool)

ScopeProvenance renders a scope as a SARIF provenance entry, and reports whether there was one to render.

Provenance is the right carrier and already says so: it is what a run states about itself rather than about what it found, and it survives a round trip through the file.

func WriteSARIF

func WriteSARIF(w io.Writer, run engine.Result) error

WriteSARIF writes the merged run results as SARIF 2.1.0 JSON.

func WriteSARIFNarrowed

func WriteSARIFNarrowed(w io.Writer, run engine.Result, band string, opts sarif.MarshalOptions) error

WriteSARIFNarrowed writes a SARIF report that says which priority band it was narrowed to.

The caller has already dropped the findings below the band; what this adds is the statement that it did. A file that is a subset and does not say so is the failure this whole provenance mechanism exists to prevent — most sharply for `draugr diff`, which would otherwise report every omitted finding as fixed.

func WriteSARIFWith

func WriteSARIFWith(w io.Writer, run engine.Result, opts sarif.MarshalOptions) error

WriteSARIFWith is WriteSARIF with marshalling options.

Types

type FeedProvenance

type FeedProvenance struct {
	Name      string     `json:"name"`
	URL       string     `json:"url,omitempty"`
	FetchedAt *time.Time `json:"fetchedAt,omitempty"`
	SHA256    string     `json:"sha256,omitempty"`
	Stale     bool       `json:"stale,omitempty"`
}

FeedProvenance is one exploitability dataset as a run saw it: where it came from, when, and whether it was already older than the run allowed for.