dfetch-org
diff --git a/‎doc/explanation/compliance_track.rst‎
Lines changed: 18 additions & 6 deletions b/‎doc/explanation/compliance_track.rst‎
Lines changed: 18 additions & 6 deletions
diff --git a/‎doc/explanation/security.rst‎
Lines changed: 37 additions & 52 deletions b/‎doc/explanation/security.rst‎
Lines changed: 37 additions & 52 deletions
diff --git a/‎doc/explanation/security_pipeline.rst‎
Lines changed: 27 additions & 19 deletions b/‎doc/explanation/security_pipeline.rst‎
Lines changed: 27 additions & 19 deletions
@@ -25,7 +25,7 @@ concrete dfetch controls or documented gaps::
            ↓
    dfetch control (C-001 … C-046) or documented gap
 
-Machine-readable artifacts are kept alongside the source, encoded in OSCAL 1.2.2:
+Machine-readable artifacts are kept alongside the source, encoded in :term:`OSCAL` 1.2.2:
 
 - `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_ — prEN 40000-1-4 catalog (includes parties, roles, and responsible-parties)
 - `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_ — dfetch Component Definition (includes supplier party, purpose, evidence links per implemented-requirement)
@@ -392,15 +392,15 @@ Gap Analysis — Compliance-Only Controls
 
 3 compliance-only controls address CRA requirements not independently covered by the Track A risk models.
 
-**:ref:`C-043 <c-043>` — Release-gate CVE check (ECR-a, SO.VulnerabilityManagementProcess → GEC-1)**
+.. rubric:: :ref:`C-043 <c-043>` — Release-gate CVE check (ECR-a, SO.VulnerabilityManagementProcess → GEC-1)
 
 dfetch's CI detects vulnerabilities at commit time (:ref:`C-015 <c-015>`, :ref:`C-016 <c-016>`, :ref:`C-017 <c-017>`). :ref:`C-043 <c-043>` completes the coverage: the publish workflow runs ``pip-audit`` against the project's runtime dependencies via the OSV database and blocks the release if any known vulnerability is found.
 
-**:ref:`C-044 <c-044>` — Data minimisation policy (ECR-g, SO.DataMinimization → DTM-1)**
+.. rubric:: :ref:`C-044 <c-044>` — Data minimisation policy (ECR-g, SO.DataMinimization → DTM-1)
 
 dfetch processes dependency metadata only. The ``.dfetch_data.yaml`` file stores: ``remote_url`` (credentials stripped by :ref:`C-036 <c-036>`), ``revision``, optional ``integrity.hash``, and ``last_fetch`` timestamp. Each field is functionally necessary for ``dfetch check`` and ``dfetch freeze``. No personal data is collected; no telemetry is sent. :ref:`C-044 <c-044>` formalises this assertion as a documented policy.
 
-**:ref:`C-046 <c-046>` — Exploit mitigation inventory (ECR-k, SO.ReduceImpactOfIncident → GEC-11)**
+.. rubric:: :ref:`C-046 <c-046>` — Exploit mitigation inventory (ECR-k, SO.ReduceImpactOfIncident → GEC-11)
 
 prEN 40000-1-4 ECR-k requires documenting applicable exploit mitigation techniques. For dfetch (pure Python):
 
@@ -417,8 +417,20 @@ prEN 40000-1-4 ECR-k requires documenting applicable exploit mitigation techniqu
 OSCAL Artifacts
 ---------------
 
-The OSCAL 1.2.2 Component Definition references the catalog file and can be
-regenerated with:
+:term:`OSCAL` (Open Security Controls Assessment Language) is a
+NIST-published JSON/XML schema set for machine-readable security
+documentation. It lets GRC tools, conformity-assessment toolchains, and
+downstream integrators ingest dfetch's control evidence programmatically —
+rather than reading prose — and map it to their own compliance frameworks.
+
+dfetch ships two OSCAL 1.2.2 artifacts alongside the source:
+
+- `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_ — the prEN 40000-1-4 Security Objectives expressed as a structured catalog;
+  import this into your GRC tool to obtain the requirement definitions.
+- `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_ — the dfetch Component Definition; maps each implemented control back to
+  the catalog objectives with evidence links.
+
+Both files are regenerated with:
 
 .. code-block:: bash
 
 
@@ -13,17 +13,14 @@ Security Model
   and dfetch itself critically, and provide feedback or contributions to enhance its accuracy and completeness.
 
 This page documents the security design of *dfetch* across its full software
-development lifecycle (SDLC): from source contribution through CI/CD,
+development lifecycle (:term:`SDLC`): from source contribution through CI/CD,
 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
+The model is aligned with the :term:`CRA` (Cyber Resilience Act) and the
+:term:`EN 40000` series of cybersecurity standards, using :term:`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/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:
@@ -55,34 +52,36 @@ Product and manufacturer identification
    * - Maintainer
      - Ben Spoor
    * - Distribution channel
-     - PyPI (``pip install dfetch``); GitHub Releases (stand-alone binary)
+     - `PyPI <https://pypi.org/project/dfetch/>`_ (``pip install dfetch``);
+       `GitHub Releases <https://github.com/dfetch-org/dfetch/releases>`_ (stand-alone binary);
+       `winget <https://winstall.app/apps/DFetch-org.DFetch>`_ (``winget install dfetch``)
    * - Source repository
      - https://github.com/dfetch-org/dfetch
    * - License
-     - MIT
+     - `MIT <https://github.com/dfetch-org/dfetch/blob/main/LICENSE>`_
    * - CRA applicability
      - dfetch is developed and distributed as a non-commercial open-source project.
-       Under the Cyber Resilience Act, applicability depends on whether software
+       Under the :term:`CRA`, applicability depends on whether software
        is placed on the market in the context of a commercial activity.
        As of 2026-05-02, dfetch is not monetized and is not offered as part
-       of a commercial service. However, CRA obligations may become applicable
+       of a commercial service. However, :term:`CRA` obligations may become applicable
        in downstream contexts where third parties integrate dfetch into commercial
-       products, in which case those manufacturers bear their own Article 13
+       products, in which case those manufacturers bear their own `Article 13 <https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R2847>`_
        obligations to assess and document the security of components they integrate,
        including open-source dependencies.
 
 Intended purpose, foreseeable use, and reasonably foreseeable misuse (IPFRU)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-*Intended purpose*: fetch and vendor external source-code dependencies (from
-Git repositories, SVN repositories, or plain archive URLs) as plain files into
-a project repository. dfetch reads a declarative manifest (``dfetch.yaml``),
+*Intended purpose*: fetch and :term:`vendor <Vendoring>` external source-code dependencies (from
+Git repositories, SVN repositories, or plain :term:`Archive` URLs) as plain files into
+a project repository. dfetch reads a declarative :term:`Manifest` (``dfetch.yaml``),
 resolves each declared dependency to the requested revision, copies the source
-tree to the declared destination path, and records metadata for subsequent
+tree to the declared :term:`destination <Destination>` path, and records :term:`Metadata` for subsequent
 up-to-date checks.
 
 *Foreseeable use*: invoked interactively on a developer workstation, or
-non-interactively inside CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, etc.)
+non-interactively inside CI/CD pipelines (`GitHub Actions <https://github.com/features/actions>`_, `GitLab CI <https://docs.gitlab.com/ee/ci/>`_, `Jenkins <https://www.jenkins.io/>`_, etc.)
 to reproduce a deterministic dependency state.
 
 *Reasonably foreseeable misuse*: the following are the principal harms *dfetch*
@@ -94,16 +93,16 @@ threat models below.
   non-interactively in a pipeline holding registry tokens, signing keys, or cloud
   credentials, a compromised or intentionally malicious upstream source could read
   and exfiltrate those secrets.
-- **Resource exhaustion from hostile archives.** A crafted archive (for example a
+- **Resource exhaustion from hostile archives.** A crafted :term:`Archive` (for example a
   decompression bomb) can expand to an extreme size or member count on extraction,
   exhausting disk or memory and denying service to the developer or build host.
 - **Introduction of vulnerable or malicious code into the superproject.** More
   subtle than denial of service: an attacker-controlled upstream may ship source
-  carrying latent vulnerabilities or backdoors that are vendored into the consuming
-  project and propagated into downstream products.
+  carrying latent vulnerabilities or backdoors that are :term:`vendored <Vendoring>` into the consuming
+  :term:`Superproject` and propagated into downstream products.
 - **Destruction or overwrite of files outside the destination folder.** A malicious
-  manifest destination path, or hostile archive entries, could write, overwrite, or
-  delete files outside the intended vendoring directory on the end-user machine.
+  :term:`Manifest` destination path, or hostile :term:`Archive` entries, could write, overwrite, or
+  delete files outside the intended :term:`Vendoring` directory on the end-user machine.
 
 .. _risk-rating-methodology:
 
@@ -177,34 +176,13 @@ for regeneration instructions.
 CRA Compliance
 --------------
 
-The :doc:`compliance_track` page maps all 13 CRA Annex I Part I essential
-requirements (ECR-a through ECR-m) through prEN 40000-1-4 Security Objectives
-to dfetch's implemented controls.  It also covers the seven Part II
-vulnerability-handling requirements via prEN 40000-1-3.
-
-The three-tier traceability model is::
-
-   CRA Annex I Essential Requirement (ECR-a … ECR-m)
-           ↓
-   prEN 40000-1-4 Security Objective (SO.*)
-           ↓
-   dfetch control (C-001 … C-046) or documented gap
-
-Three compliance-only controls address CRA requirements not independently
-surfaced by the risk models:
-
-- :ref:`C-043 <c-043>` (release-gate CVE check) — ECR-a / SO.VulnerabilityManagementProcess → GEC-1
-- :ref:`C-044 <c-044>` (data minimisation policy) — ECR-g / SO.DataMinimization → DTM-1
-- :ref:`C-046 <c-046>` (exploit mitigation inventory) — ECR-k / SO.ReduceImpactOfIncident → GEC-11
-
-Machine-readable artifacts are kept alongside the source, encoded in OSCAL 1.1.2
-(pinned version; NIST released 1.2.2 in April 2026 — migration not yet performed):
-
-- `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_ — prEN 40000-1-4 catalog
-  (derived from the CEN/CLC/JTC 13 WG 9 deep-dive session, March 2026)
-- `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.
+The :doc:`compliance_track` page provides full three-tier traceability from all
+13 CRA Annex I Part I essential requirements (ECR-a through ECR-m) through
+prEN 40000-1-4 Security Objectives to dfetch's implemented controls, including
+machine-readable :term:`OSCAL` artifacts and the gap analysis for compliance-only
+controls.  It also covers the seven Part II vulnerability-handling requirements
+via prEN 40000-1-3.  The complete list of all controls is on the
+:doc:`control_register` page.
 
 .. toctree::
    :maxdepth: 1
@@ -232,7 +210,7 @@ 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
+standards under the :term:`CRA`. Once published in the `OJEU <https://eur-lex.europa.eu/oj/direct-access.html>`_, 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/>`_ —
@@ -255,8 +233,8 @@ Threat modelling
 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.
+:term:`OSCAL` (Open Security Controls Assessment Language) 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/>`_ —
@@ -273,6 +251,13 @@ For an overview of how this documentation set is produced — the threat-model
 pipeline, compliance pipeline, release attestations, and the full artifact
 inventory — see :doc:`security_pipeline`.
 
+.. seealso::
+
+   :doc:`/reference/glossary`
+      Definitions for :term:`CRA`, :term:`EN 40000`, :term:`STRIDE`,
+      :term:`OSCAL`, :term:`SLSA`, :term:`SBOM`, :term:`Sigstore`,
+      :term:`SDLC`, :term:`ECR`, and other terms used on this page.
+
 .. toctree::
    :hidden:
 
 
@@ -21,14 +21,21 @@ a documented gap or compliance artefact.
 
 .. uml:: /static/uml/security_doc_flow.puml
 
+.. seealso::
+
+   :doc:`/reference/glossary`
+      Definitions for :term:`STRIDE`, :term:`OSCAL`, :term:`SBOM`,
+      :term:`SLSA`, :term:`Sigstore`, :term:`Attestation`, :term:`VSA`,
+      :term:`SARIF`, and other terms used on this page.
+
 **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.
+provides a catalog of 60+ :term:`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
@@ -43,27 +50,27 @@ defines all dfetch controls (Track A: risk-driven; Track B: compliance-only cont
 in ``compliance_data.py``) 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
+reads those definitions together with the static :term:`OSCAL` catalog and generates
 :doc:`compliance_track` (human-readable RST mapping tables),
 :doc:`control_register` (the full control register with GitHub references), and
 `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
-(machine-readable OSCAL 1.2.2 Component Definition). The Component Definition
+(machine-readable :term:`OSCAL` 1.2.2 Component Definition). The Component Definition
 includes the supplier party, component purpose, and ``evidence`` links on each
 implemented-requirement pointing to the concrete code or CI file that implements
 the control — making the mapping machine-verifiable.
 
-**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>`.
+**Release attestations** — GitHub Actions generates five cryptographic
+:term:`Attestation` types *about dfetch itself* during every release, signed by
+:term:`Sigstore` and verifiable by consumers with ``gh attestation verify``
+(see :ref:`verify-integrity`): CycloneDX :term:`SBOM` (composition of the
+published package), :term:`Build Provenance` (source-to-binary traceability),
+:term:`Source Provenance` (governance controls on ``main``), :term:`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
+layer emits findings about outdated or missing :term:`vendored <Vendoring>` 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
@@ -81,7 +88,7 @@ of their choice:
 
    * - :doc:`threat_model_supply_chain`
      - RST (generated)
-     - Supply-chain threat model: DFD, sequence diagram, STRIDE tables, controls
+     - Supply-chain threat model: DFD, sequence diagram, :term:`STRIDE` tables, controls
 
    * - :doc:`threat_model_usage`
      - RST (generated)
@@ -96,18 +103,19 @@ of their choice:
      - All dfetch controls with type, references, and status
 
    * - `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
-     - OSCAL 1.2.2 JSON (generated)
-     - Machine-readable Component Definition; maps dfetch controls to CRA ECRs;
+     - :term:`OSCAL` 1.2.2 JSON (generated)
+     - Machine-readable Component Definition; maps dfetch controls to CRA :term:`ECR`\ s;
        includes supplier party, component purpose, and evidence links to code
 
    * - `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_
-     - OSCAL 1.2.2 JSON (static)
+     - :term:`OSCAL` 1.2.2 JSON (static)
      - Static prEN 40000-1-4 catalog; includes parties, roles, and responsible-parties
 
    * - :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.
+     - Five :term:`Attestation` types generated *about dfetch* on every release:
+       CycloneDX :term:`SBOM`, :term:`Build Provenance`, :term:`Source Provenance`,
+       :term:`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``.