Review comments

Author: spoorcc

.devcontainer/Dockerfile

@@ -53,7 +53,7 @@ ENV PYTHONUSERBASE="/home/dev/.local"
 COPY --chown=dev:dev . .
 
 RUN pip install --no-cache-dir --root-user-action=ignore --upgrade pip==26.0.1 \
-    && pip install --no-cache-dir --root-user-action=ignore -e .[development,docs,test,casts,build] \
+    && pip install --no-cache-dir --root-user-action=ignore -e .[development,docs,test,casts,build,security] \
     && pre-commit install --install-hooks
 
 # Set bash as the default shell

doc/explanation/security.rst

@@ -14,7 +14,7 @@ The model is aligned with the `Cyber Resilience Act (CRA)`_ and the
 classification methodology.
 
 .. _`Cyber Resilience Act (CRA)`: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R2847
-.. _`EN 18031`: https://www.etsi.org/deliver/etsi_en/18031_18031_18031_18031/
+.. _`EN 18031`: https://www.cenelec.eu/
 
 The threat model is maintained as executable code in ``security/threat_model.py``
 using the `pytm`_ framework.  Regenerate analysis output with:
@@ -25,6 +25,14 @@ using the `pytm`_ framework.  Regenerate analysis output with:
    python -m security.threat_model --dfd    # Graphviz DFD (stdout)
    python -m security.threat_model --report # STRIDE findings report
 
+.. note::
+
+   The ``--seq`` and ``--dfd`` commands require **PlantUML** and **Graphviz**
+   to be installed on the system.  These are not Python packages and are not
+   installed by ``pip install .[security]``.  Install them separately (e.g.
+   ``apt install plantuml graphviz`` or via your platform package manager)
+   before running the diagram commands.
+
 .. _pytm: https://github.com/izar/pytm
 
 .. note::
@@ -202,7 +210,7 @@ Supporting Assets
    * - SA-06
      - GitHub Actions Workflows
      - Restricted
-     - ``/.github/workflows/*.yml`` — 11 CI/CD pipeline definitions checked into
+     - ``.github/workflows/*.yml`` — 11 CI/CD pipeline definitions checked into
        the repository.  A malicious pull request modifying workflows can
        exfiltrate secrets or publish a backdoored release.  Mitigated by
        SHA-pinned actions and ``persist-credentials: false``.  Risk: ``secrets:
@@ -407,7 +415,7 @@ The following controls are already in place and are reflected in the
      - PA-02, SA-05
      - ``check_no_path_traversal()`` uses ``os.path.realpath`` to reject any
        path that escapes the destination root.
-       ``dfetch/util/util.py:265–285``
+       ``check_no_path_traversal()`` in ``dfetch/util/util.py``
    * - Decompression-bomb protection
      - SA-05, PA-02
      - Archives are rejected if uncompressed size exceeds 500 MB or the member
@@ -473,7 +481,9 @@ The following controls are already in place and are reflected in the
    * - OpenSSF Scorecard
      - EA-03, SA-10
      - Weekly OSSF Scorecard analysis uploaded to GitHub Code Scanning covers
-       17 supply-chain health checks.
+       the full set of OpenSSF Scorecard checks (see the
+       `OpenSSF Scorecard project <https://github.com/ossf/scorecard>`_ for
+       the authoritative list).
        ``.github/workflows/scorecard.yml``
    * - CodeQL static analysis
      - SA-01, SA-06

security/threat_model.py

@@ -19,7 +19,6 @@
     Datastore,
     ExternalEntity,
     Process,
-    Server,
 )
 
 # ── Threat model metadata ────────────────────────────────────────────────────
@@ -134,12 +133,14 @@
     "Invokes Git and SVN as subprocesses (shell=False, list args). "
     "Extracts archives with decompression-bomb limits and path-traversal checks."
 )
-dfetch_cli.controls.validatesInput = True          # StrictYAML + SAFE_STR regex
-dfetch_cli.controls.sanitizesInput = True          # check_no_path_traversal realpath-based
-dfetch_cli.controls.usesParameterizedInput = True  # shell=False, list-based subprocesses
-dfetch_cli.controls.checksInputBounds = True       # 500MB / 10k-member archive limits
-dfetch_cli.controls.isHardened = True              # BatchMode=yes, --non-interactive, type checks
-dfetch_cli.controls.providesIntegrity = True       # hmac.compare_digest SHA-256/384/512
+dfetch_cli.controls.validatesInput = True  # StrictYAML + SAFE_STR regex
+dfetch_cli.controls.sanitizesInput = True  # check_no_path_traversal realpath-based
+dfetch_cli.controls.usesParameterizedInput = (
+    True  # shell=False, list-based subprocesses
+)
+dfetch_cli.controls.checksInputBounds = True  # 500MB / 10k-member archive limits
+dfetch_cli.controls.isHardened = True  # BatchMode=yes, --non-interactive, type checks
+dfetch_cli.controls.providesIntegrity = True  # hmac.compare_digest SHA-256/384/512
 
 gh_actions_workflow = Process("GitHub Actions Workflow")
 gh_actions_workflow.inBoundary = boundary_github
@@ -149,8 +150,12 @@
     "All actions pinned by commit SHA. "
     "harden-runner used in every workflow (egress: audit only)."
 )
-gh_actions_workflow.controls.isHardened = True        # SHA-pinned actions, persist-credentials:false
-gh_actions_workflow.controls.providesIntegrity = True # CodeQL + Scorecard + dependency-review
+gh_actions_workflow.controls.isHardened = (
+    True  # SHA-pinned actions, persist-credentials:false
+)
+gh_actions_workflow.controls.providesIntegrity = (
+    True  # CodeQL + Scorecard + dependency-review
+)
 gh_actions_workflow.controls.hasAccessControl = True  # minimal permissions per workflow
 
 python_build = Process("Python Build (wheel / sdist)")
@@ -182,7 +187,7 @@
 manifest_store.isSQL = False
 manifest_store.classification = Classification.SENSITIVE
 manifest_store.controls.isEncryptedAtRest = False
-manifest_store.controls.validatesInput = True      # StrictYAML validation on read
+manifest_store.controls.validatesInput = True  # StrictYAML validation on read
 
 fetched_source = Datastore("PA-02: Fetched Source Code")
 fetched_source.inBoundary = boundary_dev_env
@@ -209,7 +214,9 @@
     "authenticity relies entirely on transport security (TLS/SSH)."
 )
 integrity_hash_record.storesSensitiveData = False
-integrity_hash_record.hasWriteAccess = False
+integrity_hash_record.hasWriteAccess = (
+    True  # developers and processes write this field in dfetch.yaml
+)
 integrity_hash_record.classification = Classification.SENSITIVE
 integrity_hash_record.controls.providesIntegrity = True
 
@@ -222,7 +229,9 @@
     "Compromise of the PyPI account or registry affects every consumer."
 )
 pypi_package.storesSensitiveData = False
-pypi_package.hasWriteAccess = False
+pypi_package.hasWriteAccess = (
+    True  # publish pipeline writes new releases to this package
+)
 pypi_package.classification = Classification.SENSITIVE
 pypi_package.controls.usesCodeSigning = False  # no Sigstore/cosign signing
 
@@ -244,6 +253,11 @@
 # SA-01 … SA-10: assets that enable primary assets; their loss degrades
 # security or availability of primary assets.
 
+# SA-01: dfetch Process — modelled as dfetch_cli (Process above)
+# The running Python interpreter dispatching all commands.  Subprocess
+# injection or dependency confusion could compromise build-time execution.
+# Classification: Restricted.
+
 vcs_credentials = Data(
     "SA-02: VCS Credentials",
     description=(
@@ -382,6 +396,9 @@
 # EA-03: GitHub Repository — modelled as gh_repository (ExternalEntity above)
 # EA-04: GitHub Actions Infrastructure — modelled as gh_actions_runner (ExternalEntity above)
 # EA-05: PyPI / TestPyPI — modelled as pypi (ExternalEntity above)
+# EA-06: Developer Workstation / CI Runner — modelled as developer / gh_actions_runner (Actors/ExternalEntity above)
+# EA-07: Consumer Build System — modelled as consumer_build (ExternalEntity above)
+# EA-08: Network Transport — modelled as boundary_network (Boundary above); symbol: network_transport
 
 # ── DATA FLOWS ───────────────────────────────────────────────────────────────
 #
@@ -402,8 +419,8 @@
     "no protocol enforcement in manifest schema."
 )
 df03.protocol = "HTTPS / SSH / svn"
-df03.controls.isEncrypted = True   # for HTTPS/SSH paths; NOT for svn:// or http://
-df03.controls.isHardened = True    # BatchMode=yes, --non-interactive
+df03.controls.isEncrypted = True  # for HTTPS/SSH paths; NOT for svn:// or http://
+df03.controls.isHardened = True  # BatchMode=yes, --non-interactive
 
 df04 = Dataflow(remote_git_svn, dfetch_cli, "DF-04: VCS content (inbound, untrusted)")
 df04.description = (
@@ -431,7 +448,7 @@
 )
 df06.protocol = "HTTP or HTTPS"
 df06.controls.providesIntegrity = False  # hash is optional; may be absent
-df06.controls.isEncrypted = False        # http:// allowed
+df06.controls.isEncrypted = False  # http:// allowed
 
 df07 = Dataflow(dfetch_cli, fetched_source, "DF-07: Write vendored files")
 df07.description = (
@@ -453,7 +470,7 @@
     "RISK: patch files are not integrity-verified (no hash in manifest schema). "
     "patch-ng path safety depends on its own internal implementation."
 )
-df10.controls.validatesInput = False   # no integrity hash on patch files
+df10.controls.validatesInput = False  # no integrity hash on patch files
 
 df11 = Dataflow(contributor, gh_repository, "DF-11: Submit pull request")
 df11.description = (