From eac3b81f25dad328bac9bb66a260f1ca23e6fc42 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 16 Jun 2026 07:47:44 +0000 Subject: [PATCH 1/8] doc: add security documentation pipeline flow diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a PlantUML component diagram (security_doc_flow.puml) showing how the three security documentation pipelines produce their output artifacts — threat model RSTs (via tm_render.py + pytm), compliance RST and OSCAL JSON (via compliance.py), and runtime outputs (SARIF, SBOM, Code Climate, Jenkins JSON from dfetch check/report). References the diagram from a new "Security Documentation Pipeline" section in security.rst with prose explaining each pipeline. https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X --- doc/explanation/security.rst | 31 +++++++++++ doc/static/uml/security_doc_flow.puml | 74 +++++++++++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 doc/static/uml/security_doc_flow.puml diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 7a67daf7..8f97e039 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -103,6 +103,37 @@ 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 shows how the security documentation is generated from its +source files and what output artifacts each pipeline produces. + +.. 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, +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/explanation/compliance_track.rst`` (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``. + +**Runtime outputs** — When users run ``dfetch check`` or ``dfetch report``, +the reporting layer emits findings in the selected format: SARIF (for GitHub +code scanning), SBOM / CycloneDX (bill of materials), Code Climate JSON, or +Jenkins JSON. + Threat Models ------------- diff --git a/doc/static/uml/security_doc_flow.puml b/doc/static/uml/security_doc_flow.puml new file mode 100644 index 00000000..33110650 --- /dev/null +++ b/doc/static/uml/security_doc_flow.puml @@ -0,0 +1,74 @@ +@startuml + +skinparam defaultFontName Arial +skinparam defaultFontSize 11 +skinparam backgroundColor white +skinparam arrowColor #444444 +skinparam componentBorderColor #888888 +skinparam packageBorderColor #666666 +skinparam noteBorderColor #999999 +skinparam noteBackgroundColor #FFFFF0 + +left to right direction + +package "Threat Model Sources (security/)" #dae8fc { + [tm_supply_chain.py\ntm_usage.py] as tm_models + [tm_elements.py] as tm_el + [threats.json] as threats + [report_template.rst] as tmpl +} + +package "Compliance Sources (security/)" #dae8fc { + [compliance_data.py] as comp_data + [cra_pren_4000014_oscal_catalog.json] as cra_cat +} + +package "Processors (security/)" #d5e8d4 { + [pytm] as pytm + [tm_render.py] as tm_render + [compliance.py] as compliance_py +} + +package "Documentation (doc/explanation/)" #fff2cc { + [threat_model_supply_chain.rst\nthreat_model_usage.rst] as tm_rst + [compliance_track.rst] as comp_rst + [control_register.rst] as ctrl_rst +} + +package "Machine-Readable (security/)" #fff2cc { + [dfetch.component-definition.json\n(OSCAL 1.1.2)] as oscal_out +} + +package "Runtime Outputs (dfetch check/report)" #f8cecc { + [SARIF] as sarif + [SBOM / CycloneDX] as sbom + [Code Climate / Jenkins JSON] as other_fmt +} + +' Threat model pipeline +tm_models --> pytm +tm_el --> pytm +threats --> tm_render +tmpl --> tm_render +pytm --> tm_render +tm_render --> tm_rst : "DFD, sequence diagrams,\nthreat & control tables" + +' Compliance pipeline +comp_data --> compliance_py +cra_cat --> compliance_py +compliance_py --> comp_rst : "RST mapping tables" +compliance_py --> oscal_out : "OSCAL 1.1.2 JSON" + +' Runtime pipeline — dfetch check/report commands +[dfetch check/report] as dfetch_rt +dfetch_rt --> sarif +dfetch_rt --> sbom +dfetch_rt --> other_fmt + +note right of ctrl_rst + Manually maintained; + references controls + from compliance_data.py +end note + +@enduml From f87dd405abda6af903945ed8cb506fd5108a387a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 16 Jun 2026 07:57:57 +0000 Subject: [PATCH 2/8] doc: add GitHub links to source files in security pipeline description https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X --- doc/explanation/security.rst | 44 ++++++++++++++++++++++-------------- 1 file changed, 27 insertions(+), 17 deletions(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 8f97e039..579f93fc 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -111,23 +111,33 @@ source files and what output artifacts each pipeline produces. .. 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, -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/explanation/compliance_track.rst`` (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``. +**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``. **Runtime outputs** — When users run ``dfetch check`` or ``dfetch report``, the reporting layer emits findings in the selected format: SARIF (for GitHub From 4c1e2a5c0f6b6cbbe3e2bea7b4f150fafbb397bc Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 16 Jun 2026 10:30:15 +0000 Subject: [PATCH 3/8] doc: restructure security doc flow diagram after EU Blue Guide fig 4.1.2.2 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rebuilds security_doc_flow.puml to follow the four-column structure of figure 4.1.2.2 from the EU Blue Guide on product rules (OJ 2022/C 247): col 1 all requirements (CRA ECR-a…m + STRIDE catalog) col 2 risk & threat assessment step (dashed box, filter) col 3 applicable to dfetch (threats + controls + N/A gaps) col 4 output paths — solid arrows where STRIDE methodology or CRA compliance analysis provides coverage, dashed arrow for gaps with no harmonised standard Updates the security.rst prose to explain the Blue Guide analogy and links to the official EU Blue Guide PDF on EUR-Lex. https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X --- doc/explanation/security.rst | 10 ++- doc/static/uml/security_doc_flow.puml | 117 ++++++++++++++------------ 2 files changed, 73 insertions(+), 54 deletions(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 579f93fc..3f0af244 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -106,8 +106,14 @@ threat models below. Security Documentation Pipeline -------------------------------- -The diagram below shows how the security documentation is generated from its -source files and what output artifacts each pipeline produces. +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 diff --git a/doc/static/uml/security_doc_flow.puml b/doc/static/uml/security_doc_flow.puml index 33110650..28a507ca 100644 --- a/doc/static/uml/security_doc_flow.puml +++ b/doc/static/uml/security_doc_flow.puml @@ -3,72 +3,85 @@ skinparam defaultFontName Arial skinparam defaultFontSize 11 skinparam backgroundColor white -skinparam arrowColor #444444 -skinparam componentBorderColor #888888 -skinparam packageBorderColor #666666 -skinparam noteBorderColor #999999 -skinparam noteBackgroundColor #FFFFF0 +skinparam arrowColor #333333 +skinparam packageBorderColor #333333 +skinparam componentBorderColor #555555 +skinparam componentBackgroundColor white left to right direction -package "Threat Model Sources (security/)" #dae8fc { - [tm_supply_chain.py\ntm_usage.py] as tm_models - [tm_elements.py] as tm_el - [threats.json] as threats - [report_template.rst] as tmpl +' ── 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 } -package "Compliance Sources (security/)" #dae8fc { - [compliance_data.py] as comp_data - [cra_pren_4000014_oscal_catalog.json] as cra_cat +' ── 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 } -package "Processors (security/)" #d5e8d4 { - [pytm] as pytm - [tm_render.py] as tm_render - [compliance.py] as compliance_py +' ── 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 } -package "Documentation (doc/explanation/)" #fff2cc { - [threat_model_supply_chain.rst\nthreat_model_usage.rst] as tm_rst - [compliance_track.rst] as comp_rst - [control_register.rst] as ctrl_rst +' ── 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 } -package "Machine-Readable (security/)" #fff2cc { - [dfetch.component-definition.json\n(OSCAL 1.1.2)] as oscal_out +' ── Column 4b: Compliance artifacts (solid path — CRA compliance evidence) ──── + +package "Covered by\ncompliance.py" as p_comp_out #fff2cc { + [compliance_track.rst · control_register.rst\ndfetch.component-definition.json (OSCAL 1.1.2)] as comp_out } -package "Runtime Outputs (dfetch check/report)" #f8cecc { - [SARIF] as sarif - [SBOM / CycloneDX] as sbom - [Code Climate / Jenkins JSON] as other_fmt +' ── Column 4c: Runtime artifacts (dashed path — no pre-generated document) ─── + +package "Runtime evidence\n(dfetch check / report)" as p_rt_out #f8cecc { + [SARIF · SBOM / CycloneDX\nCode Climate · Jenkins JSON] as rt_out } -' Threat model pipeline -tm_models --> pytm -tm_el --> pytm -threats --> tm_render -tmpl --> tm_render -pytm --> tm_render -tm_render --> tm_rst : "DFD, sequence diagrams,\nthreat & control tables" - -' Compliance pipeline -comp_data --> compliance_py -cra_cat --> compliance_py -compliance_py --> comp_rst : "RST mapping tables" -compliance_py --> oscal_out : "OSCAL 1.1.2 JSON" - -' Runtime pipeline — dfetch check/report commands -[dfetch check/report] as dfetch_rt -dfetch_rt --> sarif -dfetch_rt --> sbom -dfetch_rt --> other_fmt - -note right of ctrl_rst - Manually maintained; - references controls - from compliance_data.py -end note +' ── 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" + +' Solid: runtime check / report commands produce live evidence +appl_c --> rt_out : "Runtime evidence" @enduml From e47be7b24ae5d0213888bf56004f0dc7b6a98fe4 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 16 Jun 2026 11:07:52 +0000 Subject: [PATCH 4/8] doc: add artifact quick-reference table and runtime output cross-links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replaces the plain "Runtime outputs" sentence with proper :ref: cross-links to check-ci-github (SARIF), sbom (CycloneDX), check-ci-gitlab (Code Climate), and check-ci-jenkins (Jenkins JSON). Adds an "Artifacts at a glance" list-table covering all ten security documentation outputs — generated RST pages, manually maintained RST page, two OSCAL JSON files, and the four runtime reporting formats — with direct doc cross-references or GitHub source links for each. https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X --- doc/explanation/security.rst | 58 ++++++++++++++++++++++++++++++++++-- 1 file changed, 55 insertions(+), 3 deletions(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 3f0af244..81c8c215 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -146,9 +146,61 @@ reads those definitions together with the static OSCAL catalog and generates defined in ``compliance_data.py``. **Runtime outputs** — When users run ``dfetch check`` or ``dfetch report``, -the reporting layer emits findings in the selected format: SARIF (for GitHub -code scanning), SBOM / CycloneDX (bill of materials), Code Climate JSON, or -Jenkins JSON. +the reporting layer emits findings in the selected format: +:ref:`SARIF ` (for GitHub code scanning), +:ref:`SBOM / CycloneDX ` (bill of materials), +: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:`SARIF output ` + - JSON (SARIF 2.1.0) + - ``dfetch check --output-type sarif``; upload to GitHub code scanning + + * - :ref:`SBOM / CycloneDX ` + - JSON (CycloneDX) + - ``dfetch report --sbom``; bill of materials with SPDX licence data + + * - :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 ------------- From cc83412421f9b324e7e1b70a65e0c39ca6c125cc Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 16 Jun 2026 11:10:55 +0000 Subject: [PATCH 5/8] doc: add Further Reading section with references to CRA, EN 40000, OSCAL, STRIDE Adds a structured Further Reading section covering: - CRA: official text, EU overview, March 2026 draft guidance, BSI TR-03183-1 - EN 40000: CEN/CENELEC cybersecurity page, March 2025 webinar slides, EU Blue Guide 2022 (fig 4.1.2.2), OSCAL catalog provenance note - Threat modelling: STRIDE docs, pytm, BSI TR-03183-1, ENISA playbook - OSCAL: NIST OSCAL project, Catalog model, Component Definition model - Output formats: SARIF 2.1.0 (OASIS), CycloneDX, Code Climate spec Also updates the EN 40000 inline link from a single webinar PDF to the CEN/CENELEC cybersecurity overview page, and adds an explicit STRIDE link. https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X --- doc/explanation/security.rst | 88 +++++++++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 2 deletions(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 81c8c215..5f0a7a42 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: @@ -248,3 +249,86 @@ 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 by ``dfetch report --sbom``; includes SPDX licence identifiers + and ``dfetch:*`` custom properties for licence provenance. +- `Code Climate test coverage spec `_ — + JSON format used by ``dfetch check --output-type code-climate`` for + :ref:`GitLab merge-request quality widgets `. From 1ae401c00521d089c8a21ca3354b93f55b3b0d22 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 16 Jun 2026 11:14:14 +0000 Subject: [PATCH 6/8] =?UTF-8?q?doc:=20correct=20SBOM=20scope=20=E2=80=94?= =?UTF-8?q?=20release=20attestations=20about=20dfetch,=20not=20dfetch=20re?= =?UTF-8?q?port?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The SBOMs relevant to dfetch's security model are the CycloneDX SBOM attestations generated by GitHub Actions about dfetch itself (signed by Sigstore, verifiable via gh attestation verify), not the SBOM output that dfetch generates for users' vendored dependencies. - diagram: replace "Runtime evidence (dfetch check/report)" with two separate clusters: "Release attestations (GitHub Actions, about dfetch)" containing CycloneDX SBOM · SLSA Build Provenance · Source Provenance · VSA · in-toto Test Results, connected from tm_out via controls C-026/C-037/C-039/C-040; and "Dependency-scanning outputs (dfetch check)" containing only SARIF · Code Climate · Jenkins JSON - prose: replace single "Runtime outputs" paragraph with "Release attestations" (five types, Sigstore-signed, gh attestation verify) and "Dependency-scanning outputs" (dfetch check formats for users) - artifacts table: replace dfetch report --sbom row with a "Release attestations" row referencing verify-integrity and the four controls - Further Reading: update CycloneDX note to clarify it is dfetch's own CI-generated SBOM, not a user-facing report --sbom output https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X --- doc/explanation/security.rst | 33 +++++++++++++++++++-------- doc/static/uml/security_doc_flow.puml | 19 +++++++++++---- 2 files changed, 38 insertions(+), 14 deletions(-) diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 5f0a7a42..91176a79 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -146,10 +146,20 @@ reads those definitions together with the static OSCAL catalog and generates :doc:`control_register` page is maintained manually and references controls defined in ``compliance_data.py``. -**Runtime outputs** — When users run ``dfetch check`` or ``dfetch report``, -the reporting layer emits findings in the selected format: +**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:`SBOM / CycloneDX ` (bill of materials), :ref:`Code Climate JSON ` (GitLab merge-request quality reports), or :ref:`Jenkins JSON ` (Jenkins warnings-ng plugin). @@ -187,14 +197,18 @@ the reporting layer emits findings in the selected format: - 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:`SBOM / CycloneDX ` - - JSON (CycloneDX) - - ``dfetch report --sbom``; bill of materials with SPDX licence data - * - :ref:`Code Climate JSON ` - JSON (Code Climate) - ``dfetch check --output-type code-climate``; GitLab MR quality widget @@ -327,8 +341,9 @@ Security assessment output formats Static Analysis Results Interchange Format; used by ``dfetch check --output-type sarif`` for :ref:`GitHub code scanning integration `. - `CycloneDX specification `_ — - SBOM format used by ``dfetch report --sbom``; includes SPDX licence identifiers - and ``dfetch:*`` custom properties for licence provenance. + 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/static/uml/security_doc_flow.puml b/doc/static/uml/security_doc_flow.puml index 28a507ca..c89c5428 100644 --- a/doc/static/uml/security_doc_flow.puml +++ b/doc/static/uml/security_doc_flow.puml @@ -48,10 +48,16 @@ package "Covered by\ncompliance.py" as p_comp_out #fff2cc { [compliance_track.rst · control_register.rst\ndfetch.component-definition.json (OSCAL 1.1.2)] as comp_out } -' ── Column 4c: Runtime artifacts (dashed path — no pre-generated document) ─── +' ── Column 4c: Supply-chain release attestations (GitHub Actions, about dfetch) ─ -package "Runtime evidence\n(dfetch check / report)" as p_rt_out #f8cecc { - [SARIF · SBOM / CycloneDX\nCode Climate · Jenkins JSON] as rt_out +package "Release attestations\n(GitHub Actions, about dfetch)" as p_sc_out #e8d5f5 { + [CycloneDX SBOM · SLSA Build Provenance\nSource Provenance · VSA · in-toto Test Results] as sc_out +} + +' ── Column 4d: Dependency-scanning outputs (dfetch check, for users) ─────────── + +package "Dependency-scanning outputs\n(dfetch check, for users)" as p_rt_out #f8cecc { + [SARIF · Code Climate JSON · Jenkins JSON] as rt_out } ' ── Arrows: Column 1 → Column 2 (dashed = assessment selects applicable items) ─ @@ -81,7 +87,10 @@ appl_c --> comp_out : "CRA compliance evidence" ' Dashed: no harmonised standard — gap documented directly na_c ..> comp_out : "No harmonised\nstandard / gap" -' Solid: runtime check / report commands produce live evidence -appl_c --> rt_out : "Runtime evidence" +' Solid: supply-chain controls (C-026, C-037, C-039, C-040) require release attestations +tm_out --> sc_out : "C-026 C-037\nC-039 C-040" + +' Solid: dfetch check outputs for users (dependency scanning) +appl_c --> rt_out : "Dependency\nscanning" @enduml From 25d02c62e61cec0cac8fbaa1e8a72ccf0aca3a2b Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 16 Jun 2026 11:21:27 +0000 Subject: [PATCH 7/8] doc: add attestation, provenance and security standard terms to glossary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New entries: Attestation — Sigstore-signed claims about dfetch release artifacts; links the five attestation types and verify-integrity Build Provenance — SLSA attestation for source-to-binary traceability CRA — Cyber Resilience Act (EU 2024/2847), 13 ECRs EN 40000 — CEN/CENELEC harmonised standard family under the CRA OSCAL — NIST Open Security Controls Assessment Language; both OSCAL artifacts (catalog + component-definition) explained SARIF — Static Analysis Results Interchange Format; links check-ci Sigstore — transparency-log code-signing infrastructure for attestations SLSA — Supply-chain Levels for Software Artifacts framework Source Provenance — SLSA attestation for governance controls on main STRIDE — threat-classification framework; links both threat model pages VSA — Verification Summary Attestation for binary installers Updated: SBOM — notes both user-facing dfetch report output and dfetch's own CI-generated CycloneDX release attestation https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X --- doc/reference/glossary.rst | 108 ++++++++++++++++++++++++++++++++++--- 1 file changed, 102 insertions(+), 6 deletions(-) diff --git a/doc/reference/glossary.rst b/doc/reference/glossary.rst index 7c430eae..9f21d180 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,102 @@ 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 five attestation types on every release: + :term:`Build Provenance`, :term:`Source 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). 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`. From b24cf6c93e2327134c25d724dd2b5766d5b7d984 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 16 Jun 2026 12:32:40 +0000 Subject: [PATCH 8/8] doc: fix three accuracy issues in glossary and flow diagram MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Attestation entry (glossary): clarified that four attestation types are published per release (Build Provenance, SBOM, VSA, in-toto Test Results) and Source Provenance is published on every push to main — not per release. Verified against verify-integrity.rst line 239. Diagram producer nodes: replaced misleading arrows (tm_out→sc_out and appl_c→rt_out) with explicit producer nodes inside each output package: - "GitHub Actions release workflow" → sc_out and src_prov (Source Provenance split out as a separate node to reflect different trigger) - "dfetch check" → rt_out Arrows from the documentation pipeline are now dashed "requires/documents" links to the producer nodes, not solid "produces" arrows to the artifacts. control_register.rst removed from comp_out: the file is manually maintained and not generated by compliance.py (which outputs only compliance_track.rst and dfetch.component-definition.json). Verified by inspection of compliance.py output path and README commands. https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X --- doc/reference/glossary.rst | 9 +++++---- doc/static/uml/security_doc_flow.puml | 18 ++++++++++++------ 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/doc/reference/glossary.rst b/doc/reference/glossary.rst index 9f21d180..7422d131 100644 --- a/doc/reference/glossary.rst +++ b/doc/reference/glossary.rst @@ -103,10 +103,11 @@ Glossary 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 five attestation types on every release: - :term:`Build Provenance`, :term:`Source 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). See + 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 diff --git a/doc/static/uml/security_doc_flow.puml b/doc/static/uml/security_doc_flow.puml index c89c5428..a0c6de0b 100644 --- a/doc/static/uml/security_doc_flow.puml +++ b/doc/static/uml/security_doc_flow.puml @@ -45,19 +45,25 @@ package "Covered by pytm\n+ tm_render.py" as p_tm_out #e1f0da { ' ── Column 4b: Compliance artifacts (solid path — CRA compliance evidence) ──── package "Covered by\ncompliance.py" as p_comp_out #fff2cc { - [compliance_track.rst · control_register.rst\ndfetch.component-definition.json (OSCAL 1.1.2)] as comp_out + [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 { - [CycloneDX SBOM · SLSA Build Provenance\nSource Provenance · VSA · in-toto Test Results] as sc_out + [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) ─ @@ -87,10 +93,10 @@ appl_c --> comp_out : "CRA compliance evidence" ' Dashed: no harmonised standard — gap documented directly na_c ..> comp_out : "No harmonised\nstandard / gap" -' Solid: supply-chain controls (C-026, C-037, C-039, C-040) require release attestations -tm_out --> sc_out : "C-026 C-037\nC-039 C-040" +' Dashed: threat model documents controls that require the release attestations +tm_out ..> release_wf : "requires\n(C-026, C-037,\nC-039, C-040)" -' Solid: dfetch check outputs for users (dependency scanning) -appl_c --> rt_out : "Dependency\nscanning" +' Dashed: applicable controls exercised by dfetch check +appl_c ..> dfetch_check : "Dependency\nscanning" @enduml