diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 7a67daf79..91176a798 100644 --- a/doc/explanation/security.rst +++ b/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) `_: +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 `_ +and +`security/tm_usage.py `_ +define the model elements (actors, data flows, trust boundaries) using the +*pytm* library. +`security/threats.json `_ +provides a catalog of 60+ STRIDE-classified threats. +`security/tm_render.py `_ +drives *pytm*, matches threats against model elements, and combines the output +with +`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 `_ +defines the 46 dfetch controls 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 +:doc:`compliance_track` (human-readable RST mapping tables) and +`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 `, :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 +of their choice: +:ref:`SARIF ` (for GitHub code scanning), +:ref:`Code Climate JSON ` (GitLab merge-request quality reports), or +:ref:`Jenkins JSON ` (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 `_ + - OSCAL 1.1.2 JSON + - Machine-readable Component Definition; maps dfetch controls to CRA ECRs + + * - `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 ` + - 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 `, :ref:`C-037 `, + :ref:`C-039 `, :ref:`C-040 `; + verifiable with ``gh attestation verify``. + + * - :ref:`SARIF output ` + - JSON (SARIF 2.1.0) + - ``dfetch check --output-type sarif``; upload to GitHub code scanning + + * - :ref:`Code Climate JSON ` + - JSON (Code Climate) + - ``dfetch check --output-type code-climate``; GitLab MR quality widget + + * - :ref:`Jenkins JSON ` + - 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 `_ — 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 `_ — + 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 `_ — + accessible summary of scope, obligations, timeline, and links to delegated and implementing acts. +- `CRA draft guidance, March 2026 (Ares(2026)2319816) `_ — + 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 `_ — + 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 `_ — + 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) `_ — + 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) `_ — + 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 `_ — + 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 `_ — + 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 `_. +- `pytm — Pythonic Threat Modeling `_ — + 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 `_ — + provides the risk-context chapter structure used in the threat model pages. +- `ENISA Security by Design and Default Playbook `_ — + ENISA guidance on integrating security from the start; the overall model structure is + inspired by this playbook. + +OSCAL +~~~~~ + +`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 `_ — + 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 `_ — + 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) `_ — + Static Analysis Results Interchange Format; used by ``dfetch check --output-type sarif`` + for :ref:`GitHub code scanning integration `. +- `CycloneDX specification `_ — + 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 `_ — + JSON format used by ``dfetch check --output-type code-climate`` for + :ref:`GitLab merge-request quality widgets `. diff --git a/doc/reference/glossary.rst b/doc/reference/glossary.rst index 7c430eae1..7422d1318 100644 --- a/doc/reference/glossary.rst +++ b/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 `_ 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 + `_. 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 ` 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 ` 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`. diff --git a/doc/static/uml/security_doc_flow.puml b/doc/static/uml/security_doc_flow.puml new file mode 100644 index 000000000..a0c6de0b9 --- /dev/null +++ b/doc/static/uml/security_doc_flow.puml @@ -0,0 +1,102 @@ +@startuml + +skinparam defaultFontName Arial +skinparam defaultFontSize 11 +skinparam backgroundColor white +skinparam arrowColor #333333 +skinparam packageBorderColor #333333 +skinparam componentBorderColor #555555 +skinparam componentBackgroundColor white + +left to right direction + +' ── Column 1: All requirements (legally binding) ────────────────────────────── + +package "All requirements\n(legally binding, given in\nlegislation and threat catalog)" as p_all #dae8fc { + [CRA ECR-a\ncyber-security properties] as ecra + [CRA ECR-b\nno known exploitable vulns] as ecrb + [CRA ECR-c\nsecure by default] as ecrc + [CRA ECR-d ... ECR-l] as ecrd_l + [CRA ECR-m\ndata protection] as ecrm + [STRIDE threat catalog\n(threats.json, 60+ threats)] as stride +} + +' ── Column 2: Risk & threat assessment (dashed = selection / filter step) ───── + +package "Risk and threat assessment\n(by dfetch maintainers)" as p_assess #line.dashed;back:#d5e8d4 { + [tm_supply_chain.py\ntm_usage.py + pytm] as tm + [compliance_data.py\n+ OSCAL catalog] as comp +} + +' ── Column 3: Applicable to dfetch ─────────────────────────────────────────── + +package "Applicable to dfetch\n(identified by maintainers)" as p_appl #fff2cc { + [Applicable STRIDE threats\n(mapped to dfetch elements)] as appl_t + [Applicable ESRs\n→ controls C-001 to C-046] as appl_c + [N/A requirements\n(documented gaps)] as na_c +} + +' ── Column 4a: Threat-model artifacts (solid path — methodology coverage) ───── + +package "Covered by pytm\n+ tm_render.py" as p_tm_out #e1f0da { + [threat_model_supply_chain.rst\nthreat_model_usage.rst\n(DFD · sequence · STRIDE tables)] as tm_out +} + +' ── Column 4b: Compliance artifacts (solid path — CRA compliance evidence) ──── + +package "Covered by\ncompliance.py" as p_comp_out #fff2cc { + [compliance_track.rst\ndfetch.component-definition.json (OSCAL 1.1.2)] as comp_out +} + +' ── Column 4c: Supply-chain release attestations (GitHub Actions, about dfetch) ─ + +package "Release attestations\n(GitHub Actions, about dfetch)" as p_sc_out #e8d5f5 { + [GitHub Actions\nrelease workflow] as release_wf + [CycloneDX SBOM · SLSA Build Provenance\nVSA · in-toto Test Results] as sc_out + [Source Provenance\n(every push to main)] as src_prov + release_wf --> sc_out + release_wf --> src_prov +} + +' ── Column 4d: Dependency-scanning outputs (dfetch check, for users) ─────────── + +package "Dependency-scanning outputs\n(dfetch check, for users)" as p_rt_out #f8cecc { + [dfetch check] as dfetch_check + [SARIF · Code Climate JSON · Jenkins JSON] as rt_out + dfetch_check --> rt_out +} + +' ── Arrows: Column 1 → Column 2 (dashed = assessment selects applicable items) ─ + +ecra ..> tm +ecrb ..> tm +ecrc ..> tm +ecrd_l ..> tm +ecrm ..> comp +stride ..> tm +ecra ..> comp + +' ── Arrows: Column 2 → Column 3 ────────────────────────────────────────────── + +tm --> appl_t +comp --> appl_c +comp ..> na_c + +' ── Arrows: Column 3 → Column 4 ────────────────────────────────────────────── + +' Solid: covered by STRIDE threat-modelling methodology +appl_t --> tm_out : "Presumption of conformity\n(STRIDE methodology)" + +' Solid: covered by explicit CRA compliance analysis +appl_c --> comp_out : "CRA compliance evidence" + +' Dashed: no harmonised standard — gap documented directly +na_c ..> comp_out : "No harmonised\nstandard / gap" + +' Dashed: threat model documents controls that require the release attestations +tm_out ..> release_wf : "requires\n(C-026, C-037,\nC-039, C-040)" + +' Dashed: applicable controls exercised by dfetch check +appl_c ..> dfetch_check : "Dependency\nscanning" + +@enduml