diff --git a/doc/explanation/compliance_track.rst b/doc/explanation/compliance_track.rst index ec58d4b03..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) @@ -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): @@ -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 `_ — 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/doc/explanation/security.rst b/doc/explanation/security.rst index 2ed8372a3..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: @@ -55,34 +52,36 @@ 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 - - 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 + 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 `_ 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 ` 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 -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* @@ -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 ` 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 ` (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 :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 `_, compliance with them confers a presumption of conformity with the corresponding CRA essential requirements. - `CEN/CENELEC cybersecurity standards page `_ — @@ -255,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 `_ — @@ -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: diff --git a/doc/explanation/security_pipeline.rst b/doc/explanation/security_pipeline.rst index 8d671bcba..43658b8a8 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 1191dd785..30a1ee476 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") @@ -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,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" + ":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" + "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"