doc: add security documentation pipeline flow diagram#1276
Merged
Conversation
Adds a PlantUML component diagram (security_doc_flow.puml) showing how the three security documentation pipelines produce their output artifacts — threat model RSTs (via tm_render.py + pytm), compliance RST and OSCAL JSON (via compliance.py), and runtime outputs (SARIF, SBOM, Code Climate, Jenkins JSON from dfetch check/report). References the diagram from a new "Security Documentation Pipeline" section in security.rst with prose explaining each pipeline. https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X
…1.2.2
Rebuilds security_doc_flow.puml to follow the four-column structure of
figure 4.1.2.2 from the EU Blue Guide on product rules (OJ 2022/C 247):
col 1 all requirements (CRA ECR-a…m + STRIDE catalog)
col 2 risk & threat assessment step (dashed box, filter)
col 3 applicable to dfetch (threats + controls + N/A gaps)
col 4 output paths — solid arrows where STRIDE methodology or
CRA compliance analysis provides coverage, dashed arrow
for gaps with no harmonised standard
Updates the security.rst prose to explain the Blue Guide analogy and
links to the official EU Blue Guide PDF on EUR-Lex.
https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X
Replaces the plain "Runtime outputs" sentence with proper :ref: cross-links to check-ci-github (SARIF), sbom (CycloneDX), check-ci-gitlab (Code Climate), and check-ci-jenkins (Jenkins JSON). Adds an "Artifacts at a glance" list-table covering all ten security documentation outputs — generated RST pages, manually maintained RST page, two OSCAL JSON files, and the four runtime reporting formats — with direct doc cross-references or GitHub source links for each. https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X
…CAL, STRIDE Adds a structured Further Reading section covering: - CRA: official text, EU overview, March 2026 draft guidance, BSI TR-03183-1 - EN 40000: CEN/CENELEC cybersecurity page, March 2025 webinar slides, EU Blue Guide 2022 (fig 4.1.2.2), OSCAL catalog provenance note - Threat modelling: STRIDE docs, pytm, BSI TR-03183-1, ENISA playbook - OSCAL: NIST OSCAL project, Catalog model, Component Definition model - Output formats: SARIF 2.1.0 (OASIS), CycloneDX, Code Climate spec Also updates the EN 40000 inline link from a single webinar PDF to the CEN/CENELEC cybersecurity overview page, and adds an explicit STRIDE link. https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X
…ch report The SBOMs relevant to dfetch's security model are the CycloneDX SBOM attestations generated by GitHub Actions about dfetch itself (signed by Sigstore, verifiable via gh attestation verify), not the SBOM output that dfetch generates for users' vendored dependencies. - diagram: replace "Runtime evidence (dfetch check/report)" with two separate clusters: "Release attestations (GitHub Actions, about dfetch)" containing CycloneDX SBOM · SLSA Build Provenance · Source Provenance · VSA · in-toto Test Results, connected from tm_out via controls C-026/C-037/C-039/C-040; and "Dependency-scanning outputs (dfetch check)" containing only SARIF · Code Climate · Jenkins JSON - prose: replace single "Runtime outputs" paragraph with "Release attestations" (five types, Sigstore-signed, gh attestation verify) and "Dependency-scanning outputs" (dfetch check formats for users) - artifacts table: replace dfetch report --sbom row with a "Release attestations" row referencing verify-integrity and the four controls - Further Reading: update CycloneDX note to clarify it is dfetch's own CI-generated SBOM, not a user-facing report --sbom output https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X
New entries:
Attestation — Sigstore-signed claims about dfetch release artifacts;
links the five attestation types and verify-integrity
Build Provenance — SLSA attestation for source-to-binary traceability
CRA — Cyber Resilience Act (EU 2024/2847), 13 ECRs
EN 40000 — CEN/CENELEC harmonised standard family under the CRA
OSCAL — NIST Open Security Controls Assessment Language; both
OSCAL artifacts (catalog + component-definition) explained
SARIF — Static Analysis Results Interchange Format; links check-ci
Sigstore — transparency-log code-signing infrastructure for attestations
SLSA — Supply-chain Levels for Software Artifacts framework
Source Provenance — SLSA attestation for governance controls on main
STRIDE — threat-classification framework; links both threat model pages
VSA — Verification Summary Attestation for binary installers
Updated:
SBOM — notes both user-facing dfetch report output and dfetch's
own CI-generated CycloneDX release attestation
https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X
Contributor
|
Warning Review limit reached
More reviews will be available in 34 minutes and 29 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (2)
WalkthroughAdds a new PlantUML diagram ( ChangesSecurity Documentation Expansion
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@doc/reference/glossary.rst`:
- Around line 169-175: Locate the Attestation glossary entry (not shown in the
provided diff but referenced in the comment) which currently states that dfetch
publishes five attestation types on every release. Update this entry to clarify
that while four attestation types are published per-release, the Source
Provenance attestation is published on every push to main instead. This
distinction ensures the Attestation entry accurately reflects the different
publication triggers for the different attestation types and resolves the
inconsistency with the Source Provenance entry.
In `@doc/static/uml/security_doc_flow.puml`:
- Around line 90-95: The diagram currently shows direct arrows from tm_out to
sc_out for release attestations (labeled with C-026, C-037, C-039, C-040) and
from appl_c to rt_out for dependency scanning, which incorrectly implies these
nodes are the sources. Create explicit producer nodes for the release
attestations workflow and the dependency scanning check workflow, then redirect
the arrows to originate from these new producer nodes instead of from tm_out and
appl_c respectively. This will accurately represent that these artifacts are
generated by separate workflows rather than being outputs of the existing nodes.
- Around line 47-49: The diagram incorrectly includes control_register.rst
inside the p_comp_out package as a generated artifact by compliance.py, but
control_register.rst is manually maintained and not produced by the generator.
Remove control_register.rst from the list of artifacts within the comp_out
component definition so that the diagram only shows compliance_track.rst and
dfetch.component-definition.json as the outputs covered by compliance.py,
reflecting the actual artifacts the generator produces.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: 7f1f2b44-fc03-4348-8d39-f0467ccdadf7
📒 Files selected for processing (3)
doc/explanation/security.rstdoc/reference/glossary.rstdoc/static/uml/security_doc_flow.puml
Attestation entry (glossary): clarified that four attestation types are
published per release (Build Provenance, SBOM, VSA, in-toto Test Results)
and Source Provenance is published on every push to main — not per release.
Verified against verify-integrity.rst line 239.
Diagram producer nodes: replaced misleading arrows (tm_out→sc_out and
appl_c→rt_out) with explicit producer nodes inside each output package:
- "GitHub Actions release workflow" → sc_out and src_prov (Source
Provenance split out as a separate node to reflect different trigger)
- "dfetch check" → rt_out
Arrows from the documentation pipeline are now dashed "requires/documents"
links to the producer nodes, not solid "produces" arrows to the artifacts.
control_register.rst removed from comp_out: the file is manually maintained
and not generated by compliance.py (which outputs only compliance_track.rst
and dfetch.component-definition.json). Verified by inspection of compliance.py
output path and README commands.
https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a PlantUML component diagram (security_doc_flow.puml) showing
how the three security documentation pipelines produce their output
artifacts — threat model RSTs (via tm_render.py + pytm), compliance
RST and OSCAL JSON (via compliance.py), and runtime outputs (SARIF,
SBOM, Code Climate, Jenkins JSON from dfetch check/report).
References the diagram from a new "Security Documentation Pipeline"
section in security.rst with prose explaining each pipeline.
https://claude.ai/code/session_01P1dbJRTSn9LooBhp9Xwt7X
Summary by CodeRabbit