Reorganize HowTo section (#379)

* reorg nav

* use page includes to merge docs

* add/fix headings

* update nav

* merge intros

* reorder nav

* refactor coordinator sections

docs/howto/bootstrap/collect.md

@@ -43,3 +43,4 @@ 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 %}

docs/howto/bootstrap/use.md

@@ -81,4 +81,6 @@ flowchart LR
     Medical device manufacturers might need to develop patches, notify regulators of the vulnerability, and provide 
     instructions to hospital users 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.
+    within the response process.
+
+{% include-markdown '../communicating_results.md' heading-offset=1 %}

docs/howto/communicating_results.md

@@ -129,16 +129,20 @@ As an initial heuristic, we suggest the associated polling frequency for each.
 These frequencies can be customized, as the update frequency is directly related to the organization's tolerance for the risk that the information is out of date.
 As discussed in [Tree Construction and Customization Guidance](#tree-construction-and-customization-guidance), risk tolerance is unique to each organization.
 Risk tolerance and risk appetite are primarily reflected in the priority labels (that is, decisions) encoded in the SSVC decision tree, but information polling frequency is also a risk tolerance decision and each organization may choose different time values.
- - [*Exploitation*](#exploitation): every 1 day
- - [*Technical Impact*](#technical-impact): never (should be static per vulnerability)
- - [*Utility*](#utility): every 6 months
- - [*Public Safety Impact*](#public-safety-impact): every 1 year
+
+| Decision Point                                                                 | Suggested Polling Frequency |
+|--------------------------------------------------------------------------------|-----------------------------|
+| [*Exploitation*](../reference/decision_points/exploitation.md)                 | every 1 day |
+| [*Technical Impact*](../reference/decision_points/technical_impact.md)         | never (should be static per vulnerability) |
+| [*Utility*](../reference/decision_points/utility.md)                           | every 6 months |
+| [*Public Safety Impact*](../reference/decision_points/public_safety_impact.md) | every 1 year |
+
 
 The following decision points are usually in the control of the organization running SSVC and should be reevaluated when a relevant change is made or during annual reviews of assets.
 
- - [*Situated Safety Impact*](#situated-safety-impact)
- - [*Mission Impact*](#mission-impact)
- - [*System Exposure*](#system-exposure)
+ - [*Situated Safety Impact*](../reference/decision_points/safety_impact.md)
+ - [*Mission Impact*](../reference/decision_points/mission_impact.md)
+ - [*System Exposure*](../reference/decision_points/system_exposure.md)
 
 If SSVC information is all timestamped appropriately (as discussed earlier in this section), then an analyst can compare the timestamp to the current date and determine whether information is considered stale.
 The above rates are heuristic suggestions, and organizations may choose different ones.

docs/howto/coordination_decisions.md

@@ -1,29 +1,4 @@
-
-# Decisions During Vulnerability Coordination
-
-Coordinators are facilitators within the vulnerability management ecosystem.
-Since coordinators neither supply nor deploy the vulnerable component in question, their decisions are different from suppliers' or deployers' decisions.
-This section provides a window into CERT/CC's decisions as an example of how a coordinator might use SSVC to make its own decisions.
-
-Coordinators vary quite a lot, and their use of SSVC may likewise vary.
-A coordinator may want to gather and publish information about SSVC decision points that it does not use internally in order to assist its constituents.
-Furthermore, a coordinator may only publish some of the information it uses to make decisions.
-Consistent with other stakeholder perspectives (supplier and deployer), SSVC provides the priority with which a coordinator should take some defined action, but not how to do that action.
-For more information about types of coordinators and their facilitation actions within vulnerability management, see [@householder2020cvd].
-
-The two decisions that CERT/CC makes as a coordinator that we will discuss in terms of SSVC are the initial triage of vulnerability reports and whether a publication about a vulnerability is warranted.
-The initial coordination decision is a prioritization decision, but it does not have the same values as prioritization by a deployer or supplier.
-The publication decision for us is a binary yes/no.
-These two decisions are not the entirety of vulnerability coordination, but we leave further details of the process for future work.
-
-Different coordinators have different scopes and constituencies.
-See [@householder2020cvd, 3.5] for a listing of different coordinator types.
-If a coordinator receives a report that is outside its own work scope or constituency, it should make an effort to route the report to a more suitable coordinator.
-The decisions in this section assume the report or vulnerability in question is in the work scope or constituency for the coordinator.
-
-
-
-## Coordination Triage Decisions
+# Coordination Triage Decisions
 
 We take three priority levels in our decision about whether and how to coordinate a vulnerability [@householder2020cvd, 1.1] based on an incoming report:
 
@@ -41,6 +16,9 @@ To assess this, the decision involves five new decision points.
 
 {== TODO link to specific decision points ==}
 
+
+
+
 ## Coordination Triage Decision Process
 
 The decision tree for reaching a [Decision](#coordination-triage-decisions) involves seven decision points.
@@ -53,4 +31,4 @@ In the second case, CERT/CC may encourage the reporter to contact the supplier a
 These two sets of exceptional circumstances mean that the seven decision points involved in the coordination triage tree can be compressed slightly, as the tree shows.
 This tree's information is available as either a [CSV](https://github.com/CERTCC/SSVC/blob/main/data/ssvc_2_coord-triage.csv) or [PDF](https://github.com/CERTCC/SSVC/blob/main/doc/graphics/ssvc_2_coord-triage.pdf)
 
-{== TODO merge with [Coordinator Trees](coordinator_trees.md)? ==}
+{% include-markdown './coordinator_trees.md' heading-offset=1 %}

docs/howto/coordination_intro.md

@@ -0,0 +1,23 @@
+# Decisions During Vulnerability Coordination
+
+Coordinators are facilitators within the vulnerability management ecosystem.
+Since coordinators neither supply nor deploy the vulnerable component in question, their decisions are different from suppliers' or deployers' decisions.
+This section provides a window into CERT/CC's decisions as an example of how a coordinator might use SSVC to make its own decisions.
+
+Coordinators vary quite a lot, and their use of SSVC may likewise vary.
+A coordinator may want to gather and publish information about SSVC decision points that it does not use internally in order to assist its constituents.
+Furthermore, a coordinator may only publish some of the information it uses to make decisions.
+Consistent with other stakeholder perspectives (supplier and deployer), SSVC provides the priority with which a coordinator should take some defined action, but not how to do that action.
+For more information about types of coordinators and their facilitation actions within vulnerability management, see [@householder2020cvd].
+
+The two decisions that CERT/CC makes as a coordinator that we will discuss in terms of SSVC are the initial triage of vulnerability reports and whether a publication about a vulnerability is warranted.
+The initial coordination decision is a prioritization decision, but it does not have the same values as prioritization by a deployer or supplier.
+The publication decision for us is a binary yes/no.
+These two decisions are not the entirety of vulnerability coordination, but we leave further details of the process for future work.
+
+Different coordinators have different scopes and constituencies.
+See [@householder2020cvd, 3.5] for a listing of different coordinator types.
+If a coordinator receives a report that is outside its own work scope or constituency, it should make an effort to route the report to a more suitable coordinator.
+The decisions in this section assume the report or vulnerability in question is in the work scope or constituency for the coordinator.
+
+

docs/howto/coordinator_trees.md

@@ -1,8 +1,4 @@
-# Coordinator Trees
-
-As described in [Decisions During Vulnerability Coordination](#decisions-during-vulnerability-coordination), a coordination stakeholder usually makes separate triage and publication decisions. Each have trees presented below.
-
-## Triage Decision Tree
+# Triage Decision Tree
 
 <embed src="../../pdf/ssvc_2_coord-triage.pdf" alt="Coordination Triage Tree" type="application/pdf"
 style="width: 100%;"
@@ -11,7 +7,7 @@ height = "700" />
 This tree is a suggestion in that CERT/CC believes it works for us.
 Other coordinators should consider customizing the tree to their needs, as described in [Tree Construction and Customization Guidance](#tree-construction-and-customization-guidance).
 
-### Table of Values
+## Table of Values
 
 {{ read_csv('../../data/csvs/coord-triage-options.csv') }}
 

docs/howto/index.md

@@ -23,3 +23,4 @@
     - how to integrate SSVC into existing processes
     - how to integrate data sources into SSVC decision points
 
+{% include-markdown './prioritization.md' heading-offset=1 %}

docs/howto/tree_customization.md

@@ -1,23 +1,30 @@
-# Tree Construction and Customization Guidance
+# Modeling Other Decisions and Customization Guidance
 
 Stakeholders are encouraged to customize the SSVC decision process to their needs.
 Indeed, the first part of SSVC stands for “stakeholder-specific."
 However, certain parts of SSVC are more amenable to customization than others.
 In this section, we'll cover what a stakeholder should leave static, what we imagine customization looks like, and some advice on building a usable and manageable decision tree based on our experience so far.
 
+## Use Existing Decision Points Where Possible
+
 We suggest that the decision points, their definitions, and the decision values should not be customized.
 Different vulnerability management teams inevitably think of topics such as [*Utility*](#utility) to the adversary in slightly different ways.
 However, a key contribution of SSVC is enabling different teams to communicate about their decision process.
 In order to clearly communicate differences in the process, the decision points that factor into the process need to be the same between different teams.
 A stakeholder community may come together and, if there is broad consensus, add or change decision points.
 
-Which decision points are involved in a vulnerability management team's decision and the priority label for each resulting situation are, for all intents and purposes, totally at the discretion of the team.
+## Customizing a Decision Model
+
+Which decision points are involved in a vulnerability management team's 
+decision and the priority label for each resulting situation are, for all intents and purposes, totally at the discretion of the team.
 We have provided some examples for different stakeholder communities here.
 What decision points a team considers reflects what it cares about and the risks prioritizes.
 Different teams may legitimately prioritize different objectives.
 It should be easier for teams to discuss and communicate such differences if the definitions of the decision points remain static.
 The other aspect of risk management that SSVC allows a team to customize is its risk appetite or risk tolerance.
 
+### Customizing for Risk Appetite
+
 A team's risk appetite is reflected directly by the priority labels for each combination of decision values.
 For example, a vulnerability with [no or minor](#public-safety-impact) [*Public Safety Impact*](#public-safety-impact), [total](#technical-impact) [*Technical Impact*](#technical-impact), and [efficient](#utility) [*Utility*](#utility) might be handled with [*scheduled*](#supplier-decisions) priority by one team and [*out-of-cycle*](#supplier-decisions) priority by another.
 As long as each team has documented this choice and is consistent in its own application of its own choice, the two teams can legitimately have different appetites for vulnerability risk.
@@ -37,7 +44,7 @@ In our case, we are not attempting to fit a tree to data.
 Rather, we are interested in producing usable trees that minimize extraneous effort.
 To that end, we briefly examine the qualities for which decision tree measurement is suitable.
 
-### Decision Tree Construction Concerns
+## Decision Tree Construction Concerns
 
 Decision tree construction methods must address five significant concerns: 
 - feature selection 
@@ -46,7 +53,7 @@ Decision tree construction methods must address five significant concerns:
 - parsimony
 - versioning
 
-#### Feature selection
+### Feature selection
 
 Feature selection is perhaps the most important consideration for SSVC, because it directly affects the information gathering requirements placed on the analyst attempting to use the tree.
 Each decision point in SSVC is a feature.
@@ -58,18 +65,19 @@ If nothing else, this means analysts are spending time gathering evidence to mak
 The added details also make it harder for the decision process to accurately manage the risks in question.
 This difficulty arises because more variance and complexity there is in the decision increases the possibility of errors in the decision process itself.
 
-#### Feature types
+### Feature types
 
 Regarding feature types, all of the features included in SSVC version 2 can be considered ordinal data.
 That is, while they can be ordered (e.g., for Exploitation, active is greater than poc is greater than none), they can not be compared via subtraction or division (active - poc = nonsense).
 The use of ordinal features is a key assumption behind our use of the parsimony analysis that follows.
 
-#### Overfitting
+### Overfitting
 
 When decision trees are used in a machine learning context, overfitting increases tree complexity by incorporating the noise in the training data set into the decision points in a tree.
 In our case, our “data” is just the set of outcomes as decided by humans, so overfitting is less of a concern, assuming the feature selection has been done with care.
 
-#### Parsimony 
+### Parsimony 
+
 Parsimony is, in essence, Occam's Razor applied to tree selection. Given the choice between two trees that have identical outputs, one should choose the tree with fewer decisions.
 One way to evaluate the parsimony of a tree is by applying the concept of feature importance to ensure that each feature is contributing adequately to the result.
 While there are a few ways to compute feature importance, the one we found most useful is permutation importance.
@@ -98,12 +106,12 @@ This sort of customization is often the simplest way to adjust the importance of
 While there is no hard and fast rule for when a tree is too big, we suggest that if all of your outcomes are associated with more than 15 situations (unique combinations of decision values), you would benefit from asking whether your analysts actually use all the information they would be gathering.
 Thus, 60 unique combinations of decision values is the point at which a decision tree with four distinct outcomes is, on average, potentially too big.
 
-#### Tree Versioning
+### Tree Versioning
 
 SSVC trees should be identifiable by name and version. A tree name is simply a short descriptive label for the tree derived from the stakeholder and/or function the tree is intended for. Tree versions are expected to share the major and minor version numbers with the SSVC version in which their decision points are defined. Revisions should increment the patch number. For example: “Applier Tree v1.1.0” would be the identity of the version of the Applier Tree as published in version 1.1 of SSVC.
 “Coordinator Publish Tree v2.0.3” would be the identity of a future revision of the Coordinator Publish Tree as described in this document. The terms “major”, “minor”, and “patch” with respect to version numbering are intended to be consistent with [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
-### Sharing Trees With Others
+## Sharing Trees With Others
 
 Communities of shared interest may desire to share information about decision points or even create custom trees to share within their community.
 Examples include:
@@ -116,7 +124,7 @@ In these and other scenarios, there are two scopes to consider:
 1. Decision Point Scope
 2. Decision Tree Scope
 
-#### Decision Point Scope
+### Decision Point Scope
 
 Each decision point defined in this document has a characteristic scope, either *stakeholder-agnostic* or *stakeholder-specific*.
 
@@ -151,7 +159,7 @@ E.g., a financial institution might have a very low tolerance for changes to a t
 - A decision point that indicates whether the affected software belongs to a list of critical software for a specific constituency.
 E.g., an open-source consortium might want to prioritize fix development for a set of key projects.
 
-#### Decision Tree Scope
+### Decision Tree Scope
 
 Two kinds of modifications are possible at the decision tree level.
 

mkdocs.yml

@@ -33,24 +33,22 @@ nav:
     - Future Work: 'topics/future_work.md'
   - SSVC How-To:
     - Intro: 'howto/index.md'
-    - Coordination Decision: 'howto/coordination_decisions.md'
-    - Publication Decision: 'howto/publication_decision.md'
-    - Prioritization:
-      - Intro: 'howto/prioritization.md'
-      - Supplier Tree: 'howto/supplier_tree.md'
-      - Deployer Tree: 'howto/deployer_tree.md'
-      - Coordinator Triage Tree: 'howto/coordinator_trees.md'
-      - Coordinator Publication Tree: 'howto/coordinator_publish_tree.md'
-    - Tree Customization: 'howto/tree_customization.md'
-    - Evidence Gathering: 'howto/evidence_gathering.md'
-    - Asset Management: 'howto/asset_management.md'
-    - Communicating Results: 'howto/communicating_results.md'
+    - Stakeholder Decision Models:
+        - Supplier Decision Model: 'howto/supplier_tree.md'
+        - Deployer Decision Model: 'howto/deployer_tree.md'
+        - Coordinator Decision Models:
+          - About Coordination: 'howto/coordination_intro.md'
+          - Coordination Decision: 'howto/coordination_decisions.md'
+          - Publication Decision: 'howto/publication_decision.md'
     - Bootstrapping SSVC:
       - Intro: 'howto/bootstrap/index.md'
       - Prepare: 'howto/bootstrap/prepare.md'
       - Collect: 'howto/bootstrap/collect.md'
       - Use & Respond: 'howto/bootstrap/use.md'
       - Summary: 'howto/bootstrap/summary.md'
+    - Customizing SSVC: 'howto/tree_customization.md'
+    - SSVC and Asset Management: 'howto/asset_management.md'
+
   - Reference:
     - Intro: 'reference/index.md'
     - Decision Points: