sarif

Documentation

Overview

Package sarif provides SARIF (Static Analysis Results Interchange Format) output for API style linting results. SARIF 2.1.0 is supported.

SARIF enables integration with IDEs (VS Code, JetBrains), GitHub Code Scanning, and other static analysis tools.

Index

• Constants
• func FormatLintReport(report *types.LintReport, opts *Options) (string, error)
• type Artifact
• type ArtifactChange
• type ArtifactContent
• type ArtifactLoc
• type CodeFlow
• type Fix
• type Invocation
• type Level
• type Location
• type Log
  • func FromLintReport(report *types.LintReport, opts *Options) *Log
  • func (l *Log) Marshal(pretty bool) ([]byte, error)
  • func (l *Log) String() string
• type LogicalLoc
• type Message
• type MultiformatMessage
• type Options
  • func DefaultOptions() *Options
• type PhysicalLoc
• type PropertyBag
• type Region
• type Relationship
• type Replacement
• type ReportingConfig
• type ReportingDescr
• type ReportingDescrRef
• type Result
• type ResultKind
• type Run
• type Snippet
• type Stack
• type StackFrame
• type Suppression
• type ThreadFlow
• type ThreadFlowLoc
• type Tool
• type ToolComponent
• type ToolComponentRef

Constants

const SchemaURI = "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json"

SchemaURI is the URI for the SARIF 2.1.0 JSON schema.

const Version = "2.1.0"

Version is the SARIF schema version.

Functions

func FormatLintReport

func FormatLintReport(report *types.LintReport, opts *Options) (string, error)

FormatLintReport converts a LintReport to SARIF JSON string.

Types

type Artifact

type Artifact struct {
	Location    *ArtifactLoc `json:"location,omitempty"`
	Length      int          `json:"length,omitempty"`
	MimeType    string       `json:"mimeType,omitempty"`
	Encoding    string       `json:"encoding,omitempty"`
	Description *Message     `json:"description,omitempty"`
}

Artifact describes a file that was analyzed.

type ArtifactChange

type ArtifactChange struct {
	ArtifactLocation *ArtifactLoc  `json:"artifactLocation"`
	Replacements     []Replacement `json:"replacements"`
}

ArtifactChange describes changes to a single artifact.

type ArtifactContent

type ArtifactContent struct {
	Text   string `json:"text,omitempty"`
	Binary string `json:"binary,omitempty"`
}

ArtifactContent contains the content to insert.

type ArtifactLoc

type ArtifactLoc struct {
	URI       string `json:"uri,omitempty"`
	URIBaseID string `json:"uriBaseId,omitempty"`
	Index     int    `json:"index,omitempty"`
}

ArtifactLoc identifies a file.

type CodeFlow

type CodeFlow struct {
	ThreadFlows []ThreadFlow `json:"threadFlows"`
	Message     *Message     `json:"message,omitempty"`
}

CodeFlow describes execution paths through the code.

type Fix

type Fix struct {
	Description     *Message         `json:"description,omitempty"`
	ArtifactChanges []ArtifactChange `json:"artifactChanges,omitempty"`
}

Fix describes a proposed fix for a result.

type Invocation

type Invocation struct {
	CommandLine         string       `json:"commandLine,omitempty"`
	ExecutionSuccessful bool         `json:"executionSuccessful"`
	StartTimeUTC        string       `json:"startTimeUtc,omitempty"`
	EndTimeUTC          string       `json:"endTimeUtc,omitempty"`
	ExitCode            int          `json:"exitCode,omitempty"`
	WorkingDirectory    *ArtifactLoc `json:"workingDirectory,omitempty"`
}

Invocation describes a single invocation of the tool.

type Level

type Level string

Level indicates the severity of a result.

const (
	LevelNone    Level = "none"
	LevelNote    Level = "note"
	LevelWarning Level = "warning"
	LevelError   Level = "error"
)

Level constants for SARIF result severity.

type Location

type Location struct {
	ID               int          `json:"id,omitempty"`
	PhysicalLocation *PhysicalLoc `json:"physicalLocation,omitempty"`
	LogicalLocations []LogicalLoc `json:"logicalLocations,omitempty"`
	Message          *Message     `json:"message,omitempty"`
	Properties       PropertyBag  `json:"properties,omitempty"`
}

Location specifies where a result was detected.

type Log

type Log struct {
	Schema  string `json:"$schema"`
	Version string `json:"version"`
	Runs    []Run  `json:"runs"`
}

Log is the top-level SARIF object containing one or more runs.

func FromLintReport

func FromLintReport(report *types.LintReport, opts *Options) *Log

FromLintReport converts a LintReport to a SARIF Log.

func (*Log) Marshal

func (l *Log) Marshal(pretty bool) ([]byte, error)

Marshal converts a SARIF Log to JSON bytes.

func (*Log) String

func (l *Log) String() string

String returns the SARIF Log as a JSON string.

type LogicalLoc

type LogicalLoc struct {
	Name               string `json:"name,omitempty"`
	Index              int    `json:"index,omitempty"`
	FullyQualifiedName string `json:"fullyQualifiedName,omitempty"`
	DecoratedName      string `json:"decoratedName,omitempty"`
	Kind               string `json:"kind,omitempty"`
	ParentIndex        int    `json:"parentIndex,omitempty"`
}

LogicalLoc identifies a logical location (like a function or JSON path).

type Message

type Message struct {
	Text      string   `json:"text,omitempty"`
	Markdown  string   `json:"markdown,omitempty"`
	ID        string   `json:"id,omitempty"`
	Arguments []string `json:"arguments,omitempty"`
}

Message provides the text of a result message.

type MultiformatMessage

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

MultiformatMessage provides text in multiple formats.

type Options

type Options struct {
	// ToolName overrides the default tool name.
	ToolName string

	// ToolVersion specifies the tool version.
	ToolVersion string

	// ToolURI is a URL for more information about the tool.
	ToolURI string

	// IncludeRules adds rule definitions to the output.
	IncludeRules bool

	// Rules provides rule metadata for the rules array.
	Rules map[string]*types.Rule

	// BaseURI is the base URI for artifact locations.
	BaseURI string

	// PrettyPrint enables indented JSON output.
	PrettyPrint bool
}

Options configures SARIF output generation.

func DefaultOptions

func DefaultOptions() *Options

DefaultOptions returns options with sensible defaults.

type PhysicalLoc

type PhysicalLoc struct {
	ArtifactLocation *ArtifactLoc `json:"artifactLocation,omitempty"`
	Region           *Region      `json:"region,omitempty"`
	ContextRegion    *Region      `json:"contextRegion,omitempty"`
}

PhysicalLoc identifies a file and region within it.

type PropertyBag

type PropertyBag map[string]any

PropertyBag is a set of key-value pairs for custom properties.

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"`
	CharOffset  int      `json:"charOffset,omitempty"`
	CharLength  int      `json:"charLength,omitempty"`
	ByteOffset  int      `json:"byteOffset,omitempty"`
	ByteLength  int      `json:"byteLength,omitempty"`
	Snippet     *Snippet `json:"snippet,omitempty"`
	Message     *Message `json:"message,omitempty"`
}

Region identifies a portion of a file.

type Relationship

type Relationship struct {
	Target      *ReportingDescrRef `json:"target"`
	Kinds       []string           `json:"kinds,omitempty"`
	Description *Message           `json:"description,omitempty"`
}

Relationship describes a relationship between rules.

type Replacement

type Replacement struct {
	DeletedRegion   *Region          `json:"deletedRegion"`
	InsertedContent *ArtifactContent `json:"insertedContent,omitempty"`
}

Replacement describes a replacement in a file.

type ReportingConfig

type ReportingConfig struct {
	Enabled bool    `json:"enabled,omitempty"`
	Level   Level   `json:"level,omitempty"`
	Rank    float64 `json:"rank,omitempty"`
}

ReportingConfig specifies the default severity and other settings.

type ReportingDescr

type ReportingDescr struct {
	ID               string              `json:"id"`
	Name             string              `json:"name,omitempty"`
	ShortDescr       *MultiformatMessage `json:"shortDescription,omitempty"`
	FullDescr        *MultiformatMessage `json:"fullDescription,omitempty"`
	HelpURI          string              `json:"helpUri,omitempty"`
	Help             *MultiformatMessage `json:"help,omitempty"`
	DefaultConfig    *ReportingConfig    `json:"defaultConfiguration,omitempty"`
	Properties       PropertyBag         `json:"properties,omitempty"`
	DeprecatedIDs    []string            `json:"deprecatedIds,omitempty"`
	DeprecatedNames  []string            `json:"deprecatedNames,omitempty"`
	RelationshipList []Relationship      `json:"relationships,omitempty"`
}

ReportingDescr describes a rule that the tool can report.

type ReportingDescrRef

type ReportingDescrRef struct {
	ID            string            `json:"id,omitempty"`
	Index         int               `json:"index,omitempty"`
	ToolComponent *ToolComponentRef `json:"toolComponent,omitempty"`
}

ReportingDescrRef references a reporting descriptor.

type Result

type Result struct {
	RuleID     string        `json:"ruleId"`
	RuleIndex  int           `json:"ruleIndex,omitempty"`
	Level      Level         `json:"level,omitempty"`
	Kind       ResultKind    `json:"kind,omitempty"`
	Message    Message       `json:"message"`
	Locations  []Location    `json:"locations,omitempty"`
	Fixes      []Fix         `json:"fixes,omitempty"`
	Properties PropertyBag   `json:"properties,omitempty"`
	RelatedLoc []Location    `json:"relatedLocations,omitempty"`
	CodeFlows  []CodeFlow    `json:"codeFlows,omitempty"`
	Stacks     []Stack       `json:"stacks,omitempty"`
	Suppressed []Suppression `json:"suppressions,omitempty"`
}

Result represents a single finding from the analysis.

type ResultKind

type ResultKind string

ResultKind indicates the nature of a result.

const (
	KindNotApplicable ResultKind = "notApplicable"
	KindPass          ResultKind = "pass"
	KindFail          ResultKind = "fail"
	KindReview        ResultKind = "review"
	KindOpen          ResultKind = "open"
	KindInformational ResultKind = "informational"
)

ResultKind constants for SARIF result classification.

type Run

type Run struct {
	Tool        Tool         `json:"tool"`
	Results     []Result     `json:"results,omitempty"`
	Invocations []Invocation `json:"invocations,omitempty"`
	Artifacts   []Artifact   `json:"artifacts,omitempty"`
}

Run represents a single invocation of an analysis tool.

type Snippet

type Snippet struct {
	Text     string              `json:"text,omitempty"`
	Rendered *MultiformatMessage `json:"rendered,omitempty"`
}

Snippet contains source code text.

type Stack

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

Stack describes a call stack.

type StackFrame

type StackFrame struct {
	Location *Location `json:"location,omitempty"`
	Module   string    `json:"module,omitempty"`
}

StackFrame describes a single frame in a stack.

type Suppression

type Suppression struct {
	Kind          string `json:"kind"`
	Status        string `json:"status,omitempty"`
	Justification string `json:"justification,omitempty"`
}

Suppression describes a suppressed result.

type ThreadFlow

type ThreadFlow struct {
	Locations []ThreadFlowLoc `json:"locations"`
}

ThreadFlow describes a sequence of locations.

type ThreadFlowLoc

type ThreadFlowLoc struct {
	Location *Location `json:"location,omitempty"`
}

ThreadFlowLoc is a location in a thread flow.

type Tool

type Tool struct {
	Driver ToolComponent `json:"driver"`
}

Tool describes the analysis tool that produced the results.

type ToolComponent

type ToolComponent struct {
	Name            string              `json:"name"`
	Version         string              `json:"version,omitempty"`
	SemanticVersion string              `json:"semanticVersion,omitempty"`
	InformationURI  string              `json:"informationUri,omitempty"`
	Rules           []ReportingDescr    `json:"rules,omitempty"`
	Organization    string              `json:"organization,omitempty"`
	FullName        string              `json:"fullName,omitempty"`
	ShortDescr      *MultiformatMessage `json:"shortDescription,omitempty"`
}

ToolComponent provides metadata about the tool.

type ToolComponentRef

type ToolComponentRef struct {
	Name  string `json:"name,omitempty"`
	Index int    `json:"index,omitempty"`
}

ToolComponentRef references a tool component.