Copy edits & punch list (#524)

Co-authored-by: Laurie Tyzenhaus <[email protected]>

docs/_includes/_cvss4_question.md

@@ -0,0 +1,5 @@
+!!! question inline end "What about CVSS v4?"
+
+    Since this documentation was written, CVSS v4 has been released.
+    While we plan to address CVSS v4 in a future update to the SSVC documentation, we are 
+    retaining our CVSS v3.1 content because it remains the most widely used version of CVSS.

docs/_includes/_scrollable_table.md

@@ -0,0 +1,3 @@
+!!! tip "Scroll to the right to see the full table"
+
+    The table below is scrollable to the right.

docs/howto/bootstrap/collect.md

@@ -59,24 +59,27 @@ That caveat notwithstanding, some automation is possible.
     At least, for those vulnerabilities that are not “automatically” PoC-ready, such as on-path attackers for TLS or network
     replays.
 
+
 Some of the decision points require a substantial upfront analysis effort to gather risk assessment or organizational
 data.
 However, once gathered, this information can be efficiently reused across many vulnerabilities and only refreshed
 occasionally.
 
 !!! example "Evidence of Mission Impact"
 
-    An obvious example of this is the mission impact decision point.
-    To answer this, a deployer must analyze their essential functions, how they interrelate, and how they are supported.
+    An obvious example of this is the [Mission Impact](../../reference/decision_points/mission_impact.md) decision point.
+    To answer this, a deployer must analyze their Mission Essential Functions (MEFs), how they interrelate, and how they are supported.
+
 
-!!! example "Evidence of Exposure"
+!!! example "Evidence of System Exposure"
 
-    Exposure is similar; answering that decision point requires an asset inventory, adequate understanding of the network
+    [System Exposure](../../reference/decision_points/system_exposure.md) is similar; answering that decision point requires an asset inventory, adequate understanding of the network
     topology, and a view of the enforced security controls.
     Independently operated scans, such as Shodan or Shadowserver, may play a role in evaluating exposure, but the entire
     exposure question cannot be reduced to a binary question of whether an organization’s assets appear in such databases.
 
-Once the deployer has the situational awareness to understand MEFs or exposure, selecting the answer for each individual
+
+Once the deployer has the situational awareness to understand their Mission Essential Functions or System Exposure, selecting the answer for each individual
 vulnerability is usually straightforward.
 
 Stakeholders who use the prioritization method should consider releasing the priority with which they handled the
@@ -94,36 +97,47 @@ deployer may want to use that information to favor the latter.
 In the case where no information is available or the organization has not yet matured its initial situational analysis,
 we can suggest something like defaults for some decision points.
 
-!!! tip "Default Exposure Values"
+!!! tip "Default Exploitation Values"
+
+    [*Exploitation*](../../reference/decision_points/exploitation.md) needs no special default; if adequate searches are made for exploit code and none is
+    found, the answer is [*none*](../../reference/decision_points/exploitation.md).
+
+!!! tip "Default System Exposure Values"
 
     If the deployer does not know their exposure,<!--lowercase exposure on purpose, this is the general concept--> that
     means they do not know where the devices are or how they are controlled, so they should assume
     [*System Exposure*](../../reference/decision_points/system_exposure.md) is [*open*](../../reference/decision_points/system_exposure.md).
 
+
+!!! tip "Default Automatable Values"
+
+    If nothing is known about [*Automatable*](../../reference/decision_points/automatable.md), the safer answer to assume is [*yes*](../../reference/decision_points/automatable.md).
+    [*Value Density*](../../reference/decision_points/value_density.md) should always be answerable; if the product is uncommon, it is probably
+    [*diffuse*](../../reference/decision_points/value_density.md).
+
 !!! tip "Default Safety Values"
 
     If the decision maker knows nothing about the environment in which the device is used, we suggest assuming a
-    [*major*](../../reference/decision_points/safety_impact.md) [*Safety Impact*](../../reference/decision_points/safety_impact.md).
+    [*marginal*](../../reference/decision_points/safety_impact.md) [*Safety Impact*](../../reference/decision_points/safety_impact.md).
     This position is conservative, but software is thoroughly embedded in daily life now, so we suggest that the decision
     maker provide evidence that no one’s well-being will suffer.
 
-The reach of software exploits is no longer limited to a research network.
-
 !!! tip "Default Mission Impact Values"
 
     Similarly, with [*Mission Impact*](../../reference/decision_points/mission_impact.md), the deployer should assume that the software is in use at the
     organization for a reason, and that it supports essential functions unless they have evidence otherwise.
     With a total lack of information, assume [*support crippled*](../../reference/decision_points/mission_impact.md) as a default.
-    [*Exploitation*](../../reference/decision_points/exploitation.md) needs no special default; if adequate searches are made for exploit code and none is
-    found, the answer is [*none*](../../reference/decision_points/exploitation.md).
+
 
+!!! example "Using Defaults"
 
-!!! tip "Default Automatable Values"
-
-    If nothing is known about [*Automatable*](../../reference/decision_points/automatable.md), the safer answer to assume is [*yes*](../../reference/decision_points/automatable.md).
-    [*Value Density*](../../reference/decision_points/value_density.md) should always be answerable; if the product is uncommon, it is probably
-    [*diffuse*](../../reference/decision_points/value_density.md).
+    Applying these defaults to the [deployer decision model](../deployer_tree.md)
 
-The resulting decision set `{none, open, yes, medium}` results in a scheduled patch application in our recommended
-deployer tree.
+    - *Exploitation*: none
+    - *System Exposure*: open
+    - *Automatable*: yes
+    - *Human Impact*: medium (combination of Safety and Mission Impacts)
+        - *Safety Impact*: marginal
+        - *Mission Impact*: support crippled
 
+    results in a `scheduled` patch application.

docs/howto/bootstrap/use.md

@@ -1,6 +1,6 @@
 # Use SSVC
 
-The [preparation](prepare.md) is complete, data is being [collected](collect.md), and now it is time to use
+The [preparation](prepare.md) is complete, data has been [collected](collect.md), and now it is time to use
 SSVC to make decisions about how to respond to vulnerabilities.
 
 ```mermaid
@@ -79,7 +79,7 @@ flowchart LR
     The service providers in previous examples might need to notify customers of the vulnerability and schedule
     maintenance windows to apply patches.
     Medical device manufacturers might need to develop patches, notify regulators of the vulnerability, and provide 
-    instructions to hospital users for applying patches.
+    instructions to deployers (e.g., device maintainers at hospitals) for applying patches.
     SSVC does not prescribe any particular response process, but it does provide a structured way to make decisions 
     within the response process.
 
@@ -149,13 +149,18 @@ The merit in this “list all values” approach emerges when the stakeholder kn
 
 !!! example "When Some Values Are Known (But Others Are Not)"
 
-    For example, say the analyst knows that [*Value Density*](../../reference/decision_points/value_density.md) is [diffuse](../../reference/decision_points/value_density.md) but does not know the value for [Automatability](../../reference/decision_points/automatable.md).
+    Extending the previous example, say the analyst knows that [*Value Density*](../../reference/decision_points/value_density.md) is [diffuse](../../reference/decision_points/value_density.md) but does not know the value for [Automatability](../../reference/decision_points/automatable.md).
 
     {% include-markdown "../../_generated/decision_points/value_density.md" %}
 
     {% include-markdown "../../_generated/decision_points/automatable.md" %}
 
-    Then the analyst can usefully restrict [Utility](../../reference/decision_points/utility.md) to one of [laborious](../../reference/decision_points/utility.md) or [efficient](../../reference/decision_points/utility.md).
+    Therefore they could rule out [super effective](../../reference/decision_points/utility.md) 
+    for [Utility](../../reference/decision_points/utility.md)
+    but not [laborious](../../reference/decision_points/utility.md)
+    or [efficient](../../reference/decision_points/utility.md).
+    In this case, the analyst could usefully restrict [Utility](../../reference/decision_points/utility.md) to one of [laborious](../../reference/decision_points/utility.md) or [efficient](../../reference/decision_points/utility.md)
+    while leaving [Automatability](../../reference/decision_points/automatable.md) open.
 
 As discussed below, information can change over time.
 Partial information may be, but is not required to be, sharpened over time into a precise value for the decision point.

docs/howto/coordination_triage_decision.md

@@ -109,5 +109,7 @@ height = "700" />
 
 ### Table of Values
 
+{% include-markdown "../_includes/_scrollable_table.md" heading-offset=1 %}
+
 <!-- relative to /data/csvs/ -->
 {{ read_csv('coord-triage-options.csv') }}

docs/howto/deployer_tree.md

@@ -119,6 +119,8 @@ More detail about each of these decision points is provided at the links above,
 {% include-markdown "../_generated/decision_points/utility.md" %}
 {% include-markdown "../_generated/decision_points/human_impact.md" %}
 
+In the _Human Impact_ table above, *MEF* stands for Mission Essential Function.
+
 ## Deployer Decision Model
 
 Below we provide an example deployer prioritization policy that maps the decision points just listed to the outcomes described above.

docs/howto/index.md

@@ -54,7 +54,8 @@ The definition of choices can take a logical form, such as:
 
  - THEN priority is *scheduled*.
 
-This example logical statement is captured in [line 35 of the deployer `.csv` file](https://github.com/CERTCC/SSVC/blob/main/data/csvs/deployer-options.csv#L35).
+<!-- csv file has a header row, so the line numbers and row numbers are off by one. -->
+This example logical statement is captured in [row 34 of the deployer `.csv` file](https://github.com/CERTCC/SSVC/blob/main/data/csvs/deployer-options.csv#L35).
 
 There are different formats for capturing these prioritization decisions depending on how and where they are going to be used.
 In this documentation, we primarily represent a full set of guidance on how one stakeholder will make a decision as a **decision tree**.
@@ -64,7 +65,7 @@ fit your organization's needs.
 
 <div class="grid cards" markdown>
 
-- :material-stairs: [Bootstrapping SSVC](bootstrap/index.md)
+- :material-stairs: [Getting Started with SSVC](bootstrap/index.md)
 - :material-factory: [Supplier Decision Model](supplier_tree.md)
 - :material-server-network: [Deployer Decision Model](deployer_tree.md)
 - :material-steering: [Coordinator Decision Models](coordination_intro.md)

docs/reference/decision_points/exploitation.md

@@ -30,15 +30,18 @@ The intent of this measure is the present state of exploitation of the vulnerabi
 
 ## CWE-IDs for *PoC*
 
+
 The table below lists CWE-IDs that could be used to mark a vulnerability as *PoC* if the vulnerability is described by the CWE-ID.
 
+
 !!! example "CWE-295"
 
-    For example, CWE-295, [Improper Certificate Validation
-    ](https://cwe.mitre.org/data/definitions/295.html), and its child CWEs,  
-    describe improper validation of TLS certificates. These CWE-IDs could 
-    always be marked as *PoC* since that meets condition (3) in 
-    the definition.
+    For example, [CWE-295 Improper Certificate Validation
+    ](https://cwe.mitre.org/data/definitions/295.html), and its child CWEs,
+    describe improper validation of TLS certificates. These CWE-IDs could
+    always be marked as *PoC* since that meets condition (3) in the definition.
+
+{% include-markdown "../../_includes/_scrollable_table.md" heading-offset=1 %}
 
 <!-- relative to /data/csvs/ -->
 {{ read_csv('cwe/possible-cwe-with-poc-examples.csv') }}

docs/reference/decision_points/technical_impact.md

@@ -2,7 +2,7 @@
 
 {% include-markdown "../../_generated/decision_points/technical_impact.md" %}
 
-When evaluating [*Technical Impact*](technical_impact.md), recall the scope definition in the [Scope Section](../../topics/scope.md).
+When evaluating *Technical Impact*, recall the scope definition in the [Scope Section](../../topics/scope.md).
 Total control is relative to the affected component where the vulnerability resides.
 If a vulnerability discloses authentication or authorization credentials to the system, this information disclosure should also be scored as “total” if those credentials give an adversary total control of the component.
 
@@ -14,7 +14,7 @@ Therefore, if there is a vulnerability then there must be some technical impact.
 
 !!! tip "Gathering Information About Technical Impact"
 
-    Assessing [*Technical Impact*](technical_impact.md) amounts to assessing the degree of control over the vulnerable component the attacker stands to gain by exploiting the vulnerability.
+    Assessing *Technical Impact* amounts to assessing the degree of control over the vulnerable component the attacker stands to gain by exploiting the vulnerability.
     One way to approach this analysis is to ask whether the control gained is *total* or not.
     If it is not total, it is *partial*.
     If an answer to one of the following questions is _yes_, then control is *total*.
@@ -25,5 +25,7 @@ Therefore, if there is a vulnerability then there must be some technical impact.
     - does the attacker get an account with full privileges to the vulnerable component (administrator or root user accounts, for example)?
 
     This list is an evolving set of heuristics.
-    If you find a vulnerability that should have [*total*](technical_impact.md)  [*Technical Impact*](technical_impact.md) but that does not answer yes to any of these questions, please describe the example and what question we might add to this list in an issue on the [SSVC GitHub](https://github.com/CERTCC/SSVC/issues).
+    If you find a vulnerability that should have *total* *Technical Impact* but that does not answer yes to any of 
+    these questions, please describe the example and what question we might add to this list in an issue on the
+    [SSVC GitHub](https://github.com/CERTCC/SSVC/issues).
 

docs/reference/decision_points/utility.md

@@ -14,7 +14,9 @@ This is a compound decision point, therefore it is a notational convenience.
 *Utility* is independent from the state of [*Exploitation*](exploitation.md), which measures whether a set of adversaries have ready access to exploit code or are in fact exploiting the vulnerability.
 In economic terms, [*Exploitation*](exploitation.md) measures whether the **capital cost** of producing reliable exploit code has been paid or not.
 *Utility* estimates the **marginal cost** of each exploitation event.
-More plainly, *Utility* is about how much an adversary might benefit from a campaign using the vulnerability in question, whereas [*Exploitation*](exploitation.md) is about how easy it would be to start such a campaign or if one is already underway.
+
+Whereas [*Exploitation*](exploitation.md) is about how easy it would be to start such a campaign or if one is already underway,
+*Utility* is about how much an adversary might benefit from a campaign using the vulnerability in question.
 
 Heuristically, we base Utility on a combination of the value density of vulnerable components and whether potential exploitation is automatable.
 This framing makes it easier to analytically derive these categories from a description of the vulnerability and the affected component.

docs/topics/asset_management.md

@@ -32,7 +32,7 @@ Once the organization remediates or mitigates all the high-priority vulnerabilit
 Asset management and risk management also drive some of the up-front work an organization would need to do to gather some of the necessary information.
 This situation is not new; an asset owner cannot prioritize which fixes to deploy to its assets if it does not have an accurate inventory of its assets.
 The organization can pick its choice of tools; there are about 200 asset management tools on the market [@captera].
-Emerging standards like the Software Bill of Materials (SBOM) [@manion2019sbom] would likely reduce the burden on asset management, and organizations should prefer systems which make such information available.
+Emerging standards like the [Software Bill of Materials](https://www.cisa.gov/sbom) (SBOM) would likely reduce the burden on asset management, and organizations should prefer systems which make such information available.
 If an organization does not have an asset management or risk management
 (see also [Gathering Information About Mission Impact](../reference/decision_points/mission_impact.md))
 plan and process in place, then SSVC provides some guidance as to what information is important to vulnerability

docs/topics/decision_points_as_bricks.md

@@ -50,7 +50,7 @@ From that starting point, there are a few different ways you might proceed:
 ### Follow the examples as provided
 
 For many people, this is the experience they want.
-They want to build the model exactly as it is pictured on the box, and for that purpose they can follow the instructions provided.
+They want to build the model exactly as it is pictured on the box, and so they will simply follow the instructions provided.
 
 ### Adapt the examples to suit your needs