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.
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/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
CRA Compliance (human-readable RST mapping tables) and
security/dfetch.component-definition.json
(machine-readable OSCAL 1.1.2 Component Definition). The
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 Verify release 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 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 (maintained) |
All 46 dfetch controls (C-001 to C-046) with references and status |
|
OSCAL 1.1.2 JSON |
Machine-readable Component Definition; maps dfetch controls to CRA ECRs |
|
OSCAL 1.1.2 JSON |
Static prEN 40000-1-4 catalog (input to compliance pipeline, not generated) |
|
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 C-026, C-037,
C-039, C-040;
verifiable with |
|
JSON (SARIF 2.1.0) |
|
|
JSON (Code Climate) |
|
|
JSON |
|
