diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index 91176a798..bae0fbe5f 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -104,118 +104,9 @@ 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 +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`. Threat Models ------------- @@ -228,6 +119,7 @@ for instructions on regenerating them. .. toctree:: :maxdepth: 1 + security_pipeline threat_model_supply_chain threat_model_usage compliance_track diff --git a/doc/explanation/security_pipeline.rst b/doc/explanation/security_pipeline.rst new file mode 100644 index 000000000..460e5acbe --- /dev/null +++ b/doc/explanation/security_pipeline.rst @@ -0,0 +1,121 @@ + +.. _security-pipeline: + +Security Documentation Pipeline +================================ + +.. note:: + + This page explains how the *dfetch* security documentation is produced. + It is aimed at contributors and maintainers who want to understand or + regenerate the security artifacts. + +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 diff --git a/doc/static/uml/security_doc_flow.puml b/doc/static/uml/security_doc_flow.puml index a0c6de0b9..89d0fe85a 100644 --- a/doc/static/uml/security_doc_flow.puml +++ b/doc/static/uml/security_doc_flow.puml @@ -7,6 +7,10 @@ skinparam arrowColor #333333 skinparam packageBorderColor #333333 skinparam componentBorderColor #555555 skinparam componentBackgroundColor white +skinparam package<> { + BackgroundColor #d5e8d4 + BorderStyle dashed +} left to right direction @@ -23,7 +27,7 @@ package "All requirements\n(legally binding, given in\nlegislation and threat ca ' ── 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 { +package "Risk and threat assessment\n(by dfetch maintainers)" <> as p_assess { [tm_supply_chain.py\ntm_usage.py + pytm] as tm [compliance_data.py\n+ OSCAL catalog] as comp }