Add detailed VEX example Annex #933
Conversation
|
cc @puerco @jeff-schutt to take a look |
There was a problem hiding this comment.
oooh thanks @rnjudge you beat me to starting this document. This is a good start!
I think we are missing an overview of how VEX works in general. I think it would be helpful to first get the idea of the mechanics into the reader's head and then building up on how SPDX implements them.
I'm happy to help with some of it :)
| ## J.2 Changing the Status of a Vulnerability | ||
|
|
||
| Because [Elements](https://spdx.github.io/spdx-spec/v3.0/model/Core/Classes/Element/) in SPDX are immutable, a new VEX Assessment Relationship of type `amends` must be issued each time the VEX status of a vulnerability changes (i.e. `underInvestigationFor` --> `affects`) in addition to creating a new type of VEX status relationship. The following example shows how you would communicate that a vulnerbaility was under investigation before determining that the vulnerability indeed affects a product. |
There was a problem hiding this comment.
This part should be treated more as an edge case as the norm.
VEX relationships do not necessarily need to be amended. When I amend a relationship, I am changing properties of an existing one. There are some cases when this is needed and this is why we have a vexVersion, but it is not required for normal operations.
Instead, as the impact knowledge evolves, a VEX agent should instead issue new statements, that is new relationships, to capture the impact evolution.
We need to describe how to amend but lower in the doc, as I view these more as correcting an existing relationships and not for the normal flow.
There was a problem hiding this comment.
@puerco my understanding was that the amends relationship is how we string together evolving impact statements -- did this change? If new relationships are created for an updated impact, how do we nullify the old relationship? Or is it expected to look at the creation metadata and take the latest relationship? If so we probably want to explain that as well.
There was a problem hiding this comment.
@puerco -- @jeff-schutt and I discussed and agree that using an amendedBy relationship is the best way to preserve context and also make it easy for tools to search for updated VEX relationships. Of course, this is not a must and I've updated the verbiage in my PR to reflect that. Please continue to review and provide feedback at your convenience :)
My assumption was that if folks are coming to this annex they are probably already familiar with how VEX works and I didn't want to clutter the page with too much background. But I'm not opposed to a brief primer! Maybe easier to point them to an already written summary of it somewhere for more detailed info? Thanks so much for your help with the first pass, I'm incorporating your suggestions and we can keep iterating on this! Maybe review at the security all on Wed if you're around? |
This commit adds an annex explaining how to implement VEX in SPDX. Signed-off-by: Rose Judge <rose.judge@broadcom.com>
|
The SPDX V 3 spec says nothing about NIST's VDR - this is a significant oversight. |
This commit adds an annex explaining how to implement VEX in SPDX.