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.
See also
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 (dfetch Supply Chain and dfetch Runtime Usage), each containing an embedded data-flow diagram, a sequence diagram, and tables for assets, threats, and controls.
Compliance pipeline —
security/tm_controls_data.py
defines all dfetch controls (Track A: risk-driven; Track B: compliance-only controls
in compliance_data.py) 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
CRA Compliance (human-readable RST mapping tables),
Control Register (the full control register with GitHub references), and
security/dfetch.component-definition.json
(machine-readable OSCAL 1.2.2 Component Definition). The Component Definition
includes the supplier party, component purpose, and evidence links on each
implemented-requirement pointing to the concrete code or CI file that implements
the control — making the mapping machine-verifiable.
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 Verify release integrity): CycloneDX SBOM (composition of the
published package), Build Provenance (source-to-binary traceability),
Source Provenance (governance controls on main), VSA, and
in-toto Test Results (CI test suite passed before any binary was produced).
These are required by supply-chain controls C-026,
C-037, C-039, and 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:
SARIF (for GitHub code scanning),
Code Climate JSON (GitLab merge-request quality reports), or
Jenkins JSON (Jenkins warnings-ng plugin).
Artifacts at a glance
Artifact |
Type |
Purpose |
|---|---|---|
RST (generated) |
Supply-chain threat model: DFD, sequence diagram, STRIDE tables, controls |
|
RST (generated) |
Runtime threat model: DFD, sequence diagram, STRIDE tables, controls |
|
RST (generated) |
CRA Annex I → prEN 40000-1-4 SO.* → dfetch control traceability tables |
|
RST (generated) |
All dfetch controls with type, references, and status |
|
OSCAL 1.2.2 JSON (generated) |
Machine-readable Component Definition; maps dfetch controls to CRA ECRs; includes supplier party, component purpose, and evidence links to code |
|
OSCAL 1.2.2 JSON (static) |
Static prEN 40000-1-4 catalog; includes parties, roles, and responsible-parties |
|
Sigstore-signed (GitHub Actions) |
Five Attestation types generated about dfetch on every release:
CycloneDX SBOM, Build Provenance, Source Provenance,
VSA, in-toto Test Results.
Required by controls C-026, C-037,
C-039, C-040;
verifiable with |
|
JSON (SARIF 2.1.0) |
|
|
JSON (Code Climate) |
|
|
JSON |
|
