sarif

Documentation

Overview

Package sarif defines Static Analysis Results Interchange Format (SARIF) types supported by govulncheck.

The implementation covers the subset of the specification available at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sarif.

The sarif encoding models govulncheck findings as Results. Each Result encodes findings for a unique OSV entry at the most precise detected level only. CodeFlows summarize call stacks, similar to govulncheck textual output, while Stacks contain call stack information verbatim.

The result Levels are defined by the govulncheck.ScanLevel and the most precise level at which the finding was detected. Result error is produced when the finding level matches the user desired level of scan precision; all other finding levels are then classified as progressively weaker. For instance, if the user specified symbol scan level and govulncheck detected a use of a vulnerable symbol, then the Result will have error Level. If the symbol was not used but its package was imported, then the Result Level is warning, and so on.

Each Result is attached to the first line of the go.mod file. Other ArtifactLocations are paths relative to their enclosing modules. Similar to JSON output format, this makes govulncheck sarif locations portable.

The relative paths in PhysicalLocations also come with a URIBaseID offset. Paths for the source module analyzed, the Go standard library, and third-party dependencies are relative to %SRCROOT%, %GOROOT%, and %GOMODCACHE% offsets, resp. We note that the URIBaseID offsets are not explicitly defined in the sarif output. It is the clients responsibility to set them to resolve paths at their local machines.

All paths use "/" delimiter for portability.

Properties field of a Tool.Driver is a govulncheck.Config used for the invocation of govulncheck producing the Results. Properties field of a Rule contains information on CVE and GHSA aliases for the corresponding rule OSV. Clients can use this information to, say, suppress and filter vulnerabilities.

Please see the definition of types below for more information.

Index

• Constants
• func NewHandler(w io.Writer) *handler
• type ArtifactLocation
• type CodeFlow
• type Description
• type Driver
• type Frame
• type Location
• type Log
• type PhysicalLocation
• type Region
• type Result
• type Rule
• type RuleTags
• type Run
• type Stack
• type ThreadFlow
• type ThreadFlowLocation
• type Tool

Constants

const (
	SrcRootID    = "%SRCROOT%"
	GoRootID     = "%GOROOT%"
	GoModCacheID = "%GOMODCACHE%"
)

Functions

func NewHandler

func NewHandler(w io.Writer) *handler

Types

type ArtifactLocation

type ArtifactLocation struct {
	// URI is a path relative to URIBaseID.
	URI string `json:"uri,omitempty"`
	// URIBaseID is offset for URI, one of %SRCROOT%, %GOROOT%,
	// and %GOMODCACHE%.
	URIBaseID string `json:"uriBaseId,omitempty"`
}

ArtifactLocation is a path to an offending file.

type CodeFlow

type CodeFlow struct {
	// ThreadFlows is effectively a set of related information flows.
	ThreadFlows []ThreadFlow `json:"threadFlows,omitempty"`
	Message     Description  `json:"message,omitempty"`
}

CodeFlow summarizes a detected offending flow of information in terms of code locations. More precisely, it can contain several related information flows, keeping them together. In govulncheck, those can be all call stacks for, say, a particular symbol or package.

type Description

type Description struct {
	Text     string `json:"text,omitempty"`
	Markdown string `json:"markdown,omitempty"`
}

Description is a text in its raw or markdown form.

type Driver

type Driver struct {
	// Name is "govulncheck"
	Name string `json:"name,omitempty"`
	// Version is the govulncheck version
	Version string `json:"semanticVersion,omitempty"`
	// InformationURI points to the description of govulncheck tool
	InformationURI string `json:"informationUri,omitempty"`
	// Properties are govulncheck run metadata, such as vuln db, Go version, etc.
	Properties govulncheck.Config `json:"properties,omitempty"`

	Rules []Rule `json:"rules,omitempty"`
}

Driver provides details about the govulncheck binary being executed.

type Frame

type Frame struct {
	// Module is module information in the form <module-path>@<version>.
	// <version> can be empty when the module version is not known as
	// with, say, the source module analyzed.
	Module   string   `json:"module,omitempty"`
	Location Location `json:"location,omitempty"`
}

Frame is effectively a module location. It can also contain thread and parameter info, but those are not needed for govulncheck.

type Location

type Location struct {
	PhysicalLocation PhysicalLocation `json:"physicalLocation,omitempty"`
	Message          Description      `json:"message,omitempty"`
}

Location is currently a physical location annotated with a message.

type Log

type Log struct {
	// Version should always be "2.1.0"
	Version string `json:"version,omitempty"`

	// Schema should always be "https://json.schemastore.org/sarif-2.1.0.json"
	Schema string `json:"$schema,omitempty"`

	// Runs describes executions of static analysis tools. For govulncheck,
	// there will be only one run object.
	Runs []Run `json:"runs,omitempty"`
}

Log is the top-level SARIF object encoded in UTF-8.

type PhysicalLocation

type PhysicalLocation struct {
	ArtifactLocation ArtifactLocation `json:"artifactLocation,omitempty"`
	Region           Region           `json:"region,omitempty"`
}

type Region

type Region struct {
	StartLine   int `json:"startLine,omitempty"`
	StartColumn int `json:"startColumn,omitempty"`
	EndLine     int `json:"endLine,omitempty"`
	EndColumn   int `json:"endColumn,omitempty"`
}

Region is a target region within a file.

type Result

type Result struct {
	// RuleID is the Rule.ID/OSV producing the finding.
	RuleID string `json:"ruleId,omitempty"`
	// Level is one of "error", "warning", and "note".
	Level string `json:"level,omitempty"`
	// Message explains the overall findings.
	Message Description `json:"message,omitempty"`
	// Locations to which the findings are associated. Always
	// a single location pointing to the first line of the go.mod
	// file. The path to the file is "go.mod".
	Locations []Location `json:"locations,omitempty"`
	// CodeFlows summarize call stacks produced by govulncheck.
	CodeFlows []CodeFlow `json:"codeFlows,omitempty"`
	// Stacks encode call stacks produced by govulncheck.
	Stacks []Stack `json:"stacks,omitempty"`
}

Result is a set of govulncheck findings for an OSV. For call stack mode, it will contain call stacks for the OSV. There is exactly one Result per detected OSV. Only findings at the most precise detected level appear in the Result. For instance, if there are symbol findings for an OSV, those findings will be in the Result, but not the package and module level findings for the same OSV.

type Rule

type Rule struct {
	// ID is OSV.ID
	ID               string      `json:"id,omitempty"`
	ShortDescription Description `json:"shortDescription,omitempty"`
	FullDescription  Description `json:"fullDescription,omitempty"`
	Help             Description `json:"help,omitempty"`
	HelpURI          string      `json:"helpUri,omitempty"`
	// Properties contain OSV.Aliases (CVEs and GHSAs) as tags.
	// Consumers of govulncheck SARIF can use these tags to filter
	// results.
	Properties RuleTags `json:"properties,omitempty"`
}

Rule corresponds to the static analysis rule/analyzer that produces findings. For govulncheck, rules are OSVs.

type RuleTags

type RuleTags struct {
	Tags []string `json:"tags,omitempty"`
}

RuleTags defines properties.tags.

type Run

type Run struct {
	Tool Tool `json:"tool,omitempty"`
	// Results contain govulncheck findings. There should be exactly one
	// Result per a detected use of an OSV.
	Results []Result `json:"results,omitempty"`
}

Run summarizes results of a single invocation of a static analysis tool, in this case govulncheck.

type Stack

type Stack struct {
	Message Description `json:"message,omitempty"`
	Frames  []Frame     `json:"frames,omitempty"`
}

Stack is a sequence of frames and can encode a govulncheck call stack.

type ThreadFlow

type ThreadFlow struct {
	Locations []ThreadFlowLocation `json:"locations,omitempty"`
}

ThreadFlow encodes an information flow as a sequence of locations. For govulncheck, it can encode a call stack.

type ThreadFlowLocation

type ThreadFlowLocation struct {
	// Module is module information in the form <module-path>@<version>.
	// <version> can be empty when the module version is not known as
	// with, say, the source module analyzed.
	Module string `json:"module,omitempty"`
	// Location also contains a Message field.
	Location Location `json:"location,omitempty"`
}

type Tool

type Tool struct {
	Driver Driver `json:"driver,omitempty"`
}

Tool captures information about govulncheck analysis that was run.