Documentation ¶
Overview ¶
Package vulnrep implements an API for working with vulnerability documents. Specifically, it implements the Common Vulnerability Reporting Format (CVRF) which uses XML serialization, and the Common Security Advisory Framework (CSAF) which uses JSON serialization. The home page for the OASIS Common Security Advisory Framework Technical Committee (https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=csaf) has more information about these standards, including schema documents to work with these standards.
There is a separate command-line conversion tool (cmd/vulnrepconv in the same repository) that invokes the API to convert documents between these two formats.
Validation ¶
This package does not rely on available schemas to perform validation of documents, but rather explicitly implements the checks in code. This is done this way in part because JSON schema does not support the notion of "key" and keyref that XML Schema supports. Therefore, for complete validation this code needs to implement validation with code.
When a Report has only compliance issues on load or save, the caller API can check for the specific *ComplianceErr type, and introspect the contents of that error.
Note that different target formats have different validation criteria. For example, the CVSS scoring vector is not required in the XML format, but due to the use of CVSS JSON schema, the CVSS vector is required.
Parsing and Serialization ¶
Documents are scanned for errors both when read and written. This implementation does not try to be clever about handling large documents, but rather assumes that vulnerability reports will not be excessively large.
Index ¶
- type Acknowledgment
- type AggregateSeverity
- type Branch
- type BranchType
- type CVSSScore
- type CWE
- type ConformanceErr
- type DocStatus
- type Generator
- type Group
- type GroupID
- type Involvement
- type InvolvementStatusType
- type Meta
- type Note
- type NoteType
- type Product
- type ProductID
- type ProductLeaf
- type ProductTree
- type Publisher
- type PublisherType
- type Reference
- type ReferenceType
- type Relationship
- type RelationshipType
- type Remediation
- type RemedyType
- type Report
- type Revision
- type RevisionStr
- type Score
- type Status
- type Threat
- type ThreatType
- type Tracking
- type VulnID
- type Vulnerability
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Acknowledgment ¶
type Acknowledgment struct { Names []string Organizations []string Description string URLs []string }
Acknowledgment captures acknowledgments for the document.
type AggregateSeverity ¶
AggregateSeverity captures the publishers declaration of the severity of the vulnerabilities defined in the report.
type Branch ¶
type Branch struct { Name string Type BranchType Branches []Branch Leaves []ProductLeaf }
Branch associates a particular type/name data pairing with all contained product definitions.
type BranchType ¶
type BranchType int
BranchType captures the type of branch in the product tree.
const ( BranchVendor BranchType = iota BranchProductFamily BranchProductName BranchProductVersion BranchPatchLevel BranchServicePack BranchArchitecture BranchLanguage BranchLegacy BranchSpecification BranchHostName BranchRealm BranchResource )
Values for BranchType
type CVSSScore ¶
type CVSSScore struct { Version string BaseScore float64 TemporalScore float64 EnvironmentalScore float64 Vector string }
ScoreSet captures the XML representation of the CVSS v3 scoring.
type CWE ¶
CWE captures the Common Weakness Enumeration (CWE) associated with a particular vulnerability.
See https://cwe.mitre.org/ for details about these values.
type ConformanceErr ¶
type ConformanceErr struct {
Issues []string
}
ConformanceErr contains identified compliance errors detected during either loading or saving a document.
func (*ConformanceErr) Error ¶
func (le *ConformanceErr) Error() string
Error produces one long string for all the conformance errors detected.
type Generator ¶
Generator captures the optional information about the tool that generated the vulnerability report. Note that this API inserts no value for Generator by default, as this is just an API to be used.
type GroupID ¶
type GroupID string
GroupID is used to identify and reference a set of ProductIDs within a Report.
type Involvement ¶
type Involvement struct { Party PublisherType Status InvolvementStatusType Description string }
Involvement captures the involvement of third parties.
type InvolvementStatusType ¶
type InvolvementStatusType int
InvolvementStatusType captures the ongoing involvement of other parties
const ( InvolvementStatusOpen InvolvementStatusType = iota InvolvementStatusDisputed InvolvementStatusInProgress InvolvementStatusCompleted InvolvementStatusContactAttempted InvolvementStatusNotContacted )
Values for InvolvementStatusType
type Meta ¶
type Meta struct { Title string Type string Publisher Publisher Tracking Tracking Notes []Note Distribution string AggregateSeverity *AggregateSeverity References []Reference Acknowledgments []Acknowledgment }
Meta captures the metadata about a vulnerability report.
type ProductID ¶
type ProductID string
ProductID is used to identify and reference a specific *Product with the scope of a Report.
type ProductLeaf ¶
type ProductLeaf struct { Name string Type BranchType Product *Product }
ProductLeaf captures a branch for a specific product.
type ProductTree ¶
type ProductTree struct { // Note that a product should be identified either under Branches // or under Products, but not both. Branches []Branch // Branches with just a product under them, and no other branches. Leaves []ProductLeaf // List of products for which no Branch information is associated. Products []*Product // Relationships amongst products Relationships []Relationship // Groups of products Groups []*Group }
ProductTree captures the representation of the product tree
type Publisher ¶
type Publisher struct { Type PublisherType VendorID string ContactDetails string IssuingAuthority string }
Publisher captures information about who published the document
type PublisherType ¶
type PublisherType int
PublisherType enumerates the different publishers of vulnerabilities.
const ( PubTypeVendor PublisherType = iota PubTypeDiscoverer PubTypeCoordinator PubTypeUser PubTypeOther )
Values for PublisherType
type Reference ¶
type Reference struct { Type ReferenceType URL string Description string }
Reference captures reference information
type ReferenceType ¶
type ReferenceType int
ReferenceType enumerates whether a reference is self or external.
const ( ReferenceExternal ReferenceType = iota ReferenceSelf )
Values for ReferenceType
type Relationship ¶
type Relationship struct { Type RelationshipType Reference *Product RelatesToReference *Product Products []*Product }
Relationship captures relationships between products.
type RelationshipType ¶
type RelationshipType int
RelationshipType defines possible relations between components.
const ( RelationshipDefaultComponentOf RelationshipType = iota RelationshipOptionalComponentOf RelationshipExternalComponentOf RelationshipInstalledOn RelationshipInstalledWith )
Values for RelationshipType
type Remediation ¶
type Remediation struct { Type RemedyType Date time.Time Description string Entitlement []string Products []*Product Groups []*Group URL string }
Remediation captures a remediation of a vulnerability
type RemedyType ¶
type RemedyType int
RemedyType enumerates the types of remedies for a vulnerability.
const ( RemedyWorkaround RemedyType = iota RemedyMitigation RemedyVendorFix RemedyNoneAvailable RemedyWillNotFix )
Values for RemedyType
type Report ¶
type Report struct { Meta Meta ProductTree ProductTree Vulnerabilities []Vulnerability }
Report captures the contents of a vulnerability report
func ParseJSON ¶
ParseJSON reads the JSON format of vulnerability report.
Note that this method validates the input document for compliance before returning it (for example, an empty description). All compliance problems are flagged as an error.
func ParseXML ¶
ParseXML parses CVRF file. Both CVRF versions 1.1 and 1.2 are supported.
If the parsing process contains only compliance errors, this returns an error of type *ComplianceErr, which can be used to access the individual issues.
type Revision ¶
type Revision struct { Number RevisionStr Date time.Time Description string }
Revision captures the xml representation of document revisions.
type Status ¶
type Status struct { Fixed []*Product FirstAffected []*Product KnownAffected []*Product KnownNotAffected []*Product FirstFixed []*Product Recommended []*Product LastAffected []*Product }
Status captures the different ways that a vulnerability applies to various products.
type Threat ¶
type Threat struct { Type ThreatType Description string Date time.Time Products []*Product Groups []*Group }
Threat captures the XML representation of the threat types
type ThreatType ¶
type ThreatType int
ThreatType captures the type of threat.
const ( ThreatImpact ThreatType = iota ThreatExploitStatus ThreatTargetSet )
Values for ThreatType
type Tracking ¶
type Tracking struct { ID string Aliases []string Status DocStatus Version RevisionStr Revisions []Revision InitialReleaseDate time.Time CurrentReleaseDate time.Time Generator *Generator }
Tracking captures the tracking data for a CVRF document
type Vulnerability ¶
type Vulnerability struct { Title string ID *VulnID Notes []Note DiscoveryDate time.Time ReleaseDate time.Time Involvements []Involvement CVE string CWE *CWE Statuses Status Threats []Threat Scores []Score Remediations []Remediation References []Reference Acknowledgments []Acknowledgment }
Vulnerability captures the vulnerabilities in the report.
Directories ¶
Path | Synopsis |
---|---|
cmd
|
|
genenums
Purpose built command line tool to generate the desired enumerations necessary for CVRF and JSON format documents.
|
Purpose built command line tool to generate the desired enumerations necessary for CVRF and JSON format documents. |
prep
Purpose built command line tool to download and prepare all the appropriate schema files used for testing.
|
Purpose built command line tool to download and prepare all the appropriate schema files used for testing. |
vulnrepconv
Usage: vulnrepconv -input <fname> [-output <fname>]
|
Usage: vulnrepconv -input <fname> [-output <fname>] |
Package schemamod contains utility functions to modify schemas.
|
Package schemamod contains utility functions to modify schemas. |