Add an 'Explanation' Overview document #716
Conversation
…e Tutorial to Reference
There was a problem hiding this comment.
A few general thoughts:
- I'm concerned about length for an intro doc
- It might be better to give readers the intro, then let them do a choose-your-own-adventure based on what roles they have. I'm thinking something like:
flowchart TB
intro --> stakeholders
stakeholders --> supplier
stakeholders --> deployer
stakeholders --> coordinator
supplier --> sddp[supplier decisions and decision points]
deployer --> dddp[deployer decisions and decision points]
coordinator --> cddp[coordinator decisions and decision points]
sddp --> fn[final notes]
dddp --> fn
cddp --> fn
This could be done as a series of pages (one for each stakeholder role) that includes
links to each of the other paths.
If you want to keep it in one page, we could do it using content tabs That might get weird with longer content though.
|
|
||
| ## Intro | ||
|
|
||
| Risk exists on a continuum, and different stakeholders have different threat models and risk appetites. |
There was a problem hiding this comment.
Consider "Cybersecurity risk"? We're not talking about Risk in general (although the statement is true without the qualifier, so I'm ok with it either way.
There was a problem hiding this comment.
Due to the audience of the document, if I were to change it, I would rather append: "Cybersecurity risk is no exception."
docs/explanation.md
Outdated
|
|
||
| Risk exists on a continuum, and different stakeholders have different threat models and risk appetites. | ||
|
|
||
| Take, for example, an exported software library that contains many functions, one of which is vulnerable to SQL injection. Your software imports this library but does not use this vulnerable function. Is your software, in its current state, at risk of this vulnerability? You likely answered, "probably not." |
There was a problem hiding this comment.
This example actually conflates deployer with a downstream supplier unless we clarify it more. Deployer is more like "I bought a license and deployed the thing I bought the license for". That's not the same thing as "I am the producer of product X which I distribute to others. X depends on Y. Y has a vul. What should I do?" This is a "supplier with a vulnerable upstream dependency" not a "deployer".
There was a problem hiding this comment.
How about:
Imagine you're a software developer, and you just found out about a vulnerability in a library upon which your product depends. You are now concerned that your software is also vulnerable. Upon investigation, you learn that your software does not use the vulnerable part of the imported library. Is your software, in its current state, at risk of this vulnerability? You likely answered, "probably not."
In this example, you are a Supplier of software that has an upstream Supplier vulnerability, but this vulnerability is not very risky to your business, so you are not very concerned. Conversely, the upstream Supplier probably wants the vulnerability patched as quickly as possible.
docs/explanation.md
Outdated
|
|
||
| Risk exists on a continuum, and different stakeholders have different threat models and risk appetites. | ||
|
|
||
| Take, for example, an exported software library that contains many functions, one of which is vulnerable to SQL injection. Your software imports this library but does not use this vulnerable function. Is your software, in its current state, at risk of this vulnerability? You likely answered, "probably not." |
There was a problem hiding this comment.
"exported software library" is awkward in this case. I think "software library" is sufficient.
Perspective wise, I'd start right off with "Imagine you are a role, and you have a situation you need to deal with..." rather than starting with the object of the situation.
docs/explanation.md
Outdated
|
|
||
| The publication decision reuses the [*Exploitation*](reference/decision_points/exploitation.md) decision point and adds two new ones ([*Supplier Involvement*](reference/decision_points/supplier_involvement.md) and [*Public Value Added*](reference/decision_points/public_value_added.md)). | ||
|
|
||
| - [*Supplier Involvement*](reference/decision_points/supplier_involvement.md) - If the supplier is involved and likely to publish already, there is less need for the CERT/CC to publish. |
There was a problem hiding this comment.
While too technical to go into in this document, see https://certcc.github.io/Vultron/reference/ssvc_crosswalk/#supplier-involvement for a brief "Engagement vs. Involvement: What's the Difference?" Might be able to summarize that distinction here.
There was a problem hiding this comment.
In trying to keep this agnostic from CERT/CC's Coordinator decision model, I suggest:
"What is the difference between Supplier Engagement and Supplier Involvement?"
*Supplier Engagement*, asks whether a Supplier has acknowledged the vulnerability and is participating in the coordination effort. *Supplier Involvement*, asks what, if anything, the Supplier is doing about the vulnerability.
|
|
||
| !!! note "Caveats" | ||
|
|
||
| All information in this document is suggested following research, but we must reiterate: it is *not a one-size-fits-all* system. We encourage stakeholders to define to define their own decision points, timeframes of actionability, and possibly, even their own roles. |
There was a problem hiding this comment.
Typo "to define to define".
There was a problem hiding this comment.
Here are some thoughts:
- I would consider removing the code blocks that appear after each decision point definition. A first time reader might be confused for what these are for (especially those who might stumble upon this on the internet). Apologies if they don't appear or if there is a good reason for those to be there.
- Something to consider down the line (which I actually want to work on) is some kind of example (text or visual) to keep enhancing accessibility. See examples here and here. Whether it should be on the same page as this somehow or as another page, we can discuss later!
|
Also at sei-renae#1 |
The target audience for the Explanation is a non-expert, and per diataxis.fr, should be able to casually read this and get an overview of what is SSVC.
This PR:
Adds the Explanation document
Modifies the main index page cards to Add the Explanation and Delete Learning SSVC
Modifies the menu bar via mkdocs.yml per index page cards
Moves Learning SSVC to Reference