From 005fa621d0474b53eee1c67d4f8a718872a60055 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Jun 2026 16:09:26 +0000 Subject: [PATCH 1/8] docs: remove duplicated compliance content from security model The three-tier traceability diagram, compliance-only controls listing, OSCAL artifact links, and control register reference were repeated verbatim in security.rst despite being the authoritative content of the auto-generated compliance_track.rst. Replace with a single forwarding sentence pointing readers to the compliance_track page. Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN --- doc/explanation/security.rst | 35 +++++++---------------------------- 1 file changed, 7 insertions(+), 28 deletions(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 2ed8372a3..cf05d3410 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -177,34 +177,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 ` (release-gate CVE check) — ECR-a / SO.VulnerabilityManagementProcess → GEC-1 -- :ref:`C-044 ` (data minimisation policy) — ECR-g / SO.DataMinimization → DTM-1 -- :ref:`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 `_ — prEN 40000-1-4 catalog - (derived from the CEN/CLC/JTC 13 WG 9 deep-dive session, March 2026) -- `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 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 From b2ff91cf1f277bcdaa7cf9ad986fd333b89843da Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Jun 2026 16:40:48 +0000 Subject: [PATCH 2/8] docs: add winget as a distribution channel in the security model Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN --- doc/explanation/security.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index cf05d3410..580ef44fe 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -55,7 +55,7 @@ Product and manufacturer identification * - Maintainer - Ben Spoor * - Distribution channel - - PyPI (``pip install dfetch``); GitHub Releases (stand-alone binary) + - PyPI (``pip install dfetch``); GitHub Releases (stand-alone binary); winget (``winget install dfetch``) * - Source repository - https://github.com/dfetch-org/dfetch * - License From 313633cf628c3862599152884a86c80e2648f432 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Jun 2026 16:49:10 +0000 Subject: [PATCH 3/8] docs: hyperlink each distribution channel in the security model Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN --- doc/explanation/security.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 580ef44fe..ed0bab3c3 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -55,7 +55,9 @@ Product and manufacturer identification * - Maintainer - Ben Spoor * - Distribution channel - - PyPI (``pip install dfetch``); GitHub Releases (stand-alone binary); winget (``winget install dfetch``) + - `PyPI `_ (``pip install dfetch``); + `GitHub Releases `_ (stand-alone binary); + `winget `_ (``winget install dfetch``) * - Source repository - https://github.com/dfetch-org/dfetch * - License From 36ff6b2f1d5b142645abaaa92a01733d6308d957 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Jun 2026 16:51:25 +0000 Subject: [PATCH 4/8] docs: add hyperlinks throughout security model text Link MIT licence, Article 13 CRA reference, GitHub Actions / GitLab CI / Jenkins CI examples, and OJEU mention to their respective pages. Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN --- doc/explanation/security.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index ed0bab3c3..4ad2a87a6 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -61,7 +61,7 @@ Product and manufacturer identification * - Source repository - https://github.com/dfetch-org/dfetch * - License - - MIT + - `MIT `_ * - CRA applicability - dfetch is developed and distributed as a non-commercial open-source project. Under the Cyber Resilience Act, applicability depends on whether software @@ -69,7 +69,7 @@ Product and manufacturer identification 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 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 `_ obligations to assess and document the security of components they integrate, including open-source dependencies. @@ -84,7 +84,7 @@ tree to the declared destination path, and records 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 `_, `GitLab CI `_, `Jenkins `_, etc.) to reproduce a deterministic dependency state. *Reasonably foreseeable misuse*: the following are the principal harms *dfetch* @@ -213,7 +213,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 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 `_ — From 8271b345ded2fa261843cdd8a697359a3d2987a7 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Jun 2026 16:54:56 +0000 Subject: [PATCH 5/8] fix: render gap analysis titles as rubrics so :ref: links resolve correctly RST does not support nesting inline roles inside **bold** markup, causing the :ref: role to be emitted as literal text. Switch to .. rubric:: which renders as a bold heading and correctly processes inline markup. Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN --- doc/explanation/compliance_track.rst | 6 +++--- security/compliance.py | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/explanation/compliance_track.rst b/doc/explanation/compliance_track.rst index ec58d4b03..89513efe5 100644 --- a/doc/explanation/compliance_track.rst +++ b/doc/explanation/compliance_track.rst @@ -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 ` — Release-gate CVE check (ECR-a, SO.VulnerabilityManagementProcess → GEC-1)** +.. rubric:: :ref:`C-043 ` — Release-gate CVE check (ECR-a, SO.VulnerabilityManagementProcess → GEC-1) dfetch's CI detects vulnerabilities at commit time (:ref:`C-015 `, :ref:`C-016 `, :ref:`C-017 `). :ref:`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 ` — Data minimisation policy (ECR-g, SO.DataMinimization → DTM-1)** +.. rubric:: :ref:`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 `), ``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 ` formalises this assertion as a documented policy. -**:ref:`C-046 ` — Exploit mitigation inventory (ECR-k, SO.ReduceImpactOfIncident → GEC-11)** +.. rubric:: :ref:`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): diff --git a/security/compliance.py b/security/compliance.py index 1191dd785..d8dece339 100644 --- a/security/compliance.py +++ b/security/compliance.py @@ -721,7 +721,7 @@ def _render_gap_analysis() -> None: "independently covered by the Track A risk models.\n" ) for title, body in entries: - print(f"**{title}**\n") + print(f".. rubric:: {title}\n") print(f"{body}\n") From 41623ff91226ec213f12c0ca0b306dbfec75e9ab Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Jun 2026 16:56:30 +0000 Subject: [PATCH 6/8] docs: expand OSCAL Artifacts section with context, purpose, and direct links Explain what OSCAL is, what problem it solves for downstream integrators, and link directly to both artifact files in the repository. Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN --- doc/explanation/compliance_track.rst | 16 ++++++++++++++-- security/compliance.py | 17 +++++++++++++++-- 2 files changed, 29 insertions(+), 4 deletions(-) diff --git a/doc/explanation/compliance_track.rst b/doc/explanation/compliance_track.rst index 89513efe5..c3c4bf0b8 100644 --- a/doc/explanation/compliance_track.rst +++ b/doc/explanation/compliance_track.rst @@ -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: +`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 `_ — 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 `_ — the dfetch Component Definition; maps each implemented control back to + the catalog objectives with evidence links. + +Both files are regenerated with: .. code-block:: bash diff --git a/security/compliance.py b/security/compliance.py index d8dece339..b415f6390 100644 --- a/security/compliance.py +++ b/security/compliance.py @@ -825,8 +825,21 @@ def render_rst(track_b_only: bool = False) -> None: print("----\n") print(_rst_title("OSCAL Artifacts", "-")) print( - "The OSCAL 1.2.2 Component Definition references the catalog file and can be\n" - "regenerated with:\n\n" + "`OSCAL (Open Security Controls Assessment Language) `_\n" + "is a NIST-published JSON/XML schema set for machine-readable security\n" + "documentation. It lets GRC tools, conformity-assessment toolchains, and\n" + "downstream integrators ingest dfetch's control evidence programmatically —\n" + "rather than reading prose — and map it to their own compliance frameworks.\n\n" + "dfetch ships two OSCAL 1.2.2 artifacts alongside the source:\n\n" + "- `security/cra_pren_4000014_oscal_catalog.json" + " `_" + " — the prEN 40000-1-4 Security Objectives expressed as a structured catalog;\n" + " import this into your GRC tool to obtain the requirement definitions.\n" + "- `security/dfetch.component-definition.json" + " `_" + " — the dfetch Component Definition; maps each implemented control back to\n" + " the catalog objectives with evidence links.\n\n" + "Both files are regenerated with:\n\n" ".. code-block:: bash\n\n" " python -m security.compliance \\\\\n" " --component security/dfetch.component-definition.json \\\\\n" From 8f0554c084914002edcb48368eec43ee4952f7ca Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Jun 2026 17:05:49 +0000 Subject: [PATCH 7/8] docs: add glossary term refs and links throughout security pages Add three new glossary terms: SDLC, CVE, ECR. Add :term: cross-references in security.rst: replace named external links for CRA/EN 40000/STRIDE with :term: refs; add refs for SDLC, Archive, Manifest, Metadata, Destination, Vendoring, Superproject, OSCAL throughout the body; add a seealso box linking to the glossary. Add :term: refs in security_pipeline.rst for STRIDE, OSCAL, SBOM, SLSA Build/Source Provenance, Sigstore, Attestation, VSA, ECR, Vendoring; add seealso box. Update compliance.py generator to use :term:`OSCAL` in the OSCAL Artifacts section and intro; regenerate compliance_track.rst. Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN --- doc/explanation/compliance_track.rst | 6 ++-- doc/explanation/security.rst | 46 +++++++++++++++------------ doc/explanation/security_pipeline.rst | 46 ++++++++++++++++----------- doc/reference/glossary.rst | 22 +++++++++++++ security/compliance.py | 6 ++-- 5 files changed, 80 insertions(+), 46 deletions(-) diff --git a/doc/explanation/compliance_track.rst b/doc/explanation/compliance_track.rst index c3c4bf0b8..0ff2dca52 100644 --- a/doc/explanation/compliance_track.rst +++ b/doc/explanation/compliance_track.rst @@ -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 `_ — prEN 40000-1-4 catalog (includes parties, roles, and responsible-parties) - `security/dfetch.component-definition.json `_ — dfetch Component Definition (includes supplier party, purpose, evidence links per implemented-requirement) @@ -417,8 +417,8 @@ prEN 40000-1-4 ECR-k requires documenting applicable exploit mitigation techniqu OSCAL Artifacts --------------- -`OSCAL (Open Security Controls Assessment Language) `_ -is a NIST-published JSON/XML schema set for machine-readable security +: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. diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 4ad2a87a6..503c29b36 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -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: @@ -64,10 +61,10 @@ Product and manufacturer identification - `MIT `_ * - 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 `_ obligations to assess and document the security of components they integrate, @@ -76,11 +73,11 @@ Product and manufacturer identification 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 ` 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 ` path, and records :term:`Metadata` for subsequent up-to-date checks. *Foreseeable use*: invoked interactively on a developer workstation, or @@ -96,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 ` 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: @@ -182,7 +179,7 @@ CRA Compliance 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 OSCAL artifacts and the gap analysis for compliance-only +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. @@ -213,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 `_, compliance with them confers a presumption of conformity with the corresponding CRA essential requirements. - `CEN/CENELEC cybersecurity standards page `_ — @@ -236,8 +233,8 @@ Threat modelling OSCAL ~~~~~ -`OSCAL (Open Security Controls Assessment Language) `_ 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 `_ — @@ -254,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: diff --git a/doc/explanation/security_pipeline.rst b/doc/explanation/security_pipeline.rst index 8d671bcba..ae833b8c3 100644 --- a/doc/explanation/security_pipeline.rst +++ b/doc/explanation/security_pipeline.rst @@ -21,6 +21,13 @@ 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 `_ and @@ -28,7 +35,7 @@ and define the model elements (actors, data flows, trust boundaries) using the *pytm* library. `security/threats.json `_ -provides a catalog of 60+ STRIDE-classified threats. +provides a catalog of 60+ :term:`STRIDE`-classified threats. `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 `_ -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 `_ -(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 `, :ref:`C-037 `, -:ref:`C-039 `, and :ref:`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 `, +:ref:`C-037 `, :ref:`C-039 `, and :ref:`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 ` dependencies in the format of their choice: :ref:`SARIF ` (for GitHub code scanning), :ref:`Code Climate JSON ` (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 `_ - - 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 `_ - - 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 ` - 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 `, :ref:`C-037 `, :ref:`C-039 `, :ref:`C-040 `; verifiable with ``gh attestation verify``. diff --git a/doc/reference/glossary.rst b/doc/reference/glossary.rst index 7422d1318..7415be3f4 100644 --- a/doc/reference/glossary.rst +++ b/doc/reference/glossary.rst @@ -118,6 +118,28 @@ Glossary control C-037; verifiable with ``gh attestation verify`` (see :ref:`verify-integrity`). + CVE + Common Vulnerabilities and Exposures — a public catalogue of + disclosed security vulnerabilities, each assigned a unique identifier + (e.g. ``CVE-2024-12345``). dfetch's CI checks runtime dependencies + against the `OSV database `_ (which aggregates CVEs + and other advisories) as part of control :ref:`C-043 `. + + ECR + Essential Cybersecurity Requirement — one of the 13 product-security + obligations (ECR-a through ECR-m) listed in Annex I Part I of the + :term:`CRA`. Each ECR maps to one or more :term:`EN 40000` Security + Objectives (SO.*) that specify the technical controls needed to satisfy + it. dfetch's :doc:`compliance track ` + maps every ECR to the dfetch controls that implement it. + + SDLC + Software Development Lifecycle — the full sequence of phases from + planning and design through development, testing, deployment, and + maintenance of a software product. dfetch's :ref:`security model + ` documents controls across the complete SDLC: from source + contribution and CI/CD through PyPI distribution to runtime execution. + CRA Cyber Resilience Act — Regulation (EU) 2024/2847, in force from 10 December 2024. It imposes cybersecurity requirements on manufacturers diff --git a/security/compliance.py b/security/compliance.py index b415f6390..30a1ee476 100644 --- a/security/compliance.py +++ b/security/compliance.py @@ -784,7 +784,7 @@ def render_rst(track_b_only: bool = False) -> None: ) print( "Machine-readable artifacts are kept alongside the source, encoded in " - "OSCAL 1.2.2:\n\n" + ":term:`OSCAL` 1.2.2:\n\n" "- `security/cra_pren_4000014_oscal_catalog.json" " `_" @@ -825,8 +825,8 @@ def render_rst(track_b_only: bool = False) -> None: print("----\n") print(_rst_title("OSCAL Artifacts", "-")) print( - "`OSCAL (Open Security Controls Assessment Language) `_\n" - "is a NIST-published JSON/XML schema set for machine-readable security\n" + ":term:`OSCAL` (Open Security Controls Assessment Language) is a\n" + "NIST-published JSON/XML schema set for machine-readable security\n" "documentation. It lets GRC tools, conformity-assessment toolchains, and\n" "downstream integrators ingest dfetch's control evidence programmatically —\n" "rather than reading prose — and map it to their own compliance frameworks.\n\n" From a564d75127e537ebbc2dfe7bbf6e3505d0d6517e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 17 Jun 2026 17:21:03 +0000 Subject: [PATCH 8/8] fix: correct RST pluralisation escape after :term:`ECR` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `:term:`ECR`\s` is malformed — the backslash escape sequence needs a trailing space: `:term:`ECR`\ s`. Co-Authored-By: Claude Sonnet 4.6 Claude-Session: https://claude.ai/code/session_01E1Kh1r5dX7VEP6AScUtgrN --- doc/explanation/security_pipeline.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/explanation/security_pipeline.rst b/doc/explanation/security_pipeline.rst index ae833b8c3..43658b8a8 100644 --- a/doc/explanation/security_pipeline.rst +++ b/doc/explanation/security_pipeline.rst @@ -104,7 +104,7 @@ of their choice: * - `security/dfetch.component-definition.json `_ - :term:`OSCAL` 1.2.2 JSON (generated) - - Machine-readable Component Definition; maps dfetch controls to CRA :term:`ECR`\s; + - 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 `_