.. # ******************************************************************************* # 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`. 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).