Skip to content

Commit b721b05

Browse files
spoorccclaude
spoorcc
and
claude
authored
doc: fix diagram syntax error and move pipeline meta-docs to separate page (#1277)
- Fix PlantUML syntax error in security_doc_flow.puml: replace unsupported `#line.dashed;back:color` combined style (not available in plantuml ≤2020) with a stereotype-based skinparam block (`skinparam package<<assess>>`) - Move the "Security Documentation Pipeline" section out of security.rst into a new security_pipeline.rst, so the security model page focuses on the model itself rather than implementation details - Add a brief cross-reference paragraph and toctree entry in security.rst pointing to the new page https://claude.ai/code/session_01QfePU2NybeWt7GnCiZg42s Co-authored-by: Claude <noreply@anthropic.com>
1 parent 91b13e3 commit b721b05

3 files changed

Lines changed: 130 additions & 113 deletions

File tree

‎doc/explanation/security.rst‎

Lines changed: 4 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -104,118 +104,9 @@ threat models below.
104104
manifest destination path, or hostile archive entries, could write, overwrite, or
105105
delete files outside the intended vendoring directory on the end-user machine.
106106

107-
Security Documentation Pipeline
108-
--------------------------------
109-
110-
The diagram below follows the structure of figure 4.1.2.2 in the
111-
`EU Blue Guide on the implementation of EU product rules (2022) <https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX%3A52022XC0629%2804%29>`_:
112-
all requirements are on the left, a risk-and-threat assessment step (dashed box)
113-
selects which requirements apply, the applicable subset sits in the third column,
114-
and the right side shows two output paths — a solid-arrow path where coverage is
115-
provided by a recognised methodology (STRIDE / pytm), and a dashed-arrow path
116-
where no harmonised standard applies and the requirement is addressed directly as
117-
a documented gap or compliance artefact.
118-
119-
.. uml:: /static/uml/security_doc_flow.puml
120-
121-
**Threat model pipeline** —
122-
`security/tm_supply_chain.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_supply_chain.py>`_
123-
and
124-
`security/tm_usage.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_usage.py>`_
125-
define the model elements (actors, data flows, trust boundaries) using the
126-
*pytm* library.
127-
`security/threats.json <https://github.com/dfetch-org/dfetch/blob/main/security/threats.json>`_
128-
provides a catalog of 60+ STRIDE-classified threats.
129-
`security/tm_render.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_render.py>`_
130-
drives *pytm*, matches threats against model elements, and combines the output
131-
with
132-
`security/report_template.rst <https://github.com/dfetch-org/dfetch/blob/main/security/report_template.rst>`_
133-
to produce the two RST threat-model pages (:doc:`threat_model_supply_chain` and
134-
:doc:`threat_model_usage`), each containing an embedded data-flow diagram, a
135-
sequence diagram, and tables for assets, threats, and controls.
136-
137-
**Compliance pipeline** —
138-
`security/compliance_data.py <https://github.com/dfetch-org/dfetch/blob/main/security/compliance_data.py>`_
139-
defines the 46 dfetch controls and their mapping to CRA essential requirements
140-
and prEN 40000-1-4 security objectives.
141-
`security/compliance.py <https://github.com/dfetch-org/dfetch/blob/main/security/compliance.py>`_
142-
reads those definitions together with the static OSCAL catalog and generates
143-
:doc:`compliance_track` (human-readable RST mapping tables) and
144-
`security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
145-
(machine-readable OSCAL 1.1.2 Component Definition). The
146-
:doc:`control_register` page is maintained manually and references controls
147-
defined in ``compliance_data.py``.
148-
149-
**Release attestations** — GitHub Actions generates five cryptographic attestation
150-
types *about dfetch itself* during every release, signed by Sigstore and verifiable
151-
by consumers with ``gh attestation verify`` (see :ref:`verify-integrity`):
152-
CycloneDX SBOM (composition of the published package), SLSA Build Provenance
153-
(source-to-binary traceability), SLSA Source Provenance (governance controls on
154-
``main``), Verification Summary Attestation (VSA), and in-toto Test Results
155-
(CI test suite passed before any binary was produced). These are required by
156-
supply-chain controls :ref:`C-026 <c-026>`, :ref:`C-037 <c-037>`,
157-
:ref:`C-039 <c-039>`, and :ref:`C-040 <c-040>`.
158-
159-
**Dependency-scanning outputs** — When users run ``dfetch check``, the reporting
160-
layer emits findings about outdated or missing vendored dependencies in the format
161-
of their choice:
162-
:ref:`SARIF <check-ci-github>` (for GitHub code scanning),
163-
:ref:`Code Climate JSON <check-ci-gitlab>` (GitLab merge-request quality reports), or
164-
:ref:`Jenkins JSON <check-ci-jenkins>` (Jenkins warnings-ng plugin).
165-
166-
**Artifacts at a glance**
167-
168-
.. list-table::
169-
:header-rows: 1
170-
:widths: 40 15 45
171-
172-
* - Artifact
173-
- Type
174-
- Purpose
175-
176-
* - :doc:`threat_model_supply_chain`
177-
- RST (generated)
178-
- Supply-chain threat model: DFD, sequence diagram, STRIDE tables, controls
179-
180-
* - :doc:`threat_model_usage`
181-
- RST (generated)
182-
- Runtime threat model: DFD, sequence diagram, STRIDE tables, controls
183-
184-
* - :doc:`compliance_track`
185-
- RST (generated)
186-
- CRA Annex I → prEN 40000-1-4 SO.* → dfetch control traceability tables
187-
188-
* - :doc:`control_register`
189-
- RST (maintained)
190-
- All 46 dfetch controls (C-001 to C-046) with references and status
191-
192-
* - `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
193-
- OSCAL 1.1.2 JSON
194-
- Machine-readable Component Definition; maps dfetch controls to CRA ECRs
195-
196-
* - `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_
197-
- OSCAL 1.1.2 JSON
198-
- Static prEN 40000-1-4 catalog (input to compliance pipeline, not generated)
199-
200-
* - :ref:`Release attestations <verify-integrity>`
201-
- Sigstore-signed (GitHub Actions)
202-
- Five attestation types generated *about dfetch* on every release: CycloneDX
203-
SBOM, SLSA Build Provenance, SLSA Source Provenance, VSA, in-toto Test Results.
204-
Required by controls :ref:`C-026 <c-026>`, :ref:`C-037 <c-037>`,
205-
:ref:`C-039 <c-039>`, :ref:`C-040 <c-040>`;
206-
verifiable with ``gh attestation verify``.
207-
208-
* - :ref:`SARIF output <check-ci-github>`
209-
- JSON (SARIF 2.1.0)
210-
- ``dfetch check --output-type sarif``; upload to GitHub code scanning
211-
212-
* - :ref:`Code Climate JSON <check-ci-gitlab>`
213-
- JSON (Code Climate)
214-
- ``dfetch check --output-type code-climate``; GitLab MR quality widget
215-
216-
* - :ref:`Jenkins JSON <check-ci-jenkins>`
217-
- JSON
218-
- ``dfetch check --output-type jenkins``; Jenkins warnings-ng plugin
107+
For an overview of how this documentation set is produced — the threat-model
108+
pipeline, compliance pipeline, release attestations, and the full artifact
109+
inventory — see :doc:`security_pipeline`.
219110

220111
Threat Models
221112
-------------
@@ -228,6 +119,7 @@ for instructions on regenerating them.
228119
.. toctree::
229120
:maxdepth: 1
230121

122+
security_pipeline
231123
threat_model_supply_chain
232124
threat_model_usage
233125
compliance_track

‎doc/explanation/security_pipeline.rst‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
2+
.. _security-pipeline:
3+
4+
Security Documentation Pipeline
5+
================================
6+
7+
.. note::
8+
9+
This page explains how the *dfetch* security documentation is produced.
10+
It is aimed at contributors and maintainers who want to understand or
11+
regenerate the security artifacts.
12+
13+
The diagram below follows the structure of figure 4.1.2.2 in the
14+
`EU Blue Guide on the implementation of EU product rules (2022) <https://eur-lex.europa.eu/legal-content/EN/TXT/PDF/?uri=CELEX%3A52022XC0629%2804%29>`_:
15+
all requirements are on the left, a risk-and-threat assessment step (dashed box)
16+
selects which requirements apply, the applicable subset sits in the third column,
17+
and the right side shows two output paths — a solid-arrow path where coverage is
18+
provided by a recognised methodology (STRIDE / pytm), and a dashed-arrow path
19+
where no harmonised standard applies and the requirement is addressed directly as
20+
a documented gap or compliance artefact.
21+
22+
.. uml:: /static/uml/security_doc_flow.puml
23+
24+
**Threat model pipeline** —
25+
`security/tm_supply_chain.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_supply_chain.py>`_
26+
and
27+
`security/tm_usage.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_usage.py>`_
28+
define the model elements (actors, data flows, trust boundaries) using the
29+
*pytm* library.
30+
`security/threats.json <https://github.com/dfetch-org/dfetch/blob/main/security/threats.json>`_
31+
provides a catalog of 60+ STRIDE-classified threats.
32+
`security/tm_render.py <https://github.com/dfetch-org/dfetch/blob/main/security/tm_render.py>`_
33+
drives *pytm*, matches threats against model elements, and combines the output
34+
with
35+
`security/report_template.rst <https://github.com/dfetch-org/dfetch/blob/main/security/report_template.rst>`_
36+
to produce the two RST threat-model pages (:doc:`threat_model_supply_chain` and
37+
:doc:`threat_model_usage`), each containing an embedded data-flow diagram, a
38+
sequence diagram, and tables for assets, threats, and controls.
39+
40+
**Compliance pipeline** —
41+
`security/compliance_data.py <https://github.com/dfetch-org/dfetch/blob/main/security/compliance_data.py>`_
42+
defines the 46 dfetch controls and their mapping to CRA essential requirements
43+
and prEN 40000-1-4 security objectives.
44+
`security/compliance.py <https://github.com/dfetch-org/dfetch/blob/main/security/compliance.py>`_
45+
reads those definitions together with the static OSCAL catalog and generates
46+
:doc:`compliance_track` (human-readable RST mapping tables) and
47+
`security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
48+
(machine-readable OSCAL 1.1.2 Component Definition). The
49+
:doc:`control_register` page is maintained manually and references controls
50+
defined in ``compliance_data.py``.
51+
52+
**Release attestations** — GitHub Actions generates five cryptographic attestation
53+
types *about dfetch itself* during every release, signed by Sigstore and verifiable
54+
by consumers with ``gh attestation verify`` (see :ref:`verify-integrity`):
55+
CycloneDX SBOM (composition of the published package), SLSA Build Provenance
56+
(source-to-binary traceability), SLSA Source Provenance (governance controls on
57+
``main``), Verification Summary Attestation (VSA), and in-toto Test Results
58+
(CI test suite passed before any binary was produced). These are required by
59+
supply-chain controls :ref:`C-026 <c-026>`, :ref:`C-037 <c-037>`,
60+
:ref:`C-039 <c-039>`, and :ref:`C-040 <c-040>`.
61+
62+
**Dependency-scanning outputs** — When users run ``dfetch check``, the reporting
63+
layer emits findings about outdated or missing vendored dependencies in the format
64+
of their choice:
65+
:ref:`SARIF <check-ci-github>` (for GitHub code scanning),
66+
:ref:`Code Climate JSON <check-ci-gitlab>` (GitLab merge-request quality reports), or
67+
:ref:`Jenkins JSON <check-ci-jenkins>` (Jenkins warnings-ng plugin).
68+
69+
**Artifacts at a glance**
70+
71+
.. list-table::
72+
:header-rows: 1
73+
:widths: 40 15 45
74+
75+
* - Artifact
76+
- Type
77+
- Purpose
78+
79+
* - :doc:`threat_model_supply_chain`
80+
- RST (generated)
81+
- Supply-chain threat model: DFD, sequence diagram, STRIDE tables, controls
82+
83+
* - :doc:`threat_model_usage`
84+
- RST (generated)
85+
- Runtime threat model: DFD, sequence diagram, STRIDE tables, controls
86+
87+
* - :doc:`compliance_track`
88+
- RST (generated)
89+
- CRA Annex I → prEN 40000-1-4 SO.* → dfetch control traceability tables
90+
91+
* - :doc:`control_register`
92+
- RST (maintained)
93+
- All 46 dfetch controls (C-001 to C-046) with references and status
94+
95+
* - `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
96+
- OSCAL 1.1.2 JSON
97+
- Machine-readable Component Definition; maps dfetch controls to CRA ECRs
98+
99+
* - `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_
100+
- OSCAL 1.1.2 JSON
101+
- Static prEN 40000-1-4 catalog (input to compliance pipeline, not generated)
102+
103+
* - :ref:`Release attestations <verify-integrity>`
104+
- Sigstore-signed (GitHub Actions)
105+
- Five attestation types generated *about dfetch* on every release: CycloneDX
106+
SBOM, SLSA Build Provenance, SLSA Source Provenance, VSA, in-toto Test Results.
107+
Required by controls :ref:`C-026 <c-026>`, :ref:`C-037 <c-037>`,
108+
:ref:`C-039 <c-039>`, :ref:`C-040 <c-040>`;
109+
verifiable with ``gh attestation verify``.
110+
111+
* - :ref:`SARIF output <check-ci-github>`
112+
- JSON (SARIF 2.1.0)
113+
- ``dfetch check --output-type sarif``; upload to GitHub code scanning
114+
115+
* - :ref:`Code Climate JSON <check-ci-gitlab>`
116+
- JSON (Code Climate)
117+
- ``dfetch check --output-type code-climate``; GitLab MR quality widget
118+
119+
* - :ref:`Jenkins JSON <check-ci-jenkins>`
120+
- JSON
121+
- ``dfetch check --output-type jenkins``; Jenkins warnings-ng plugin

‎doc/static/uml/security_doc_flow.puml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,10 @@ skinparam arrowColor #333333
77
skinparam packageBorderColor #333333
88
skinparam componentBorderColor #555555
99
skinparam componentBackgroundColor white
10+
skinparam package<<assess>> {
11+
BackgroundColor #d5e8d4
12+
BorderStyle dashed
13+
}
1014

1115
left to right direction
1216

@@ -23,7 +27,7 @@ package "All requirements\n(legally binding, given in\nlegislation and threat ca
2327

2428
' ── Column 2: Risk & threat assessment (dashed = selection / filter step) ─────
2529

26-
package "Risk and threat assessment\n(by dfetch maintainers)" as p_assess #line.dashed;back:#d5e8d4 {
30+
package "Risk and threat assessment\n(by dfetch maintainers)" <<assess>> as p_assess {
2731
[tm_supply_chain.py\ntm_usage.py + pytm] as tm
2832
[compliance_data.py\n+ OSCAL catalog] as comp
2933
}

0 commit comments

Comments
 (0)