Upgrade OSCAL artifacts to 1.2.2 and enrich with security-as-code data (#1284)

* Upgrade OSCAL artifacts to 1.2.2 and enrich with security-as-code data

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

* Auto-generate compliance_track.rst and control_register.rst from Python 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

* refactor: move control register to pytm-free tm_controls_data module

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

* fix: address review findings in compliance tooling and docs

* 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

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: spoorcc

CHANGELOG.rst

@@ -3,10 +3,19 @@ Release 0.15.0 (unreleased)
 
 * Implement C-043: add ``pip-audit`` OSV gate to the release workflow; publishing is blocked if
   any known vulnerability is found in dfetch's runtime dependencies
-* Add CRA Compliance Track B: OSCAL 1.1.2 Component Definition mapping all CRA Annex I Part I
+* Add CRA Compliance Track B: OSCAL 1.2.2 Component Definition mapping all CRA Annex I Part I
   essential requirements (ECR-a–m) through prEN 40000-1-4 Security Objectives to dfetch controls;
   covers Part II via prEN 40000-1-3; introduces controls C-043 (release-gate CVE check), C-044
   (data minimisation policy), and C-046 (exploit mitigation inventory)
+* Upgrade OSCAL artifacts to 1.2.2: both the prEN 40000-1-4 catalog and the Component Definition
+  now declare ``oscal-version: 1.2.2``; the catalog gains ``parties``, ``roles``, and
+  ``responsible-parties`` in its metadata; the Component Definition adds a ``purpose`` field on
+  the component, a ``supplier`` party, ``document-ids`` for stable cross-referencing,
+  ``responsible-roles``, and ``evidence`` links on every implemented-requirement pointing to the
+  concrete code or CI workflow file that implements the control — turning the compliance mapping
+  into a machine-verifiable security-as-code artifact; the back-matter is enriched with references
+  to the OpenSSF Scorecard, SLSA Source Provenance, Sigstore attestation, in-toto test results,
+  CodeQL, and dependency-review workflows
 
 Release 0.14.0 (released 2026-06-14)
 ====================================

doc/explanation/compliance_track.rst

@@ -1,11 +1,12 @@
+.. This file is auto-generated by ``python -m security.compliance --control-register``.
+   Do not edit manually — edit security/compliance_data.py or the threat model files instead.
+
 .. _control_register:
 
 Control Register
 ================
 
-All controls implemented by dfetch, sorted by ID. Risk-driven controls emerge
-from the :doc:`threat models <security>`; compliance-only controls address CRA
-requirements not independently surfaced by the risk analysis.
+All controls implemented by dfetch, sorted by ID. Risk-driven controls emerge from the :doc:`threat models <security>`; compliance-only controls address CRA requirements not independently surfaced by the risk analysis.
 
 .. list-table::
    :header-rows: 1
@@ -69,7 +70,7 @@ requirements not independently surfaced by the risk analysis.
        C-009
      - Actions commit-SHA pinning
      - Risk-driven
-     - `.github/workflows/ <https://github.com/dfetch-org/dfetch/tree/main/.github/workflows>`_
+     - `.github/workflows/*.yml <https://github.com/dfetch-org/dfetch/tree/main/.github/workflows>`_
    * - .. _c-010:
 
        C-010
@@ -81,19 +82,19 @@ requirements not independently surfaced by the risk analysis.
        C-011
      - Minimal workflow permissions
      - Risk-driven
-     - `.github/workflows/ <https://github.com/dfetch-org/dfetch/tree/main/.github/workflows>`_
+     - `.github/workflows/*.yml <https://github.com/dfetch-org/dfetch/tree/main/.github/workflows>`_
    * - .. _c-012:
 
        C-012
      - persist-credentials: false
      - Risk-driven
-     - `.github/workflows/ <https://github.com/dfetch-org/dfetch/tree/main/.github/workflows>`_
+     - `.github/workflows/*.yml <https://github.com/dfetch-org/dfetch/tree/main/.github/workflows>`_
    * - .. _c-013:
 
        C-013
      - Harden-runner (egress block)
      - Risk-driven
-     - `.github/workflows/ <https://github.com/dfetch-org/dfetch/tree/main/.github/workflows>`_
+     - `.github/workflows/*.yml <https://github.com/dfetch-org/dfetch/tree/main/.github/workflows>`_
    * - .. _c-015:
 
        C-015
@@ -221,3 +222,4 @@ requirements not independently surfaced by the risk analysis.
      - Exploit mitigation inventory
      - Compliance-only
      - :doc:`compliance_track`
+

doc/explanation/control_register.rst

@@ -38,17 +38,19 @@ to produce the two RST threat-model pages (:doc:`threat_model_supply_chain` and
 sequence diagram, and tables for assets, threats, and controls.
 
 **Compliance pipeline** —
-`security/compliance_data.py <https://github.com/dfetch-org/dfetch/blob/main/security/compliance_data.py>`_
-defines the 46 dfetch controls and their mapping to CRA essential requirements
+`security/tm_controls_data.py <https://github.com/dfetch-org/dfetch/blob/main/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 <https://github.com/dfetch-org/dfetch/blob/main/security/compliance.py>`_
 reads those definitions together with the static OSCAL catalog and generates
-:doc:`compliance_track` (human-readable RST mapping tables) and
+:doc:`compliance_track` (human-readable RST mapping tables),
+:doc:`control_register` (the full control register with GitHub references), and
 `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
-(machine-readable OSCAL 1.1.2 Component Definition; 1.1.2 is the pinned version —
-NIST released 1.2.2 in April 2026, migration not yet performed). The
-:doc:`control_register` page is maintained manually and references controls
-defined in ``compliance_data.py``.
+(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
@@ -90,16 +92,17 @@ of their choice:
      - CRA Annex I → prEN 40000-1-4 SO.* → dfetch control traceability tables
 
    * - :doc:`control_register`
-     - RST (maintained)
-     - All 46 dfetch controls (C-001 to C-046) with references and status
+     - RST (generated)
+     - All dfetch controls with type, references, and status
 
    * - `security/dfetch.component-definition.json <https://github.com/dfetch-org/dfetch/blob/main/security/dfetch.component-definition.json>`_
-     - OSCAL 1.1.2 JSON (pinned)
-     - Machine-readable Component Definition; maps dfetch controls to CRA ECRs
+     - 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
 
    * - `security/cra_pren_4000014_oscal_catalog.json <https://github.com/dfetch-org/dfetch/blob/main/security/cra_pren_4000014_oscal_catalog.json>`_
-     - OSCAL 1.1.2 JSON (pinned)
-     - Static prEN 40000-1-4 catalog (input to compliance pipeline, not generated)
+     - OSCAL 1.2.2 JSON (static)
+     - Static prEN 40000-1-4 catalog; includes parties, roles, and responsible-parties
 
    * - :ref:`Release attestations <verify-integrity>`
      - Sigstore-signed (GitHub Actions)