aboutcode-org
Introduce VEX Export Capability to DejaCode
Introduce VEX Support to DejaCode
- enhance data model to support a Product VEX List
- provide Export capabilities to product VEX documents that comply with industry-recognized formats
Here are a few suggested details (subject to improvement upon review):
A VEX (Vulnerability Exploitability Exchange) is an assertion about the status of a vulnerability in specific products.
In DejaCode a VEX exists only in the context of a Product. Our first implementation of VEX support will apply only to Product Packages.
The standard VEX Status can be: ● Not affected – No remediation is required regarding this vulnerability. ● Affected – Actions are recommended to remediate or address this vulnerability. ● Fixed – Represents that these product versions contain a fix for the vulnerability. ● Under Investigation – It is not yet known whether these product versions are affected by the vulnerability. An update will be provided in a later release.
DejaCode should support the standard VEX Status list. To avoid adding too much complexity to the data model, this could simply be coded into DejaCode, rather than creating a new VEX Status code table.
Given that a Product Package can have more than one vulnerability (VCID) and that a vulnerability can apply to more than one Product Package, it is probably best to consider defining a VEX in DejaCode as relating to an overall Product. Consider an on-demand process (button or command) in DejaCode that collects all the Vulnerabilities currently associated with Product Packages and creates or refreshes a list that we can call “Product VEX List” (working title) and presents them on a new tab (“VEX List”) of the Product User View.
The “logical” key of a Product VEX List is Product+VCID+PackageID, and the presentation should be in that order, with one row for each Product VEX. Supporting data elements should include:
- VEX Status (default value “Under Investigation”) – modifiable
- VEX Action. modifiable. free form text. If the status is Affected, a valid VEX must have an action statement that tells the product user what to do.
- VEX Impact modifiable. free form text. If the status is Not affected, a valid VEX must have an impact statement to further explain details.
- VEX Notes. modifiable. free form text. Additional notes to explain the VEX.
DejaCode Processing:
- [ ] From the Product VEX list, ability to open a Product VEX detail form.
- [ ] From the Product VEX list, provide a navigation link to the Product Package details.
- [ ] Provide full support for Product VEX in Reporting.
- [ ] Provide full support for Product VEX in the DejaCode API.
- [ ] (future) Generate DejaCode Notifications when a Product VEX is created and when the VEX Status is modified. Provide a link to the Product VEX from the Notification.
Some useful files, background, and links:
See the example VEX at
- https://github.com/CycloneDX/bom-examples/blob/master/VEX/vex.json
There is a descriptive overview of the CycloneDX approach to VEX here
- https://github.com/CycloneDX/bom-examples/tree/master/VEX
Note that we are primarily interested in what they call the "Independent BOM and VEX BOM" rather that an SBOM with embedded VEX info, mainly because it is always important to remember that an SBOM is essentially static, associated with a specific Version of a package (or in our case a Product defined in DejaCode) while the VEX is intended to report time-critical information about potential impact of a software vulnerability and how it is being addressed.
The CSAF standard format, recommended by the CycloneDX team, is described here: https://www.oasis-open.org/2022/11/28/common-security-advisory-framework-version-2-0-oasis-standard-is-now-published/
The CSAF also provides a downloadable package of the spec here: https://docs.oasis-open.org/csaf/csaf/v2.0/os/csaf-v2.0-os.zip
The most useful file in that package for us is probably csaf_json_schema.json
Additional guidelines from CISA 2023-11-06 attached. When-to-Issue-a-VEX-508c.pdf.zip
Interesting commentary from Tom Alrich attached. When will there be VEX tools.pdf
@DennisClark Is it a must for every Product Package that has a vulnerability to have a VEX? ( should the admin create a vex or Is vex automatically created when there is a vulnerability related to this package )
@ziadhany Good question and good idea! In principle, there ought to be a VEX for each Product Package that has a vulnerability, so creating one automatically when the product package is originally created is a good idea, as long as the user has the ability to list, review, edit, and possibly delete VEXs.
@DennisClark should we use a multiple choice field instead of free text for ( action and impact )?
according to my understanding, CycloneDX Vex uses a multiple-choice field
the main problem is that it is difficult to map our vex to CycloneDX vex using a text field And our mapping should be something like this:
status -> state ( should we ignore `Fixed` status? )
action -> response
impact -> justification
notes -> detail
https://github.com/CycloneDX/bom-examples/blob/master/VEX/vex.json#L83 :
"analysis": {
"state": "not_affected",
"justification": "code_not_reachable",
"response": ["will_not_fix", "update"],
"detail": "Automated dataflow analysis and manual code review indicates that the vulnerable code is not reachable, either directly or indirectly."
},
from cyclonedx.model.vulnerability import ImpactAnalysisAffectedStatus, ....
STATUS_VEX_CYCLONEDX = {
"Affected": ImpactAnalysisAffectedStatus.AFFECTED,
"Not affected": ImpactAnalysisAffectedStatus.UNAFFECTED,
"Under Investigation": ImpactAnalysisAffectedStatus.UNKNOWN,
# "Fixed":
}
JUSTIFICATION_VEX_CYCLONEDX = {
"code_not_present": ImpactAnalysisJustification.CODE_NOT_PRESENT,
"code_not_reachable": ImpactAnalysisJustification.CODE_NOT_REACHABLE,
"": ImpactAnalysisJustification.PROTECTED_AT_PERIMITER,
"": ImpactAnalysisJustification.PROTECTED_AT_RUNTIME,
"": ImpactAnalysisJustification.PROTECTED_BY_COMPILER,
"": ImpactAnalysisJustification.PROTECTED_BY_MITIGATING_CONTROL,
"": ImpactAnalysisJustification.REQUIRES_CONFIGURATION,
"": ImpactAnalysisJustification.REQUIRES_DEPENDENCY,
"": ImpactAnalysisJustification.REQUIRES_ENVIRONMENT,
}
RESPONSE_VEX_CYCLONEDX = {
"can_not_fix": ImpactAnalysisResponse.CAN_NOT_FIX,
"rollback": ImpactAnalysisResponse.ROLLBACK,
"update": ImpactAnalysisResponse.UPDATE,
"will_not_fix": ImpactAnalysisResponse.WILL_NOT_FIX ,
"workaround_available": ImpactAnalysisResponse.WORKAROUND_AVAILABLE
}
@ziadhany sorry for the delay in responding to your questions.
Yes, we should use the cyclonedx terms, and only use valid values when they are defined as enum.
Let's use 'state' , 'justification', 'response', 'detail' instead of the other labels that I suggested, which originally came from the available CISA documents, but those docs are not at all finalized yet. It makes a lot more sense to align with the CycloneDX terms.
@ziadhany multiple choice is best where appropriate, using the values defined by CycloneDX.
We have (at least) 2 use cases then:
- I have created a Product in DejaCode and I am ready to export an SBOM, but I don't have my VEX data reviewed and ready yet. So I simply use the existing SBOM generation feature.
- I have a Product and I have also reviewed/edited/finished the VEX data, and now I want to generate both a VEX document and a fresh copy of the the SBOM. So my action is to generate the VEX doc and that also triggers an SBOM generation.
https://github.com/CycloneDX/bom-examples/tree/master/VEX#bom-with-embedded-vex
from @DennisClark we need to do this further as far as the generated SBOM and not as a separate process or document
Implemented in https://github.com/aboutcode-org/dejacode/pull/187
Introduce a new VulnerabilityAnalysis model based on CycloneDX spec: https://cyclonedx.org/docs/1.6/json/#vulnerabilities_items_analysis A VulnerabilityAnalysis is always assigned to a Vulnerability object and a ProductPackage relation. The values for a VulnerabilityAnalysis are display in the Product "Vulnerabilities" tab. A "Edit" button can be used to open a form in a model to provided analysis data. Those new VEX related columns can be sorted and filtered. The VulnerabilityAnalysis data is exported in the VEX (only) and SBOM+VEX (combined) outputs.
