doc: add security documentation pipeline flow diagram

doc/explanation/security.rst

@@ -18,11 +18,12 @@ PyPI distribution, and runtime execution in developer and build
 environments.
 
 The model is aligned with the `Cyber Resilience Act (CRA)`_ and the
-`EN 40000`_ series of cybersecurity standards, using STRIDE as the threat
+`EN 40000`_ series of cybersecurity standards, using `STRIDE`_ as the threat
 classification methodology. It is inspired by the `ENISA Security by Design and Default Playbook`_.
 
 .. _`Cyber Resilience Act (CRA)`: https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R2847
-.. _`EN 40000`: https://www.cencenelec.eu/media/CEN-CENELEC/Events/Webinars/2025/2025-03-10_webinar_cyberresilience_act.pdf
+.. _`EN 40000`: https://www.cencenelec.eu/areas-of-work/cen-cenelec-topics/cybersecurity/
+.. _`STRIDE`: https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats
 .. _`ENISA Security by Design and Default Playbook`: https://www.enisa.europa.eu/sites/default/files/2026-03/ENISA_Secure_By_Design_and_Default_Playbook_v0.4_draft_for_consultation.pdf
 
 The threat model is split into two focused modules:
@@ -103,6 +104,119 @@ threat models below.
   manifest destination path, or hostile archive entries, could write, overwrite, or
   delete files outside the intended vendoring directory on the end-user machine.
 
+Security Documentation Pipeline
+--------------------------------
+
+The diagram below follows the structure of figure 4.1.2.2 in the
+`EU Blue Guide on the implementation of EU product rules (2022) <https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX%3A52022XC0629%2804%29>`_:
+all requirements are on the left, a risk-and-threat assessment step (dashed box)
+selects which requirements apply, the applicable subset sits in the third column,
+and the right side shows two output paths — a solid-arrow path where coverage is
+provided by a recognised methodology (STRIDE / pytm), and a dashed-arrow path
+where no harmonised standard applies and the requirement is addressed directly as
+a documented gap or compliance artefact.
+
+.. uml:: /static/uml/security_doc_flow.puml
+
+**Threat model pipeline** —
+`security/tm_supply_chain.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_supply_chain.py>`_
+and
+`security/tm_usage.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_usage.py>`_
+define the model elements (actors, data flows, trust boundaries) using the
+*pytm* library.
+`security/threats.json <https://github.com/dfetch-org/dfetch/blob/main/security/threats.json>`_
+provides a catalog of 60+ STRIDE-classified threats.
+`security/tm_render.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_render.py>`_
+drives *pytm*, matches threats against model elements, and combines the output
+with
+`security/report_template.rst <https://github.com/dfetch-org/dfetch/blob/main/security/report_template.rst>`_
+to produce the two RST threat-model pages (:doc:`threat_model_supply_chain` and
+:doc:`threat_model_usage`), each containing an embedded data-flow diagram, a
+sequence diagram, and tables for assets, threats, and controls.
+
+**Compliance pipeline** —
+`security/compliance_data.py <https://github.com/dfetch-org/dfetch/blob/main/security/compliance_data.py>`_
+defines the 46 dfetch controls and their mapping to CRA essential requirements
+and prEN 40000-1-4 security objectives.
+`security/compliance.py <https://github.com/dfetch-org/dfetch/blob/main/security/compliance.py>`_
+reads those definitions together with the static OSCAL catalog and generates
+:doc:`compliance_track` (human-readable RST mapping tables) and
+`security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
+(machine-readable OSCAL 1.1.2 Component Definition). The
+:doc:`control_register` page is maintained manually and references controls
+defined in ``compliance_data.py``.
+
+**Release attestations** — GitHub Actions generates five cryptographic attestation
+types *about dfetch itself* during every release, signed by Sigstore and verifiable
+by consumers with ``gh attestation verify`` (see :ref:`verify-integrity`):
+CycloneDX SBOM (composition of the published package), SLSA Build Provenance
+(source-to-binary traceability), SLSA Source Provenance (governance controls on
+``main``), Verification Summary Attestation (VSA), and in-toto Test Results
+(CI test suite passed before any binary was produced).  These are required by
+supply-chain controls :ref:`C-026 <c-026>`, :ref:`C-037 <c-037>`,
+:ref:`C-039 <c-039>`, and :ref:`C-040 <c-040>`.
+
+**Dependency-scanning outputs** — When users run ``dfetch check``, the reporting
+layer emits findings about outdated or missing vendored dependencies in the format
+of their choice:
+:ref:`SARIF <check-ci-github>` (for GitHub code scanning),
+:ref:`Code Climate JSON <check-ci-gitlab>` (GitLab merge-request quality reports), or
+:ref:`Jenkins JSON <check-ci-jenkins>` (Jenkins warnings-ng plugin).
+
+**Artifacts at a glance**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 15 45
+
+   * - Artifact
+     - Type
+     - Purpose
+
+   * - :doc:`threat_model_supply_chain`
+     - RST (generated)
+     - Supply-chain threat model: DFD, sequence diagram, STRIDE tables, controls
+
+   * - :doc:`threat_model_usage`
+     - RST (generated)
+     - Runtime threat model: DFD, sequence diagram, STRIDE tables, controls
+
+   * - :doc:`compliance_track`
+     - RST (generated)
+     - CRA Annex I → prEN 40000-1-4 SO.* → dfetch control traceability tables
+
+   * - :doc:`control_register`
+     - RST (maintained)
+     - All 46 dfetch controls (C-001 to C-046) with references and status
+
+   * - `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
+     - OSCAL 1.1.2 JSON
+     - Machine-readable Component Definition; maps dfetch controls to CRA ECRs
+
+   * - `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_
+     - OSCAL 1.1.2 JSON
+     - Static prEN 40000-1-4 catalog (input to compliance pipeline, not generated)
+
+   * - :ref:`Release attestations <verify-integrity>`
+     - Sigstore-signed (GitHub Actions)
+     - Five attestation types generated *about dfetch* on every release: CycloneDX
+       SBOM, SLSA Build Provenance, SLSA Source Provenance, VSA, in-toto Test Results.
+       Required by controls :ref:`C-026 <c-026>`, :ref:`C-037 <c-037>`,
+       :ref:`C-039 <c-039>`, :ref:`C-040 <c-040>`;
+       verifiable with ``gh attestation verify``.
+
+   * - :ref:`SARIF output <check-ci-github>`
+     - JSON (SARIF 2.1.0)
+     - ``dfetch check --output-type sarif``; upload to GitHub code scanning
+
+   * - :ref:`Code Climate JSON <check-ci-gitlab>`
+     - JSON (Code Climate)
+     - ``dfetch check --output-type code-climate``; GitLab MR quality widget
+
+   * - :ref:`Jenkins JSON <check-ci-jenkins>`
+     - JSON
+     - ``dfetch check --output-type jenkins``; Jenkins warnings-ng plugin
+
 Threat Models
 -------------
 
@@ -149,3 +263,87 @@ Machine-readable OSCAL 1.1.2 artifacts are kept alongside the source:
 - `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_ — dfetch Component Definition
 
 The complete list of all controls is on the :doc:`control_register` page.
+
+Further Reading
+---------------
+
+Cyber Resilience Act
+~~~~~~~~~~~~~~~~~~~~
+
+- `Regulation (EU) 2024/2847 — Cyber Resilience Act <https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R2847>`_ —
+  the legislative text; Annex I Part I lists the 13 essential requirements (ECR-a … ECR-m)
+  and Part II the seven vulnerability-handling requirements.
+- `EU Commission CRA overview <https://digital-strategy.ec.europa.eu/en/policies/cyber-resilience-act>`_ —
+  accessible summary of scope, obligations, timeline, and links to delegated and implementing acts.
+- `CRA draft guidance, March 2026 (Ares(2026)2319816) <https://digital-strategy.ec.europa.eu/en/news/commission-publishes-feedback-draft-guidance-assist-companies-applying-cyber-resilience-act>`_ —
+  Commission guidance on applying the CRA; covers free and open-source software, remote data
+  processing, and support periods.
+- `BSI TR-03183-1: Cyber Resilience Requirements for Manufacturers <https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TR03183/BSI-TR-03183-1.pdf>`_ —
+  practical risk-based guidance aligned with CRA; used as the risk-context framework in
+  dfetch's threat model pages.
+
+EN 40000 harmonised standards
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The EN 40000 family is being developed by CEN/CLC/JTC 13 to provide harmonised
+standards under the CRA. Once published in the OJEU, compliance with them confers a
+presumption of conformity with the corresponding CRA essential requirements.
+
+- `CEN/CENELEC cybersecurity standards page <https://www.cencenelec.eu/areas-of-work/cen-cenelec-topics/cybersecurity/>`_ —
+  overview of the EN 40000 work programme (prEN 40000-1-1 through 40000-1-4) and
+  the CEN/CLC/JTC 13 committee.
+- `CEN/CENELEC CRA webinar slides (March 2025) <https://www.cencenelec.eu/media/CEN-CENELEC/Events/Webinars/2025/2025-03-10_webinar_cyberresilience_act.pdf>`_ —
+  explains how each part of EN 40000 maps to CRA obligations, with an overview of
+  the Security Objectives (SO.*) in prEN 40000-1-4.
+- `EU Blue Guide on the implementation of EU product rules (2022) <https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX%3A52022XC0629%2804%29>`_ —
+  explains how manufacturers identify applicable requirements, choose specifications,
+  and demonstrate conformity; figure 4.1.2.2 inspired the security documentation
+  flow diagram on this page.
+- `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_ —
+  dfetch's machine-readable OSCAL 1.1.2 representation of the prEN 40000-1-4 catalog,
+  derived from the CEN/CLC/JTC 13 WG 9 deep-dive session (March 2026).
+
+Threat modelling
+~~~~~~~~~~~~~~~~
+
+- `STRIDE methodology <https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats>`_ —
+  Microsoft's six-category threat classification (Spoofing, Tampering, Repudiation,
+  Information Disclosure, Denial of Service, Elevation of Privilege); used to classify
+  every entry in
+  `security/threats.json <https://github.com/dfetch-org/dfetch/blob/main/security/threats.json>`_.
+- `pytm — Pythonic Threat Modeling <https://github.com/izar/pytm>`_ —
+  the library used by ``tm_supply_chain.py`` and ``tm_usage.py`` to define model elements
+  (actors, data flows, trust boundaries) and auto-generate threat findings.
+- `BSI TR-03183-1 <https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TR03183/BSI-TR-03183-1.pdf>`_ —
+  provides the risk-context chapter structure used in the threat model pages.
+- `ENISA Security by Design and Default Playbook <https://www.enisa.europa.eu/sites/default/files/2026-03/ENISA_Secure_By_Design_and_Default_Playbook_v0.4_draft_for_consultation.pdf>`_ —
+  ENISA guidance on integrating security from the start; the overall model structure is
+  inspired by this playbook.
+
+OSCAL
+~~~~~
+
+`OSCAL (Open Security Controls Assessment Language) <https://pages.nist.gov/OSCAL/>`_ is a
+set of NIST-published JSON/XML schemas for machine-readable security documentation.
+dfetch uses OSCAL 1.1.2 for two artifacts:
+
+- `OSCAL Catalog model <https://pages.nist.gov/OSCAL/reference/latest/catalog/>`_ —
+  used by ``cra_pren_4000014_oscal_catalog.json`` to represent the prEN 40000-1-4
+  security objectives as a structured catalog.
+- `OSCAL Component Definition model <https://pages.nist.gov/OSCAL/reference/latest/component-definition/>`_ —
+  used by ``dfetch.component-definition.json`` to describe how dfetch implements each
+  control and maps it back to CRA essential requirements via SO.* objectives.
+
+Security assessment output formats
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `SARIF 2.1.0 (OASIS standard) <https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html>`_ —
+  Static Analysis Results Interchange Format; used by ``dfetch check --output-type sarif``
+  for :ref:`GitHub code scanning integration <check-ci-github>`.
+- `CycloneDX specification <https://cyclonedx.org/specification/overview/>`_ —
+  SBOM format used for the release attestation that GitHub Actions generates
+  *about dfetch itself* on every release; verifiable with ``gh attestation verify``
+  (see :ref:`verify-integrity`).
+- `Code Climate test coverage spec <https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md>`_ —
+  JSON format used by ``dfetch check --output-type code-climate`` for
+  :ref:`GitLab merge-request quality widgets <check-ci-gitlab>`.

doc/reference/glossary.rst

@@ -65,12 +65,15 @@ Glossary
       entries.
 
    SBOM
-      Software Bill of Materials.  A machine-readable inventory of all vendored
-      dependencies, generated by ``dfetch report -t sbom``.  *Dfetch* produces
-      SBOMs in `CycloneDX <https://cyclonedx.org/>`_ JSON format, including
-      each dependency's URL, revision, auto-detected license, and — for
-      :term:`Archive` sources — a cryptographic hash when an
-      :term:`Integrity` field is present.
+      Software Bill of Materials — a machine-readable inventory of software
+      components and their licences.  *Dfetch* uses CycloneDX JSON format
+      in two contexts: (1) ``dfetch report -t sbom`` generates an SBOM of a
+      project's vendored dependencies, listing each dependency's URL, revision,
+      auto-detected licence, and — for :term:`Archive` sources — the
+      cryptographic hash from the :term:`Integrity` field; (2) the dfetch
+      release pipeline generates a CycloneDX SBOM *about dfetch itself* as a
+      Sigstore-signed :term:`Attestation` on every release, verifiable with
+      ``gh attestation verify`` (see :ref:`verify-integrity`).
 
    Source
       The subfolder inside an upstream repository to copy, declared with the
@@ -95,9 +98,103 @@ Glossary
       all :term:`Subproject` dependencies and is typically the repository that
       is committed to version control.
 
+   Attestation
+      A cryptographic claim about a software artifact, signed by GitHub Actions
+      via :term:`Sigstore` and published in the `dfetch attestation registry
+      <https://github.com/dfetch-org/dfetch/attestations>`_.  Attestations are
+      verifiable by anyone using ``gh attestation verify`` without trusting any
+      private key.  dfetch publishes four attestation types on every release:
+      :term:`Build Provenance`, :term:`SBOM` (CycloneDX composition of the
+      package), :term:`VSA`, and in-toto Test Results (the CI test suite passed
+      before any binary was produced).  :term:`Source Provenance` is published
+      on every push to ``main`` rather than per-release.  See
+      :ref:`verify-integrity` for per-artifact verification instructions.
+
+   Build Provenance
+      An :term:`SLSA` attestation recording the exact source commit and GitHub
+      Actions workflow that produced a release artifact.  Lets consumers verify
+      that a binary was built from the claimed source by the official CI workflow
+      and was not injected or modified after the build.  Required by supply-chain
+      control C-037; verifiable with ``gh attestation verify`` (see
+      :ref:`verify-integrity`).
+
+   CRA
+      Cyber Resilience Act — Regulation (EU) 2024/2847, in force from
+      10 December 2024.  It imposes cybersecurity requirements on manufacturers
+      of *Products with Digital Elements* placed on the EU market.  dfetch's
+      :ref:`security model <security>` aligns with the 13 CRA Annex I essential
+      requirements (ECR-a through ECR-m) using the :term:`EN 40000` harmonised
+      standards and :term:`OSCAL` machine-readable documentation.
+
+   EN 40000
+      The CEN/CENELEC family of harmonised cybersecurity standards developed
+      under the :term:`CRA` by CEN/CLC/JTC 13.  The relevant parts for dfetch
+      are prEN 40000-1-2 (product security context), prEN 40000-1-3
+      (vulnerability handling), and prEN 40000-1-4 (security objectives SO.*
+      that bridge CRA essential requirements to concrete controls).  Once
+      published in the OJEU, compliance with these standards gives a presumption
+      of conformity with the corresponding CRA requirements.  dfetch's mapping
+      is captured in :doc:`/explanation/compliance_track`.
+
+   OSCAL
+      Open Security Controls Assessment Language — a set of NIST-published
+      JSON/XML schemas for machine-readable security control documentation.
+      dfetch uses OSCAL 1.1.2 for
+      ``security/cra_pren_4000014_oscal_catalog.json`` (the prEN 40000-1-4
+      catalog) and ``security/dfetch.component-definition.json`` (dfetch's
+      Component Definition, which maps the 46 dfetch controls to :term:`CRA`
+      ECRs via :term:`EN 40000` Security Objectives).
+
+   SARIF
+      Static Analysis Results Interchange Format — an OASIS standard
+      (version 2.1.0) for exchanging static-analysis findings.
+      ``dfetch check --output-type sarif`` produces a SARIF file that can be
+      uploaded to GitHub code scanning to surface out-of-date or missing
+      dependencies as security alerts in pull requests.  See
+      :ref:`check-ci-github`.
+
+   Sigstore
+      An open-source project providing transparency-log-backed code-signing
+      without long-lived private keys.  GitHub Actions signs dfetch's
+      :term:`Attestation` artifacts via Sigstore; the signatures are anchored
+      in a public, append-only transparency log (Rekor) so that forgery is
+      detectable by anyone.
+
+   SLSA
+      Supply-chain Levels for Software Artifacts — a security framework defining
+      increasing levels of supply-chain integrity guarantees.  dfetch publishes
+      two SLSA attestation types per release: :term:`Build Provenance`
+      (source-to-binary traceability) and :term:`Source Provenance` (governance
+      controls on the ``main`` branch).
+
+   Source Provenance
+      An :term:`SLSA` attestation recording which branch-protection, code-review,
+      and ancestry-enforcement controls were active when a commit was merged to
+      ``main``.  Lets consumers verify that dfetch source code went through the
+      required governance process before being included in a release.  Required
+      by control C-037; published on every push to ``main`` via
+      ``slsa-framework/source-actions``.  See :ref:`verify-integrity`.
+
+   STRIDE
+      A threat-classification framework developed by Microsoft: Spoofing,
+      Tampering, Repudiation, Information Disclosure, Denial of Service,
+      Elevation of Privilege.  Every threat in ``security/threats.json`` is
+      classified by STRIDE category to identify which security property it
+      violates and which controls address it.  See
+      :doc:`/explanation/threat_model_supply_chain` and
+      :doc:`/explanation/threat_model_usage`.
+
    Vendoring
       The practice of copying third-party source code directly into your own
       repository rather than relying on a package manager to fetch it at build
       time.  *Dfetch* automates the fetch, version-pinning, patching, and
       update lifecycle of vendored dependencies.  See :ref:`Vendoring <vendoring>`
       for a detailed discussion of the trade-offs.
+
+   VSA
+      Verification Summary Attestation — an :term:`SLSA` attestation attached
+      to binary installer artifacts that records the source archive was itself
+      attested and verified before the binary was produced.  It links
+      source-level trust to the installed binary so consumers can confirm the
+      full source-to-installer chain without re-verifying the source separately.
+      See :ref:`verify-integrity`.