osv.go (9761B)
1 // Copyright 2023 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 // Package osv implements the Go OSV vulnerability format 6 // (https://go.dev/security/vuln/database#schema), which is a subset of 7 // the OSV shared vulnerability format 8 // (https://ossf.github.io/osv-schema), with database and 9 // ecosystem-specific meanings and fields. 10 // 11 // As this package is intended for use with the Go vulnerability 12 // database, only the subset of features which are used by that 13 // database are implemented (for instance, only the SEMVER affected 14 // range type is implemented). 15 package osv 16 17 import "time" 18 19 // RangeType specifies the type of version range being recorded and 20 // defines the interpretation of the RangeEvent object's Introduced 21 // and Fixed fields. 22 // 23 // In this implementation, only the "SEMVER" type is supported. 24 // 25 // See https://ossf.github.io/osv-schema/#affectedrangestype-field. 26 type RangeType string 27 28 // RangeTypeSemver indicates a semantic version as defined by 29 // SemVer 2.0.0, with no leading "v" prefix. 30 const RangeTypeSemver RangeType = "SEMVER" 31 32 // Ecosystem identifies the overall library ecosystem. 33 // In this implementation, only the "Go" ecosystem is supported. 34 type Ecosystem string 35 36 // GoEcosystem indicates the Go ecosystem. 37 const GoEcosystem Ecosystem = "Go" 38 39 // Pseudo-module paths used to describe vulnerabilities 40 // in the Go standard library and toolchain. 41 const ( 42 // GoStdModulePath is the pseudo-module path string used 43 // to describe vulnerabilities in the Go standard library. 44 GoStdModulePath = "stdlib" 45 // GoCmdModulePath is the pseudo-module path string used 46 // to describe vulnerabilities in the go command. 47 GoCmdModulePath = "toolchain" 48 ) 49 50 // Module identifies the Go module containing the vulnerability. 51 // Note that this field is called "package" in the OSV specification. 52 // 53 // See https://ossf.github.io/osv-schema/#affectedpackage-field. 54 type Module struct { 55 // The Go module path. Required. 56 // For the Go standard library, this is "stdlib". 57 // For the Go toolchain, this is "toolchain." 58 Path string `json:"name"` 59 // The ecosystem containing the module. Required. 60 // This should always be "Go". 61 Ecosystem Ecosystem `json:"ecosystem"` 62 } 63 64 // RangeEvent describes a single module version that either 65 // introduces or fixes a vulnerability. 66 // 67 // Exactly one of Introduced and Fixed must be present. Other range 68 // event types (e.g, "last_affected" and "limit") are not supported in 69 // this implementation. 70 // 71 // See https://ossf.github.io/osv-schema/#affectedrangesevents-fields. 72 type RangeEvent struct { 73 // Introduced is a version that introduces the vulnerability. 74 // A special value, "0", represents a version that sorts before 75 // any other version, and should be used to indicate that the 76 // vulnerability exists from the "beginning of time". 77 Introduced string `json:"introduced,omitempty"` 78 // Fixed is a version that fixes the vulnerability. 79 Fixed string `json:"fixed,omitempty"` 80 } 81 82 // Range describes the affected versions of the vulnerable module. 83 // 84 // See https://ossf.github.io/osv-schema/#affectedranges-field. 85 type Range struct { 86 // Type is the version type that should be used to interpret the 87 // versions in Events. Required. 88 // In this implementation, only the "SEMVER" type is supported. 89 Type RangeType `json:"type"` 90 // Events is a list of versions representing the ranges in which 91 // the module is vulnerable. Required. 92 // The events should be sorted, and MUST represent non-overlapping 93 // ranges. 94 // There must be at least one RangeEvent containing a value for 95 // Introduced. 96 // See https://ossf.github.io/osv-schema/#examples for examples. 97 Events []RangeEvent `json:"events"` 98 } 99 100 // ReferenceType is a reference (link) type. 101 type ReferenceType string 102 103 const ( 104 // ReferenceTypeAdvisory is a published security advisory for 105 // the vulnerability. 106 ReferenceTypeAdvisory = ReferenceType("ADVISORY") 107 // ReferenceTypeArticle is an article or blog post describing the vulnerability. 108 ReferenceTypeArticle = ReferenceType("ARTICLE") 109 // ReferenceTypeReport is a report, typically on a bug or issue tracker, of 110 // the vulnerability. 111 ReferenceTypeReport = ReferenceType("REPORT") 112 // ReferenceTypeFix is a source code browser link to the fix (e.g., a GitHub commit). 113 ReferenceTypeFix = ReferenceType("FIX") 114 // ReferenceTypePackage is a home web page for the package. 115 ReferenceTypePackage = ReferenceType("PACKAGE") 116 // ReferenceTypeEvidence is a demonstration of the validity of a vulnerability claim. 117 ReferenceTypeEvidence = ReferenceType("EVIDENCE") 118 // ReferenceTypeWeb is a web page of some unspecified kind. 119 ReferenceTypeWeb = ReferenceType("WEB") 120 ) 121 122 // Reference is a reference URL containing additional information, 123 // advisories, issue tracker entries, etc., about the vulnerability. 124 // 125 // See https://ossf.github.io/osv-schema/#references-field. 126 type Reference struct { 127 // The type of reference. Required. 128 Type ReferenceType `json:"type"` 129 // The fully-qualified URL of the reference. Required. 130 URL string `json:"url"` 131 } 132 133 // Affected gives details about a module affected by the vulnerability. 134 // 135 // See https://ossf.github.io/osv-schema/#affected-fields. 136 type Affected struct { 137 // The affected Go module. Required. 138 // Note that this field is called "package" in the OSV specification. 139 Module Module `json:"package"` 140 // The module version ranges affected by the vulnerability. 141 Ranges []Range `json:"ranges,omitempty"` 142 // Details on the affected packages and symbols within the module. 143 EcosystemSpecific EcosystemSpecific `json:"ecosystem_specific"` 144 } 145 146 // Package contains additional information about an affected package. 147 // This is an ecosystem-specific field for the Go ecosystem. 148 type Package struct { 149 // Path is the package import path. Required. 150 Path string `json:"path,omitempty"` 151 // GOOS is the execution operating system where the symbols appear, if 152 // known. 153 GOOS []string `json:"goos,omitempty"` 154 // GOARCH specifies the execution architecture where the symbols appear, if 155 // known. 156 GOARCH []string `json:"goarch,omitempty"` 157 // Symbols is a list of function and method names affected by 158 // this vulnerability. Methods are listed as <recv>.<method>. 159 // 160 // If included, only programs which use these symbols will be marked as 161 // vulnerable by `govulncheck`. If omitted, any program which imports this 162 // package will be marked vulnerable. 163 Symbols []string `json:"symbols,omitempty"` 164 } 165 166 // EcosystemSpecific contains additional information about the vulnerable 167 // module for the Go ecosystem. 168 // 169 // See https://go.dev/security/vuln/database#schema. 170 type EcosystemSpecific struct { 171 // Packages is the list of affected packages within the module. 172 Packages []Package `json:"imports,omitempty"` 173 } 174 175 // Entry represents a vulnerability in the Go OSV format, documented 176 // in https://go.dev/security/vuln/database#schema. 177 // It is a subset of the OSV schema (https://ossf.github.io/osv-schema). 178 // Only fields that are published in the Go Vulnerability Database 179 // are supported. 180 type Entry struct { 181 // SchemaVersion is the OSV schema version used to encode this 182 // vulnerability. 183 SchemaVersion string `json:"schema_version,omitempty"` 184 // ID is a unique identifier for the vulnerability. Required. 185 // The Go vulnerability database issues IDs of the form 186 // GO-<YEAR>-<ENTRYID>. 187 ID string `json:"id"` 188 // Modified is the time the entry was last modified. Required. 189 Modified time.Time `json:"modified,omitempty"` 190 // Published is the time the entry should be considered to have 191 // been published. 192 Published time.Time `json:"published,omitempty"` 193 // Withdrawn is the time the entry should be considered to have 194 // been withdrawn. If the field is missing, then the entry has 195 // not been withdrawn. 196 Withdrawn *time.Time `json:"withdrawn,omitempty"` 197 // Aliases is a list of IDs for the same vulnerability in other 198 // databases. 199 Aliases []string `json:"aliases,omitempty"` 200 // Summary gives a one-line, English textual summary of the vulnerability. 201 // It is recommended that this field be kept short, on the order of no more 202 // than 120 characters. 203 Summary string `json:"summary,omitempty"` 204 // Details contains additional English textual details about the vulnerability. 205 Details string `json:"details"` 206 // Affected contains information on the modules and versions 207 // affected by the vulnerability. 208 Affected []Affected `json:"affected"` 209 // References contains links to more information about the 210 // vulnerability. 211 References []Reference `json:"references,omitempty"` 212 // Credits contains credits to entities that helped find or fix the 213 // vulnerability. 214 Credits []Credit `json:"credits,omitempty"` 215 // DatabaseSpecific contains additional information about the 216 // vulnerability, specific to the Go vulnerability database. 217 DatabaseSpecific *DatabaseSpecific `json:"database_specific,omitempty"` 218 } 219 220 // Credit represents a credit for the discovery, confirmation, patch, or 221 // other event in the life cycle of a vulnerability. 222 // 223 // See https://ossf.github.io/osv-schema/#credits-fields. 224 type Credit struct { 225 // Name is the name, label, or other identifier of the individual or 226 // entity being credited. Required. 227 Name string `json:"name"` 228 } 229 230 // DatabaseSpecific contains additional information about the 231 // vulnerability, specific to the Go vulnerability database. 232 // 233 // See https://go.dev/security/vuln/database#schema. 234 type DatabaseSpecific struct { 235 // The URL of the Go advisory for this vulnerability, of the form 236 // "https://pkg.go.dev/GO-YYYY-XXXX". 237 URL string `json:"url,omitempty"` 238 // The review status of this report (UNREVIEWED or REVIEWED). 239 ReviewStatus ReviewStatus `json:"review_status,omitempty"` 240 }