Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added vulnerabilities as part of core spec #91

Merged
merged 26 commits into from
Dec 20, 2021
Merged

Added vulnerabilities as part of core spec #91

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
adb75ab
#38 - Added initial support for vulnerabilities as part of core spec.…
stevespringett Oct 3, 2021
173b781
Corrected issues preventing validation
stevespringett Oct 3, 2021
a04e72f
Clarified description of when the vulnerability was created per https…
stevespringett Oct 5, 2021
821fdfa
Refactored 'affects' by incorporating ranges and versions into indivi…
stevespringett Oct 15, 2021
df947e9
Refactored 'affects' by incorporating ranges and versions into indivi…
stevespringett Oct 15, 2021
d290235
spelling
stevespringett Oct 15, 2021
b7e37c6
Added not_affected justifications based on discussion https://github.…
stevespringett Nov 12, 2021
f15b462
Removed not_set as its implied if value is not specified. Added expli…
stevespringett Nov 12, 2021
052e702
Added description for vulnerability reference
stevespringett Nov 18, 2021
485456c
Added description for vulnerability reference
stevespringett Nov 18, 2021
8db5a20
Standardizing on version range syntax from CVE v5.0 JSON schema
stevespringett Nov 19, 2021
35b5bc0
Minor hardening. Added default to affected status as unlike the CVE 5…
stevespringett Nov 20, 2021
d3f0e50
Documentation updates
stevespringett Nov 22, 2021
dcad6ef
Added info to severity
stevespringett Nov 22, 2021
6c62cc6
Documentation updates
stevespringett Nov 22, 2021
0ac6b87
#91 - Added analysis (vendor) response
stevespringett Dec 7, 2021
b42bbca
#91 - Changed credits from a string to structured data supporting an …
stevespringett Dec 7, 2021
9f9f4ca
Migrated from version range syntax defined in CVE 5.0 Schema to Packa…
stevespringett Dec 13, 2021
5ac7976
Minor doc updates
stevespringett Dec 13, 2021
1ec2ca4
Added XSD and XML example that are ported from the draft JSON schema.
stevespringett Dec 13, 2021
ae3a4ab
Added Protobuf and textproto example that are ported from the draft J…
stevespringett Dec 14, 2021
937b8fd
Changed SEVERITY_UNKNOWN to default
stevespringett Dec 17, 2021
7a7d7ad
Changed SEVERITY_UNKNOWN to default
stevespringett Dec 17, 2021
6201ede
Changed IMPACT_ANALYSIS_STATE_NULL to default
stevespringett Dec 17, 2021
c85bdd6
Changed IMPACT_ANALYSIS_JUSTIFICATION_NULL to default and VULNERABILI…
stevespringett Dec 17, 2021
0e1df61
Changed VULNERABILITY_AFFECTED_STATUS_UNKNOWN to default
stevespringett Dec 17, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
317 changes: 317 additions & 0 deletions schema/bom-1.4-strict-SNAPSHOT.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,6 +85,14 @@
"uniqueItems": true,
"title": "Compositions",
"description": "Compositions describe constituent parts (including components, services, and dependency relationships) and their completeness."
},
"vulnerabilities": {
"$id": "#/properties/vulnerabilities",
"type": "array",
"items": {"$ref": "#/definitions/vulnerability"},
"uniqueItems": true,
"title": "Vulnerabilities",
"description": "Vulnerabilities identified in components or services."
}
},
"definitions": {
Expand Down Expand Up @@ -1074,6 +1082,315 @@
"description": "The value of the property."
}
}
},
"advisory": {
"type": "object",
"title": "Advisory",
"description": "Location of additional advisory information.",
"required": ["url"],
"additionalProperties": false,
"properties": {
"title": {
"type": "string"
},
"url": {
"type": "string",
"format": "iri-reference"
}
}
},
"cwe": {
"type": "integer",
"minimum": 1,
"title": "CWE",
"description": "Integer representation of a Common Weaknesses Enumerations (CWE). For example 399 (of https://cwe.mitre.org/data/definitions/399.html)"
},
"severity": {
"type": "string",
"title": "Severity",
"description": "Textual representation of the severity of the vulnerability adopted by the risk analysis method. If an other risk analysis method is used other than whats defined in scoreSourceType, the user is expected to translate appropriately to match with an element value below.",
"enum": [
"critical",
"high",
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this a generic rating of this vulnerability, like the CVSS score? Or is the scoring intended to be specific to the particular application that this component is part of? If the latter, then the description could be updated to emphasize that.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Multiple ratings can be specified, including those from the NVD and for the creators or operators of the application that component is a part of. OWASP Risk Rating is also supported here.

"medium",
"low",
"none",
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
"unknown"
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
]
},
"scoreMethod": {
"type": "string",
"title": "method",
"description": "Specifies the risk scoring methodology/standard used.",
"enum": [
"CVSSv2",
"CVSSv3",
"CVSSv31",
"OWASP",
"Other"
]
},
"impactAnalysisState": {
"type": "string",
"title": "Impact Analysis State",
"description": "Textual representation of the state of the impact analysis.",
"enum": [
"exploitable",
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
"in_triage",
"false_positive",
"not_affected",
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
"not_set"
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
]
},
"rating": {
"type": "object",
"title": "Rating",
"description": "Defines the risk ratings of a vulnerability.",
"additionalProperties": false,
"properties": {
"source": {
"$ref": "#/definitions/vulnerabilitySource",
"description": "The source that published the vulnerability."
},
"score": {
"type": "number",
"title": "Score",
"description": "The numerical score of the rating."
},
"severity": {
"$ref": "#/definitions/severity"
},
"method": {
"$ref": "#/definitions/scoreMethod"
},
"vector": {
"type": "string",
"title": "Vector",
"description": "Textual representation of the metric values used to score the vulnerability"
},
"justification": {
"type": "string",
"title": "Justification",
"description": "An optional reason for rating the vulnerability as it was"
}
}
},
"vulnerabilitySource": {
"type": "object",
"title": "Source",
"description": "The source of the vulnerability where it is documented. Usually the name of the organization publishing vulnerability information",
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"title": "URL",
"description": "The url of the vulnerability documentation as provided by the source.",
"examples": [
"https://nvd.nist.gov/vuln/detail/CVE-2019-15842"
]
},
"name": {
"type": "string",
"title": "Name",
"description": "The name of the source.",
"examples": [
"NVD",
"National Vulnerability Database",
"OSS Index",
"VulnDB",
"NPM Advisories"
]
}
}
},
"vulnerability": {
"type": "object",
"title": "Vulnerability",
"description": "Defines the structure of a vulnerability.",
"additionalProperties": false,
"properties": {
"bom-ref": {
"type": "string",
"title": "BOM Reference",
"description": "An optional identifier which can be used to reference the vulnerability elsewhere in the BOM. Every bom-ref should be unique."
},
"id": {
"type": "string",
"title": "ID",
"description": "The id of the vulnerability as defined by the risk scoring methodology. For example CVE-2019-15842 (of https://nvd.nist.gov/vuln/detail/CVE-2019-15842)"
},
"source": {
"$ref": "#/definitions/vulnerabilitySource",
"description": "The source that published the vulnerability."
},
"references": {
"type": "array",
"title": "References",
"description": "",
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
"additionalItems": false,
"items": {
"required": [
"id",
"source"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"title": "ID",
"description": "The id of the vulnerability as defined by the risk scoring methodology. For example CVE-2019-15842 (of https://nvd.nist.gov/vuln/detail/CVE-2019-15842)"
},
"source": {
"$ref": "#/definitions/vulnerabilitySource",
"description": "The source that published the vulnerability."
}
}
}
},
"ratings": {
"type": "array",
"title": "Ratings",
"description": "List of the vulnerability ratings as defined by various risk rating methodologies.",
"items": {
"$ref": "#/definitions/rating"
}
},
"cwes": {
"type": "array",
"title": "CWEs",
"description": "List of Common Weaknesses Enumerations (CWEs) codes that describes this vulnerability. For example 399 (of https://cwe.mitre.org/data/definitions/399.html)",
"items": {
"$ref": "#/definitions/cwe"
}
},
"description": {
"type": "string",
"title": "Description",
"description": "A description of the vulnerability as provided by the source."
},
"detail": {
"type": "string",
"title": "Details",
"description": "If available, an in-depth description of the vulnerability as provided by the source organization. Details often include examples, proof-of-concepts, and other information useful in understanding root cause."
},
"recommendation": {
"type": "string",
"title": "Details",
"description": "Recommendations of how the vulnerability can be remediated or mitigated."
},
Comment on lines +1310 to +1314
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I saw this line in the PR description...

Recommendations was previously an array. This has changed to a single field and renamed 'remediation'

  1. Should this field name get updated to remediation?
  2. What's the motivation for collapsing the array into a string?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Should this field name get updated to remediation?

The spec supports recommendation which would typically include remediation or mitigation advise.

CVE 5.0 schema supports 'workaround', which is kinda the same thing.

Do you see any issues with the current approach?

  1. What's the motivation for collapsing the array into a string?

I was looking at the OSV schema and they have a single field. I also looked at CVE 5.0 schema and they support an array, but it appears to be used for languages - so a vulnerability supporting recommendations in English, French, and Mandarin for example.

Do you see value in supporting an array of recommendations? I'm indifferent about it.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this field name get updated to remediation?

The spec supports recommendation which would typically include remediation or mitigation advise.

Just to clarify, my confusion is around this part of the PR's description:

This has changed to a single field and renamed 'remediation'

I think logically the structure makes sense, this was just a minor naming curiosity.

Do you see value in supporting an array of recommendations? I'm indifferent about it.

Good question. So far, only in contrived scenarios. I think string is good for the time being. 👍

"advisories": {
"type": "array",
"title": "Advisories",
"description": "Published advisories of the vulnerability if provided.",
"items": {
"$ref": "#/definitions/advisory"
}
},
"created": {
"type": "string",
"format": "date-time",
"title": "Created",
"description": "The date and time (timestamp) when the vulnerability record was created in the vulnerability database."
},
"published": {
"type": "string",
"format": "date-time",
"title": "Published",
"description": "The date and time (timestamp) when the vulnerability record was first published."
},
"updated": {
"type": "string",
"format": "date-time",
"title": "Updated",
"description": "The date and time (timestamp) when the vulnerability record was last updated."
},
"credits": {
"type": "string",
"title": "Credits",
"description": "Individuals or organizations credited by with the discovery of the vulnerability."
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
},
"tools": {
"type": "array",
"title": "Creation Tools",
"description": "The tool(s) used in the creation of the BOM.",
"items": {"$ref": "#/definitions/tool"}
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
},
"analysis": {
"type": "object",
"title": "Impact Analysis",
"description": "An assessment of the impact and exploitability of the vulnerability.",
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this "impact analysis" intended to include both likellihood of discovery/exploit as well as the technical/business impact of a successful exploit? I was looking for the basic Risk = Likelihood * Impact factors but maybe I'm looking in the wrong place.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Its currently in the 'ratings' property. One or more ratings can be specified. So if you opted to use temportal and environmental criteria in CVSS, you'll get some of that. You can also use OWASP risk rating which is directly supported.

"additionalProperties": false,
"properties": {
"state": {
"$ref": "#/definitions/impactAnalysisState"
},
"impact": {
"type": "string",
"title": "Impact",
"description": "A description of the impact."
},
"detail": {
"type": "string",
"title": "Detail",
"description": "Detailed description of the impact including methods used during assessment. If a vulnerability is not exploitable, this field should include specific details on why the component or service is not impacted by this vulnerability."
}
}
},
"affects": {
"type": "array",
"uniqueItems": true,
"additionalItems": false,
"items": {
"required": [
"ref"
],
"additionalProperties": false,
"properties": {
"ref": {
"type": "string",
"title": "Reference",
"description": "References a component or service by the objects bom-ref"
},
"ranges": {
"$ref": "#/definitions/versionRangeArray"
},
"versions": {
"type": "array",
"title": "Versions",
"description": "Zero or more individual versions. Version can be combined with ranges.",
"items": {
"type": "string"
}
}
}
},
"title": "Affects",
"description": "The bom-ref identifiers of the components or services that are affected by the vulnerability."
},
"properties": {
"type": "array",
"title": "Properties",
"description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values.",
"items": {
"$ref": "#/definitions/property"
}
}
}
},
"versionRangeArray": {
"type": "array",
"title": "Ranges",
"description": "Zero or more version ranges",
"additionalItems": false,
"items": {
"$ref": "#/definitions/versionRange"
}
},
"versionRange": {
"type": "string",
"title": "Range",
"description": "A simplified version range specification derived from node-semver. A version range is a set of comparators which specify versions that satisfy the range. A comparator is composed of an operator and a version. The set of primitive operators is: < Less than, <= Less than or equal to, > Greater than, >= Greater than or equal to, and = Equal. If no operator is specified, then equality is assumed, so this operator is optional, but MAY be included. Comparators can be joined by whitespace to form a comparator set. Only a single comparator set is allowed per range specified in the BOM. No further node-semver syntax is supported. Semver 2.0 and higher is required.",
"examples": [ ">=1.2.7 <1.3.0", ">=1.2.7" ]
stevespringett marked this conversation as resolved.
Show resolved Hide resolved
}
}
}
Loading