README
¶
sarif
A small, dependency-free SARIF 2.1.0 emitter for the hawk-eco. Used by
sight (code review findings) and inspect (web-scan findings) to produce
output compatible with GitHub Code Scanning, VS Code SARIF Viewer, and other
SARIF-consuming tools.
Why this package exists
sight and inspect were each carrying their own ~250-line copy of the
SARIF 2.1.0 type tree and JSON marshalling. This package collapses them into
a single canonical implementation. Both repos now consume it and only need
to map their domain Finding types into the small sarif.Rule / sarif.Result
shape.
API
b := sarif.New(sarif.Tool{
Name: "mytool",
Version: "1.2.3",
InformationURI: "https://github.com/example/mytool",
})
b.AddRule(sarif.Rule{
ID: "mytool/sql-injection",
Name: "sql-injection",
ShortDescription: "Possible SQL injection sink",
Severity: sarif.SeverityError,
})
b.AddResult(sarif.Result{
RuleID: "mytool/sql-injection",
Severity: sarif.SeverityError,
Message: "concatenated user input into SQL",
URI: "src/handlers.go",
Region: &sarif.Region{StartLine: 42},
Taxa: []sarif.TaxaRef{{ID: "CWE-89", Component: "CWE"}},
})
json, err := b.JSON()
The output is canonical SARIF 2.1.0 — see https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html.
Versioning
Version is read at compile time from the VERSION file at the repo root
(see hawk-eco VERSIONING.md).
Status
Local module — until this is published as github.com/GrayCodeAI/sarif,
consuming repos use a replace directive in their go.mod to point at the
local path. Once published:
# In the consuming repo
go get github.com/GrayCodeAI/sarif@latest
# Then remove the `replace github.com/GrayCodeAI/sarif => ../sarif` line.
Documentation
¶
Overview ¶
Package sarif emits SARIF 2.1.0 JSON for static-analysis-style tools.
It is intentionally small: a single Builder type that accumulates a tool description, rules, and results, then serialises to canonical SARIF 2.1.0. Consumers are responsible for mapping their domain Finding types into the Rule / Result shape exposed here.
Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
Index ¶
Constants ¶
This section is empty.
Variables ¶
var Version = strings.TrimSpace(versionFile)
Version of this sarif package. Sourced from the VERSION file at the repo root (single source of truth, see hawk VERSIONING.md).
Functions ¶
This section is empty.
Types ¶
type Builder ¶
type Builder struct {
// contains filtered or unexported fields
}
Builder accumulates rules and results for a single SARIF run.
Builders are not safe for concurrent use; build the run on one goroutine then publish the JSON. Re-adding the same Rule by ID is a no-op.
func (*Builder) AddResult ¶
AddResult appends a result to the run. The RuleID should refer to a rule added via AddRule; if it doesn't, the result is still emitted but tools may flag the SARIF as malformed.
func (*Builder) AddRule ¶
AddRule registers a rule. Calls with a duplicate Rule.ID are no-ops, so it's safe to call this from a per-result loop.
type Region ¶
Region describes the file region a Result references. All fields are optional; zero values are omitted from output.
type Result ¶
type Result struct {
RuleID string
Severity Severity
Message string
URI string // artifact location (file path or URL)
Region *Region // optional file region
Fix string // optional fix description (text only — no patch)
Taxa []TaxaRef
}
Result is a single finding against a Rule.
type Rule ¶
type Rule struct {
ID string
Name string
ShortDescription string
FullDescription string
HelpURI string
Severity Severity
Tags []string
}
Rule defines a check that can produce results. IDs must be unique within a run; the Builder dedups by ID so callers can re-add the same rule freely.
type Severity ¶
type Severity int
Severity is the normalised severity model exposed by this package. It maps onto SARIF's `level` field via the level() method.
const ( // SeverityNone is "none" — informational, never failing. SeverityNone Severity = iota // SeverityNote is "note" — low-severity advisory. SeverityNote // SeverityWarning is "warning" — medium-severity issue. SeverityWarning // SeverityError is "error" — high or critical severity issue. SeverityError )
Source Files