internal: document structs in cve.go
Also rearrange the file in order of struct hierachy.
Change-Id: If2d05f2bbc9f6d5a267be7a15780f5a0c4597033
Reviewed-on: https://go-review.googlesource.com/c/vulndb/+/355194
Trust: Julie Qiu <julie@golang.org>
Run-TryBot: Julie Qiu <julie@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Roland Shoemaker <roland@golang.org>
diff --git a/internal/cve.go b/internal/cve.go
index 54cab41..da22b33 100644
--- a/internal/cve.go
+++ b/internal/cve.go
@@ -2,91 +2,200 @@
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
+// Package internal contains functionality for interacting with x/vulndb.
package internal
-// Affects
-type Affects struct {
- Vendor Vendor `json:"vendor"`
+// CVE represents a "Common Vulnerabilities and Exposures" record, which is
+// associated with a CVE ID and provided by a CNA.
+//
+// A CVE corresponds to a flaw in a software, firmware, hardware, or service
+// component resulting from a weakness that can be exploited, causing a negative
+// impact to the confidentiality, integrity, or availability of an impacted
+// component or components.
+//
+// This schema is derived from
+// https://github.com/CVEProject/automation-working-group/tree/master/cve_json_schema.
+type CVE struct {
+ // DataType identifies what kind of data is held in this JSON file. This is
+ // mandatory and designed to prevent problems with attempting to detect
+ // what kind of file this is. Valid values for this string are CVE, CNA,
+ // CVEMENTOR.
+ DataType string `json:"data_type"`
+
+ // DataFormat identifies what data format is used in this JSON file. This
+ // is mandatory and designed to prevent problems with attempting to detect
+ // what format of data is used. Valid values for this string are MITRE, it can
+ // also be user defined (e.g. for internal use).
+ DataFormat string `json:"data_format"`
+
+ // DataVersion identifies which version of the data format is in use. This
+ // is mandatory and designed to prevent problems with attempting to detect
+ // what format of data is used.
+ DataVersion string `json:"data_version"`
+
+ // CVEDataMeta is meta data about the CVE ID such as the CVE ID, who
+ // requested it, who assigned it, when it was requested, when it was assigned,
+ // the current state (PUBLIC, REJECT, etc.) and so on.
+ CVEDataMeta CVEDataMeta `json:"CVE_data_meta"`
+
+ // Affects is the root level container for affected vendors and in turn
+ // their affected technologies, products, hardware, etc. It only goes in
+ // the root level.
+ Affects Affects `json:"affects"`
+
+ // Description is a description of the issue. It can exist in the root
+ // level or within virtually any other container, the intent being that for
+ // example different products, and configurations may result in different
+ // impacts and thus descriptions of the issue.
+ Description Description `json:"description"`
+
+ // ProblemType is problem type information (e.g. CWE identifier).
+ Problemtype Problemtype `json:"problemtype"`
+
+ // References is reference data in the form of URLs or file objects
+ // (uuencoded and embedded within the JSON file, exact format to be
+ // decided, e.g. we may require a compressed format so the objects require
+ // unpacking before they are "dangerous").
+ References References `json:"references"`
}
-// CVEDataMeta
+// CVEDataMeta is meta data about the CVE ID such as the CVE ID, who requested
+// it, who assigned it, when it was requested, when it was assigned, the
+// current state (PUBLIC, REJECT, etc.) and so on.
type CVEDataMeta struct {
ASSIGNER string `json:"ASSIGNER"`
ID string `json:"ID"`
STATE string `json:"STATE"`
}
-// Description
+// Affects is the root level container for affected vendors and in turn their
+// affected technologies, products, hardware, etc. It only goes in the root
+// level.
+type Affects struct {
+ Vendor Vendor `json:"vendor"`
+}
+
+// Description is a description of the issue. It can exist in the root level or
+// within virtually any other container, the intent being that for example
+// different products, and configurations may result in different impacts and
+// thus descriptions of the issue.
+//
+// The description could include:
+//
+// An explanation of an attack type using the vulnerability;
+// The impact of the vulnerability;
+// The software components within a software product that are affected by the
+// vulnerability; and
+// Any attack vectors that can make use of the vulnerability.
+//
+// Descriptions often follow this template:
+//
+// [PROBLEM TYPE] in [PRODUCT/VERSION] causes [IMPACT] when [ATTACK]
+//
+// where impact and attack are arbitrary terms that should be relevant to the
+// nature of the vulnerability.
type Description struct {
DescriptionData []LangString `json:"description_data"`
}
-// LangString
+// ProblemType is problem type information (e.g. CWE identifier).
+//
+// It can include an arbitrary summary of the problem, though Common Weakness
+// Enumerations (CWEs) are a standard to use in this field.
+type Problemtype struct {
+ ProblemtypeData []ProblemtypeDataItems `json:"problemtype_data"`
+}
+
+// ProblemtypeDataItems are the entries in a ProblemType.
+type ProblemtypeDataItems struct {
+ Description []LangString `json:"description"`
+}
+
+// LangString is a JSON data type containing the language that a description is
+// written in and the text string.
type LangString struct {
Lang string `json:"lang"`
Value string `json:"value"`
}
-// Problemtype
-type Problemtype struct {
- ProblemtypeData []ProblemtypeDataItems `json:"problemtype_data"`
-}
-
-// ProblemtypeDataItems
-type ProblemtypeDataItems struct {
- Description []LangString `json:"description"`
-}
-
-type VersionData struct {
- VersionData []VersionDataItems `json:"version_data"`
-}
-
-type ProductDataItem struct {
- ProductName string `json:"product_name"`
- Version VersionData `json:"version"`
-}
-
-// Product
-type Product struct {
- ProductData []ProductDataItem `json:"product_data"`
-}
-
-// Reference
-type Reference struct {
- URL string `json:"url"`
-}
-
-// References
+// References is reference data in the form of URLs or file objects (uuencoded
+// and embedded within the JSON file, exact format to be decided, e.g. we may
+// require a compressed format so the objects require unpacking before they are
+// "dangerous").
type References struct {
ReferenceData []Reference `json:"reference_data"`
}
-// Vendor
+// A reference is a URL pointing to a world-wide-web-based resource. For
+// CSV and flat-file formats, they should be separated by a space. References
+// should point to content that is relevant to the vulnerability and include at
+// least all the details included in the CVE entry. Ideally, references should
+// point to content that includes the CVE ID itself whenever possible. References
+// must also be publicly available, as described in Section 2.1.1 of the CVE
+// Numbering Authorities (CNA) Rules.
+type Reference struct {
+ URL string `json:"url"`
+}
+
+// Vendor is the container for affected vendors, it only goes in the affects
+// container.
type Vendor struct {
+ // VendorData is an array of version values (vulnerable and not); we use an
+ // array so that different entities can make statements about the same
+ // vendor and they are separate (if we used a JSON object we'd essentially
+ // be keying on the vendor name and they would have to overlap). Also this
+ // allows things like data_version or description to be applied directly to
+ // the vendor entry.
VendorData []VendorDataItems `json:"vendor_data"`
}
-// VendorDataItems
+// VendorDataItems represents a single vendor name and product.
type VendorDataItems struct {
Product Product `json:"product"`
VendorName string `json:"vendor_name"`
}
-// VersionDataItems
+// Product is the container for affected technologies, products, hardware, etc.
+//
+// As a general guideline, the product should include the vendor, developer, or
+// project name as well as the name of the actual software or hardware in which
+// the vulnerability exists.
+type Product struct {
+ // ProductData is an array of version values (vulnerable and not); we use
+ // an array so that we can make multiple statements about the same product and
+ // they are separate (if we used a JSON object we'd essentially be keying on
+ // the product name and they would have to overlap). Also this allows things
+ // like data_version or description to be applied directly to the product
+ // entry.
+ ProductData []ProductDataItem `json:"product_data"`
+}
+
+// ProductDataItem represents a single product name and version that belongs to
+// a product container.
+type ProductDataItem struct {
+ ProductName string `json:"product_name"`
+ Version VersionData `json:"version"`
+}
+
+// VersionData is an array of version values (vulnerable and not); we use an
+// array so that we can make multiple statements about the same version and they
+// are separate (if we used a JSON object we'd essentially be keying on the
+// version name/number and they would have to overlap). Also this allows things
+// like data_version or description to be applied directly to the product entry.
+// This also allows more complex statements such as "Product X between versions
+// 10.2 and 10.8" to be put in a machine-readable format. As well since multiple
+// statements can be used multiple branches of the same product can be defined
+// here.
+type VersionData struct {
+ VersionData []VersionDataItems `json:"version_data"`
+}
+
+// VersionDataItems represents a version, the date of release, or whatever
+// indicator that is used by vendors, developers, or projects to differentiate
+// between releases. The version can be described with specific version
+// numbers, ranges of versions, or “all versions before/after” a version number or
+// date.
type VersionDataItems struct {
VersionValue string `json:"version_value"`
VersionAffected string `json:"version_affected"`
}
-
-// CVE
-type CVE struct {
- DataType string `json:"data_type"`
- DataFormat string `json:"data_format"`
- DataVersion string `json:"data_version"`
- CVEDataMeta CVEDataMeta `json:"CVE_data_meta"`
-
- Affects Affects `json:"affects"`
- Description Description `json:"description"`
- Problemtype Problemtype `json:"problemtype"`
- References References `json:"references"`
-}
