Documentation
¶
Overview ¶
Package govulncheck contains the JSON output structs for govulncheck.
govulncheck supports streaming JSON by emitting a series of Message objects as it analyzes user code and discovers vulnerabilities. Streaming JSON is useful for displaying progress in real-time for large projects where govulncheck execution might take some time.
govulncheck JSON emits configuration used to perform the analysis, a user-friendly message about what is being analyzed, and the vulnerability findings. Findings for the same vulnerability can can be emitted several times. For instance, govulncheck JSON will emit a finding when it sees that a vulnerable module is required before proceeding to check if the vulnerability is imported or called. Please see documentation on Message and related types for precise details on the stream encoding.
There are no guarantees on the order of messages. The pattern of emitted messages can change in the future. Clients can follow code in handler.go for consuming the streaming JSON programmatically.
Index ¶
Constants ¶
const ( ScanLevelModule = "module" ScanLevelPackage = "package" ScanLevelSymbol = "symbol" )
const ( ScanModeSource = "source" ScanModeBinary = "binary" ScanModeConvert = "convert" ScanModeQuery = "query" ScanModeExtract = "extract" // currently, only binary extraction is supported )
const (
// ProtocolVersion is the current protocol version this file implements
ProtocolVersion = "v1.0.0"
)
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// ProtocolVersion specifies the version of the JSON protocol.
ProtocolVersion string `json:"protocol_version"`
// ScannerName is the name of the tool, for example, govulncheck.
//
// We expect this JSON format to be used by other tools that wrap
// govulncheck, which will have a different name.
ScannerName string `json:"scanner_name,omitempty"`
// ScannerVersion is the version of the tool.
ScannerVersion string `json:"scanner_version,omitempty"`
// DB is the database used by the tool, for example,
// vuln.go.dev.
DB string `json:"db,omitempty"`
// LastModified is the last modified time of the data source.
DBLastModified *time.Time `json:"db_last_modified,omitempty"`
// GoVersion is the version of Go used for analyzing standard library
// vulnerabilities.
GoVersion string `json:"go_version,omitempty"`
// ScanLevel instructs govulncheck to analyze at a specific level of detail.
// Valid values include module, package and symbol.
ScanLevel ScanLevel `json:"scan_level,omitempty"`
// ScanMode instructs govulncheck how to interpret the input and
// what to do with it. Valid values are source, binary, query,
// and extract.
ScanMode ScanMode `json:"scan_mode,omitempty"`
}
Config must occur as the first message of a stream and informs the client about the information used to generate the findings. The only required field is the protocol version.
type Finding ¶ added in v0.2.0
type Finding struct {
// OSV is the id of the detected vulnerability.
OSV string `json:"osv,omitempty"`
// FixedVersion is the module version where the vulnerability was
// fixed. This is empty if a fix is not available.
//
// If there are multiple fixed versions in the OSV report, this will
// be the fixed version in the latest range event for the OSV report.
//
// For example, if the range events are
// {introduced: 0, fixed: 1.0.0} and {introduced: 1.1.0}, the fixed version
// will be empty.
//
// For the stdlib, we will show the fixed version closest to the
// Go version that is used. For example, if a fix is available in 1.17.5 and
// 1.18.5, and the GOVERSION is 1.17.3, 1.17.5 will be returned as the
// fixed version.
FixedVersion string `json:"fixed_version,omitempty"`
// Trace contains an entry for each frame in the trace.
//
// Frames are sorted starting from the imported vulnerable symbol
// until the entry point. The first frame in Frames should match
// Symbol.
//
// In binary mode, trace will contain a single-frame with no position
// information.
//
// For module level source findings, the trace will contain a single-frame
// with no symbol, position, or package information. For package level source
// findings, the trace will contain a single-frame with no symbol or position
// information.
Trace []*Frame `json:"trace,omitempty"`
}
Finding contains information on a discovered vulnerability. Each vulnerability will likely have multiple findings in JSON mode. This is because govulncheck emits findings as it does work, and therefore could emit one module level, one package level, and potentially multiple symbol level findings depending on scan level. Multiple symbol level findings can be emitted when multiple symbols of the same vuln are called or govulncheck decides to show multiple traces for the same symbol.
type Frame ¶ added in v0.2.0
type Frame struct {
// Module is the module path of the module containing this symbol.
//
// Importable packages in the standard library will have the path "stdlib".
Module string `json:"module"`
// Version is the module version from the build graph.
Version string `json:"version,omitempty"`
// Package is the import path.
Package string `json:"package,omitempty"`
// Function is the function name.
Function string `json:"function,omitempty"`
// Receiver is the receiver type if the called symbol is a method.
//
// The client can create the final symbol name by
// prepending Receiver to FuncName.
Receiver string `json:"receiver,omitempty"`
// Position describes an arbitrary source position
// including the file, line, and column location.
// A Position is valid if the line number is > 0.
//
// The filenames are relative to the directory of
// the enclosing module and always use "/" for
// portability.
Position *Position `json:"position,omitempty"`
}
Frame represents an entry in a finding trace.
type Handler ¶
type Handler interface {
// Config communicates introductory message to the user.
Config(config *Config) error
// Progress is called to display a progress message.
Progress(progress *Progress) error
// OSV is invoked for each osv Entry in the stream.
OSV(entry *osv.Entry) error
// Finding is called for each vulnerability finding in the stream.
Finding(finding *Finding) error
}
Handler handles messages to be presented in a vulnerability scan output stream.
func NewJSONHandler ¶
NewJSONHandler returns a handler that writes govulncheck output as json.
type Message ¶
type Message struct {
Config *Config `json:"config,omitempty"`
Progress *Progress `json:"progress,omitempty"`
OSV *osv.Entry `json:"osv,omitempty"`
Finding *Finding `json:"finding,omitempty"`
}
Message is an entry in the output stream. It will always have exactly one field filled in.
type Position ¶
type Position struct {
Filename string `json:"filename,omitempty"` // filename, if any
Offset int `json:"offset"` // byte offset, starting at 0
Line int `json:"line"` // line number, starting at 1
Column int `json:"column"` // column number, starting at 1 (byte count)
}
Position represents arbitrary source position.
type Progress ¶
type Progress struct {
// A time stamp for the message.
Timestamp *time.Time `json:"time,omitempty"`
// Message is the progress message.
Message string `json:"message,omitempty"`
}
Progress messages are informational only, intended to allow users to monitor the progress of a long running scan. A stream must remain fully valid and able to be interpreted with all progress messages removed.
type ScanLevel ¶ added in v0.2.0
type ScanLevel string
ScanLevel represents the detail level at which a scan occurred. This can be necessary to correctly interpret the findings, for instance if a scan is at symbol level and a finding does not have a symbol it means the vulnerability was imported but not called. If the scan however was at "package" level, that determination cannot be made.
func (ScanLevel) WantPackages ¶ added in v1.0.2
WantPackages can be used to check whether the scan level is one that is able to generate package-level findings.
func (ScanLevel) WantSymbols ¶ added in v0.2.0
WantSymbols can be used to check whether the scan level is one that is able to generate symbol-level findings.
type ScanMode ¶ added in v1.1.0
type ScanMode string
ScanMode represents the mode in which a scan occurred. This can be necessary to correctly to interpret findings. For instance, a binary can be checked for vulnerabilities or the user just wants to extract minimal data necessary for the vulnerability check.
Source Files