diff --git a/doc/explanation/compliance_track.rst b/doc/explanation/compliance_track.rst index c88420d75..90a453c22 100644 --- a/doc/explanation/compliance_track.rst +++ b/doc/explanation/compliance_track.rst @@ -5,11 +5,12 @@ CRA Compliance .. note:: - dfetch is **non-commercial open-source software** and is exempt from - mandatory CRA obligations under Recital 18 of Regulation (EU) 2024/2847. - This document is produced voluntarily under Article 13(5) to support + dfetch is **non-commercial open-source software** and falls outside the + mandatory scope of Regulation (EU) 2024/2847 (CRA): it is not placed on the + market in the context of a commercial activity (CRA Article 3(1); Recital 18 + provides interpretive context). This document is produced voluntarily to support downstream integrators who must account for open-source components in - their own conformity assessments. + their own Article 13 conformity assessments. This page provides three-tier traceability from the CRA Annex I essential requirements through the prEN 40000-1-4 Security Objectives to the @@ -21,7 +22,7 @@ concrete dfetch controls or documented gaps:: ↓ dfetch control (C-001 … C-046) or documented gap -Machine-readable OSCAL 1.1.2 artifacts are kept alongside the source: +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 - `security/dfetch.component-definition.json `_ — dfetch Component Definition @@ -56,11 +57,65 @@ Classification Decision * - CRA classification - Non-commercial open-source software (Recital 18 exemption) * - Legal basis - - Article 3(14), Recital 18, Article 13(5) of Regulation (EU) 2024/2847 + - CRA Article 3(1) (scope — dfetch is not placed on the market in the context of a commercial activity); Article 3(14) (definition of open-source software steward, for reference); Recital 18 (interpretive context for the treatment of non-commercial FOSS) * - Mandatory obligations - None — not a commercial product; no CE marking required * - Voluntary alignment - - This compliance document is produced voluntarily under Article 13(5) to support downstream integrators who must account for open-source components in their own CRA conformity assessments. + - This compliance document is produced voluntarily — dfetch has no legal obligation under the CRA — to support downstream integrators who must account for open-source components in their own Article 13 conformity assessments. + +---- + +CRA Annex V — Technical Documentation Map +------------------------------------------ + +Annex V of Regulation (EU) 2024/2847 specifies the minimum content for +a manufacturer's technical documentation. The table below maps each +Annex V element to the corresponding dfetch artifact or section. +Because dfetch is outside mandatory CRA scope, this mapping is provided +as a convenience for downstream integrators conducting their own +Article 13 conformity assessments. + +.. list-table:: + :header-rows: 1 + :widths: 45 55 + + * - Annex V element + - dfetch artifact / section + + * - **1. General description** — intended purpose, product name and version, + manufacturer address + - :doc:`security` § *Product and manufacturer identification*; + :doc:`../reference/manifest` (manifest schema and version field) + + * - **2. Design and development** — software architecture; how components + build on or feed into each other + - :doc:`../explanation/architecture` (layer diagram and module overview); + :doc:`security_pipeline` § *Threat model pipeline* (security-relevant + component relationships) + + * - **3. Production and monitoring** — build pipeline, dependency + management, CI/CD monitoring + - :doc:`security_pipeline` § *Compliance pipeline* and *Release + attestations*; CI workflows in + `.github/workflows/ `_ + + * - **4. Cybersecurity risk assessment** (Article 13(2)) — asset + identification, threat analysis, risk treatment + - :doc:`threat_model_supply_chain` (pre-install lifecycle); + :doc:`threat_model_usage` (runtime invocation); + see also :doc:`security` § *Risk Rating Methodology* + + * - **5. Implemented security solutions and applied standards** — + list of harmonised standards applied; where not applied, + description of how each Annex I requirement is met + - This page (§§ *Applicable Standards*, *Part I*, *Part II*); + :doc:`control_register` (all 46 controls with references); + OSCAL Component Definition + `security/dfetch.component-definition.json `_ + + * - **6. EU Declaration of Conformity** (Annex IV) + - Not required. dfetch is outside mandatory CRA scope (see + *Classification Decision* above). No CE marking is affixed. ---- @@ -77,7 +132,7 @@ Applicable Standards - Scope note - Gap * - prEN 40000-1-2 - - Cyber Resilience Principles and Risk Management + - Cyber Resilience Principles and Secure Development Lifecycle (working title; subject to change on publication) - Yes - Process standard covering risk-based product security across the lifecycle. The Product Security Context (§6.2) is documented in :doc:`security`. The threat models (`tm_supply_chain.py `_, `tm_usage.py `_) implement §6.3–§6.6. - — @@ -89,7 +144,7 @@ Applicable Standards * - prEN 40000-1-4 - Generic Security Requirements (draft, indicative publication October 2027) - Yes - - Primary standard for this document. Maps CRA Annex I Part I Art. 2(a)–(m) to Security Objectives (SO.\*) and Technical Controls (GEC-\*, SUM-\*, etc.). The catalog is included as `security/cra_pren_4000014_oscal_catalog.json `_. + - Primary standard for this document. Maps CRA Annex I Part I requirements (a)–(m) to Security Objectives (SO.\*) and Technical Controls (GEC-\*, SUM-\*, etc.). The catalog is included as `security/cra_pren_4000014_oscal_catalog.json `_. - Standard is in draft; final clause numbering may change. * - EN 18031-1/2:2024 - Common security requirements for radio equipment (basis of prEN 40000-1-4) @@ -120,13 +175,13 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - Status * - **ECR-A** — Be made available on the market without known exploitable vulnerabilities. - SO.VulnerabilityManagementProcess - - :ref:`C-015 `, :ref:`C-016 `, :ref:`C-017 `, :ref:`C-022 `, :ref:`C-043 ` + - :ref:`C-015 `, :ref:`C-016 `, :ref:`C-017 `, :ref:`C-022 `, :ref:`C-040 `, :ref:`C-043 ` - — - ✓ Implemented * - **ECR-B** — Be made available on the market with a secure by default configuration, including the possibility to reset the product to its original state. - SO.SecureDefaultConfiguration - :ref:`C-001 `, :ref:`C-002 ` - - — + - Integrity hash verification (:ref:`C-005 `) is opt-in; manifest entries without an ``integrity`` field are fetched without hash verification by default - ⚠ Partial * - - SO.SecureStartupConfig @@ -150,8 +205,8 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - — N/A * - - SO.UserUpdateNotification - - :ref:`C-040 ` - - — + - `dfetch/util/github_version_check.py `_ + - ``dfetch check`` suppresses the call when ``CI`` is set (`check.py `_ line 102); ``dfetch environment`` calls it unconditionally - ✓ Implemented * - - SO.PostponeUpdates @@ -161,12 +216,12 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi * - **ECR-D** — Ensure protection from unauthorised access by appropriate control mechanisms including authentication, identity or access management systems, and report on possible unauthorised access. - SO.AccessControl - :ref:`C-006 `, :ref:`C-036 ` - - — + - dfetch has no native authentication or authorisation layer; access control is fully delegated to the underlying VCS server and host OS. C-006 prevents interactive credential prompts (mitigating credential interception), and C-036 strips credentials from persisted metadata — both are confidentiality controls, not access control mechanisms in the authentication/authorisation sense. - ⚠ Partial * - - SO.AccessControlReport - :ref:`C-045 ` - - No persistent log of unauthorised access attempts + - No persistent log of access attempts; C-045 detects and warns on plaintext transport but does not log events - ⚠ Partial * - **ECR-E** — Protect the confidentiality of stored, transmitted or otherwise processed data by state-of-the-art mechanisms such as encryption at rest and in transit. - SO.DataStoredConfidentiality @@ -180,14 +235,14 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - ✓ Implemented * - - SO.DataTransmittedConfidentiality - - :ref:`C-005 `, :ref:`C-045 ` - - — - - ✓ Implemented + - :ref:`C-045 ` + - C-045 warns on plaintext-scheme URLs but does not refuse to proceed; TLS/SSH confidentiality is provided by the underlying VCS client, not enforced by dfetch itself + - ⚠ Partial * - - SO.ComAuth - - :ref:`C-003 `, :ref:`C-004 `, :ref:`C-045 ` - - — - - ✓ Implemented + - :ref:`C-045 ` + - Server authentication (TLS certificate verification, SSH host-key checking) is delegated to the OS trust store and VCS client; dfetch does not independently authenticate remote endpoints and cannot enforce authenticated channels when C-045's warning is overridden by the user + - ⚠ Partial * - - SO.SecureProvisioning - :ref:`C-005 ` @@ -205,8 +260,8 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - ✓ Implemented * - - SO.DataTransmittedIntegrity - - :ref:`C-003 `, :ref:`C-004 ` - - No end-to-end hash for git/svn transport beyond TLS/SSH channel integrity + - :ref:`C-005 ` + - C-005 provides end-to-end hash verification for archive sources only (opt-in); git and svn sources rely solely on VCS object integrity (SHA-1/SHA-256 object model) and TLS/SSH channel integrity — no dfetch-level hash verification - ⚠ Partial * - - SO.IntegrityReport @@ -231,7 +286,7 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi * - **ECR-I** — Minimise the negative impact by the products themselves or connected devices on the availability of services provided by other devices or networks. - SO.LimitExternalImpact - :ref:`C-001 `, :ref:`C-007 ` - - — + - Archive HTTP operations time out at 15 s (reachability) and 60 s (download) via ``archive.py``; git and svn subprocess calls have no timeout and can stall indefinitely - ⚠ Partial * - - SO.PreventAttackPropagation @@ -246,7 +301,7 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi * - **ECR-J** — Be designed, developed and produced to limit attack surfaces, including external interfaces. - SO.ReduceAttackSurface - :ref:`C-001 `, :ref:`C-003 `, :ref:`C-004 `, :ref:`C-007 `, :ref:`C-008 ` - - — + - No domain or URL-scheme allowlist constrains which remote URLs the manifest may reference; git and svn subprocess calls have no timeout (archive HTTP operations time out at 15 s / 60 s) - ⚠ Partial * - **ECR-K** — Be designed, developed and produced to reduce the impact of an incident using appropriate exploitation mitigation mechanisms and techniques. - SO.ReduceImpactOfIncident @@ -255,8 +310,8 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - ✓ Implemented * - **ECR-L** — Provide security related information by recording and monitoring relevant internal activity, including the access to or modification of data, services or functions, with an opt-out mechanism for the user. - SO.LogSecurityRelevantActivities - - :ref:`C-036 ` - - No persistent security event log (LGM-2/3/4 gap); No opt-out for logging — dfetch does not log by default + - — + - No persistent structured security event log (LGM-1/2/3/4 gap). dfetch prints operational output to stderr but does not retain it, does not record which credentials were used, which files were modified, or when remote access occurred. C-036 ensures credentials are excluded from the operational output but is not a logging control. - ⚠ Partial * - - SO.MonitorSecurityRelevantActivities @@ -296,11 +351,20 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi .. rubric:: Notes on "Implemented" rows with no control listed -**ECR-C SO.Updateability** — No dfetch-specific control is needed. SUM-1/SUM-2 -are satisfied by the PyPI distribution mechanism (``pip install --upgrade dfetch`` -and GitHub Releases binary packages). pip's TLS-protected download channel provides -the required secure update path. The update mechanism is the responsibility of the -user's package manager, not of dfetch itself. +**ECR-C SO.Updateability** — SUM-1/SUM-2 require the manufacturer to make security +updates available through a secure channel. dfetch publishes every release to PyPI +(TLS-protected, OIDC-authenticated via :ref:`C-010 `) and GitHub Releases +(with release attestations per :ref:`C-039 `). The CVE gate (:ref:`C-043 `) +blocks release if known vulnerabilities are present in runtime dependencies. Providing +the update *mechanism* is the manufacturer's obligation under SUM-1/SUM-2; delivery +to the end user is the responsibility of the user's package manager. + +**ECR-C SO.UserUpdateNotification** — ``dfetch check`` and ``dfetch environment`` +both call ``newer_version_available()`` (``dfetch/util/github_version_check.py``), +which polls the GitHub releases API and prints a notice if a newer dfetch release +exists. ``dfetch check`` suppresses the call when the ``CI`` environment variable +is set (``check.py`` line 102: ``if not os.environ.get("CI")``); ``dfetch environment`` +does not apply this guard and always performs the check. **ECR-M SO.SecureDataDeletion** — No dfetch-specific control is needed. DLM-1 is satisfied by design: dfetch stores no personal data, credentials, or cryptographic @@ -314,7 +378,7 @@ sufficient to remove all dfetch data; no secure-wipe facility is warranted. Part II — Vulnerability Handling (prEN 40000-1-3) ------------------------------------------------- -Part II requirements are addressed via prEN 40000-1-3. pii-04 is not applicable under Recital 18. +Part II requirements are addressed via prEN 40000-1-3. Part II §4 (active vulnerability reporting to national CSIRTs and ENISA) is not applicable: this obligation falls on commercial manufacturers placing products on the market, not on non-commercial open-source software outside mandatory CRA scope. .. list-table:: :header-rows: 1 diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 87147988d..2ed8372a3 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -67,8 +67,9 @@ 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 may retain due diligence - responsibilities under Article 13(5). + 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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -104,10 +105,6 @@ 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. -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`. - .. _risk-rating-methodology: Risk Rating Methodology @@ -159,26 +156,23 @@ constrained, and must be reassessed whenever the control set changes. - Catastrophic, near-certain potential (e.g. unencrypted channel with no compensating control). Immediate mitigation required; accept decision requires explicit sign-off. The risk treatment decisions (Mitigate / Accept / Transfer) in each threat -table follow the same vocabulary as ISO/IEC 27005 and BSI TR-03183-1: an +table follow the risk treatment vocabulary of BSI TR-03183-1: an **Accept** decision requires explicit rationale citing the assumption under which the residual risk is acceptable, documented alongside the threat entry. Threat Models ------------- -The following pages document the two threat models in detail. Each page is -generated from the corresponding Python module in ``security/`` — see +The two threat models below cover the full lifecycle of *dfetch*. Both are +generated from the Python modules in ``security/``; see `security/README.md `_ -for instructions on regenerating them. +for regeneration instructions. .. toctree:: :maxdepth: 1 - security_pipeline threat_model_supply_chain threat_model_usage - compliance_track - control_register CRA Compliance -------------- @@ -203,7 +197,8 @@ surfaced by the risk models: - :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 OSCAL 1.1.2 artifacts are kept alongside the source: +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) @@ -211,6 +206,12 @@ Machine-readable OSCAL 1.1.2 artifacts are kept alongside the source: The complete list of all controls is on the :doc:`control_register` page. +.. toctree:: + :maxdepth: 1 + + compliance_track + control_register + Further Reading --------------- @@ -221,13 +222,11 @@ 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. + accessible summary of scope, obligations, and timeline. - `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. + Commission guidance covering 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. + practical risk-based guidance aligned with CRA; the risk-rating framework above is derived from this document. EN 40000 harmonised standards ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -237,35 +236,21 @@ standards under the CRA. Once published in the OJEU, compliance with them confer 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. + overview of the EN 40000 work programme (prEN 40000-1-1 through 40000-1-4). - `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). + explains how each part of EN 40000 maps to CRA obligations and the Security Objectives (SO.*) in prEN 40000-1-4. 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 + Microsoft's six-category threat classification 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. + and auto-generate threat findings. - `ENISA Security by Design and Default Playbook `_ — - ENISA guidance on integrating security from the start; the overall model structure is - inspired by this playbook. + ENISA guidance that inspired the overall model structure. OSCAL ~~~~~ @@ -281,16 +266,14 @@ dfetch uses OSCAL 1.1.2 for two artifacts: 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 `. +Security documentation pipeline +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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`. + +.. toctree:: + :hidden: + + security_pipeline diff --git a/doc/explanation/security_pipeline.rst b/doc/explanation/security_pipeline.rst index 460e5acbe..ec0e66ed7 100644 --- a/doc/explanation/security_pipeline.rst +++ b/doc/explanation/security_pipeline.rst @@ -45,7 +45,8 @@ and prEN 40000-1-4 security objectives. 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 +(machine-readable OSCAL 1.1.2 Component Definition; 1.1.2 is the pinned version — +NIST released 1.2.2 in April 2026, migration not yet performed). The :doc:`control_register` page is maintained manually and references controls defined in ``compliance_data.py``. @@ -93,11 +94,11 @@ of their choice: - All 46 dfetch controls (C-001 to C-046) with references and status * - `security/dfetch.component-definition.json `_ - - OSCAL 1.1.2 JSON + - OSCAL 1.1.2 JSON (pinned) - Machine-readable Component Definition; maps dfetch controls to CRA ECRs * - `security/cra_pren_4000014_oscal_catalog.json `_ - - OSCAL 1.1.2 JSON + - OSCAL 1.1.2 JSON (pinned) - Static prEN 40000-1-4 catalog (input to compliance pipeline, not generated) * - :ref:`Release attestations `