Merge branch 'main' into 296-decision-points-as-primary-focus

.github/workflows/link_checker.yml

@@ -0,0 +1,41 @@
+name: Link Checker
+on:
+  pull_request:
+    paths:
+      # run on any PR that modifies a markdown file
+      - '**/*.md'
+      # run on any PR that changes this workflow
+      - .github/workflows/linkchecker.yml
+  # let us trigger it manually
+  workflow_dispatch:
+
+jobs:
+  linkcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements.txt
+          python -m pip install linkchecker
+
+      - name: Install our python stuff
+        run: |
+          python -m pip install -e src
+
+      - name: Build Site
+        run: |
+          mkdocs build --verbose --clean --config-file mkdocs.yml       
+
+      - name: Check links
+        run: |
+          linkchecker site/index.html
+          

README.md

@@ -1,4 +1,4 @@
-[![pandoc_html_pdf](https://github.com/CERTCC/SSVC/actions/workflows/pandoc_html_pdf.yaml/badge.svg)](https://github.com/CERTCC/SSVC/actions/workflows/pandoc_html_pdf.yaml)
+[![Link Checker](https://github.com/CERTCC/SSVC/actions/workflows/link_checker.yml/badge.svg?branch=main)](https://github.com/CERTCC/SSVC/actions/workflows/link_checker.yml)
 
 # SSVC
 

docs/adr/0005-ssvc-decision-point-group-versioning.md

@@ -8,13 +8,13 @@ deciders: adh, jspring, vssarvepalli, cgyarbrough, latyzenhaus, ehatleback
 
 ## Context and Problem Statement
 
-[ADR 004](./0004-ssvc-decision-point-groups-are-versioned.md) established that Decision Point Groups should be versioned.
+[ADR 004](0004-ssvc-decision-point-groups-are-versioned.md) established that Decision Point Groups should be versioned.
 
 This ADR establishes the rules for versioning Decision Point Groups.
 
 ## Decision Drivers
 
-(See [ADR 004](./0004-ssvc-decision-point-groups-are-versioned.md) for additional context.)
+(See [ADR 004](0004-ssvc-decision-point-groups-are-versioned.md) for additional context.)
 
 - Decision Points change over time
 - The composition of decision point groups change over time
@@ -103,7 +103,7 @@ In row 4, DP C undergoes a major version increment, which triggers a major versi
 - Because we don't anticipate frequent changes to decision point groups, the burden of maintaining version numbers should be minimal.
 - We are deliberately avoiding using the _name_ of the Decision Point Group as part of the versioning scheme, as
 in the motivating example in
-[ADR 0004](/0004-ssvc-decision-point-groups-are-versioned.md) we shifted the
+[ADR 0004](0004-ssvc-decision-point-groups-are-versioned.md) we shifted the
 group name from _Patch Applier_ to _Deployer_, but since the group is still
 intended to represent the same _stakeholder role_ and _decision_, we want
 to be able to treat name changes as aliases rather than versioning events.

docs/howto/bootstrap/steps_table.md → docs/howto/bootstrap/_steps_table.md

@@ -3,4 +3,4 @@
 | [**Prepare**](prepare.md) | Define the decision you want to make, the outcomes you care about, the decision points you will use to make the decision, the decision policy, and the data you need to inform the decision points. |
 | [**Collect**](collect.md) | Collect the data you need to make informed decisions.                                                                                                                                               |
 | [**Use SSVC**](use.md) | Use SSVC to make decisions about how to respond to vulnerabilities.                                                                                                        |
-| [**Respond**](use.md#respond-to-vulnerabilities) | Respond to vulnerabilities according to the prioritization.                                                                                                                                         |
+| [**Respond**](use.md) | Respond to vulnerabilities according to the prioritization.                                                                                                                                         |

docs/howto/bootstrap/collect.md

@@ -10,7 +10,7 @@
 While the actual collection of operational data is outside the scope of SSVC, it is an important part of any implementation
 of the process.
 SSVC is designed to be flexible enough to accommodate a variety of data collection methods.
-The [Data Mapping](prepare.md#data-mapping) step defines the data that is needed to assign a value to each decision point.
+The [Data Mapping](prepare.md) step defines the data that is needed to assign a value to each decision point.
 The Data Operations process collects that data so that it can be used to assign values to decision points in the 
 [Use SSVC](use.md) step.
 
@@ -43,4 +43,87 @@ flowchart LR
      They also write a script that parses the data from the threat feeds and applies the data map to assign a value to 
      the _Exploitation_ decision point.
 
-{% include-markdown '../evidence_gathering.md' heading-offset=1 %}
+## Guidance for Evidence Gathering
+
+To answer each of these decision points, a stakeholder should, as much as possible, have a repeatable evidence
+collection and evaluation process.
+However, we are proposing decisions for humans to make, so evidence collection and evaluation is not totally automatable.
+That caveat notwithstanding, some automation is possible.
+
+!!! example "Evidence of Exploitation"
+
+    For example, whether exploitation modules are available in ExploitDB, Metasploit, or other sources is straightforward.
+    We hypothesize that searching Github and Pastebin for exploit code can be captured in a script.
+    A supplier or deployer could then define [*Exploitation*](../../reference/decision_points/exploitation.md) to take the value of [*PoC*](../../reference/decision_points/exploitation.md) if
+    there are positive search results for a set of inputs derived from the CVE entry in at least one of these venues.
+    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.
+
+!!! example "Evidence of Exposure"
+
+    Exposure 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
+vulnerability is usually straightforward.
+
+Stakeholders who use the prioritization method should consider releasing the priority with which they handled the
+vulnerability.
+This disclosure has various benefits.
+For example, if the supplier publishes a priority ranking, then deployers could consider that in their decision-making
+process.
+One reasonable way to include it is to break ties for the deployer.
+If a deployer has three “scheduled” vulnerabilities to remediate, they may address them in any order.
+If two vulnerabilities were produced by the supplier as “scheduled” patches, and one was “out-of-cycle,” then the
+deployer may want to use that information to favor the latter.
+
+### Suggested Default Values
+
+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"
+
+    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 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).
+    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).
+
+
+!!! 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).
+
+The resulting decision set `{none, open, yes, medium}` results in a scheduled patch application in our recommended
+deployer tree.
+

docs/howto/bootstrap/index.md

@@ -18,7 +18,7 @@ Using SSVC to prioritize vulnerability response requires a few steps. The steps
         r --> dataops
     ```
 
-{% include-markdown "howto/bootstrap/steps_table.md" %}
+{% include-markdown "howto/bootstrap/_steps_table.md" %}
 
 We cover each of these in the following sections, starting with [Prepare to Use SSVC](prepare.md).
 If you want to skip ahead to the full process, see [Bootstrapping SSVC Summary](summary.md).

docs/howto/bootstrap/prepare.md

@@ -34,10 +34,10 @@ We will go through each step in detail.
 
     Decisions we have modeled with SSVC include:
 
-    - [Patch Supplier Prioritization](supplier_tree.md)
-    - [Patch Deployer Prioritization](deployer_tree.md)
-    - [Coordinator Triage](coordinator_trees.md)
-    - [Coordinator Publication](coordinator_publish_tree.md)
+    - [Patch Supplier Prioritization](../supplier_tree.md)
+    - [Patch Deployer Prioritization](../deployer_tree.md)
+    - [Coordinator Triage](../coordination_decisions.md)
+    - [Coordinator Publication](../publication_decision.md)
 
 The first step in preparing to use SSVC is to choose a decision to model.
 SSVC is designed to help you make decisions about how to respond to a vulnerability.
@@ -60,9 +60,9 @@ flowchart LR
 
 !!! example inline end
 
-     In the [Patch Supplier](supplier_tree.md) and [Patch Deployer](deployer_tree) prioritization examples, the outcomes are:
-     _Defer_, _Scheduled_, _Out-of-Cycle_, and _Immediate_. In the [Coordinator Triage](coordinator_trees.md) example,
-     the outcomes are _Coordinate_, _Track_, and _Decline_. In the [Coordinator Publication](coordinator_publish_tree.md) example,
+     In the [Patch Supplier](../supplier_tree.md) and [Patch Deployer](../deployer_tree.md) prioritization examples, the outcomes are:
+     _Defer_, _Scheduled_, _Out-of-Cycle_, and _Immediate_. In the [Coordinator Triage](../coordination_decisions.md) example,
+     the outcomes are _Coordinate_, _Track_, and _Decline_. In the [Coordinator Publication](../publication_decision.md) example,
      the outcomes are _Publish_ and _Do Not Publish_.
 
 Once you have chosen a decision to model, you need to define the outcomes for that decision.
@@ -109,7 +109,7 @@ Once you know what decision you want to make and what the possible outcomes are,
 A decision usually requires more than one piece of information.
 SSVC organizes this information into decision points.
 A single decision point enumerates a set of options for a particular aspect of the decision.
-We have defined a number of decision points in the [SSVC documentation](../reference/decision_points/index.md).
+We have defined a number of decision points in the [SSVC documentation](../../reference/decision_points/index.md).
 You can choose from these decision points, or you can define your own decision points to meet your needs.
 
 Whether you choose from the existing decision points or define your own, the set of decision points you use to make a 
@@ -159,7 +159,7 @@ Now, you need to define the policy you want to use to make that decision.
 A policy is a function that takes a set of decision point values as input and returns an outcome as output.
 While we often choose to represent policies as decision trees, they can be represented in other ways as well.
 In fact, we find that it is often useful to represent policies in tabular form, for example as a CSV file.
-We have provided a number of example policies in the [SSVC documentation](../prioritization.md), but you can define your own policy to meet your needs.
+We have provided a number of example policies in the [SSVC documentation](../index.md), but you can define your own policy to meet your needs.
 
 ```mermaid
 flowchart LR
@@ -181,11 +181,11 @@ flowchart LR
 !!! example
 
      A small bank has a policy that they must deploy patches within 48 hours of release if the vulnerability affects systems
-     that could lead to customer data being exposed. They examine the example [Deployer Prioritization](supplier_tree.md)
+     that could lead to customer data being exposed. They examine the example [Deployer Prioritization](../supplier_tree.md)
      decision model and decide that both the outcome set and the decision point set that define the structure of the
      decision model are appropriate for their needs. They map the 48 hour requirement to the _Immediate_ outcome, because
      it essentially represents their highest priority response.
-     However, they notice that the specific policy given in the [Deployer Prioritization](supplier_tree.md)
+     However, they notice that the specific policy given in the [Deployer Prioritization](../supplier_tree.md)
      example—that is, the mapping from decision point values to outcomes—is not appropriate for their needs
      because it has too few _Immediate_ outcomes to suit their policy.
      Therefore, the bank decides to reuse the same decision point set and outcome set but define their own policy.
@@ -220,7 +220,7 @@ flowchart LR
 !!! example
 
     A Software-as-a-Service Provider differentiates its service levels into three categories: silver, gold, and platinum.
-    In the [Define Inputs](#define-inputs) step, they defined a custom decision point called _Service Level_ with the values
+    In the Define Inputs step, they defined a custom decision point called _Service Level_ with the values
     _Silver_, _Gold_, and _Platinum_.
     Now, they need to define a data map that will assign a value to the _Service Level_ decision point.
     The data they need to assign a value to the _Service Level_ decision point originates in the service level

docs/howto/bootstrap/summary.md

@@ -2,7 +2,7 @@
 
 Using SSVC to prioritize vulnerability response requires a few steps. The steps are:
 
-{% include-markdown "howto/bootstrap/steps_table.md" %}
+{% include-markdown "howto/bootstrap/_steps_table.md" %}
 
 We covered each of these in the previous sections, see the links in the table above for more information.