initial draft of new process area security analysis

Author: masc2023

process/_assets/score_process_area_overview.drawio.svg

@@ -34,6 +34,7 @@ Process Areas
    requirements_engineering/index.rst
    safety_analysis/index.rst
    safety_management/index.rst
+   security_analysis/index.rst
    security_management/index.rst
    tool_management/index.rst
    verification/index.rst

process/process_areas/index.rst

@@ -0,0 +1,29 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+   # Some portions generated by Co-Pilot
+
+Guidance
+########
+
+.. toctree::
+   :maxdepth: 1
+
+   security_analysis_guideline
+   security_analysis_threat_scenarios_guideline
+   security_analysis_threat_scenario_templates
+   security_analysis_threat_models_guideline
+   security_analysis_threat_templates
+   security_analysis_checklist
+   security_analysis_process_reqs

process/process_areas/security_analysis/guidance/index.rst

@@ -0,0 +1,82 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+   # Some portions generated by Co-Pilot
+
+Security Analysis Checklist
+============================
+
+.. gd_chklst:: Security Analysis Checklist Template
+   :id: gd_chklst__security_analysis
+   :status: valid
+   :tags: security_analysis
+
+   **Purpose**
+   The purpose of this Security Analysis checklist template is to collect the topics to
+   be checked during verification of the Security Analysis.
+
+   **Checklist**
+
+   .. list-table:: Security Analysis Checklist
+      :header-rows: 1
+      :widths: 10,30,30,15,8,8
+
+      * - Review ID
+        - Acceptance Criteria
+        - Guidance
+        - Passed
+        - Remarks
+        - Issue link
+      * - REQ_01_01
+        - Is / are the attribute sufficient set correctly?
+        - The mitigations shall have a direct influence on the threat by (accept, avoid, reduce, share) to mitigate the risk.
+        - The mitigations are sufficient.
+        - <yes|no>
+        -
+      * - REQ_01_02
+        - Are the templates defined used?
+        - See :ref:`security_analysis_templates` / :ref:`security_analysis_threat_templates` and also :ref:`process_requirements_security_analysis`
+        - Templates are used to generate the security analysis.
+        - <yes|no>
+        -
+      * - REQ_01_03
+        - Were the threat scenarios / threat models applied?
+        - See :need:`gd_guidl__sec_ana_threat_scenarios` / :need:`gd_guidl__threat_models_stride`
+        - The applicable items of the threat scenarios / threat models are used to ensure a structured analysis. For all not applicable items an argument shall be given in the content of the document.
+        - <yes|no>
+        -
+      * - REQ_01_04
+        - Are the threat effects clearly and completely described?
+        - Use the generic threat effect descriptions and enlarge the description if it's applicable to the considered element.
+        - The effects of the threat are described completely. The effect can be recognized easily.
+        - <yes|no>
+        -
+      * - REQ_01_06
+        - Is the attribute "mitigated by" linked correctly?
+        - Check if the correct threat effect is linked via "mitigated by".
+        - The "mitigated by" link is correct.
+        - <yes|no>
+        -
+      * - REQ_01_07
+        - Is the sufficiency of the "mitigated by" (accept, avoid, reduce, share) described or can it be recognized easily?
+        - The sufficiency of the "mitigated by" is described in the content of the document. It can be recognized easily.
+        - The "mitigated by" shows clearly that a threat can be mitigated by the linked requirement by (accept, avoid, reduce, share). It shall be described in the content.
+        - <yes|no>
+        -
+      * - REQ_01_08
+        - Is the overall result of the Security Analysis described in the report?
+        - It shall be shown in the report if the Security Analysis is finished and if all artifacts are "valid" and "sufficient".
+        - The results of the Security Analysis are described in the report. The report is available :need:`wp__verification_platform_ver_report`.
+        - <yes|no>
+        -

process/process_areas/security_analysis/guidance/security_analysis_checklist.rst

@@ -0,0 +1,115 @@
+..
+   # *******************************************************************************
+   # Copyright (c) 2025 Contributors to the Eclipse Foundation
+   #
+   # See the NOTICE file(s) distributed with this work for additional
+   # information regarding copyright ownership.
+   #
+   # This program and the accompanying materials are made available under the
+   # terms of the Apache License Version 2.0 which is available at
+   # https://www.apache.org/licenses/LICENSE-2.0
+   #
+   # SPDX-License-Identifier: Apache-2.0
+   # *******************************************************************************
+
+   # Some portions generated by Co-Pilot
+
+Security Analysis Guidelines
+############################
+
+.. gd_guidl:: Security Analysis Guideline
+   :id: gd_guidl__security_analysis
+   :status: valid
+   :complies:
+
+This document describes the general guidance for Security Analysis based on the concept
+which is defined :need:`Security Analysis Concept<doc_concept__security_analysis>`.
+Use the platform Security Analysis as an input so that general security controls are
+only defined once and not in every single Security Analysis.
+
+Workflow for Security Analysis
+==============================
+
+The workflow of the Security Analysis is described in :ref:`workflow_security_analysis`.
+The single steps in these workflows are described in detail in the following sections.
+
+
+Step-by-Step-approach Security Analysis Feature/Component:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The analysis is done by using the template :ref:`security_analysis_threat_templates` on
+the feature or component architectural diagrams. By using the threat models
+<:need:`gd_guidl__threat_models_stride`> it can be ensured that the analysis is done in
+a structured way. Apply the threat model to the diagram and document the results in the
+template. Use the content of the document :need:`gd_temp__feat_sec_ana_threat`,
+:need:`gd_temp__comp_sec_ana_threat` to describe e.g. why a threat model is not
+applicable for the diagram. If a treat can't be applied, the reason has to be documented
+in the content of the document, so it can be recognized.
+
+The attributes of the template are described in :ref:`process_requirements_security_analysis_attributes`.
+
+**Steps:**
+
+#. For each of the security functions realized by an architecture element check if a threat from the threat model :need:`gd_guidl__threat_models_stride` applies.
+#. If a threat model applies, use the template :need:`gd_temp__feat_sec_ana_threat` or :need:`gd_temp__comp_sec_ana_threat` to perform the analysis.
+#. The title of the analysis should be easily recognizable e.g. "Component xy unauthorized access".
+#. Link the violated architecture with the "violates" attribute.
+#. Replace the placeholders in the "id" attribute with the name of the feature or component and a short description of the element so that it can be easily identified.
+#. Document the threat ID from the threat model :need:`gd_guidl__threat_models_stride` that applies to the element in the "threat_id" attribute.
+#. Describe the threat effect of the threat model on the element in the "threat_effect" attribute. Use the threat description and enlarge it if it's applicable to the considered element.
+#. Document the mitigation. This can be (accept, avoid, reduce, share) of the threat.
+#. If there is no mitigation or existing mitigation is not sufficient, a mitigation issue has to be created in the Issue Tracking system and linked in the "mitigation_issue" attribute.
+#. The analysis is finished if for each identified threat a sufficient mitigation exists.
+#. Unless the attribute sufficient is yes, mitigation and argument attributes can be still empty.
+#. Continue the analysis until all applicable threat models are checked.
+#. The verification is done by applying the checklist :need:`gd_chklst__security_analysis`.
+
+.. note::
+   If there are changes they have to be analyzed with an impact analysis
+   :need:`gd_temp__change_impact_analysis`. If needed the Security Analysis has to be
+   updated accordingly. Therefore all necessary steps have to be repeated.
+
+
+Step-by-Step-approach Security Analysis Platform:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The analysis is done by using the template :ref:`security_analysis_templates` on the
+platform diagrams using a list of threat scenarios <:need:`gd_guidl__sec_ana_threat_scenarios`>.
+Use the content of the document :need:`gd_temp__plat_threat_scenario`,
+:need:`gd_temp__feat_sec_ana_threat` or :need:`gd_temp__comp_sec_ana_threat` to describe
+e.g. why a threat scenario is not applicable for the diagram. If a threat scenario can't
+be applied, the reason has to be documented in the content of the document, so it
+can be recognized.
+
+The attributes of the template are described in :ref:`process_requirements_security_analysis_attributes`.
+
+**Steps:**
+
+#. For each architectural element check if a threat from the threat scenarios :need:`gd_guidl__sec_ana_threat_scenarios` applies.
+#. If a threat scenario applies, use the template :need:`gd_temp__plat_threat_scenario`, :need:`gd_temp__feat_sec_ana_threat` or :need:`gd_temp__comp_sec_ana_threat` to perform the analysis.
+#. The title of the analysis should be easily recognizable e.g. "Component xy unauthorized access".
+#. Link the violated architecture with the "violates" attribute.
+#. Replace the placeholders in the "id" attribute with the name of the feature or component and a short description of the element so that it can be easily identified.
+#. Document the threat ID from the threat scenario :need:`gd_guidl__sec_ana_threat_scenarios` that applies to the element in the "threat_id" attribute.
+#. Describe the threat effect of the threat scenario on the element in the "threat_effect" attribute. Use the violation cause description and enlarge it if it's applicable to the considered element.
+#. Document the mitigation. This can be (accept, avoid, reduce, share) of the threat.
+#. If there is no mitigation or the mitigation is not sufficient, a mitigation issue has to be created in the Issue Tracking system and linked in the "mitigation_issue" attribute.
+#. The analysis is finished if for each identified threat a sufficient mitigation exists.
+#. Unless the attribute sufficient is yes, mitigation and argument attributes can be still empty.
+#. Continue the analysis until all applicable threat scenarios are checked.
+#. The verification is done by applying the checklist :need:`gd_chklst__security_analysis`.
+
+.. note::
+   If there are changes they have to be analyzed with an impact analysis
+   :need:`gd_temp__change_impact_analysis`. If needed the Security Analysis has to be
+   updated accordingly. Therefore all necessary steps have to be repeated.
+
+Examples for Security Analysis at feature level
+===============================================
+
+future PR (https://github.com/eclipse-score/process_description/issues/409).
+
+Examples for Security Analysis at component level
+=================================================
+
+future PR (https://github.com/eclipse-score/process_description/issues/409).