CERTCC · ahouseholder · Aug 25, 2025 · Aug 22, 2025 · Aug 22, 2025 · Aug 22, 2025
diff --git a/data/json/decision_tables/ssvc/public_safety_impact_1_0_0.json b/data/json/decision_tables/ssvc/public_safety_impact_1_0_0.json
@@ -0,0 +1,79 @@
+{
+  "namespace": "ssvc",
+  "key": "DT_PSI",
+  "version": "1.0.0",
+  "name": "Public Safety Impact",
+  "description": "Public Safety Impact Decision Table",
+  "schemaVersion": "2.0.0",
+  "decision_points": {
+    "ssvc:SI:2.0.0": {
+      "namespace": "ssvc",
+      "key": "SI",
+      "version": "2.0.0",
+      "name": "Safety Impact",
+      "description": "The safety impact of the vulnerability. (based on IEC 61508)",
+      "schemaVersion": "2.0.0",
+      "values": [
+        {
+          "key": "N",
+          "name": "Negligible",
+          "description": "Any one or more of these conditions hold.<br/><br/>- *Physical harm*: Minor injuries at worst (IEC 61508 Negligible).<br/>- *Operator resiliency*: Requires action by system operator to maintain safe system state as a result of exploitation of the vulnerability where operator actions would be well within expected operator abilities; OR causes a minor occupational safety hazard.<br/>- *System resiliency*: Small reduction in built-in system safety margins; OR small reduction in system functional capabilities that support safe operation.<br/>- *Environment*: Minor externalities (property damage, environmental damage, etc.) imposed on other parties.<br/>- *Financial*: Financial losses, which are not readily absorbable, to multiple persons.<br/>- *Psychological*: Emotional or psychological harm, sufficient to be cause for counselling or therapy, to multiple persons."
+        },
+        {
+          "key": "M",
+          "name": "Marginal",
+          "description": "Any one or more of these conditions hold.<br/><br/>- *Physical harm*: Major injuries to one or more persons (IEC 61508 Marginal).<br/>- *Operator resiliency*: Requires action by system operator to maintain safe system state as a result of exploitation of the vulnerability where operator actions would be within their capabilities but the actions require their full attention and effort; OR significant distraction or discomfort to operators; OR causes significant occupational safety hazard.<br/>- *System resiliency*: System safety margin effectively eliminated but no actual harm; OR failure of system functional capabilities that support safe operation.<br/>- *Environment*: Major externalities (property damage, environmental damage, etc.) imposed on other parties.<br/>- *Financial*: Financial losses that likely lead to bankruptcy of multiple persons.<br/>- *Psychological*: Widespread emotional or psychological harm, sufficient to be cause for counselling or therapy, to populations of people."
+        },
+        {
+          "key": "R",
+          "name": "Critical",
+          "description": "Any one or more of these conditions hold.<br/><br/>- *Physical harm*: Loss of life (IEC 61508 Critical).<br/>- *Operator resiliency*: Actions that would keep the system in a safe state are beyond system operator capabilities, resulting in adverse conditions; OR great physical distress to system operators such that they cannot be expected to operate the system properly.<br/>- *System resiliency*: Parts of the cyber-physical system break; system’s ability to recover lost functionality remains intact.<br/>- *Environment*: Serious externalities (threat to life as well as property, widespread environmental damage, measurable public health risks, etc.) imposed on other parties.<br/>- *Financial*: Socio-technical system (elections, financial grid, etc.) of which the affected component is a part is actively destabilized and enters unsafe state.<br/>- *Psychological*: N/A."
+        },
+        {
+          "key": "C",
+          "name": "Catastrophic",
+          "description": "Any one or more of these conditions hold.<br/><br/>- *Physical harm*: Multiple loss of life (IEC 61508 Catastrophic).<br/>- *Operator resiliency*: Operator incapacitated (includes fatality or otherwise incapacitated).<br/>- *System resiliency*: Total loss of whole cyber-physical system, of which the software is a part.<br/>- *Environment*: Extreme externalities (immediate public health threat, environmental damage leading to small ecosystem collapse, etc.) imposed on other parties.<br/>- *Financial*: Social systems (elections, financial grid, etc.) supported by the software collapse.<br/>- *Psychological*: N/A."
+        }
+      ]
+    },
+    "ssvc:PSI:2.0.1": {
+      "namespace": "ssvc",
+      "key": "PSI",
+      "version": "2.0.1",
+      "name": "Public Safety Impact",
+      "description": "A coarse-grained representation of impact to public safety.",
+      "schemaVersion": "2.0.0",
+      "values": [
+        {
+          "key": "M",
+          "name": "Minimal",
+          "description": "Safety Impact:Negligible"
+        },
+        {
+          "key": "S",
+          "name": "Significant",
+          "description": "Safety Impact:(Marginal OR Critical OR Catastrophic)"
+        }
+      ]
+    }
+  },
+  "outcome": "ssvc:PSI:2.0.1",
+  "mapping": [
+    {
+      "ssvc:SI:2.0.0": "N",
+      "ssvc:PSI:2.0.1": "M"
+    },
+    {
+      "ssvc:SI:2.0.0": "M",
+      "ssvc:PSI:2.0.1": "S"
+    },
+    {
+      "ssvc:SI:2.0.0": "R",
+      "ssvc:PSI:2.0.1": "S"
+    },
+    {
+      "ssvc:SI:2.0.0": "C",
+      "ssvc:PSI:2.0.1": "S"
+    }
+  ]
+}
diff --git a/data/json/ssvc_object_registry.json b/data/json/ssvc_object_registry.json
@@ -21869,6 +21869,93 @@
                 }
               }
             },
+            "DT_PSI": {
+              "key": "DT_PSI",
+              "versions": {
+                "1.0.0": {
+                  "version": "1.0.0",
+                  "obj": {
+                    "namespace": "ssvc",
+                    "key": "DT_PSI",
+                    "version": "1.0.0",
+                    "name": "Public Safety Impact",
+                    "description": "Public Safety Impact Decision Table",
+                    "schemaVersion": "2.0.0",
+                    "decision_points": {
+                      "ssvc:SI:2.0.0": {
+                        "namespace": "ssvc",
+                        "key": "SI",
+                        "version": "2.0.0",
+                        "name": "Safety Impact",
+                        "description": "The safety impact of the vulnerability. (based on IEC 61508)",
+                        "schemaVersion": "2.0.0",
+                        "values": [
+                          {
+                            "key": "N",
+                            "name": "Negligible",
+                            "description": "Any one or more of these conditions hold.<br/><br/>- *Physical harm*: Minor injuries at worst (IEC 61508 Negligible).<br/>- *Operator resiliency*: Requires action by system operator to maintain safe system state as a result of exploitation of the vulnerability where operator actions would be well within expected operator abilities; OR causes a minor occupational safety hazard.<br/>- *System resiliency*: Small reduction in built-in system safety margins; OR small reduction in system functional capabilities that support safe operation.<br/>- *Environment*: Minor externalities (property damage, environmental damage, etc.) imposed on other parties.<br/>- *Financial*: Financial losses, which are not readily absorbable, to multiple persons.<br/>- *Psychological*: Emotional or psychological harm, sufficient to be cause for counselling or therapy, to multiple persons."
+                          },
+                          {
+                            "key": "M",
+                            "name": "Marginal",
+                            "description": "Any one or more of these conditions hold.<br/><br/>- *Physical harm*: Major injuries to one or more persons (IEC 61508 Marginal).<br/>- *Operator resiliency*: Requires action by system operator to maintain safe system state as a result of exploitation of the vulnerability where operator actions would be within their capabilities but the actions require their full attention and effort; OR significant distraction or discomfort to operators; OR causes significant occupational safety hazard.<br/>- *System resiliency*: System safety margin effectively eliminated but no actual harm; OR failure of system functional capabilities that support safe operation.<br/>- *Environment*: Major externalities (property damage, environmental damage, etc.) imposed on other parties.<br/>- *Financial*: Financial losses that likely lead to bankruptcy of multiple persons.<br/>- *Psychological*: Widespread emotional or psychological harm, sufficient to be cause for counselling or therapy, to populations of people."
+                          },
+                          {
+                            "key": "R",
+                            "name": "Critical",
+                            "description": "Any one or more of these conditions hold.<br/><br/>- *Physical harm*: Loss of life (IEC 61508 Critical).<br/>- *Operator resiliency*: Actions that would keep the system in a safe state are beyond system operator capabilities, resulting in adverse conditions; OR great physical distress to system operators such that they cannot be expected to operate the system properly.<br/>- *System resiliency*: Parts of the cyber-physical system break; system’s ability to recover lost functionality remains intact.<br/>- *Environment*: Serious externalities (threat to life as well as property, widespread environmental damage, measurable public health risks, etc.) imposed on other parties.<br/>- *Financial*: Socio-technical system (elections, financial grid, etc.) of which the affected component is a part is actively destabilized and enters unsafe state.<br/>- *Psychological*: N/A."
+                          },
+                          {
+                            "key": "C",
+                            "name": "Catastrophic",
+                            "description": "Any one or more of these conditions hold.<br/><br/>- *Physical harm*: Multiple loss of life (IEC 61508 Catastrophic).<br/>- *Operator resiliency*: Operator incapacitated (includes fatality or otherwise incapacitated).<br/>- *System resiliency*: Total loss of whole cyber-physical system, of which the software is a part.<br/>- *Environment*: Extreme externalities (immediate public health threat, environmental damage leading to small ecosystem collapse, etc.) imposed on other parties.<br/>- *Financial*: Social systems (elections, financial grid, etc.) supported by the software collapse.<br/>- *Psychological*: N/A."
+                          }
+                        ]
+                      },
+                      "ssvc:PSI:2.0.1": {
+                        "namespace": "ssvc",
+                        "key": "PSI",
+                        "version": "2.0.1",
+                        "name": "Public Safety Impact",
+                        "description": "A coarse-grained representation of impact to public safety.",
+                        "schemaVersion": "2.0.0",
+                        "values": [
+                          {
+                            "key": "M",
+                            "name": "Minimal",
+                            "description": "Safety Impact:Negligible"
+                          },
+                          {
+                            "key": "S",
+                            "name": "Significant",
+                            "description": "Safety Impact:(Marginal OR Critical OR Catastrophic)"
+                          }
+                        ]
+                      }
+                    },
+                    "outcome": "ssvc:PSI:2.0.1",
+                    "mapping": [
+                      {
+                        "ssvc:SI:2.0.0": "N",
+                        "ssvc:PSI:2.0.1": "M"
+                      },
+                      {
+                        "ssvc:SI:2.0.0": "M",
+                        "ssvc:PSI:2.0.1": "S"
+                      },
+                      {
+                        "ssvc:SI:2.0.0": "R",
+                        "ssvc:PSI:2.0.1": "S"
+                      },
+                      {
+                        "ssvc:SI:2.0.0": "C",
+                        "ssvc:PSI:2.0.1": "S"
+                      }
+                    ]
+                  }
+                }
+              }
+            },
             "DT_SP": {
               "key": "DT_SP",
               "versions": {

diff --git a/docs/reference/code/decision_point_groups.md b/docs/reference/code/decision_point_groups.md
@@ -0,0 +1,18 @@
+# Decision Point Groups
+
+Decision Point groups provide collections of related Decision Points for some
+specific purpose.
+
+With the introduction of [Decision Tables](decision_tables.md), 
+Decision Point groups are less important than they once were, and may be
+deprecated in a future release.
+However, they can still be useful for documentation and
+for some programmatic uses.
+
+## SSVC Decision Point Groups
+
+::: ssvc.dp_groups.ssvc.collections
+
+## CVSS Decision Point Groups
+
+::: ssvc.dp_groups.cvss.collections
diff --git a/docs/reference/code/decision_points.md b/docs/reference/code/decision_points.md
@@ -0,0 +1,7 @@
+# Decision Point Objects
+
+::: ssvc.decision_points
+
+::: ssvc.decision_points.base
+
+::: ssvc.decision_points.helpers
diff --git a/docs/reference/code/decision_tables.md b/docs/reference/code/decision_tables.md
@@ -0,0 +1,7 @@
+# Decision Tables
+
+::: ssvc.decision_tables
+
+::: ssvc.decision_tables.base
+
+::: ssvc.decision_tables.helpers
diff --git a/docs/reference/code/index.md b/docs/reference/code/index.md
@@ -3,8 +3,9 @@
 This section provides documentation for the SSVC Python modules.
 These include:
 
+- [Decision Points](decision_points.md) and [Outcomes](outcomes.md) 
+- [Decision Tables](decision_tables.md)
 - [CSV Analyzer](analyze_csv.md)
 - [Policy Generator](policy_generator.md)
-- [Outcomes](outcomes.md)
 - [Namespaces](namespaces.md)
 - [Doctools](doctools.md)
diff --git a/docs/reference/decision_points/human_impact.md b/docs/reference/decision_points/human_impact.md
@@ -7,13 +7,6 @@ from ssvc.doc_helpers import example_block
 print(example_block(LATEST))
 ```
 
-!!! tip "See also"
-
-    *Human Impact* is a combination of [Safety Impact](./safety_impact.md) and
-    [Mission Impact](./mission_impact.md)
-
-Note: This is a compound decision point[^1], therefore it is a notational convenience.
-
 *Human Impact* is a combination of how a vulnerability can affect an organization's mission essential functions as well as
 safety considerations, whether for the organization's personnel or the public at large.
 We observe that the day-to-day operations of an organization often have already built in a degree of tolerance to small-scale variance in mission impacts.
@@ -25,7 +18,39 @@ Even small deviations in safety are unlikely to go unnoticed or unaddressed.
 We suspect that the presence of regulatory oversight for safety issues and its absence at the lower end of the mission impact scale influences this behavior.
 Because of this higher sensitivity to safety concerns, we chose to retain a four-level resolution for the safety dimension.
 We then combine Mission Impact with Situated Safety impact and map them onto a 4-tiered scale (Low, Medium, High, Very High).
-The mapping is shown in the table above.
+
+!!! tip "See also"
+
+    *Human Impact* is a combination of [Safety Impact](./safety_impact.md) and
+    [Mission Impact](./mission_impact.md)
+
+    ```python exec="true" idprefix=""
+    from ssvc.decision_tables.ssvc.human_impact import LATEST as DT
+    from ssvc.doc_helpers import example_block
+
+    for dp in [v for k,v in DT.decision_points.items() if k != DT.outcome]:
+        print(example_block(dp))
+    ```
+
+The mapping is shown in the diagram and table below.
+
+```python exec="true" idprefix=""
+from ssvc.decision_tables.ssvc.human_impact import LATEST as DT
+from ssvc.decision_tables.helpers import mapping2mermaid, mermaid_title_from_dt
+
+rows = DT.mapping
+title = mermaid_title_from_dt(DT)
+print(mapping2mermaid(rows, title=title))
+```
+
+```python exec="true" idprefix=""
+
+from ssvc.decision_tables.ssvc.human_impact import LATEST as DT
+from ssvc.decision_tables.helpers import dt2df_md
+
+print(dt2df_md(DT))
+```
+
 
 [^1]: In pilot implementations of SSVC, we received feedback that organizations tend to think of mission and safety impacts as
 if they were combined into a single factor: in other words, the priority increases regardless which of the two  impact factors was increased.

diff --git a/docs/reference/decision_points/public_safety_impact.md b/docs/reference/decision_points/public_safety_impact.md
@@ -9,7 +9,6 @@ print(example_block(LATEST))
 
 {% include-markdown "../../_includes/safety_cvss_ssvc.md" %}
 
-This is a compound decision point, therefore it is a notational convenience.
 
 Suppliers necessarily have a rather coarse-grained perspective on the broadly defined [Safety Impact](safety_impact.md) Decision Point.
 Therefore we simplify the above into a binary categorization:
@@ -18,6 +17,26 @@ Therefore we simplify the above into a binary categorization:
   [Safety Impact](safety_impact.md) table.
 - *Minimal* is when none do.
 
+The mapping is shown in the diagram and table below.
+
+```python exec="true" idprefix=""
+from ssvc.decision_tables.ssvc.public_safety_impact import LATEST as DT
+from ssvc.decision_tables.helpers import mapping2mermaid, mermaid_title_from_dt
+
+rows = DT.mapping
+title = mermaid_title_from_dt(DT)
+print(mapping2mermaid(rows, title=title))
+```
+
+```python exec="true" idprefix=""
+
+from ssvc.decision_tables.ssvc.public_safety_impact import LATEST as DT
+from ssvc.decision_tables.helpers import dt2df_md
+
+print(dt2df_md(DT))
+```
+
+
 ## Prior Versions
 
 ```python exec="true" idprefix=""

diff --git a/docs/reference/decision_points/utility.md b/docs/reference/decision_points/utility.md
@@ -29,6 +29,26 @@ This framing makes it easier to analytically derive these categories from a desc
 Roughly, *Utility* is a combination of two things: (1) the value of each exploitation event and (2) the ease and speed with which the adversary can cause exploitation events.
 We define *Utility* as laborious, efficient, or super effective, as described in the table above.
 
+The mapping is shown in the diagram and table below.
+
+```python exec="true" idprefix=""
+from ssvc.decision_tables.ssvc.utility import LATEST as DT
+from ssvc.decision_tables.helpers import mapping2mermaid, mermaid_title_from_dt
+
+rows = DT.mapping
+title = mermaid_title_from_dt(DT)
+print(mapping2mermaid(rows, title=title))
+```
+
+```python exec="true" idprefix=""
+
+from ssvc.decision_tables.ssvc.utility import LATEST as DT
+from ssvc.decision_tables.helpers import dt2df_md
+
+print(dt2df_md(DT))
+```
+
+
 ## Alternative Utility Outputs
 
 Alternative heuristics can plausibly be used as proxies for adversary utility.

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -117,11 +117,14 @@ nav:
             - Target Distribution: 'reference/decision_points/cvss/target_distribution.md'
     - Code:
         - Intro: 'reference/code/index.md'
+        - Decision Points: 'reference/code/decision_points.md'
+        - Decision Tables: 'reference/code/decision_tables.md'
+        - Decision Point Groups: 'reference/code/decision_point_groups.md'
+        - Outcomes: 'reference/code/outcomes.md'
         - Namespaces: 'reference/code/namespaces.md'
         - Selections: 'reference/code/selection.md'
         - CSV Analyzer: 'reference/code/analyze_csv.md'
         - Policy Generator: 'reference/code/policy_generator.md'
-        - Outcomes: 'reference/code/outcomes.md'
         - Doctools: 'reference/code/doctools.md'
     - Learning SSVC:
         - Tutorials: 'tutorials/index.md'

diff --git a/src/ssvc/decision_tables/helpers.py b/src/ssvc/decision_tables/helpers.py
@@ -102,14 +102,19 @@ def _mapping2mermaid(mapping: list[dict[str:str]], title: str = None) -> str:
         # add the yaml front matter for the title
         lines.extend(["---", f"title: {title}", "---"])
 
-    lines.extend(["graph LR", "n1(( ))"])
+    lines.extend(["graph LR", "subgraph inputs[Inputs]", "n1(( ))"])
     columns = list(mapping[0].keys())
 
     node_ids = {}  # (col_idx, path_tuple) -> node_id
     seen_edges = set()  # (parent_id, child_id)
 
     # Build subgraphs + nodes
     for col_idx, col in enumerate(columns):
+        # if it's the last column, close the Inputs subgraph and start the Outputs subgraph
+        if col_idx == len(columns) - 1:
+            lines.append("end")
+            lines.append("subgraph outputs[Outcome]")
+
         subgraph_name = f's{col_idx+1}["{col}"]'
         lines.append(f"subgraph {subgraph_name}")
         seen_paths = set()
@@ -124,6 +129,7 @@ def _mapping2mermaid(mapping: list[dict[str:str]], title: str = None) -> str:
             lines.append(f"{node_id}([{label}])")
             node_ids[(col_idx, path)] = node_id
         lines.append("end")
+    lines.append("end")  # close the outputs subgraph
 
     # Root → level 0
     for row in mapping: