Add threat models to docs

doc/conf.py

@@ -117,11 +117,14 @@
 # -- Options for autosectionlabel extension -------------------------------
 autosectionlabel_maxdepth = 3
 
-# Suppress warnings about duplicate labels from argparse directive
+# Suppress warnings about duplicate labels from argparse directive and
+# from the generated threat-model pages (which share section names).
 suppress_warnings = [
     "autosectionlabel.reference/commands",
     "autosectionlabel.reference/manifest",
     "autosectionlabel.howto/updating-projects",
+    "autosectionlabel.explanation/threat_model_supply_chain",
+    "autosectionlabel.explanation/threat_model_usage",
 ]
 
 # Options for sphinx-autoissues

doc/explanation/security.rst

@@ -95,3 +95,16 @@ to reproduce a deterministic dependency state.
 - Execution in CI environments with insufficient network or secret isolation may
   allow exfiltration risks if upstream sources are compromised or intentionally
   malicious.
+
+Threat Models
+-------------
+
+The following pages document the two threat models in detail. Each page is
+generated from the corresponding Python module in ``security/`` — see
+``security/README.md`` for instructions on regenerating them.
+
+.. toctree::
+   :maxdepth: 1
+
+   threat_model_supply_chain
+   threat_model_usage

security/README.md

@@ -13,11 +13,11 @@ the SHA above.
 After this you can generate various reports using:
 
 ```bash
-python -m security.tm_supply_chain --report security/report_template.md > report.md
+python -m security.tm_supply_chain --report security/report_template.rst > doc/explanation/threat_model_supply_chain.rst
 python -m security.tm_supply_chain --dfd
 python -m security.tm_supply_chain --seq
 
-python -m security.tm_usage --report security/report_template.md > report_usage.md
+python -m security.tm_usage --report security/report_template.rst > doc/explanation/threat_model_usage.rst
 python -m security.tm_usage --dfd
 python -m security.tm_usage --seq
 ```

security/report_template.rst

@@ -0,0 +1,129 @@
+.. ============================================================
+.. Auto-generated file — do not edit manually.
+.. Regenerate with (see security/README.md for exact commands):
+..
+..   python -m security.tm_<supply_chain|usage> \
+..       --report security/report_template.rst \
+..       > doc/explanation/threat_model_<name>.rst
+.. ============================================================
+
+System Description
+------------------
+
+{tm.description}
+
+Assumptions
+-----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Name
+     - Description
+{tm.assumptions:repeat:
+   * - {{item.name}}
+     - {{item.description}}
+}
+
+Dataflows
+---------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 35 20 20 25
+
+   * - Name
+     - From
+     - To
+     - Protocol
+{dataflows:repeat:
+   * - {{item.display_name:call:}}
+     - {{item.source.name}}
+     - {{item.sink.name}}
+     - {{item.protocol}}
+}
+
+Data Dictionary
+---------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 55 20
+
+   * - Name
+     - Description
+     - Classification
+{data:repeat:
+   * - {{item.name}}
+     - {{item.description}}
+     - {{item.classification.name}}
+}
+
+Actors
+------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Name
+     - Description
+{actors:repeat:
+   * - {{item.name}}
+     - {{item.description}}
+}
+
+Boundaries
+----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 75
+
+   * - Name
+     - Description
+{boundaries:repeat:
+   * - {{item.name}}
+     - {{item.description}}
+}
+
+Assets
+------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 55 20
+
+   * - Name
+     - Description
+     - Type
+{assets:repeat:
+   * - {{item.name}}
+     - {{item.description}}
+     - {{item:call:getElementType}}
+}
+
+{tm.excluded_findings:if:
+Excluded Threats
+----------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 12 28 20 20 8 12
+
+   * - ID
+     - Description
+     - Target
+     - Assumption
+     - Severity
+     - References
+}
+{tm.excluded_findings:repeat:
+   * - {{item:call:getThreatId}}
+     - {{item:call:getFindingDescription}}
+     - {{item:call:getFindingTarget}}
+     - {{item.assumption.name}}
+     - {{item:call:getFindingSeverity}}
+     - {{item:call:getFindingReferences}}
+}