From 711448dcf11ecc504d28fb35bc00013721f26c9b Mon Sep 17 00:00:00 2001 From: Renae Metcalf Date: Fri, 3 Apr 2026 15:37:57 -0400 Subject: [PATCH 1/8] Add admonition box --- docs/topics/decision_trees.md | 93 ++++++++++++++++++++++++----------- 1 file changed, 65 insertions(+), 28 deletions(-) diff --git a/docs/topics/decision_trees.md b/docs/topics/decision_trees.md index 8e03ce6c..1ce20da0 100644 --- a/docs/topics/decision_trees.md +++ b/docs/topics/decision_trees.md @@ -1,43 +1,78 @@ # Decision Trees -A decision tree is an acyclic structure where nodes represent aspects of the decision or relevant properties and branches represent possible options for each aspect or property. -Each decision point can have two or more options. +!!! note inline end "About the term "decision tree"" -Decision trees can be used to meet all of the design goals, even plural recommendations and transparent tree-construction processes. -Decision trees support plural recommendations because a separate tree can represent each stakeholder group. -The opportunity for transparency surfaces immediately: any deviation among the decision trees for different stakeholder groups should have a documented reason—supported by public evidence when possible—for the deviation. -Transparency may be difficult to achieve, since each node in the tree and each of the values need to be explained and justified, but this cost is paid infrequently. + In machine learning, a decision tree usually refers to a model learned from + data through statistical analysis. That’s not what SSVC uses the term for. In + the original SSVC documentation, decision tree referred to the + operations-research concept: a hand-crafted structure that encodes deliberate + choices, not a model inferred from datasets. -There has been limited but positive use of decision trees in vulnerability management. -For example, Vulnerability Response Decision Assistance (VRDA) studies how to make decisions about how to respond to vulnerability reports [@manion2009vrda]. -This paper continues roughly in the vein of such work to construct multiple decision trees for prioritization within the vulnerability management process. + Starting in SSVC v2025.9, we shifted to the term decision table to avoid + confusion with the ML meaning. For more information, see + [ADR-0014](../../docs/adr/0014-decision-tree-vs-decision-table.md). + +A decision tree is an acyclic structure where nodes represent aspects of the +decision or relevant properties and branches represent possible options for each +aspect or property. Each decision point can have two or more options. + +Decision trees can be used to meet all of the design goals, even plural +recommendations and transparent tree-construction processes. Decision trees +support plural recommendations because a separate tree can represent each +stakeholder group. The opportunity for transparency surfaces immediately: any +deviation among the decision trees for different stakeholder groups should have +a documented reason—supported by public evidence when possible—for the +deviation. Transparency may be difficult to achieve, since each node in the +tree and each of the values need to be explained and justified, but this cost is +paid infrequently. + +There has been limited but positive use of decision trees in vulnerability +management. For example, Vulnerability Response Decision Assistance (VRDA) +studies how to make decisions about how to respond to vulnerability reports +[@manion2009vrda]. This paper continues roughly in the vein of such work to +construct multiple decision trees for prioritization within the vulnerability +management process. ## Representation choices -A decision tree can represent the same content in different ways. -Since a decision tree is a representation of logical relationships between qualitative variables, the equivalent content can be represented in other formats as well. -The R package [data.tree](https://cran.r-project.org/web/packages/data.tree/data.tree.pdf) has a variety of both internal representations and visualizations. +A decision tree can represent the same content in different ways. Since a +decision tree is a representation of logical relationships between qualitative +variables, the equivalent content can be represented in other formats as well. +The R package +[data.tree](https://cran.r-project.org/web/packages/data.tree/data.tree.pdf) has +a variety of both internal representations and visualizations. -For data input, we elected to keep SSVC simpler than R, and just use a CSV (or other fixed-delimiter separated file) as canonical data input. -All visualizations of a tree should be built from a canonical CSV that defines the decisions for that stakeholder. -Examples are located in [SSVC/data](https://github.com/CERTCC/SSVC/tree/main/data). -An interoperable CSV format is also flexible enough to support a variety of uses. -Every situation in SSVC is defined by the values for each decision point and the priority label (outcome) for that situation (as defined in [Likely Decision Points and Relevant Data](../reference/decision_points/index.md)). -A CSV will typically be 30-100 rows that each look something like: +For data input, we elected to keep SSVC simpler than R, and just use a CSV (or +other fixed-delimiter separated file) as canonical data input. All +visualizations of a tree should be built from a canonical CSV that defines the +decisions for that stakeholder. Examples are located in +[SSVC/data](https://github.com/CERTCC/SSVC/tree/main/data). An interoperable +CSV format is also flexible enough to support a variety of uses. Every +situation in SSVC is defined by the values for each decision point and the +priority label (outcome) for that situation (as defined in [Likely Decision +Points and Relevant Data](../reference/decision_points/index.md)). A CSV will +typically be 30-100 rows that each look something like: ``` 2,none,laborious,partial,significant,scheduled ``` -Where “2” is the row number, [*none*](../reference/decision_points/exploitation.md) through [*significant*](../reference/decision_points/public_safety_impact.md) are values for decision points, and *scheduled* is a priority label or outcome. -Different stakeholders will have different decision points (and so different options for values) and different outcomes, but this is the basic shape of a CSV file to define SSVC stakeholder decisions. +Where “2” is the row number, +[*none*](../reference/decision_points/exploitation.md) through +[*significant*](../reference/decision_points/public_safety_impact.md) are values +for decision points, and *scheduled* is a priority label or outcome. Different +stakeholders will have different decision points (and so different options for +values) and different outcomes, but this is the basic shape of a CSV file to +define SSVC stakeholder decisions. ### Visualizing Decision Trees -The tree visualization options are more diverse. -We provide an example format, and codified it in [src/SSVC_csv-to-latex.py](https://github.com/CERTCC/SSVC/tree/main/src). -Why have we gone to this trouble when (for example) the R data.tree package has a handy print-to-ASCII function? -Because this function produces output like the following: +The tree visualization options are more diverse. We provide an example format, +and codified it in +[src/SSVC_csv-to-latex.py](https://github.com/CERTCC/SSVC/tree/main/src). Why +have we gone to this trouble when (for example) the R data.tree package has a +handy print-to-ASCII function? Because this function produces output like the +following: ``` 1 start @@ -52,7 +87,9 @@ Because this function produces output like the following: 35 ¦ ¦ ¦ ¦ ¦ ¦ ¦--A:H Critical ``` -This sample is a snippet of the CVSS version 3.0 base scoring algorithm represented as a decision tree. -The full tree can be found [here](cvss_full_tree.md). -This tree representation is functional, but not as flexible or aesthetic as might be hoped. -The visualizations provided by R are geared towards analysis of decision trees in a random forest ML model, rather than operations-research type trees. +This sample is a snippet of the CVSS version 3.0 base scoring algorithm +represented as a decision tree. The full tree can be found +[here](cvss_full_tree.md). This tree representation is functional, but not as +flexible or aesthetic as might be hoped. The visualizations provided by R are +geared towards analysis of decision trees in a random forest ML model, rather +than operations-research type trees. From 88dae2a8c474a4676c6b867e719f0b08310c43e5 Mon Sep 17 00:00:00 2001 From: Renae Metcalf Date: Fri, 3 Apr 2026 15:44:54 -0400 Subject: [PATCH 2/8] Change footnote cite to hyperlink --- docs/topics/decision_trees.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/topics/decision_trees.md b/docs/topics/decision_trees.md index 1ce20da0..49bbfc6b 100644 --- a/docs/topics/decision_trees.md +++ b/docs/topics/decision_trees.md @@ -27,11 +27,11 @@ tree and each of the values need to be explained and justified, but this cost is paid infrequently. There has been limited but positive use of decision trees in vulnerability -management. For example, Vulnerability Response Decision Assistance (VRDA) -studies how to make decisions about how to respond to vulnerability reports -[@manion2009vrda]. This paper continues roughly in the vein of such work to -construct multiple decision trees for prioritization within the vulnerability -management process. +management. For example, [Vulnerability Response Decision Assistance +(VRDA)](https://www.sei.cmu.edu/library/effectiveness-of-the-vulnerability-response-decision-assistance-vrda-framework) +studies how to make decisions about how to respond to vulnerability reports . +This paper continues roughly in the vein of such work to construct multiple +decision trees for prioritization within the vulnerability management process. ## Representation choices From d5fc9d37e157bbed2bba94af98ddcc1a85234ddd Mon Sep 17 00:00:00 2001 From: Renae Metcalf Date: Fri, 3 Apr 2026 15:59:21 -0400 Subject: [PATCH 3/8] Make admonition box an includable --- docs/_includes/ADR0014.md | 12 ++++++++++++ docs/topics/decision_trees.md | 12 +----------- 2 files changed, 13 insertions(+), 11 deletions(-) create mode 100644 docs/_includes/ADR0014.md diff --git a/docs/_includes/ADR0014.md b/docs/_includes/ADR0014.md new file mode 100644 index 00000000..5b2f4259 --- /dev/null +++ b/docs/_includes/ADR0014.md @@ -0,0 +1,12 @@ +!!! note inline end "About the term "decision tree"" + + In machine learning, a decision tree usually refers to a model learned from + data through statistical analysis. That’s not what SSVC uses the term for. In + the original SSVC documentation, decision tree referred to the + operations-research concept: a hand-crafted structure that encodes deliberate + choices, not a model inferred from datasets. + + Starting in SSVC v2025.9, we shifted to the term decision table to avoid + confusion with the ML meaning. For more information, see + [ADR-0014](../../docs/adr/0014-decision-tree-vs-decision-table.md). + diff --git a/docs/topics/decision_trees.md b/docs/topics/decision_trees.md index 49bbfc6b..86fdd5b3 100644 --- a/docs/topics/decision_trees.md +++ b/docs/topics/decision_trees.md @@ -1,16 +1,6 @@ # Decision Trees -!!! note inline end "About the term "decision tree"" - - In machine learning, a decision tree usually refers to a model learned from - data through statistical analysis. That’s not what SSVC uses the term for. In - the original SSVC documentation, decision tree referred to the - operations-research concept: a hand-crafted structure that encodes deliberate - choices, not a model inferred from datasets. - - Starting in SSVC v2025.9, we shifted to the term decision table to avoid - confusion with the ML meaning. For more information, see - [ADR-0014](../../docs/adr/0014-decision-tree-vs-decision-table.md). +{% include-markdown "../_includes/ADR0014.md" %} A decision tree is an acyclic structure where nodes represent aspects of the decision or relevant properties and branches represent possible options for each From 6ffa47e55fdec58d1284745595a01fb2b7ee78b7 Mon Sep 17 00:00:00 2001 From: Renae Metcalf Date: Fri, 3 Apr 2026 16:02:06 -0400 Subject: [PATCH 4/8] handle 991 as well --- docs/topics/formalization_options.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/topics/formalization_options.md b/docs/topics/formalization_options.md index 75d8d14e..8f911feb 100644 --- a/docs/topics/formalization_options.md +++ b/docs/topics/formalization_options.md @@ -1,5 +1,7 @@ # Formalization Options +{% include-markdown "../_includes/ADR0014.md" %} + This section briefly surveys the available formalization options against the six design goals described above. The table below summarizes the results. This survey is opportunistic; it is based on conversations with several experts and our professional experience. From 97b6eb3d877b7471529ed8dc0a800fa35dbb0365 Mon Sep 17 00:00:00 2001 From: Renae Metcalf Date: Fri, 3 Apr 2026 16:04:37 -0400 Subject: [PATCH 5/8] fix brokenlink --- docs/_includes/ADR0014.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_includes/ADR0014.md b/docs/_includes/ADR0014.md index 5b2f4259..239d24f2 100644 --- a/docs/_includes/ADR0014.md +++ b/docs/_includes/ADR0014.md @@ -8,5 +8,5 @@ Starting in SSVC v2025.9, we shifted to the term decision table to avoid confusion with the ML meaning. For more information, see - [ADR-0014](../../docs/adr/0014-decision-tree-vs-decision-table.md). + [ADR-0014](../../docs/adr/0014-use-decision-table-terminology.md). From c7cfd40f9877c08f62abd3c8e06b6026e6131f87 Mon Sep 17 00:00:00 2001 From: sei-renae Date: Fri, 3 Apr 2026 16:05:56 -0400 Subject: [PATCH 6/8] Update docs/topics/decision_trees.md remove stray space Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/topics/decision_trees.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/topics/decision_trees.md b/docs/topics/decision_trees.md index 86fdd5b3..004b38fa 100644 --- a/docs/topics/decision_trees.md +++ b/docs/topics/decision_trees.md @@ -19,7 +19,7 @@ paid infrequently. There has been limited but positive use of decision trees in vulnerability management. For example, [Vulnerability Response Decision Assistance (VRDA)](https://www.sei.cmu.edu/library/effectiveness-of-the-vulnerability-response-decision-assistance-vrda-framework) -studies how to make decisions about how to respond to vulnerability reports . +studies how to make decisions about how to respond to vulnerability reports. This paper continues roughly in the vein of such work to construct multiple decision trees for prioritization within the vulnerability management process. From f8027d899c374291dbe1302db383a2b843c2307a Mon Sep 17 00:00:00 2001 From: Renae Metcalf Date: Fri, 3 Apr 2026 16:09:18 -0400 Subject: [PATCH 7/8] really fix the link --- docs/_includes/ADR0014.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/_includes/ADR0014.md b/docs/_includes/ADR0014.md index 239d24f2..ebfbe436 100644 --- a/docs/_includes/ADR0014.md +++ b/docs/_includes/ADR0014.md @@ -8,5 +8,4 @@ Starting in SSVC v2025.9, we shifted to the term decision table to avoid confusion with the ML meaning. For more information, see - [ADR-0014](../../docs/adr/0014-use-decision-table-terminology.md). - + [ADR-0014](../docs/adr/0014-use-decision-table-terminology.md). From 3088e245c2e88c6a98432e3150c1c7604cdeee97 Mon Sep 17 00:00:00 2001 From: Renae Metcalf Date: Fri, 3 Apr 2026 16:13:49 -0400 Subject: [PATCH 8/8] rebase --- docs/_includes/ADR0014.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_includes/ADR0014.md b/docs/_includes/ADR0014.md index ebfbe436..787b159c 100644 --- a/docs/_includes/ADR0014.md +++ b/docs/_includes/ADR0014.md @@ -8,4 +8,4 @@ Starting in SSVC v2025.9, we shifted to the term decision table to avoid confusion with the ML meaning. For more information, see - [ADR-0014](../docs/adr/0014-use-decision-table-terminology.md). + [ADR-0014](../adr/0014-use-decision-table-terminology.md).