Introduce VEX Analysis Capability to DejaCode

[DennisClark]

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 to Product Packages Vulnerabilities

The standard VEX Status can be as defined for the “state” field in the CDX VEX spec
https://cyclonedx.org/docs/1.6/json/#vulnerabilities_items_analysis

"resolved"
"resolved_with_pedigree"
"exploitable"
"in_triage" applied automatically to a Package when a new vulnerability is identified for it.
"false_positive"

DejaCode should support this 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 each VEX in DejaCode as relating to a Product Package Vulnerability. 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 (or perhaps Product+PackageID+VCID), and the presentation should be in that order, with one row for each Product VEX. Supporting data elements should include:

VEX Status (default value “in_triage”) – modifiable
VEX Action. modifiable. free form text. If the status is "exploitable", 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 "false_positive", 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 that includes the various VEX fields discussed above.
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

DejaCode supports SBOM with or without VEX, as well as VEX documents.

After we finish CycloneDX:
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

[ziadhany]

@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 )

[DennisClark]

@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.

[ziadhany]

@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
}

[DennisClark]

@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.

[DennisClark]

@ziadhany multiple choice is best where appropriate, using the values defined by CycloneDX.

[DennisClark]

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.

[ziadhany]

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

[tdruez]

Implemented in #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.