docs(threat-model): refresh top-level page

The top-level page for threat model documents is evidently out-dated,
as it contains text which no longer makes sense on its own. Most
likely it relates back to the days where we had a single threat model
document.

Reword it accordingly. While we are at it, explain the motivation and
structure of the documents.

Change-Id: I63c8f38ec32b6edbfd1b4332eeaca19a01ae70e9
Signed-off-by: Sandrine Bailleux <sandrine.bailleux@arm.com>

diff --git a/docs/threat_model/index.rst b/docs/threat_model/index.rst
index 9fd55a92c14b231c5eb00b1a9720d656d529d205..b22fb1813e69a39494006c13e0c7b3ad2e18aa49 100644 (file)
--- a/docs/threat_model/index.rst
+++ b/docs/threat_model/index.rst
@@ -4,9 +4,27 @@ Threat Model
 Threat modeling is an important part of Secure Development Lifecycle (SDL)
 that helps us identify potential threats and mitigations affecting a system.
 
-In the next sections, we first give a description of the target of evaluation
-using a data flow diagram. Then we provide a list of threats we have identified
-based on the data flow diagram and potential threat mitigations.
+As the TF-A codebase is highly configurable to allow tailoring it best for each
+platform's needs, providing a holistic threat model covering all of its features
+is not necessarily the best approach. Instead, we provide a collection of
+documents which, together, form the project's threat model. These are
+articulated around a core document, called the :ref:`Generic Threat Model`,
+which focuses on the most common configuration we expect to see. The other
+documents typically focus on specific features not covered in the core document.
+
+As the TF-A codebase evolves and new features get added, these threat model
+documents will be updated and extended in parallel to reflect at best the
+current status of the code from a security standpoint.
+
+   .. note::
+
+      Although our aim is eventually to provide threat model material for all
+      features within the project, we have not reached that point yet. We expect
+      to gradually fill these gaps over time.
+
+Each of these documents give a description of the target of evaluation using a
+data flow diagram, as well as a list of threats we have identified using the
+`STRIDE threat modeling technique`_ and corresponding mitigations.
 
 .. toctree::
    :maxdepth: 1
@@ -20,4 +38,6 @@ based on the data flow diagram and potential threat mitigations.
 
 --------------
 
-*Copyright (c) 2021-2022, Arm Limited and Contributors. All rights reserved.*
+*Copyright (c) 2021-2023, Arm Limited and Contributors. All rights reserved.*
+
+.. _STRIDE threat modeling technique: https://docs.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats#stride-model