Upgrade OSCAL artifacts to 1.2.2 and enrich with security-as-code data#1284
Conversation
Both the prEN 40000-1-4 catalog and the Component Definition are upgraded from OSCAL 1.1.2 to 1.2.2 and significantly enriched: Catalog (cra_pren_4000014_oscal_catalog.json): - oscal-version 1.1.2 → 1.2.2 - metadata.parties: dfetch-org (catalog maintainer) and Angelo D'Amato/Vulnir B.V. (original content author, STAN4CR grant) - metadata.roles: catalog-maintainer, content-creator - metadata.responsible-parties: role→party mapping Component Definition (dfetch.component-definition.json, generated by compliance.py): - oscal-version 1.1.2 → 1.2.2 - metadata.document-ids: stable URI cross-reference - metadata.roles: supplier, maintainer - metadata.parties: dfetch-org organisation with GitHub homepage link - metadata.responsible-parties: supplier and maintainer role mapping - metadata.props: OpenSSF Scorecard URL added - component.purpose: describes what dfetch does and its security-relevant properties - component.responsible-roles: supplier party linked to component - component.links: adds SECURITY.md as vulnerability disclosure reference - component.props: asset-type, vendor-name, license enrichment - implemented-requirements: 21 of 35 requirements now carry evidence links (rel="evidence") pointing to the concrete code or CI workflow file that implements each control — making the compliance mapping machine-verifiable - back-matter: 12 resources (up from 3), adding OpenSSF Scorecard, Scorecard workflow, SLSA Source Provenance workflow, Sigstore attestation workflow, in-toto test-results workflow, CodeQL workflow, dependency-review workflow, GitHub Releases, and verify-integrity how-to doc compliance_data.py: - SOImplementation gets evidence_hrefs: list[tuple[str, str]] field - 21 SOs populated with (href, description) pairs pointing to code/CI evidence compliance.py: - _build_metadata: emits 1.2.2 structure with parties/roles/document-ids - _build_component: adds purpose, responsible-roles, enriched props and links - _build_implemented_requirements: emits evidence links from evidence_hrefs - _build_back_matter: 12 resources with tool/framework/type props - render_rst: references updated to OSCAL 1.2.2 Documentation updated in compliance_track.rst and security_pipeline.rst. Changelog entry added to 0.15.0 (unreleased). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01342LwMTGpgbJXEDptAEF5z
…on data - Add `note`, `TRACK_A_CONTROLS`, `ANNEX_V_MAP` to compliance_data.py so both RST documents can be rendered without pytm installed - Fix 13 SO_IMPLEMENTATIONS divergences from the curated manual RST: ECR-a adds C-040; ECR-b gains integrity-hash-opt-in gap; ECR-c SO.UserUpdateNotification loses incorrect C-040 reference and gains a note; ECR-d SO.AccessControl gains delegation gap; ECR-e DataTransmittedConfidentiality/ComAuth trimmed to [C-045]; ECR-f DataTransmittedIntegrity corrected to [C-005]; ECR-l LogSecurityRelevantActivities loses C-036 (not a logging control); ECR-i/j gain timeout-gap entries; ECR-m SecureDataDeletion gains note - Add _rst_ctrl_ref(), _format_ref_as_rst(), _format_single_ref() helpers; update _part_i_rows() to emit :ref: cross-references; update Part II table and gap analysis to use RST refs and hyperlinks - Add _render_annex_v(), _render_impl_notes(), render_control_register_rst() - Rewrite render_rst(): auto-gen header, richer preamble, Annex V section, status key, horizontal rules, Notes on Implemented rows - Both doc/explanation/*.rst are now auto-generated committed artifacts; removed 430 lines of manually-maintained duplication Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01342LwMTGpgbJXEDptAEF5z
Eliminates the TRACK_A_CONTROLS static-copy duplication in compliance_data.py. All 31 Track A controls (SC_CONTROLS + USAGE_CONTROLS) now live in a single source-of-truth module (security/tm_controls_data.py) with no pytm dependency. - security/tm_controls_data.py (new): Control dataclass + SC_CONTROLS (20 supply-chain controls) + USAGE_CONTROLS (11 usage controls) - security/tm_elements.py: remove duplicate Control class, re-export from tm_controls_data - security/compliance_data.py: remove duplicate Control class and the 180-line TRACK_A_CONTROLS static fallback; import Control from tm_controls_data - security/tm_supply_chain.py: remove inline CONTROLS list; import SC_CONTROLS as CONTROLS from tm_controls_data - security/tm_usage.py: remove inline CONTROLS list; import USAGE_CONTROLS as CONTROLS from tm_controls_data - security/compliance.py: remove importlib/try-except fallback; _load_track_a_ controls() now reads directly from SC_CONTROLS + USAGE_CONTROLS Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01342LwMTGpgbJXEDptAEF5z
WalkthroughIntroduces a pytm-free shared control register module ( ChangesOSCAL 1.2.2 CRA Compliance Track B upgrade with shared control register
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 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 |
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
security/dfetch.component-definition.json (1)
133-171:⚠️ Potential issue | 🟠 Major | ⚡ Quick winComponent Definition appears out of sync with current compliance source data.
This JSON still carries pre-update values for multiple SO rows (for example, Line 144 and Lines 487-499), which diverge from
security/compliance_data.pyand whatsecurity/compliance.pynow emits. That breaks the source-of-truth contract for machine-verifiable compliance artifacts.Suggested fix
Regenerate the artifact from the current Python source-of-truth and commit the result:
python -m security.compliance \ --component security/dfetch.component-definition.json \ --version 0.15.0Also applies to: 483-514
🤖 Prompt for 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. In `@security/dfetch.component-definition.json` around lines 133 - 171, The security/dfetch.component-definition.json file contains outdated values that are out of sync with the current Python source-of-truth in security/compliance_data.py and security/compliance.py. To fix this, regenerate the component definition JSON artifact from the Python source by running the compliance generation command with the correct parameters pointing to the component file and specifying the appropriate version number, which will ensure the JSON reflects the current compliance data definitions and maintains the source-of-truth contract.doc/explanation/security_pipeline.rst (1)
41-53:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winSecurity pipeline docs still describe the old manual control-register flow.
The page says
control_registeris manually maintained and attributes all 46 controls tocompliance_data.py, but the current flow is auto-generated viapython -m security.compliance --control-registerwith Track A controls sourced fromsecurity/tm_controls_data.py.Suggested fix
-:doc:`control_register` page is maintained manually and references controls -defined in ``compliance_data.py``. +:doc:`control_register` is auto-generated via +``python -m security.compliance --control-register``. Track A controls are +defined in ``security/tm_controls_data.py`` and Track B controls in +``security/compliance_data.py``. - * - :doc:`control_register` - - RST (maintained) + * - :doc:`control_register` + - RST (generated)Also applies to: 94-96
🤖 Prompt for 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. In `@doc/explanation/security_pipeline.rst` around lines 41 - 53, Update the security_pipeline.rst documentation to accurately reflect the current auto-generated control register flow. Replace the statement that says the control_register page is "maintained manually" with information describing how it is auto-generated using the command python -m security.compliance --control-register. Update the documentation to indicate that Track A controls are sourced from security/tm_controls_data.py in addition to or instead of the existing reference to compliance_data.py. Apply similar updates to other sections of the document that reference this manual flow, particularly around lines 94-96 as indicated in the comment.
🤖 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/explanation/compliance_track.rst`:
- Around line 173-176: The compliance table shows SO.Updateability and the
objectives at lines 183-186 as implemented with checkmarks but display `—` in
the dfetch controls column, while the implementation details at lines 330-333
specify the actual controls and functionality used. Update the dfetch controls
column entries at lines 173-176 and 183-186 to replace the `—` characters with
the specific controls referenced in the corresponding implementation notes at
lines 330-333 to restore consistency and traceability throughout the document.
In `@doc/explanation/control_register.rst`:
- Line 73: The links in the RST file on lines 73, 85, 91, and 97 contain glob
patterns (*.yml) in the GitHub URL paths, which breaks navigation. Replace each
of these broken links by removing the glob pattern from the URL and updating the
reference to point to the directory path instead. For example, change
`.github/workflows/*.yml
<https://github.com/dfetch-org/dfetch/tree/main/.github/workflows/*.yml>` to
reference the directory without the glob pattern, so the URL points to a valid
navigable GitHub tree path.
In `@security/compliance.py`:
- Around line 68-70: The `track_b_only` parameter in the
`_load_track_a_controls()` function is being ignored, causing the function to
always return Track A controls regardless of the parameter value. Modify the
function to check the `track_b_only` parameter and conditionally return either
Track B controls or Track A controls based on its value, ensuring that when
`track_b_only=True` only Track B controls are returned and when False the
standard Track A controls (SC_CONTROLS and USAGE_CONTROLS) are returned.
---
Outside diff comments:
In `@doc/explanation/security_pipeline.rst`:
- Around line 41-53: Update the security_pipeline.rst documentation to
accurately reflect the current auto-generated control register flow. Replace the
statement that says the control_register page is "maintained manually" with
information describing how it is auto-generated using the command python -m
security.compliance --control-register. Update the documentation to indicate
that Track A controls are sourced from security/tm_controls_data.py in addition
to or instead of the existing reference to compliance_data.py. Apply similar
updates to other sections of the document that reference this manual flow,
particularly around lines 94-96 as indicated in the comment.
In `@security/dfetch.component-definition.json`:
- Around line 133-171: The security/dfetch.component-definition.json file
contains outdated values that are out of sync with the current Python
source-of-truth in security/compliance_data.py and security/compliance.py. To
fix this, regenerate the component definition JSON artifact from the Python
source by running the compliance generation command with the correct parameters
pointing to the component file and specifying the appropriate version number,
which will ensure the JSON reflects the current compliance data definitions and
maintains the source-of-truth contract.
🪄 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: 71f9786b-c54b-43c3-85e6-22a9582628f1
📒 Files selected for processing (12)
CHANGELOG.rstdoc/explanation/compliance_track.rstdoc/explanation/control_register.rstdoc/explanation/security_pipeline.rstsecurity/compliance.pysecurity/compliance_data.pysecurity/cra_pren_4000014_oscal_catalog.jsonsecurity/dfetch.component-definition.jsonsecurity/tm_controls_data.pysecurity/tm_elements.pysecurity/tm_supply_chain.pysecurity/tm_usage.py
* security/compliance_data.py: add C-010, C-039, C-043 to SO.Updateability
controls list — the note already cited these controls but the controls column
showed — causing an inconsistency between the table and the implementation note
* security/compliance.py:
- _format_single_ref: strip glob pattern from GitHub tree URL so *.yml
references link to the directory (valid URL) not the glob path (broken URL)
- _load_track_a_controls: honour track_b_only=True by returning [] instead
of ignoring the parameter (previously silenced a warning; now actually omits
Track A from the merged register when the flag is set)
* doc/explanation/security_pipeline.rst: update two stale descriptions
- control_register entry: RST (maintained) → RST (generated)
- compliance pipeline paragraph: reflect that controls now live in
tm_controls_data.py and that control_register is also auto-generated
* Regenerate all three derived artifacts from updated source:
doc/explanation/compliance_track.rst, doc/explanation/control_register.rst,
security/dfetch.component-definition.json (version 0.15.0)
Skipped: SO.UserUpdateNotification controls column remains — because the
implementation note references only code paths (github_version_check.py),
not any formal C-xxx control.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01342LwMTGpgbJXEDptAEF5z
|
@coderabbitai review |
✅ Action performedReview finished.
|
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (5)
security/compliance_data.py (2)
25-38:⚠️ Potential issue | 🟠 Major | ⚡ Quick win
SOImplementationnow fails pylint’s instance-attribute limit.This dataclass now has 9 fields, and CI is failing with
R0902 (too-many-instance-attributes). Add a targeted suppression for this DTO (or adjust lint config for dataclasses) to unblock the pipeline.Suggested minimal fix
-@dataclass +@dataclass # pylint: disable=too-many-instance-attributes class SOImplementation:🤖 Prompt for 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. In `@security/compliance_data.py` around lines 25 - 38, The SOImplementation dataclass is triggering pylint's R0902 error due to having 9 instance attributes. Add a pylint disable comment (# pylint: disable=too-many-instance-attributes or # pylint: disable=R0902) on the line immediately before the SOImplementation class definition to suppress this specific violation for this DTO.Source: Pipeline failures
79-85:⚠️ Potential issue | 🟠 Major | ⚡ Quick winWrap overlong literals to satisfy the enforced line-length gate.
CI is failing on
C0301in this file. Reflow the flagged string literals so each physical line stays within 120 chars.Example pattern to apply
- reference="Cyber Resilience Principles and Secure Development Lifecycle (working title; subject to change on publication)", + reference=( + "Cyber Resilience Principles and Secure Development Lifecycle " + "(working title; subject to change on publication)" + ),Also applies to: 93-97, 104-107, 254-255
🤖 Prompt for 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. In `@security/compliance_data.py` around lines 79 - 85, The CI linting gate is failing on line-length violations (C0301) in compliance_data.py. Refactor all overlong string literals in the file to ensure each physical line does not exceed 120 characters. This includes the scope_note parameter starting at line 79 and continuing through line 85, as well as the additional locations mentioned at lines 93-97, 104-107, and 254-255. Use implicit string concatenation or explicit line breaks to split long strings across multiple lines while maintaining readability and proper indentation.Source: Pipeline failures
doc/explanation/security_pipeline.rst (1)
4-5:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winSection title collides with autosectionlabel in another page.
Docs pipeline warns about duplicate label for this heading. Rename the heading (or adjust autosectionlabel strategy) to avoid collisions.
🤖 Prompt for 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. In `@doc/explanation/security_pipeline.rst` around lines 4 - 5, The section heading "Security Documentation Pipeline" is generating a duplicate autosectionlabel that conflicts with another page in the documentation. Rename the heading to a unique title that doesn't collide with existing autosectionlabels in other documentation pages, ensuring the new heading is descriptive and specific to this page's content.Source: Pipeline failures
security/compliance.py (2)
758-759:⚠️ Potential issue | 🟠 Major | ⚡ Quick winRemove or consume
track_b_onlyinrender_rstto fix W0613.
render_rst()currently acceptstrack_b_onlybut never uses it, and CI fails onunused-argument.Suggested minimal fix
-def render_rst(track_b_only: bool = False) -> None: +def render_rst() -> None: @@ - if args.rst: - render_rst(track_b_only=args.track_b_only) + if args.rst: + render_rst()Also applies to: 911-913
🤖 Prompt for 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. In `@security/compliance.py` around lines 758 - 759, The function render_rst has an unused parameter track_b_only that is never referenced in the function body, causing a W0613 unused-argument warning. Remove the track_b_only parameter from the function signature of render_rst (including the default value assignment) since it serves no purpose. Check the other locations mentioned in the comment (around lines 911-913) for the same issue and apply the same fix there as well.Source: Pipeline failures
483-486:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winEscape standalone
*in table row cells to avoid docutils parsing warnings.Headers are escaped, but row values are not. This leaks tokens like
GEC-*into RST and triggers inline-emphasis warnings in generated docs.Suggested fix
- for row in rows: - lines.append(" * - " + "\n - ".join(str(c) for c in row)) + for row in rows: + lines.append( + " * - " + "\n - ".join(_rst_escape_star(str(c)) for c in row) + )🤖 Prompt for 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. In `@security/compliance.py` around lines 483 - 486, Table row cells are not being escaped for RST special characters while headers are, causing parsing warnings for tokens like GEC-*. In the loop that appends rows to lines (where you process each row with str(c) for c in row), apply the _rst_escape_star() function to each cell value, matching the approach used for headers in the line above it.Source: Pipeline failures
🤖 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/explanation/security_pipeline.rst`:
- Around line 95-96: The documentation in security_pipeline.rst claims that the
control_register.rst includes a "status" column, but the actual
control_register.rst file only exposes ID, Name, Type, and Reference columns.
Remove the mention of "status" from the line "All dfetch controls with type,
references, and status" to accurately reflect what columns are actually present
in control_register.rst. Update the text to only list the columns that actually
exist in the control register.
---
Outside diff comments:
In `@doc/explanation/security_pipeline.rst`:
- Around line 4-5: The section heading "Security Documentation Pipeline" is
generating a duplicate autosectionlabel that conflicts with another page in the
documentation. Rename the heading to a unique title that doesn't collide with
existing autosectionlabels in other documentation pages, ensuring the new
heading is descriptive and specific to this page's content.
In `@security/compliance_data.py`:
- Around line 25-38: The SOImplementation dataclass is triggering pylint's R0902
error due to having 9 instance attributes. Add a pylint disable comment (#
pylint: disable=too-many-instance-attributes or # pylint: disable=R0902) on the
line immediately before the SOImplementation class definition to suppress this
specific violation for this DTO.
- Around line 79-85: The CI linting gate is failing on line-length violations
(C0301) in compliance_data.py. Refactor all overlong string literals in the file
to ensure each physical line does not exceed 120 characters. This includes the
scope_note parameter starting at line 79 and continuing through line 85, as well
as the additional locations mentioned at lines 93-97, 104-107, and 254-255. Use
implicit string concatenation or explicit line breaks to split long strings
across multiple lines while maintaining readability and proper indentation.
In `@security/compliance.py`:
- Around line 758-759: The function render_rst has an unused parameter
track_b_only that is never referenced in the function body, causing a W0613
unused-argument warning. Remove the track_b_only parameter from the function
signature of render_rst (including the default value assignment) since it serves
no purpose. Check the other locations mentioned in the comment (around lines
911-913) for the same issue and apply the same fix there as well.
- Around line 483-486: Table row cells are not being escaped for RST special
characters while headers are, causing parsing warnings for tokens like GEC-*. In
the loop that appends rows to lines (where you process each row with str(c) for
c in row), apply the _rst_escape_star() function to each cell value, matching
the approach used for headers in the line above it.
🪄 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: a1b9e36b-b272-4520-869c-14d10367df6c
📒 Files selected for processing (6)
doc/explanation/compliance_track.rstdoc/explanation/control_register.rstdoc/explanation/security_pipeline.rstsecurity/compliance.pysecurity/compliance_data.pysecurity/dfetch.component-definition.json
| - RST (generated) | ||
| - All dfetch controls with type, references, and status |
There was a problem hiding this comment.
Control-register description says “status”, but that column is not present.
control_register.rst currently exposes ID, Name, Type, and Reference only. This row should not claim status is included.
Suggested wording
- - All dfetch controls with type, references, and status
+ - All dfetch controls with type and references📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - RST (generated) | |
| - All dfetch controls with type, references, and status | |
| - RST (generated) | |
| - All dfetch controls with type and references |
🤖 Prompt for 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.
In `@doc/explanation/security_pipeline.rst` around lines 95 - 96, The
documentation in security_pipeline.rst claims that the control_register.rst
includes a "status" column, but the actual control_register.rst file only
exposes ID, Name, Type, and Reference columns. Remove the mention of "status"
from the line "All dfetch controls with type, references, and status" to
accurately reflect what columns are actually present in control_register.rst.
Update the text to only list the columns that actually exist in the control
register.
|
@coderabbitai review |
✅ Action performedReview finished.
|
Both the prEN 40000-1-4 catalog and the Component Definition are upgraded
from OSCAL 1.1.2 to 1.2.2 and significantly enriched:
Catalog (cra_pren_4000014_oscal_catalog.json):
B.V. (original content author, STAN4CR grant)
Component Definition (dfetch.component-definition.json, generated by compliance.py):
(rel="evidence") pointing to the concrete code or CI workflow file that
implements each control — making the compliance mapping machine-verifiable
workflow, SLSA Source Provenance workflow, Sigstore attestation workflow,
in-toto test-results workflow, CodeQL workflow, dependency-review workflow,
GitHub Releases, and verify-integrity how-to doc
compliance_data.py:
compliance.py:
Documentation updated in compliance_track.rst and security_pipeline.rst.
Changelog entry added to 0.15.0 (unreleased).
Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01342LwMTGpgbJXEDptAEF5z
Summary by CodeRabbit
New Features
Documentation
Refactor