govulncheck

package
v0.2.5 Latest Latest
Warning

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

 Go to latest Published: Aug 21, 2025 License: MIT Imports: 9 Imported by: 0

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.

Package osv implements the Go OSV vulnerability format (https://go.dev/security/vuln/database#schema), which is a subset of the OSV shared vulnerability format (https://ossf.github.io/osv-schema), with database and ecosystem-specific meanings and fields.

As this package is intended for use with the Go vulnerability database, only the subset of features which are used by that database are implemented (for instance, only the SEMVER affected range type is implemented).

Index

Constants

View Source 
const (
	ScanLevelModule  = "module"
	ScanLevelPackage = "package"
	ScanLevelSymbol  = "symbol"
)
View Source 
const (
	ScanModeSource  = "source"
	ScanModeBinary  = "binary"
	ScanModeConvert = "convert"
	ScanModeQuery   = "query"
	ScanModeExtract = "extract" // currently, only binary extraction is supported
)
View Source 
const (
	// GoStdModulePath is the pseudo-module path string used
	// to describe vulnerabilities in the Go standard library.
	GoStdModulePath = "stdlib"
	// GoCmdModulePath is the pseudo-module path string used
	// to describe vulnerabilities in the go command.
	GoCmdModulePath = "toolchain"
)

Pseudo-module paths used to describe vulnerabilities in the Go standard library and toolchain.

View Source 
const (
	// ReferenceTypeAdvisory is a published security advisory for
	// the vulnerability.
	ReferenceTypeAdvisory = ReferenceType("ADVISORY")
	// ReferenceTypeArticle is an article or blog post describing the vulnerability.
	ReferenceTypeArticle = ReferenceType("ARTICLE")
	// ReferenceTypeReport is a report, typically on a bug or issue tracker, of
	// the vulnerability.
	ReferenceTypeReport = ReferenceType("REPORT")
	// ReferenceTypeFix is a source code browser link to the fix (e.g., a GitHub commit).
	ReferenceTypeFix = ReferenceType("FIX")
	// ReferenceTypePackage is a home web page for the package.
	ReferenceTypePackage = ReferenceType("PACKAGE")
	// ReferenceTypeEvidence is a demonstration of the validity of a vulnerability claim.
	ReferenceTypeEvidence = ReferenceType("EVIDENCE")
	// ReferenceTypeWeb is a web page of some unspecified kind.
	ReferenceTypeWeb = ReferenceType("WEB")
)
View Source 
const (
	// ProtocolVersion is the current protocol version this file implements
	ProtocolVersion = "v1.0.0"
)

Variables

This section is empty.

Functions

func ReviewStatusValues 

func ReviewStatusValues() []string

Types

type Affected 

type Affected struct {
	// The affected Go module. Required.
	// Note that this field is called "package" in the OSV specification.
	Module Module `json:"package"`
	// The module version ranges affected by the vulnerability.
	Ranges []Range `json:"ranges,omitempty"`
	// Details on the affected packages and symbols within the module.
	EcosystemSpecific EcosystemSpecific `json:"ecosystem_specific"`
}

Affected gives details about a module affected by the vulnerability.

See https://ossf.github.io/osv-schema/#affected-fields.

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 Credit 

type Credit struct {
	// Name is the name, label, or other identifier of the individual or
	// entity being credited. Required.
	Name string `json:"name"`
}

Credit represents a credit for the discovery, confirmation, patch, or other event in the life cycle of a vulnerability.

See https://ossf.github.io/osv-schema/#credits-fields.

type DatabaseSpecific 

type DatabaseSpecific struct {
	// The URL of the Go advisory for this vulnerability, of the form
	// "https://pkg.go.dev/GO-YYYY-XXXX".
	URL string `json:"url,omitempty"`
	// The review status of this report (UNREVIEWED or REVIEWED).
	ReviewStatus ReviewStatus `json:"review_status,omitempty"`
}

DatabaseSpecific contains additional information about the vulnerability, specific to the Go vulnerability database.

See https://go.dev/security/vuln/database#schema.

type Ecosystem 

type Ecosystem string

Ecosystem identifies the overall library ecosystem. In this implementation, only the "Go" ecosystem is supported. 

const GoEcosystem Ecosystem = "Go"

GoEcosystem indicates the Go ecosystem.

type EcosystemSpecific 

type EcosystemSpecific struct {
	// Packages is the list of affected packages within the module.
	Packages []Package `json:"imports,omitempty"`
}

EcosystemSpecific contains additional information about the vulnerable module for the Go ecosystem.

See https://go.dev/security/vuln/database#schema.

type Entry 

type Entry struct {
	// SchemaVersion is the OSV schema version used to encode this
	// vulnerability.
	SchemaVersion string `json:"schema_version,omitempty"`
	// ID is a unique identifier for the vulnerability. Required.
	// The Go vulnerability database issues IDs of the form
	// GO-<YEAR>-<ENTRYID>.
	ID string `json:"id"`
	// Modified is the time the entry was last modified. Required.
	Modified time.Time `json:"modified,omitempty"`
	// Published is the time the entry should be considered to have
	// been published.
	Published time.Time `json:"published,omitempty"`
	// Withdrawn is the time the entry should be considered to have
	// been withdrawn. If the field is missing, then the entry has
	// not been withdrawn.
	Withdrawn *time.Time `json:"withdrawn,omitempty"`
	// Aliases is a list of IDs for the same vulnerability in other
	// databases.
	Aliases []string `json:"aliases,omitempty"`
	// Summary gives a one-line, English textual summary of the vulnerability.
	// It is recommended that this field be kept short, on the order of no more
	// than 120 characters.
	Summary string `json:"summary,omitempty"`
	// Details contains additional English textual details about the vulnerability.
	Details string `json:"details"`
	// Affected contains information on the modules and versions
	// affected by the vulnerability.
	Affected []Affected `json:"affected"`
	// References contains links to more information about the
	// vulnerability.
	References []Reference `json:"references,omitempty"`
	// Credits contains credits to entities that helped find or fix the
	// vulnerability.
	Credits []Credit `json:"credits,omitempty"`
	// DatabaseSpecific contains additional information about the
	// vulnerability, specific to the Go vulnerability database.
	DatabaseSpecific *DatabaseSpecific `json:"database_specific,omitempty"`
}

Entry represents a vulnerability in the Go OSV format, documented in https://go.dev/security/vuln/database#schema. It is a subset of the OSV schema (https://ossf.github.io/osv-schema). Only fields that are published in the Go Vulnerability Database are supported.

type Finding 

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 

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 Message 

type Message struct {
	Config   *Config   `json:"config,omitempty"`
	Progress *Progress `json:"progress,omitempty"`
	SBOM     *SBOM     `json:"SBOM,omitempty"`
	// OSV is emitted for every vulnerability in the current database
	// that applies to user modules regardless of their version. If a
	// module is being used at a vulnerable version, the corresponding
	// OSV will be referenced in Findings depending on the type of usage
	// and the desired scan level.
	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 Module 

type Module struct {
	// The full module path.
	Path string `json:"path,omitempty"`

	// The version of the module.
	Version string `json:"version,omitempty"`
}

type OSVModule 

type OSVModule struct {
	// The Go module path. Required.
	// For the Go standard library, this is "stdlib".
	// For the Go toolchain, this is "toolchain."
	Path string `json:"name"`
	// The ecosystem containing the module. Required.
	// This should always be "Go".
	Ecosystem Ecosystem `json:"ecosystem"`
}

Module identifies the Go module containing the vulnerability. Note that this field is called "package" in the OSV specification.

See https://ossf.github.io/osv-schema/#affectedpackage-field.

type Package 

type Package struct {
	// Path is the package import path. Required.
	Path string `json:"path,omitempty"`
	// GOOS is the execution operating system where the symbols appear, if
	// known.
	GOOS []string `json:"goos,omitempty"`
	// GOARCH specifies the execution architecture where the symbols appear, if
	// known.
	GOARCH []string `json:"goarch,omitempty"`
	// Symbols is a list of function and method names affected by
	// this vulnerability. Methods are listed as <recv>.<method>.
	//
	// If included, only programs which use these symbols will be marked as
	// vulnerable by `govulncheck`. If omitted, any program which imports this
	// package will be marked vulnerable.
	Symbols []string `json:"symbols,omitempty"`
}

Package contains additional information about an affected package. This is an ecosystem-specific field for the Go ecosystem.

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 Range 

type Range struct {
	// Type is the version type that should be used to interpret the
	// versions in Events. Required.
	// In this implementation, only the "SEMVER" type is supported.
	Type RangeType `json:"type"`
	// Events is a list of versions representing the ranges in which
	// the module is vulnerable. Required.
	// The events should be sorted, and MUST represent non-overlapping
	// ranges.
	// There must be at least one RangeEvent containing a value for
	// Introduced.
	// See https://ossf.github.io/osv-schema/#examples for examples.
	Events []RangeEvent `json:"events"`
}

Range describes the affected versions of the vulnerable module.

See https://ossf.github.io/osv-schema/#affectedranges-field.

type RangeEvent 

type RangeEvent struct {
	// Introduced is a version that introduces the vulnerability.
	// A special value, "0", represents a version that sorts before
	// any other version, and should be used to indicate that the
	// vulnerability exists from the "beginning of time".
	Introduced string `json:"introduced,omitempty"`
	// Fixed is a version that fixes the vulnerability.
	Fixed string `json:"fixed,omitempty"`
}

RangeEvent describes a single module version that either introduces or fixes a vulnerability.

Exactly one of Introduced and Fixed must be present. Other range event types (e.g, "last_affected" and "limit") are not supported in this implementation.

See https://ossf.github.io/osv-schema/#affectedrangesevents-fields.

type RangeType 

type RangeType string

RangeType specifies the type of version range being recorded and defines the interpretation of the RangeEvent object's Introduced and Fixed fields.

In this implementation, only the "SEMVER" type is supported.

See https://ossf.github.io/osv-schema/#affectedrangestype-field. 

const RangeTypeSemver RangeType = "SEMVER"

RangeTypeSemver indicates a semantic version as defined by SemVer 2.0.0, with no leading "v" prefix.

type Reference 

type Reference struct {
	// The type of reference. Required.
	Type ReferenceType `json:"type"`
	// The fully-qualified URL of the reference. Required.
	URL string `json:"url"`
}

Reference is a reference URL containing additional information, advisories, issue tracker entries, etc., about the vulnerability.

See https://ossf.github.io/osv-schema/#references-field.

type ReferenceType 

type ReferenceType string

ReferenceType is a reference (link) type.

type ReviewStatus 

type ReviewStatus int
const (
	ReviewStatusUnknown ReviewStatus = iota
	ReviewStatusUnreviewed
	ReviewStatusReviewed
)

func ToReviewStatus 

func ToReviewStatus(s string) (ReviewStatus, bool)

func (ReviewStatus) IsValid 

func (r ReviewStatus) IsValid() bool

func (ReviewStatus) MarshalJSON 

func (r ReviewStatus) MarshalJSON() ([]byte, error)

func (ReviewStatus) String 

func (r ReviewStatus) String() string

func (*ReviewStatus) UnmarshalJSON 

func (r *ReviewStatus) UnmarshalJSON(b []byte) error

type SBOM 

type SBOM struct {
	// The go version used by govulncheck when scanning, which also defines
	// the version of the standard library used for detecting vulns.
	GoVersion string `json:"go_version,omitempty"`

	// The set of modules included in the scan.
	Modules []*Module `json:"modules,omitempty"`

	// The roots of the scan, as package paths.
	// For binaries, this will be the main package.
	// For source code, this will be the packages matching the provided package patterns.
	Roots []string `json:"roots,omitempty"`
}

SBOM contains minimal information about the artifacts govulncheck is scanning.

type ScanLevel 

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 

func (l ScanLevel) WantPackages() bool

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

func (ScanLevel) WantSymbols 

func (l ScanLevel) WantSymbols() bool

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

type ScanMode 

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.

type Vunerability 

type Vunerability struct {
	Description  string
	URL          string
	Module       string
	Version      string
	FixedVersion string
	Examples     []string
}

func GetVunerabilities 

func GetVunerabilities() ([]Vunerability, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.