Skip to content

Richer SBOM/HBOM/VEX linkage via a typed linkedArtifacts[] traceability layer #52

Description

@JohnASRG

Motivation

REQUIREMENTS.md requires linkage to SBOM and HBOM data for supply-chain traceability, but the current schema offers only a single top-level bomRefRef string plus a few hashes. A vehicle/system TARA realistically needs references to SBOM, HBOM, SaaSBOM, VEX, VDR, test reports, architecture models, and CSMS evidence — and each link must be component-scoped, version-scoped, and identify the supplier. This is the foundation for CRA, R155, and ISO 21434 distributed-cybersecurity workflows.

Note: this is complementary to #44 (VEX/CSAF reachability) — that issue adds VEX statements and reachability semantics; this issue adds the generic typed-link substrate that VEX statements (and many other artifact types) can sit on.

Proposed change

  1. New top-level linkedArtifacts[] in riskSet (JSON + XSD). Each entry:
    { id, type, format, uri, bomLink, hashes[], supplier, version, versionRange,
      componentRefs[], notes }
    
    type enum: sbom | hbom | saasbom | vex | vdr | testReport | securityCase | csmsEvidence | vulnerabilityAdvisory | architectureModel | regulatoryEvidence | cdxAttestation.
  2. BOM-Link semantics: accept full CycloneDX BOM-Link URNs in bomLink and in componentRefs[].bomRef so cross-document refs are deterministic.
  3. Per-component linkage: component.linkedArtifactRefs[] and control.linkedArtifactRefs[] so risks/controls can attach to specific BOM components, not just the whole document.
  4. Supplier / manufacturer identity: linkedArtifact.supplier and component.supplier with optional cscrmIdentifier (DUNS, GLEIF LEI, internal supplier id).
  5. Version applicability: versionRange supports SemVer ranges, NVD configuration-style match expressions, or a free applicabilityExpression.
  6. Examples: a new examples/rdx-linked-artifacts-example.json showing SBOM + HBOM + VEX + test report + architecture model all linked from one RDX document, with component-scoped refs.

References

  • REQUIREMENTS.md — SBOM/HBOM linkage requirement
  • AI peer review, section 5 ("SBOM/HBOM linkage is not yet rich enough")
  • CycloneDX BOM-Link spec: https://cyclonedx.org/capabilities/bomlink/
  • Related: #44 (VEX/CSAF + reachability)

Acceptance criteria

  • linkedArtifacts[] added in JSON Schema and XSD with the type enum above
  • Component- and control-level link arrays added
  • bomLink accepts and validates CycloneDX BOM-Link URNs
  • New end-to-end example validates and demonstrates SBOM + HBOM + VEX + test report linkage
  • Backwards compatible: existing bomRefRef continues to validate; methodology docs mark it secondary to linkedArtifacts[]

Surfaced by external AI peer review; see chat transcript for full review text.

Metadata

Metadata

Assignees

No one assigned

    Labels

    ai-proposalProposed by the AI idea scout; needs human reviewenhancementNew feature or requestpeer-reviewSurfaced by external AI/peer review of the repopriority/P1High priority — V1.0 foundation

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions