diff

Documentation

Overview

Package diff compares two Draugr scan results and classifies every finding as new, fixed, or unchanged — the security delta of a change (typically a PR's head vs the base branch). It powers `draugr diff` and its differential gate ("fail only on findings this change introduces").

Inputs are SARIF reports (the results.sarif that `draugr scan -o` writes): SARIF is Draugr's complete, structured result currency, whereas the JSON summary can be trimmed by --min-priority.

Index

• func Formats() []string
• func Render(w io.Writer, format string, r Result) error
• type PriorityCounts
• type Result
  • func Compare(base, head sarif.Report) Result
  • func (r Result) GateNew(failOn sarif.Level, failOnPriority string) []sarif.Result
  • func (r Result) HelpURI(ruleID string) string
  • func (r Result) NarrowNew(band string) Result
  • func (r Result) OnlyRepository(ref string) Result
• type SeverityCounts

Functions

func Formats

func Formats() []string

Formats lists the diff output formats, sorted.

func Render

func Render(w io.Writer, format string, r Result) error

Render writes the diff in the named format. Unknown formats error.

Types

type PriorityCounts

type PriorityCounts struct {
	P1 int `json:"p1"`
	P2 int `json:"p2"`
	P3 int `json:"p3"`
	P4 int `json:"p4"`
}

PriorityCounts tallies findings by action band. Unprioritized findings are not counted here.

type Result

type Result struct {
	New       []sarif.Result // present in head, absent in base
	Fixed     []sarif.Result // present in base, absent in head
	Unchanged []sarif.Result // present in both (head copy)
	// Rules is what the scanners said about the rules these findings cite, carried over from the
	// reports being compared.
	//
	// A diff that keeps only results keeps only identifiers. `CVE-2018-1000656` in a table is a
	// string to copy into a search box, and the same id uploaded to code scanning arrives with no
	// description and whatever link can be guessed from its shape — while the scanner that found
	// it published both. Keeping the rules is what lets a reader click the finding instead of
	// looking it up.
	Rules map[string]sarif.Rule
}

Result is the classified delta between a base and a head report.

func Compare

func Compare(base, head sarif.Report) Result

Compare classifies every finding across the two reports by stable identity.

func (Result) GateNew

func (r Result) GateNew(failOn sarif.Level, failOnPriority string) []sarif.Result

GateNew returns the new findings that meet the differential gate: level at or above failOn (when set) OR priority at or above failOnPriority (when set). An empty threshold disables that dimension. With both empty, nothing is returned.

func (Result) HelpURI

func (r Result) HelpURI(ruleID string) string

HelpURI is where a reader can look up a rule: what the scanner published, or a URL derived from a well-known identifier scheme. Empty when neither applies — a wrong link is worse than none.

func (Result) NarrowNew

func (r Result) NarrowNew(band string) Result

NarrowNew drops new findings below a priority band, leaving fixed and unchanged alone.

Only the new ones, because they are what the diff is reporting and what a reviewer is asked to act on; fixed and unchanged are context, and a count of them that moved with a threshold would mean something different on every run.

A finding the scanner never prioritized is kept. An empty Priority means prioritization did not run for it, not that it ranked low — dropping it would hide a finding for the reason it was hardest to judge.

func (Result) OnlyRepository

func (r Result) OnlyRepository(ref string) Result

OnlyRepository keeps the new findings a given repository's checkout can actually anchor.

Paths are repository-relative, so a finding from another repository uploaded against this one resolves to a same-named file here — an annotation on a line that does not have that problem. That is wrong rather than merely noisy, and there is no case where it is wanted, so this is not offered as a preference.

A finding with no repository is kept. Not everything Draugr reports comes from a checkout: an image finding is located at an image reference and belongs to no repository, and dropping those would remove most of a container scan from the surface a reviewer reads.

type SeverityCounts

type SeverityCounts struct {
	Critical int `json:"critical"`
	High     int `json:"high"`
	Medium   int `json:"medium"`
	Low      int `json:"low"`
}

SeverityCounts tallies findings by Draugr's normalized severity band.

Bands rather than SARIF levels, because a diff is read next to the scan report it came from and the two have to agree. error/warning/note is the wire vocabulary of the file; a reader deciding whether a pull request made things worse is thinking in critical/high/medium/low.