internal/cveschema/cveschema.go - vulndb - Git at Google

 // Copyright 2021 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 // Package cveschema contains the schema for a CVE, as derived from
 // https://github.com/CVEProject/automation-working-group/tree/master/cve_json_schema.
 package cveschema

 import (
 	"bytes"
 	"encoding/json"
 	"errors"

 	"golang.org/x/vulndb/internal/derrors"
 )

 const (
 	// StateReserved is the initial state for a CVE Record; when the associated
 	// CVE ID is Reserved by a CNA.
 	StateReserved = "RESERVED"

 	// StatePublic is when a CNA populates the data associated with a CVE ID
 	// as a CVE Record, the state of the CVE Record is PUBLIC. The
 	// associated data must contain an identification number (CVE ID), a prose
 	// description, and at least one public reference.
 	StatePublic = "PUBLIC"

 	// StateRejected is when the CVE ID and associated CVE Record should no
 	// longer be used, the CVE Record is placed in the REJECT state. A Rejected
 	// CVE Record remains on the CVE List so that users can know when it is
 	// invalid.
 	StateRejected = "REJECT"
 )

 // 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.
 type CVE struct {
 	// Metadata is metadata 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.
 	Metadata `json:"CVE_data_meta"`

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

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

 	// Credit is the credit information (different than CVE_timeline in that
 	// these are specific things being credited to specific
 	// people/organizations/etc.).
 	Credit Credit `json:"-"`

 	// RawCredit is for unmarshaling only. Do not use.
 	RawCredit json.RawMessage `json:"credit"`
 }

 // Credit is the credit information (different than CVE_timeline in that these
 // are specific things being credited to specific people/organizations/etc.).
 type Credit struct {
 	Data CreditData `json:"credit_data"`
 }

 type CreditData struct {
 	Description Description `json:"description"`
 }

 // Metadata 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 Metadata struct {
 	Assigner string `json:"ASSIGNER"`
 	ID       string `json:"ID"`
 	State    string `json:"STATE"`
 }

 // 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 {
 	Data []LangString `json:"description_data"`
 }

 // 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 {
 	Data []ProblemTypeDataItem `json:"problemtype_data"`
 }

 // A ProblemTypeDataItem is an entry in ProblemType.Data.
 type ProblemTypeDataItem 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"`
 }

 // 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 {
 	Data []Reference `json:"reference_data"`
 }

 // 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 {
 	// Data 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.
 	Data []VendorDataItem `json:"vendor_data"`
 }

 // A VendorDataItem represents a single vendor name and product.
 type VendorDataItem struct {
 	Product    Product `json:"product"`
 	VendorName string  `json:"vendor_name"`
 }

 // 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 {
 	// Data 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.
 	Data []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 {
 	Data []VersionDataItem `json:"version_data"`
 }

 // A VersionDataItem 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 VersionDataItem struct {
 	VersionValue    string `json:"version_value"`
 	VersionAffected string `json:"version_affected"`
 }

 var nullBytes = []byte("null")

 // UnmarshalJSON implements json.Unmarshaler.
 func (c *CVE) UnmarshalJSON(data []byte) (err error) {
 	defer derrors.Wrap(&err, "cveschema.CVE.UnmarshalJSON")
 	if bytes.Equal(data, nullBytes) {
 		return nil
 	}
 	// To avoid infinite recursion, disable the UnmarshalJSON method on CVE
 	// by defining a new type.
 	type nomethod CVE
 	if err := json.Unmarshal(data, (*nomethod)(c)); err != nil {
 		return err
 	}
 	c.Credit, err = decodeCredit(c.RawCredit)
 	if err != nil {
 		return err
 	}
 	c.RawCredit = nil
 	return nil
 }

 // The Credit field can have one of several formats.
 func decodeCredit(raw []byte) (Credit, error) {
 	if len(raw) == 0 {
 		return Credit{}, nil
 	}

 	var c Credit
 	if err := json.Unmarshal(raw, &c); err == nil {
 		return c, nil
 	}

 	var lstrings []LangString
 	if err := json.Unmarshal(raw, &lstrings); err == nil {
 		return Credit{Data: CreditData{Description: Description{Data: lstrings}}}, nil
 	}

 	var strings []string
 	if err := json.Unmarshal(raw, &strings); err == nil {
 		var ls []LangString
 		for _, s := range strings {
 			ls = append(ls, LangString{Lang: "eng", Value: s})
 		}
 		return Credit{Data: CreditData{Description: Description{Data: ls}}}, nil
 	}

 	var str string
 	if err := json.Unmarshal(raw, &str); err == nil {
 		return Credit{
 			Data: CreditData{
 				Description: Description{
 					Data: []LangString{{Lang: "eng", Value: str}},
 				},
 			},
 		}, nil
 	}

 	return Credit{}, errors.New("could not parse credit field")
 }
	// Copyright 2021 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	// Package cveschema contains the schema for a CVE, as derived from
	// https://github.com/CVEProject/automation-working-group/tree/master/cve_json_schema.
	package cveschema

	import (
	"bytes"
	"encoding/json"
	"errors"

	"golang.org/x/vulndb/internal/derrors"
	)

	const (
	// StateReserved is the initial state for a CVE Record; when the associated
	// CVE ID is Reserved by a CNA.
	StateReserved = "RESERVED"

	// StatePublic is when a CNA populates the data associated with a CVE ID
	// as a CVE Record, the state of the CVE Record is PUBLIC. The
	// associated data must contain an identification number (CVE ID), a prose
	// description, and at least one public reference.
	StatePublic = "PUBLIC"

	// StateRejected is when the CVE ID and associated CVE Record should no
	// longer be used, the CVE Record is placed in the REJECT state. A Rejected
	// CVE Record remains on the CVE List so that users can know when it is
	// invalid.
	StateRejected = "REJECT"
	)

	// 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.
	type CVE struct {
	// Metadata is metadata 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.
	Metadata `json:"CVE_data_meta"`

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

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

	// Credit is the credit information (different than CVE_timeline in that
	// these are specific things being credited to specific
	// people/organizations/etc.).
	Credit Credit `json:"-"`

	// RawCredit is for unmarshaling only. Do not use.
	RawCredit json.RawMessage `json:"credit"`
	}

	// Credit is the credit information (different than CVE_timeline in that these
	// are specific things being credited to specific people/organizations/etc.).
	type Credit struct {
	Data CreditData `json:"credit_data"`
	}

	type CreditData struct {
	Description Description `json:"description"`
	}

	// Metadata 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 Metadata struct {
	Assigner string `json:"ASSIGNER"`
	ID string `json:"ID"`
	State string `json:"STATE"`
	}

	// 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 {
	Data []LangString `json:"description_data"`
	}

	// 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 {
	Data []ProblemTypeDataItem `json:"problemtype_data"`
	}

	// A ProblemTypeDataItem is an entry in ProblemType.Data.
	type ProblemTypeDataItem 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"`
	}

	// 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 {
	Data []Reference `json:"reference_data"`
	}

	// 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 {
	// Data 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.
	Data []VendorDataItem `json:"vendor_data"`
	}

	// A VendorDataItem represents a single vendor name and product.
	type VendorDataItem struct {
	Product Product `json:"product"`
	VendorName string `json:"vendor_name"`
	}

	// 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 {
	// Data 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.
	Data []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 {
	Data []VersionDataItem `json:"version_data"`
	}

	// A VersionDataItem 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 VersionDataItem struct {
	VersionValue string `json:"version_value"`
	VersionAffected string `json:"version_affected"`
	}

	var nullBytes = []byte("null")

	// UnmarshalJSON implements json.Unmarshaler.
	func (c *CVE) UnmarshalJSON(data []byte) (err error) {
	defer derrors.Wrap(&err, "cveschema.CVE.UnmarshalJSON")
	if bytes.Equal(data, nullBytes) {
	return nil
	}
	// To avoid infinite recursion, disable the UnmarshalJSON method on CVE
	// by defining a new type.
	type nomethod CVE
	if err := json.Unmarshal(data, (*nomethod)(c)); err != nil {
	return err
	}
	c.Credit, err = decodeCredit(c.RawCredit)
	if err != nil {
	return err
	}
	c.RawCredit = nil
	return nil
	}

	// The Credit field can have one of several formats.
	func decodeCredit(raw []byte) (Credit, error) {
	if len(raw) == 0 {
	return Credit{}, nil
	}

	var c Credit
	if err := json.Unmarshal(raw, &c); err == nil {
	return c, nil
	}

	var lstrings []LangString
	if err := json.Unmarshal(raw, &lstrings); err == nil {
	return Credit{Data: CreditData{Description: Description{Data: lstrings}}}, nil
	}

	var strings []string
	if err := json.Unmarshal(raw, &strings); err == nil {
	var ls []LangString
	for _, s := range strings {
	ls = append(ls, LangString{Lang: "eng", Value: s})
	}
	return Credit{Data: CreditData{Description: Description{Data: ls}}}, nil
	}

	var str string
	if err := json.Unmarshal(raw, &str); err == nil {
	return Credit{
	Data: CreditData{
	Description: Description{
	Data: []LangString{{Lang: "eng", Value: str}},
	},
	},
	}, nil
	}

	return Credit{}, errors.New("could not parse credit field")
	}