v1.0.4 Latest Latest

This package is not in the latest version of its module.

Go to latest
Published: Feb 6, 2024 License: BSD-3-Clause Imports: 4 Imported by: 0



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.



View Source
const (
	ScanLevelModule  = "module"
	ScanLevelPackage = "package"
	ScanLevelSymbol  = "symbol"
View Source
const (
	// ProtocolVersion is the current protocol version this file implements
	ProtocolVersion = "v1.0.0"


This section is empty.


func HandleJSON

func HandleJSON(from io.Reader, to Handler) error

HandleJSON reads the json from the supplied stream and hands the decoded output to the handler.


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,
	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"`

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.
	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

func NewJSONHandler(w io.Writer) Handler

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

func (l ScanLevel) WantPackages() bool

WantPackages can be used to check whether the scan level is one that is able to generate package

func (ScanLevel) WantSymbols added in v0.2.0

func (l ScanLevel) WantSymbols() bool

WantSymbols can be used to check whether the scan level is one that is able to generate symbols called findings.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL