Add CISA custom decision points (#427)

* add public well being impact as version 1 of public safety impact (now version 2)

* add mission prevalence decision point

* add version diff output

* add Mission and Well Being Impact as earlier version of Human Impact

* clean up version printing

* updated generated docs

* remove obsoleted generated docs

* s/Mission Impact/Mission Prevalence/

* s/Mission Impact/Mission Prevalence/

data/json/decision_points/human_impact_2_0_0.json

@@ -0,0 +1,29 @@
+{
+  "namespace": "ssvc",
+  "version": "2.0.0",
+  "key": "HI",
+  "name": "Human Impact",
+  "description": "Human Impact is a combination of Safety and Mission impacts.",
+  "values": [
+    {
+      "key": "L",
+      "name": "Low",
+      "description": "Safety=None/Minor, Mission=None/Degraded/Crippled"
+    },
+    {
+      "key": "M",
+      "name": "Medium",
+      "description": "Safety=None/Minor, Mission=MEF Failure OR Safety=Major, Mission=None/Degraded/Crippled"
+    },
+    {
+      "key": "H",
+      "name": "High",
+      "description": "Safety=Hazardous, Mission=None/Degraded/Crippled/MEF Failure OR Safety=Major, Mission=MEF Failure"
+    },
+    {
+      "key": "VH",
+      "name": "Very High",
+      "description": "Safety=Catastrophic OR Mission=Mission Failure"
+    }
+  ]
+}

data/json/decision_points/mission_and_well-being_impact_1_0_0.json

@@ -0,0 +1,24 @@
+{
+  "namespace": "ssvc",
+  "version": "1.0.0",
+  "key": "MWI",
+  "name": "Mission and Well-Being Impact",
+  "description": "Mission and Well-Being Impact is a combination of Mission Prevalence and Public Well-Being Impact.",
+  "values": [
+    {
+      "key": "L",
+      "name": "Low",
+      "description": "Mission Prevalence Minimal and Public Well-Being Impact Minimal"
+    },
+    {
+      "key": "M",
+      "name": "Medium",
+      "description": "Mission Prevalence Support and Public Well-Being Impact Minimal or Material"
+    },
+    {
+      "key": "H",
+      "name": "High",
+      "description": "Mission Prevalence Essential or Public Well-Being Impact Irreversible"
+    }
+  ]
+}

data/json/decision_points/public_safety_impact_2_0_0.json

@@ -0,0 +1,19 @@
+{
+  "namespace": "ssvc",
+  "version": "2.0.0",
+  "key": "PSI",
+  "name": "Public Safety Impact",
+  "description": "A coarse-grained representation of impact to public safety.",
+  "values": [
+    {
+      "key": "M",
+      "name": "Minimal",
+      "description": "Safety impact of None or Minor."
+    },
+    {
+      "key": "S",
+      "name": "Significant",
+      "description": "Safety impact of Major, Hazardous, or Catastrophic."
+    }
+  ]
+}

data/json/decision_points/public_well-being_impact_1_0_0.json

@@ -0,0 +1,24 @@
+{
+  "namespace": "ssvc",
+  "version": "1.0.0",
+  "key": "PWI",
+  "name": "Public Well-Being Impact",
+  "description": "A coarse-grained representation of impact to public well-being.",
+  "values": [
+    {
+      "key": "M",
+      "name": "Minimal",
+      "description": "The effect is below the threshold for all aspects described in material. "
+    },
+    {
+      "key": "M",
+      "name": "Material",
+      "description": "(Any one or more of these conditions hold.) \n\n*Physical harm*: Does one or more of the following:\n\n- Causes physical distress or injury to system users.\n- Introduces occupational safety hazards.\n- Reduces and/or results in failure of cyber-physical system safety margins.\n\n*Environment*: Major externalities (property damage, environmental damage, etc.) are\nimposed on other parties. \n\n*Financial*: Financial losses likely lead to bankruptcy of multiple persons. \n \n*Psychological*: Widespread emotional or psychological harm, sufficient to necessitate\ncounseling or therapy, impact populations of people. \n"
+    },
+    {
+      "key": "I",
+      "name": "Irreversible",
+      "description": "(Any one or more of these conditions hold.)\n \n*Physical harm*: One or both of the following are true:\n\n- Multiple fatalities are likely.\n- The cyber-physical system, of which the vulnerable componen is a part, is likely lost or destroyed.\n\n*Environment*: Extreme or serious externalities (immediate public health threat, environmental damage leading to small\necosystem collapse, etc.) are imposed on other parties.\n\n*Financial*: Social systems (elections, financial grid, etc.) supported by the software are destabilized and potentially\ncollapse.\n\n*Psychological*: N/A \n"
+    }
+  ]
+}

data/json/decision_points/safety_impact_1_0_0.json

@@ -13,7 +13,7 @@
     {
       "key": "M",
       "name": "Minor",
-      "description": "Any one or more of these conditions hold. Physical harm: Physical discomfort for users (not operators) of the system. 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. System resiliency: Small reduction in built-in system safety margins; OR small reduction in system functional capabilities that support safe operation. Environment Minor externalities (property damage, environmental damage, etc.) imposed on other parties. Financial Financial losses, which are not readily absorbable, to multiple persons. Psychological: Emotional or psychological harm, sufficient to be cause for counselling or therapy, to multiple persons."
+      "description": "Any one or more of these conditions hold. Physical harm: Physical discomfort for users (not operators) of the system. 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. System resiliency: Small reduction in built-in system safety margins; OR small reduction in system functional capabilities that support safe operation. Environment: Minor externalities (property damage, environmental damage, etc.) imposed on other parties. Financial Financial losses, which are not readily absorbable, to multiple persons. Psychological: Emotional or psychological harm, sufficient to be cause for counselling or therapy, to multiple persons."
     },
     {
       "key": "J",

docs/_generated/decision_points/human_impact.md

@@ -1 +1 @@
-human_impact_1_0_0.md
+human_impact_2_0_0.md

docs/_generated/decision_points/human_impact_1_0_0.md → docs/_generated/decision_points/human_impact_2_0_0.md

@@ -1,5 +1,5 @@
 <!-- This content is autogenerated by doctools.py. Do not Edit. -->
-!!! note "Human Impact v1.0.0"
+!!! note "Human Impact v2.0.0"
 
     === "Text" 
 
@@ -15,5 +15,5 @@
     === "JSON"
 
         ```json
-        {% include "../../../data/json/decision_points/human_impact_1_0_0.json" %}
+        {% include "../../../data/json/decision_points/human_impact_2_0_0.json" %}
         ```

docs/_generated/decision_points/mission_and_well-being_impact.md

@@ -0,0 +1 @@
+mission_and_well-being_impact_1_0_0.md

docs/_generated/decision_points/mission_and_well-being_impact_1_0_0.md

@@ -0,0 +1,18 @@
+<!-- This content is autogenerated by doctools.py. Do not Edit. -->
+!!! note "Mission and Well-Being Impact v1.0.0"
+
+    === "Text" 
+
+        Mission and Well-Being Impact is a combination of Mission Prevalence and Public Well-Being Impact.
+
+        | Value | Definition |
+        |:-----|:-----------|
+        | Low | Mission Prevalence Minimal and Public Well-Being Impact Minimal |
+        | Medium | Mission Prevalence Support and Public Well-Being Impact Minimal or Material |
+        | High | Mission Prevalence Essential or Public Well-Being Impact Irreversible |
+        
+    === "JSON"
+
+        ```json
+        {% include "../../../data/json/decision_points/mission_and_well-being_impact_1_0_0.json" %}
+        ```

docs/_generated/decision_points/public_safety_impact.md

@@ -1 +1 @@
-public_safety_impact_1_0_0.md
+public_safety_impact_2_0_0.md

docs/_generated/decision_points/public_safety_impact_1_0_0.md → docs/_generated/decision_points/public_safety_impact_2_0_0.md

@@ -1,5 +1,5 @@
 <!-- This content is autogenerated by doctools.py. Do not Edit. -->
-!!! note "Public Safety Impact v1.0.0"
+!!! note "Public Safety Impact v2.0.0"
 
     === "Text" 
 
@@ -13,5 +13,5 @@
     === "JSON"
 
         ```json
-        {% include "../../../data/json/decision_points/public_safety_impact_1_0_0.json" %}
+        {% include "../../../data/json/decision_points/public_safety_impact_2_0_0.json" %}
         ```

docs/_generated/decision_points/public_well-being_impact.md

@@ -0,0 +1 @@
+public_well-being_impact_1_0_0.md

docs/_generated/decision_points/public_well-being_impact_1_0_0.md

@@ -0,0 +1,47 @@
+<!-- This content is autogenerated by doctools.py. Do not Edit. -->
+!!! note "Public Well-Being Impact v1.0.0"
+
+    === "Text" 
+
+        A coarse-grained representation of impact to public well-being.
+
+        | Value | Definition |
+        |:-----|:-----------|
+        | Minimal | The effect is below the threshold for all aspects described in material.  |
+        | Material | (Any one or more of these conditions hold.) 
+
+*Physical harm*: Does one or more of the following:
+
+- Causes physical distress or injury to system users.
+- Introduces occupational safety hazards.
+- Reduces and/or results in failure of cyber-physical system safety margins.
+
+*Environment*: Major externalities (property damage, environmental damage, etc.) are
+imposed on other parties. 
+
+*Financial*: Financial losses likely lead to bankruptcy of multiple persons. 
+
+*Psychological*: Widespread emotional or psychological harm, sufficient to necessitate
+counseling or therapy, impact populations of people. 
+ |
+        | Irreversible | (Any one or more of these conditions hold.)
+
+*Physical harm*: One or both of the following are true:
+
+- Multiple fatalities are likely.
+- The cyber-physical system, of which the vulnerable componen is a part, is likely lost or destroyed.
+
+*Environment*: Extreme or serious externalities (immediate public health threat, environmental damage leading to small
+ecosystem collapse, etc.) are imposed on other parties.
+
+*Financial*: Social systems (elections, financial grid, etc.) supported by the software are destabilized and potentially
+collapse.
+
+*Psychological*: N/A 
+ |
+
+    === "JSON"
+
+        ```json
+        {% include "../../../data/json/decision_points/public_well-being_impact_1_0_0.json" %}
+        ```

docs/_generated/decision_points/safety_impact_1_0_0.md

@@ -8,7 +8,7 @@
         | Value | Definition |
         |:-----|:-----------|
         | None | The effect is below the threshold for all aspects described in Minor. |
-        | Minor | Any one or more of these conditions hold. Physical harm: Physical discomfort for users (not operators) of the system. 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. System resiliency: Small reduction in built-in system safety margins; OR small reduction in system functional capabilities that support safe operation. Environment Minor externalities (property damage, environmental damage, etc.) imposed on other parties. Financial Financial losses, which are not readily absorbable, to multiple persons. Psychological: Emotional or psychological harm, sufficient to be cause for counselling or therapy, to multiple persons. |
+        | Minor | Any one or more of these conditions hold. Physical harm: Physical discomfort for users (not operators) of the system. 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. System resiliency: Small reduction in built-in system safety margins; OR small reduction in system functional capabilities that support safe operation. Environment: Minor externalities (property damage, environmental damage, etc.) imposed on other parties. Financial Financial losses, which are not readily absorbable, to multiple persons. Psychological: Emotional or psychological harm, sufficient to be cause for counselling or therapy, to multiple persons. |
         | Major | Any one or more of these conditions hold. Physical harm: Physical distress and injuries for users (not operators) of the system. 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. System resiliency: System safety margin effectively eliminated but no actual harm; OR failure of system functional capabilities that support safe operation. Environment: Major externalities (property damage, environmental damage, etc.) imposed on other parties. Financial: Financial losses that likely lead to bankruptcy of multiple persons. Psychological: Widespread emotional or psychological harm, sufficient to be cause for counselling or therapy, to populations of people. |
         | Hazardous | Any one or more of these conditions hold. Physical harm: Serious or fatal injuries, where fatalities are plausibly preventable via emergency services or other measures. 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. System resiliency: Parts of the cyber-physical system break; system’s ability to recover lost functionality remains intact. Environment: Serious externalities (threat to life as well as property, widespread environmental damage, measurable public health risks, etc.) imposed on other parties. Financial: Socio-technical system (elections, financial grid, etc.) of which the affected component is a part is actively destabilized and enters unsafe state. Psychological: N/A. |
         | Catastrophic | Any one or more of these conditions hold. Physical harm: Multiple immediate fatalities (Emergency response probably cannot save the victims.) Operator resiliency: Operator incapacitated (includes fatality or otherwise incapacitated). System resiliency: Total loss of whole cyber-physical system, of which the software is a part. Environment: Extreme externalities (immediate public health threat, environmental damage leading to small ecosystem collapse, etc.) imposed on other parties. Financial: Social systems (elections, financial grid, etc.) supported by the software collapse. Psychological: N/A. |

src/ssvc/decision_points/helpers.py

@@ -2,7 +2,7 @@
 """
 Provides helper functions for working with SSVC decision points.
 """
-#  Copyright (c) 2023 Carnegie Mellon University and Contributors.
+#  Copyright (c) 2024 Carnegie Mellon University and Contributors.
 #  - see Contributors.md for a full list of Contributors
 #  - see ContributionInstructions.md for information on how you can Contribute to this project
 #  Stakeholder Specific Vulnerability Categorization (SSVC) is
@@ -15,9 +15,25 @@
 #  Carnegie Mellon®, CERT® and CERT Coordination Center® are registered in the
 #  U.S. Patent and Trademark Office by Carnegie Mellon University
 
+from typing import Sequence
+
 from ssvc.decision_points import SsvcDecisionPoint
 
 
+#  Copyright (c) 2023 Carnegie Mellon University and Contributors.
+#  - see Contributors.md for a full list of Contributors
+#  - see ContributionInstructions.md for information on how you can Contribute to this project
+#  Stakeholder Specific Vulnerability Categorization (SSVC) is
+#  licensed under a MIT (SEI)-style license, please see LICENSE.md distributed
+#  with this Software or contact [email protected] for full terms.
+#  Created, in part, with funding and support from the United States Government
+#  (see Acknowledgments file). This program may include and/or can make use of
+#  certain third party source code, object code, documentation and other files
+#  (“Third Party Software”). See LICENSE.md for more details.
+#  Carnegie Mellon®, CERT® and CERT Coordination Center® are registered in the
+#  U.S. Patent and Trademark Office by Carnegie Mellon University
+
+
 def dp_diff(dp1: SsvcDecisionPoint, dp2: SsvcDecisionPoint) -> list[str]:
     """
     Compares two decision points and returns a list of differences.
@@ -175,7 +191,7 @@ def dp_diff(dp1: SsvcDecisionPoint, dp2: SsvcDecisionPoint) -> list[str]:
     return diffs
 
 
-def show_diffs(versions: list[SsvcDecisionPoint]) -> None:
+def show_diffs(versions: Sequence[SsvcDecisionPoint]) -> None:
     if len(versions) < 2:
         print("Not enough versions to compare")
         return
@@ -186,7 +202,7 @@ def show_diffs(versions: list[SsvcDecisionPoint]) -> None:
         print()
 
 
-def print_versions_and_diffs(versions: list[SsvcDecisionPoint]) -> None:
+def print_versions_and_diffs(versions: Sequence[SsvcDecisionPoint]) -> None:
     """
     Prints the json representation of each version and then shows the diffs between each version.
 

src/ssvc/decision_points/human_impact.py

@@ -4,7 +4,7 @@
 author: adh
 created_at: 9/21/23 10:49 AM
 """
-#  Copyright (c) 2023 Carnegie Mellon University and Contributors.
+#  Copyright (c) 2023-2024 Carnegie Mellon University and Contributors.
 #  - see Contributors.md for a full list of Contributors
 #  - see ContributionInstructions.md for information on how you can Contribute to this project
 #  Stakeholder Specific Vulnerability Categorization (SSVC) is
@@ -18,47 +18,81 @@
 #  U.S. Patent and Trademark Office by Carnegie Mellon University
 
 from ssvc.decision_points.base import SsvcDecisionPoint, SsvcDecisionPointValue
+from ssvc.decision_points.helpers import print_versions_and_diffs
 
-VERY_HIGH = SsvcDecisionPointValue(
+LOW_1 = SsvcDecisionPointValue(
+    name="Low",
+    key="L",
+    description="Mission Prevalence Minimal and Public Well-Being Impact Minimal",
+)
+
+MEDIUM_1 = SsvcDecisionPointValue(
+    name="Medium",
+    key="M",
+    description="Mission Prevalence Support and Public Well-Being Impact Minimal or Material",
+)
+
+HIGH_1 = SsvcDecisionPointValue(
+    name="High",
+    key="H",
+    description="Mission Prevalence Essential or Public Well-Being Impact Irreversible",
+)
+
+VERY_HIGH_1 = SsvcDecisionPointValue(
     name="Very High",
     key="VH",
     description="Safety=Catastrophic OR Mission=Mission Failure",
 )
 
-HIGH = SsvcDecisionPointValue(
+HIGH_2 = SsvcDecisionPointValue(
     name="High",
     key="H",
     description="Safety=Hazardous, Mission=None/Degraded/Crippled/MEF Failure OR Safety=Major, Mission=MEF Failure",
 )
 
-MEDIUM = SsvcDecisionPointValue(
+MEDIUM_2 = SsvcDecisionPointValue(
     name="Medium",
     key="M",
     description="Safety=None/Minor, Mission=MEF Failure OR Safety=Major, Mission=None/Degraded/Crippled",
 )
 
-LOW = SsvcDecisionPointValue(
+LOW_2 = SsvcDecisionPointValue(
     name="Low",
     key="L",
     description="Safety=None/Minor, Mission=None/Degraded/Crippled",
 )
 
-HUMAN_IMPACT_1 = SsvcDecisionPoint(
+
+MISSION_AND_WELL_BEING_IMPACT_1 = SsvcDecisionPoint(
+    name="Mission and Well-Being Impact",
+    description="Mission and Well-Being Impact is a combination of Mission Prevalence and Public Well-Being Impact.",
+    key="MWI",
+    version="1.0.0",
+    values=(
+        LOW_1,
+        MEDIUM_1,
+        HIGH_1,
+    ),
+)
+
+HUMAN_IMPACT_2 = SsvcDecisionPoint(
     name="Human Impact",
     description="Human Impact is a combination of Safety and Mission impacts.",
     key="HI",
-    version="1.0.0",
+    version="2.0.0",
     values=(
-        LOW,
-        MEDIUM,
-        HIGH,
-        VERY_HIGH,
+        LOW_2,
+        MEDIUM_2,
+        HIGH_2,
+        VERY_HIGH_1,
     ),
 )
 
 
 def main():
-    print(HUMAN_IMPACT_1.to_json(indent=2))
+    versions = (MISSION_AND_WELL_BEING_IMPACT_1, HUMAN_IMPACT_2)
+
+    print_versions_and_diffs(versions)
 
 
 if __name__ == "__main__":