diff --git a/doc/explanation/compliance_track.rst b/doc/explanation/compliance_track.rst index 90c8a1a3..9f5881c7 100644 --- a/doc/explanation/compliance_track.rst +++ b/doc/explanation/compliance_track.rst @@ -23,8 +23,8 @@ concrete dfetch controls or documented gaps:: Machine-readable OSCAL 1.1.2 artifacts are kept alongside the source: -- ``security/cra_pren_4000014_oscal_catalog.json`` — prEN 40000-1-4 catalog -- ``security/dfetch.component-definition.json`` — dfetch Component Definition +- `security/cra_pren_4000014_oscal_catalog.json `_ — prEN 40000-1-4 catalog +- `security/dfetch.component-definition.json `_ — dfetch Component Definition The full list of all controls is available on the :doc:`control_register` page. @@ -79,17 +79,17 @@ Applicable Standards * - prEN 40000-1-2 - Cyber Resilience Principles and Risk Management - 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. + - 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. - — * - prEN 40000-1-3 - Vulnerability Handling Requirements - Yes - - Covers CRA Annex I Part II vulnerability handling obligations. Addressed in the Part II table below via SECURITY.md, SBOM (C-022), and dependency-review CI (C-016). + - Covers CRA Annex I Part II vulnerability handling obligations. Addressed in the Part II table below via `SECURITY.md `_, SBOM (:ref:`C-022 `), and dependency-review CI (:ref:`C-016 `). - No formal patch SLA or LTS backport policy defined. * - 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 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 `_. - 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,12 +120,12 @@ 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 - - C-015, C-016, C-017, C-022 - - No CVE gate at release time (→ C-043 planned) + - :ref:`C-015 `, :ref:`C-016 `, :ref:`C-017 `, :ref:`C-022 ` + - No CVE gate at release time (→ :ref:`C-043 ` planned) - ⚠ Partial * - **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 - - C-001, C-002 + - :ref:`C-001 `, :ref:`C-002 ` - — - ⚠ Partial * - @@ -150,7 +150,7 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - — N/A * - - SO.UserUpdateNotification - - C-040 + - :ref:`C-040 ` - — - ✓ Implemented * - @@ -160,62 +160,62 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - — N/A * - **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 - - C-006, C-036 + - :ref:`C-006 `, :ref:`C-036 ` - — - ⚠ Partial * - - SO.AccessControlReport - - C-009 + - :ref:`C-009 ` - No persistent log of unauthorised access attempts - ⚠ 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 - - C-036 + - :ref:`C-036 ` - — - ✓ Implemented * - - SO.DataProcessedConfidentiality - - C-005, C-034 + - :ref:`C-005 `, :ref:`C-034 ` - — - ✓ Implemented * - - SO.DataTransmittedConfidentiality - - C-005, C-009 + - :ref:`C-005 `, :ref:`C-009 ` - — - ✓ Implemented * - - SO.ComAuth - - C-003, C-004, C-009 + - :ref:`C-003 `, :ref:`C-004 `, :ref:`C-009 ` - — - ✓ Implemented * - - SO.SecureProvisioning - - C-005 + - :ref:`C-005 ` - — - ⚠ Partial * - **ECR-F** — Protect the integrity of stored, transmitted or otherwise processed data, commands, programs and configuration against unauthorised manipulation or modification, and report on corruptions. - SO.DataStoredIntegrity - - C-005 + - :ref:`C-005 ` - Integrity hash opt-in only; not enforced by default for git/svn - ⚠ Partial * - - SO.DataProcessedIntegrity - - C-005, C-034 + - :ref:`C-005 `, :ref:`C-034 ` - — - ✓ Implemented * - - SO.DataTransmittedIntegrity - - C-003, C-004 + - :ref:`C-003 `, :ref:`C-004 ` - No end-to-end hash for git/svn transport beyond TLS/SSH channel integrity - ⚠ Partial * - - SO.IntegrityReport - - C-009 + - :ref:`C-009 ` - No persistent integrity-violation log - ⚠ Partial * - **ECR-G** — Process only data, personal or other, that are adequate, relevant and limited to what is necessary in relation to the intended purpose of the product with digital elements (data minimisation). - SO.DataMinimization - - C-044 + - :ref:`C-044 ` - — - ✓ Implemented * - **ECR-H** — Protect the availability of essential and basic functions, also after an incident, including through resilience and mitigation measures against denial-of-service attacks. @@ -225,17 +225,17 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - — N/A * - - SO.IncidentResilience - - C-002, C-007 + - :ref:`C-002 `, :ref:`C-007 ` - No timeout on VCS operations (potential resource exhaustion) - ⚠ Partial * - **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 - - C-001, C-007 + - :ref:`C-001 `, :ref:`C-007 ` - — - ⚠ Partial * - - SO.PreventAttackPropagation - - C-001, C-008 + - :ref:`C-001 `, :ref:`C-008 ` - — - ✓ Implemented * - @@ -245,22 +245,22 @@ The table below summarises dfetch's implementation of each prEN 40000-1-4 Securi - — N/A * - **ECR-J** — Be designed, developed and produced to limit attack surfaces, including external interfaces. - SO.ReduceAttackSurface - - C-001, C-003, C-004, C-007, C-008 + - :ref:`C-001 `, :ref:`C-003 `, :ref:`C-004 `, :ref:`C-007 `, :ref:`C-008 ` - — - ⚠ Partial * - **ECR-K** — Be designed, developed and produced to reduce the impact of an incident using appropriate exploitation mitigation mechanisms and techniques. - SO.ReduceImpactOfIncident - - C-005, C-007, C-015, C-017, C-046 + - :ref:`C-005 `, :ref:`C-007 `, :ref:`C-015 `, :ref:`C-017 `, :ref:`C-046 ` - — - ✓ 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 - - C-036 + - :ref:`C-036 ` - No persistent security event log (LGM-2/3/4 gap); No opt-out for logging — dfetch does not log by default - ⚠ Partial * - - SO.MonitorSecurityRelevantActivities - - C-009 + - :ref:`C-009 ` - — - ⚠ Partial * - @@ -312,17 +312,17 @@ Part II requirements are addressed via prEN 40000-1-3. pii-04 is not applicable - Status * - Part II §1 - Identify and document vulnerabilities and components (SBOM). - - C-021, C-022 + - :ref:`C-021 `, :ref:`C-022 ` - — - ✓ Implemented * - Part II §2 - Address vulnerabilities without delay; provide free security updates. - - C-015, C-016, SECURITY.md - - No LTS backport policy (latest release only — documented in SECURITY.md) + - :ref:`C-015 `, :ref:`C-016 `, `SECURITY.md `_ + - No LTS backport policy (latest release only — documented in `SECURITY.md `_) - ⚠ Partial * - Part II §3 - Apply effective coordinated vulnerability disclosure (CVD) policy. - - SECURITY.md + - `SECURITY.md `_ - — - ✓ Implemented * - Part II §4 @@ -332,17 +332,17 @@ Part II requirements are addressed via prEN 40000-1-3. pii-04 is not applicable - — N/A * - Part II §5 - Publish coordinated vulnerability disclosure policy. - - SECURITY.md + - `SECURITY.md `_ - — - ✓ Implemented * - Part II §6 - Share information on vulnerabilities in integrated components. - - C-022, C-016 + - :ref:`C-022 `, :ref:`C-016 ` - No proactive downstream notification process - ⚠ Partial * - Part II §7 - Provide security updates free of charge for the support period. - - MIT licence, PyPI, SECURITY.md + - MIT licence, PyPI, `SECURITY.md `_ - — - ✓ Implemented @@ -353,24 +353,24 @@ Gap Analysis — Compliance-Only Controls Three compliance-only controls address CRA requirements not independently covered by the risk models. -**C-043 — Release-gate CVE check (ECR-a, SO.VulnerabilityManagementProcess → GEC-1)** +**:ref:`C-043 ` — Release-gate CVE check (ECR-a, SO.VulnerabilityManagementProcess → GEC-1)** -dfetch's CI detects vulnerabilities at commit time (C-015, C-016, C-017) but does not gate the release publish on a CVE scan of runtime dependencies. C-043 (planned) adds ``pip-audit`` or ``osv-scanner`` to the publish workflow. +dfetch's CI detects vulnerabilities at commit time (:ref:`C-015 `, :ref:`C-016 `, :ref:`C-017 `) but does not gate the release publish on a CVE scan of runtime dependencies. :ref:`C-043 ` (planned) adds ``pip-audit`` or ``osv-scanner`` to the publish workflow. -**C-044 — Data minimisation policy (ECR-g, SO.DataMinimization → DTM-1)** +**: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 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. C-044 formalises this assertion as a documented policy. +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. -**C-046 — Exploit mitigation inventory (ECR-k, SO.ReduceImpactOfIncident → GEC-11)** +**: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): - **ASLR / DEP / stack canaries**: provided by CPython and the OS; not in dfetch's control but inherited. - **No eval/exec of remote content**: dfetch never evaluates fetched content as code. -- **Constant-time comparison** (C-005): HMAC-based integrity hash uses ``hmac.compare_digest``. -- **No shell injection** (C-007): all subprocess calls use ``shell=False``. -- **Input validation** (C-008): URL scheme, path, and revision inputs are validated. -- **Static analysis** (C-015, C-017): CodeQL and bandit gate every commit. +- **Constant-time comparison** (:ref:`C-005 `): HMAC-based integrity hash uses ``hmac.compare_digest``. +- **No shell injection** (:ref:`C-007 `): all subprocess calls use ``shell=False``. +- **Input validation** (:ref:`C-008 `): URL scheme, path, and revision inputs are validated. +- **Static analysis** (:ref:`C-015 `, :ref:`C-017 `): CodeQL and bandit gate every commit. - CFI, sandboxing, and signed-execution policies are not applicable to a pure-Python tool. ---- diff --git a/doc/explanation/control_register.rst b/doc/explanation/control_register.rst index 9756f5aa..1346d830 100644 --- a/doc/explanation/control_register.rst +++ b/doc/explanation/control_register.rst @@ -15,135 +15,202 @@ requirements not independently surfaced by the risk analysis. - Name - Type - Reference - * - C-001 + * - .. _c-001: + + C-001 - Path-traversal prevention - Risk-driven - - dfetch/util/util.py - * - C-002 + - `dfetch/util/util.py `_ + * - .. _c-002: + + C-002 - Decompression-bomb protection - Risk-driven - - dfetch/vcs/archive.py - * - C-003 + - `dfetch/vcs/archive.py `_ + * - .. _c-003: + + C-003 - Archive symlink validation - Risk-driven - - dfetch/vcs/archive.py - * - C-004 + - `dfetch/vcs/archive.py `_ + * - .. _c-004: + + C-004 - Archive member type checks - Risk-driven - - dfetch/vcs/archive.py - * - C-005 + - `dfetch/vcs/archive.py `_ + * - .. _c-005: + + C-005 - Integrity hash verification - Risk-driven - - dfetch/vcs/integrity_hash.py - * - C-006 + - `dfetch/vcs/integrity_hash.py `_ + * - .. _c-006: + + C-006 - Non-interactive VCS - Risk-driven - - dfetch/vcs/git.py, dfetch/vcs/svn.py - * - C-007 + - `dfetch/vcs/git.py `_, + `dfetch/vcs/svn.py `_ + * - .. _c-007: + + C-007 - Subprocess safety - Risk-driven - - dfetch/util/cmdline.py - * - C-008 + - `dfetch/util/cmdline.py `_ + * - .. _c-008: + + C-008 - Manifest input validation - Risk-driven - - dfetch/manifest/schema.py - * - C-009 + - `dfetch/manifest/schema.py `_ + * - .. _c-009: + + C-009 - Actions commit-SHA pinning - Risk-driven - - .github/workflows/\*.yml - * - C-010 + - `.github/workflows/ `_ + * - .. _c-010: + + C-010 - OIDC trusted publishing - Risk-driven - - .github/workflows/python-publish.yml - * - C-011 + - `.github/workflows/python-publish.yml `_ + * - .. _c-011: + + C-011 - Minimal workflow permissions - Risk-driven - - .github/workflows/\*.yml - * - C-012 + - `.github/workflows/ `_ + * - .. _c-012: + + C-012 - persist-credentials: false - Risk-driven - - .github/workflows/\*.yml - * - C-013 + - `.github/workflows/ `_ + * - .. _c-013: + + C-013 - Harden-runner (egress block) - Risk-driven - - .github/workflows/\*.yml - * - C-015 + - `.github/workflows/ `_ + * - .. _c-015: + + C-015 - CodeQL static analysis - Risk-driven - - .github/workflows/codeql-analysis.yml - * - C-016 + - `.github/workflows/codeql-analysis.yml `_ + * - .. _c-016: + + C-016 - Dependency review - Risk-driven - - .github/workflows/dependency-review.yml - * - C-017 + - `.github/workflows/dependency-review.yml `_ + * - .. _c-017: + + C-017 - bandit security linter - Risk-driven - - pyproject.toml - * - C-021 + - `pyproject.toml `_ + * - .. _c-021: + + C-021 - Sigstore SBOM attestation - Risk-driven - — - * - C-022 + * - .. _c-022: + + C-022 - CycloneDX SBOM on PyPI - Risk-driven - — - * - C-024 + * - .. _c-024: + + C-024 - ``secrets: inherit`` scope - Risk-driven - — - * - C-026 + * - .. _c-026: + + C-026 - Consumer-side package provenance verification - Risk-driven - - doc/howto/verify-integrity.rst - * - C-032 + - :doc:`../howto/verify-integrity` + * - .. _c-032: + + C-032 - Consumer attestation verification pins to release tag ref - Risk-driven - - doc/howto/verify-integrity.rst - * - C-033 + - :doc:`../howto/verify-integrity` + * - .. _c-033: + + C-033 - Ref-scoped build cache keys isolate PR and release builds - Risk-driven - - .github/workflows/build.yml - * - C-034 + - `.github/workflows/build.yml `_ + * - .. _c-034: + + C-034 - Hash algorithm allowlist (SHA-256/384/512 only) - Risk-driven - - dfetch/vcs/integrity_hash.py - * - C-036 + - `dfetch/vcs/integrity_hash.py `_ + * - .. _c-036: + + C-036 - Persisted-metadata credential redaction - Risk-driven - - dfetch/project/metadata.py - * - C-037 + - `dfetch/project/metadata.py `_ + * - .. _c-037: + + C-037 - SLSA Source Provenance Attestation of repository governance controls - Risk-driven - - .github/workflows/source-provenance.yml - * - C-038 + - `.github/workflows/source-provenance.yml `_ + * - .. _c-038: + + C-038 - Ancestry enforcement on dfetch main branch - Risk-driven - - .github/workflows/ - * - C-039 + - `.github/workflows/ `_ + * - .. _c-039: + + C-039 - Source build provenance and VSA attestations - Risk-driven - - doc/howto/verify-integrity.rst - * - C-040 + - :doc:`../howto/verify-integrity` + * - .. _c-040: + + C-040 - Test result attestation on source archive - Risk-driven - - .github/workflows/test.yml - * - C-041 + - `.github/workflows/test.yml `_ + * - .. _c-041: + + C-041 - Winget manifest PRs reviewed by community maintainers - Risk-driven - - .github/workflows/winget-publish.yml - * - C-042 + - `.github/workflows/winget-publish.yml `_ + * - .. _c-042: + + C-042 - WINGET_TOKEN scoped to dedicated Winget environment - Risk-driven - - .github/workflows/winget-publish.yml - * - C-043 + - `.github/workflows/winget-publish.yml `_ + * - .. _c-043: + + C-043 - Release-gate CVE check on runtime dependencies - Compliance-only - - .github/workflows/python-publish.yml (planned CI addition) - * - C-044 + - `.github/workflows/python-publish.yml `_ (planned CI addition) + * - .. _c-044: + + C-044 - Data minimisation policy - Compliance-only - - doc/explanation/compliance_track.rst - * - C-046 + - :doc:`compliance_track` + * - .. _c-046: + + C-046 - Exploit mitigation inventory - Compliance-only - - doc/explanation/compliance_track.rst + - :doc:`compliance_track` diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 79797ac4..7a67daf7 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -108,7 +108,8 @@ Threat Models The following pages document the two threat models in detail. Each page is generated from the corresponding Python module in ``security/`` — see -``security/README.md`` for instructions on regenerating them. +`security/README.md `_ +for instructions on regenerating them. .. toctree:: :maxdepth: 1 @@ -137,14 +138,14 @@ The three-tier traceability model is:: Three compliance-only controls address CRA requirements not independently surfaced by the risk models: -- **C-043** (release-gate CVE check) — ECR-a / SO.VulnerabilityManagementProcess → GEC-1 -- **C-044** (data minimisation policy) — ECR-g / SO.DataMinimization → DTM-1 -- **C-046** (exploit mitigation inventory) — ECR-k / SO.ReduceImpactOfIncident → GEC-11 +- :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 OSCAL 1.1.2 artifacts are kept alongside the source: -- ``security/cra_pren_4000014_oscal_catalog.json`` — prEN 40000-1-4 catalog +- `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 +- `security/dfetch.component-definition.json `_ — dfetch Component Definition The complete list of all controls is on the :doc:`control_register` page.