README
¶
scanfindings Package
The scanfindings package provides a shared representation of the findings reported by the scanner integrations (zizmor, poutine, grype, grant, runner-guard, yamllint, markdown security scan, audit findings).
Overview
Each scanner speaks its own native JSON dialect, with severities spelled in a different vocabulary (High, error, Negligible, note, ...) and locations shaped differently. Integrations decode their native output into their own structs and then map those structs onto the shared Finding type declared here, so severity classification, ordering and rendering are implemented once instead of once per tool.
Public API
Types
| Type | Description |
|---|---|
SeverityLevel |
Shared severity vocabulary: unknown, info, low, medium, high, critical |
Finding |
Tool-independent finding: RuleID, Severity, Message, File, Line, Column, Context |
Functions and methods
| Function | Signature | Description |
|---|---|---|
ParseSeverity |
func ParseSeverity(raw string) SeverityLevel |
Normalizes a native severity label (case-insensitive) |
SeverityLevel.String |
func (s SeverityLevel) String() string |
Canonical lowercase severity name |
SeverityLevel.Rank |
func (s SeverityLevel) Rank() int |
Relative ordering, higher is more severe |
SeverityLevel.AtLeast |
func (s SeverityLevel) AtLeast(min SeverityLevel) bool |
Severity threshold comparison |
SeverityLevel.ErrorType |
func (s SeverityLevel) ErrorType() string |
Console error type (error, warning, info) |
Finding.CompilerError |
func (f Finding) CompilerError() console.CompilerError |
Converts a finding to the console error format |
FormatMessage |
func FormatMessage(severityLabel, ruleID, description string) string |
Builds the [severity] rule: description message |
Render |
func Render(w io.Writer, findings []Finding) |
Writes findings using the shared console format |
Sort |
func Sort(findings []Finding) |
Orders findings by file, line, column, severity, rule |
CountAtLeast |
func CountAtLeast(findings []Finding, min SeverityLevel) int |
Counts findings at or above a severity |
ContextLines |
func ContextLines(fileLines []string, line int) []string |
Returns the source lines surrounding a finding |
Usage Examples
import "github.com/github/gh-aw/pkg/scanfindings"
findings := []scanfindings.Finding{{
RuleID: "template-injection",
Severity: scanfindings.ParseSeverity("High"),
Message: scanfindings.FormatMessage("High", "template-injection", "template injection with untrusted input"),
File: ".github/workflows/demo.lock.yml",
Line: 12,
Column: 24,
}}
scanfindings.Sort(findings)
scanfindings.Render(os.Stderr, findings)
highCount := scanfindings.CountAtLeast(findings, scanfindings.SeverityHigh)
Dependencies
Internal:
pkg/console— console error formatting
External:
- None beyond the Go standard library.
This specification is automatically maintained by the spec-extractor workflow.
Documentation
¶
Overview ¶
Package scanfindings provides a shared representation of the findings reported by the scanner integrations (zizmor, poutine, grype, grant, runner-guard, yamllint, ...).
Each scanner speaks its own native JSON dialect, with severities spelled in a different vocabulary ("High", "error", "Negligible", "note", ...) and locations shaped differently. Integrations decode their native output into their own structs and then map those structs onto the shared Finding type declared here, so that severity classification, ordering and rendering are implemented once instead of once per tool.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContextLines ¶
ContextLines returns a symmetric window of up to two source lines before and after the 1-based line number. The window shrinks at file boundaries to keep the target line at its midpoint for context rendering. It returns nil when the line is out of range for the provided file lines.
func FormatMessage ¶
FormatMessage builds the standard "[severity] rule: description" message used by the scanner integrations. Empty parts are omitted.
Types ¶
type Finding ¶
type Finding struct {
RuleID string `json:"rule_id,omitempty"`
Severity SeverityLevel `json:"severity,omitempty"`
Message string `json:"message"`
File string `json:"file,omitempty"`
Line int `json:"line,omitempty"`
Column int `json:"column,omitempty"`
// Context holds the source lines surrounding the finding, used when
// rendering the finding to a terminal. It is optional.
Context []string `json:"-"`
}
Finding is the shared, tool-independent representation of a single scanner finding. Message holds the already-formatted, human readable description of the finding as produced by the owning integration.
func (Finding) CompilerError ¶
func (f Finding) CompilerError() console.CompilerError
CompilerError converts the finding into the console error format shared by all scanner output. Missing line and column values default to 1 so that the rendered position stays well formed.
type SeverityLevel ¶
type SeverityLevel string
SeverityLevel is the shared severity vocabulary used by every scanner integration. Native severity labels are normalized with ParseSeverity.
const ( // SeverityUnknown is used when a tool reports no severity, or one that // cannot be mapped onto the shared vocabulary. SeverityUnknown SeverityLevel = "unknown" // SeverityInfo covers informational findings ("info", "note", "notice"). SeverityInfo SeverityLevel = "info" // SeverityLow covers low impact findings ("low", "negligible", "minor"). SeverityLow SeverityLevel = "low" // SeverityMedium covers medium impact findings ("medium", "moderate", "warning"). SeverityMedium SeverityLevel = "medium" // SeverityHigh covers high impact findings ("high", "error"). SeverityHigh SeverityLevel = "high" // SeverityCritical covers the most severe findings ("critical"). SeverityCritical SeverityLevel = "critical" )
func ParseSeverity ¶
func ParseSeverity(raw string) SeverityLevel
ParseSeverity normalizes a native scanner severity label onto the shared vocabulary. Comparison is case-insensitive and unrecognized labels (including the empty string) map to SeverityUnknown.
func (SeverityLevel) AtLeast ¶
func (s SeverityLevel) AtLeast(min SeverityLevel) bool
AtLeast reports whether the severity is at least as severe as min.
func (SeverityLevel) ErrorType ¶
func (s SeverityLevel) ErrorType() string
ErrorType maps the severity onto the console error type used when rendering a finding as a console.CompilerError. Unknown severities are rendered as warnings so that unclassified findings remain visible.
func (SeverityLevel) Rank ¶
func (s SeverityLevel) Rank() int
Rank returns the relative ordering of a severity, with higher values meaning more severe. Unknown severities rank lowest.
func (SeverityLevel) String ¶
func (s SeverityLevel) String() string
String returns the canonical lowercase name of the severity.
Source Files