feat: add new security needs (#558)

Author: a-zw

docs/internals/requirements/requirements.rst

@@ -140,9 +140,9 @@ This section provides an overview of current process requirements and their clar
   :parent_covered: NO: Can not cover 'ISO/IEC/IEEE/29148'
   :version: 1
   :implemented: YES
-  :satisfies: gd_req__req_attr_description, gd_req__req_check_mandatory,
+  :satisfies: gd_req__req_attr_description, gd_req__req_check_mandatory, gd_req__sec_argument
 
-  Docs-as-Code shall enforce that each need of type :need:`tool_req__docs_req_types` has a description (content)
+  Enforce that each need of type :need:`tool_req__docs_req_types` has a description (content)
 
 
 .. tool_req:: Enforces description wording rules
@@ -1186,15 +1186,82 @@ Testing
 
    Docs-As-Code shall enforce that every Safety Analysis has a short description of the failure effect (e.g. failure lead to an unintended actuation of the analysed element)
 
-----------------------------------------------------------------
-Safety Analysis (DFA + FMEA) Process to Tool Requirement Mapping
-----------------------------------------------------------------
 
-.. needtable::
-   :style: table
-   :types: gd_req
-   :columns: id;satisfies_back as "tool_req"
-   :filter: "gd_req__saf" in id
+🔒 Security Analysis
+#####################
+
+
+.. tool_req:: Security Analysis Need Types
+  :id: tool_req__docs_sec_types
+  :implemented: YES
+  :tags: Security Analysis
+  :version: 1
+  :satisfies:
+    gd_req__sec_attr_uid,
+    gd_req__sec_attr_title,
+  :parent_covered: YES
+
+  Docs-As-Code shall support the following need types:
+
+  * Feature Security Analysis Threat (STRIDE) -> ``feat_sec_threat``
+  * Component Security Analysis Threat (STRIDE) -> ``comp_sec_threat``
+  * Platform Security Analysis Threat (STRIDE) -> ``plat_sec_threat``
+  * Feature Security Analysis (Threat Scenario) -> ``feat_sec_ana``
+  * Component Security Analysis (Threat Scenario) -> ``comp_sec_ana``
+  * Platform Security Analysis (Threat Scenario) -> ``plat_sec_ana``
+
+
+.. tool_req:: Security Analysis: STRIDE Threat ID Attribute
+  :id: tool_req__docs_sec_attr_stride_threat_id
+  :implemented: YES
+  :tags: Security Analysis
+  :version: 1
+  :satisfies: gd_req__sec_attr_stride_threat_id
+  :parent_covered: YES
+
+  Docs-As-Code shall enforce that STRIDE threat needs
+  (``feat_sec_threat``, ``comp_sec_threat``, ``plat_sec_threat``)
+  have a mandatory ``threat_id`` attribute.
+
+
+.. tool_req:: Security Analysis Threat Scenario Mandatory Attributes
+  :id: tool_req__docs_sec_attrs_mandatory
+  :implemented: YES
+  :tags: Security Analysis
+  :version: 1
+  :satisfies:
+    gd_req__sec_attr_threat_scenario_id,
+    gd_req__sec_attr_status,
+    gd_req__sec_attr_sufficient,
+    gd_req__sec_attr_teffect,
+  :parent_covered: YES
+
+  Enforce that threat scenario needs
+  (``feat_sec_ana``, ``comp_sec_ana``, ``plat_sec_ana``)
+  have the following mandatory attributes:
+
+  * ``threat_scenario_id``
+  * ``status``: ``valid`` or ``invalid``
+  * ``sufficient``: ``yes`` or ``no``
+  * ``threat_effect``: short description of the threat impact
+
+
+.. tool_req:: Security Analysis Optional Attributes
+  :id: tool_req__docs_sec_attrs_optional
+  :implemented: YES
+  :tags: Security Analysis
+  :version: 1
+  :satisfies:
+    gd_req__sec_attr_mitigation_issue,
+    gd_req__sec_attr_aou,
+  :parent_covered: YES
+
+  Allow threat scenario needs
+  (``feat_sec_ana``, ``comp_sec_ana``, ``plat_sec_ana``)
+  to have the following optional attributes and links:
+
+  * ``mitigation_issue``: link to a GitHub issue
+  * ``mitigated_by``: link to ``aou_req``
 
 
 🗺️ Full Mapping

src/extensions/score_metamodel/__init__.py

@@ -327,6 +327,15 @@ def setup(app: Sphinx) -> dict[str, str | bool]:
     app.config.needs_types += metamodel.needs_types
     app.config.needs_links.update(metamodel.needs_links)
     app.config.needs_fields.update(metamodel.needs_fields)
+    app.config.needs_string_links.setdefault(
+        "mitigation_issue_linker",
+        {
+            "regex": r"(?P<url>https://github\.com/[^/]+/(?P<repo>[^/]+)/issues/(?P<number>\d+))",
+            "link_url": "{{url}}",
+            "link_name": "{{repo}}#{{number}}",
+            "options": ["mitigation_issue"],
+        },
+    )
     app.config.graph_checks = metamodel.needs_graph_check
     app.config.prohibited_words_checks = metamodel.prohibited_words_checks
 

src/extensions/score_metamodel/metamodel.yaml

@@ -127,6 +127,7 @@ needs_types:
   gd_req:
     title: Process Requirements
     mandatory_options:
+      # req-Id: tool_req__docs_common_attr_description
       content: ^[\s\S]+$
     optional_links:
       # req-Id: tool_req__docs_req_link_satisfies_allowed
@@ -289,6 +290,7 @@ needs_types:
       safety: ^(QM|ASIL_B)$
       # req-Id: tool_req__docs_common_attr_status
       status: ^(valid|invalid)$
+      # req-Id: tool_req__docs_common_attr_description
       content: ^[\s\S]+$
     mandatory_links:
       # req-Id: tool_req__docs_req_link_satisfies_allowed
@@ -325,6 +327,7 @@ needs_types:
       safety: ^(QM|ASIL_B)$
       # req-Id: tool_req__docs_common_attr_status
       status: ^(valid|invalid)$
+      # req-Id: tool_req__docs_common_attr_description
       content: ^[\s\S]+$
     mandatory_links:
       # req-Id: tool_req__docs_req_link_satisfies_allowed
@@ -350,6 +353,7 @@ needs_types:
   tool_req:
     title: Tool Requirement
     mandatory_options:
+      # req-Id: tool_req__docs_common_attr_description
       content: ^[\s\S]+$
     optional_links:
       # req-Id: tool_req__docs_req_link_satisfies_allowed
@@ -385,6 +389,7 @@ needs_types:
       safety: ^(QM|ASIL_B)$
       # req-Id: tool_req__docs_common_attr_status
       status: ^(valid|invalid)$
+      # req-Id: tool_req__docs_common_attr_description
       content: ^[\s\S]+$
     optional_options:
       codelink: ^.*$
@@ -746,11 +751,12 @@ needs_types:
       failure_effect: ^.*$
       sufficient: ^(yes|no)$
       status: ^(valid|invalid)$
+      # req-Id: tool_req__docs_common_attr_description
       content: ^[\s\S]+$
     mandatory_links:
       violates: feat_arc_sta
     optional_options:
-      mitigation_issue: ^https://github.com/.*$
+      mitigation_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$
     optional_links:
       mitigated_by: stkh_req, aou_req
     parts: 3
@@ -766,13 +772,14 @@ needs_types:
       sufficient: ^(yes|no)$
       status: ^(valid|invalid)$
       # req-Id: tool_req__docs_saf_attrs_content
+      # req-Id: tool_req__docs_common_attr_description
       content: ^[\s\S]+$
     mandatory_links:
       # req-Id: tool_req__docs_saf_attrs_violates
       violates: feat_arc_sta
     optional_options:
       # req-Id: tool_req__docs_saf_attrs_mitigation_issue
-      mitigation_issue: ^https://github.com/.*$
+      mitigation_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$
     optional_links:
       # req-Id: tool_req__docs_saf_attrs_mitigated_by
       # (only mandatory once valid status == valid)
@@ -796,7 +803,7 @@ needs_types:
       content: ^[\s\S]+$
     optional_options:
       # req-Id: tool_req__docs_saf_attrs_mitigation_issue
-      mitigation_issue: ^https://github.com/.*$
+      mitigation_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$
     mandatory_links:
       # req-Id: tool_req__docs_saf_attrs_violates
       violates: comp_arc_sta
@@ -824,7 +831,7 @@ needs_types:
       content: ^[\s\S]+$
     optional_options:
       # req-Id: tool_req__docs_saf_attrs_mitigation_issue
-      mitigation_issue: ^https://github.com/.*$
+      mitigation_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$
     mandatory_links:
       # req-Id: tool_req__docs_saf_attrs_violates
       violates: feat_arc_dyn, feat_arc_sta
@@ -851,7 +858,7 @@ needs_types:
       content: ^[\s\S]+$
     optional_options:
       # req-Id: tool_req__docs_saf_attrs_mitigation_issue
-      mitigation_issue: ^https://github.com/.*$
+      mitigation_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$
     mandatory_links:
       # req-Id: tool_req__docs_saf_attrs_violates
       violates: comp_arc_dyn, comp_arc_sta
@@ -862,6 +869,109 @@ needs_types:
       - safety_analysis
     parts: 3
 
+  # Security Analysis
+  # req-Id: tool_req__docs_sec_types
+  feat_sec_threat:
+    title: Feature Security Analysis Threat (STRIDE)
+    mandatory_options:
+      # req-Id: tool_req__docs_sec_attr_stride_threat_id
+      threat_id: ^(AU_01_0[1-3]|AZ_01_0[1-3]|CT_01_0[1-2]|DS_01_0[1-3]|EX_01_0[1-6]|LA_01_0[1-3]|MT_01_0[1-7])$
+      status: ^(valid|invalid)$
+      content: ^[\s\S]+$
+    tags:
+      - stride_threat
+      - security_analysis
+    parts: 3
+
+  # req-Id: tool_req__docs_sec_types
+  comp_sec_threat:
+    title: Component Security Analysis Threat (STRIDE)
+    mandatory_options:
+      # req-Id: tool_req__docs_sec_attr_stride_threat_id
+      threat_id: ^(AU_01_0[1-3]|AZ_01_0[1-3]|CT_01_0[1-2]|DS_01_0[1-3]|EX_01_0[1-6]|LA_01_0[1-3]|MT_01_0[1-7])$
+      status: ^(valid|invalid)$
+      content: ^[\s\S]+$
+    tags:
+      - stride_threat
+      - security_analysis
+    parts: 3
+
+  # req-Id: tool_req__docs_sec_types
+  plat_sec_threat:
+    title: Platform Security Analysis Threat (STRIDE)
+    mandatory_options:
+      # req-Id: tool_req__docs_sec_attr_stride_threat_id
+      threat_id: ^(AU_01_0[1-3]|AZ_01_0[1-3]|CT_01_0[1-2]|DS_01_0[1-3]|EX_01_0[1-6]|LA_01_0[1-3]|MT_01_0[1-7])$
+      status: ^(valid|invalid)$
+      content: ^[\s\S]+$
+    tags:
+      - stride_threat
+      - security_analysis
+    parts: 3
+
+  # req-Id: tool_req__docs_sec_types
+  feat_sec_ana:
+    title: Feature Security Analysis (Threat Scenario)
+    mandatory_options:
+      # req-Id: tool_req__docs_sec_attrs_mandatory
+      threat_scenario_id: ^(AS_01_(01|02|04|05|06|07|09|10)|CO_01_0[1-7]|SC_01_0[2-5]|SI_01_0[2-5]|UI_01_(0[1-9]|1[0-2]))$
+      # req-Id: tool_req__docs_sec_attrs_mandatory
+      status: ^(valid|invalid)$
+      # req-Id: tool_req__docs_sec_attrs_mandatory
+      sufficient: ^(yes|no)$
+      # req-Id: tool_req__docs_sec_attrs_mandatory
+      threat_effect: ^.+$
+      # req-Id: tool_req__docs_common_attr_description
+      content: ^[\s\S]+$
+    optional_options:
+      # req-Id: tool_req__docs_sec_attrs_optional
+      mitigation_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$
+    optional_links:
+      # req-Id: tool_req__docs_sec_attrs_optional
+      mitigated_by: feat_req, aou_req
+    tags:
+      - threat_scenario
+      - security_analysis
+    parts: 3
+
+  # req-Id: tool_req__docs_sec_types
+  comp_sec_ana:
+    title: Component Security Analysis (Threat Scenario)
+    mandatory_options:
+      threat_scenario_id: ^(AS_01_(01|02|04|05|06|07|09|10)|CO_01_0[1-7]|SC_01_0[2-5]|SI_01_0[2-5]|UI_01_(0[1-9]|1[0-2]))$
+      status: ^(valid|invalid)$
+      sufficient: ^(yes|no)$
+      threat_effect: ^.+$
+      # req-Id: tool_req__docs_common_attr_description
+      content: ^[\s\S]+$
+    optional_options:
+      mitigation_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$
+    optional_links:
+      mitigated_by: comp_req, aou_req
+    tags:
+      - threat_scenario
+      - security_analysis
+    parts: 3
+
+  # req-Id: tool_req__docs_sec_types
+  plat_sec_ana:
+    title: Platform Security Analysis (Threat Scenario)
+    mandatory_options:
+      threat_scenario_id: ^(AS_01_(01|02|04|05|06|07|09|10)|CO_01_0[1-7]|SC_01_0[2-5]|SI_01_0[2-5]|UI_01_(0[1-9]|1[0-2]))$
+      status: ^(valid|invalid)$
+      sufficient: ^(yes|no)$
+      threat_effect: ^.+$
+      # req-Id: tool_req__docs_common_attr_description
+      content: ^[\s\S]+$
+    optional_options:
+      mitigation_issue: ^https://github\.com/[^/]+/[^/]+/issues/\d+$
+    optional_links:
+      mitigated_by: feat_req, aou_req
+    tags:
+      - threat_scenario
+      - security_analysis
+    parts: 3
+
   testcase:
     title: Testcase Needs parsed from test.xml files
     optional_options: