-
-
Notifications
You must be signed in to change notification settings - Fork 44
Adding new cdx sub namespaces: fda and cisa #186
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
jorlando-elucid
wants to merge
28
commits into
CycloneDX:main
Choose a base branch
from
jorlando-elucid:patch-1
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 9 commits
Commits
Show all changes
28 commits
Select commit
Hold shift + click to select a range
ca0681c
Add CISA and FDA namespaces to cdx.md
jorlando-elucid 8443446
Document `cdx:fda` namespace for FDA cybersecurity
jorlando-elucid 0062621
Add cdx:cisa namespace taxonomy documentation
jorlando-elucid ea342b6
Add source code custody and risk transfer fields
jorlando-elucid 8a140e8
Add new CISA fields to SBOM specification
jorlando-elucid 3371bfe
Correct U.S. spelling in FDA namespace description
jorlando-elucid 1fc8203
Add newline at end of cisa.md
jorlando-elucid d2e6002
Update cisa.md
jorlando-elucid 5e2ee91
Revise cdx:cisa namespace documentation
jorlando-elucid 66ae2d7
Revise cdx:fda namespace documentation
jorlando-elucid 4b404ad
Refactor cdx:fda namespace taxonomy documentation
jorlando-elucid 6491d4a
Refactor cdx:cisa documentation for clarity
jorlando-elucid aa8467c
Fix formatting issues in cdx:cisa.md
jorlando-elucid be2f53c
Fix formatting issues in cdx:fda documentation
jorlando-elucid 72f2cbc
Update fda.md
jorlando-elucid 1b94795
Enhance cdx:cisa documentation with links and clarifications
jorlando-elucid d8e58d5
Refine CISA and FDA namespace descriptions
jorlando-elucid 8b7175b
Rename redacted-information-inquiry to withheld-information-inquiry
jorlando-elucid 6577d31
Update fda.md
jorlando-elucid a4a5646
Clarify CISA namespace description to 2026 elements
jorlando-elucid f635443
Enhance CISA documentation with guidance mapping
jorlando-elucid ca56a51
Update fda.md
jorlando-elucid eb8a3a9
Update cdx/cisa.md
jorlando-elucid 5f472d3
Update cdx/cisa.md
jorlando-elucid 738f076
Update cdx/fda.md
jorlando-elucid 61b82e1
Enhance CISA property descriptions with HTML formatting
jorlando-elucid f188656
Enhance property descriptions with HTML formatting
jorlando-elucid 21026a3
Clarify support assessed date description
jorlando-elucid File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,69 @@ | ||
| # cdx:cisa Namespace Taxonomy | ||
|
|
||
| This is the namespace for official CycloneDX properties carrying SBOM information defined in the 2026 Minimum Elements for a Software Bill of Materials (SBOM), published July 29, 2026 by CISA and co- | ||
| authoring organizations (referred to below as "the 2026 Minimum Elements"), which replaces the 2021 NTIA minimum elements. Only information without a complete native CycloneDX representation is | ||
| defined here. | ||
|
|
||
| The official rules and processes apply - see ../cdx.md. | ||
|
|
||
| Where a property value names a data field, the value MUST be the data field name exactly as listed in Appendix A of the 2026 Minimum Elements (for example, Component Version, Component Producer, or | ||
| Component Hash Value). Properties are repeatable unless stated otherwise. The key words MUST, SHOULD, and MAY are to be interpreted as described in RFC 2119. | ||
|
|
||
| When a required data field is unknown, its native CycloneDX representation SHOULD also be populated when the native field supports an unknown value. For example, use the literal unknown for | ||
| components[].version and components[].manufacturer.name, and use compositions to describe unknown or incomplete dependency relationships. The cdx:cisa:unknown-information property is still required | ||
| in these cases because it explicitly identifies which required information is unknown to the SBOM author. | ||
|
|
||
| ——— | ||
|
|
||
| Property Description | ||
| ━━━━━━━━━━━━━━━━━━ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ | ||
| cdx:cisa:unknown Explicitly identifies a required data field whose information is unknown to the SBOM author, as specified by Explicitly Identifying Unknown Information. The value MUST be the | ||
| -information applicable Appendix A data field name. One property instance MUST be provided for each unknown data field, including when a native field contains unknown or another native | ||
| mechanism also describes the missing information. Use metadata.properties for SBOM Metadata fields and the applicable components[].properties for Component Data fields. | ||
| ────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── | ||
| cdx:cisa:withhel Explicitly identifies a required data field whose information the SBOM author is intentionally withholding from the SBOM, as specified by Explicitly Identifying Unknown | ||
| d-information Information. The value MUST be the applicable Appendix A data field name. One property instance MUST be provided for each withheld data field. Use metadata.properties for SBOM | ||
| Metadata fields and the applicable components[].properties for Component Data fields. | ||
| ────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── | ||
| cdx:cisa:withhel Describes how a recipient may request withheld, redacted, security-related information. The value is free text and MAY contain a URL, email address, or document reference for | ||
| d-information- the inquiry process. This document-level property MUST be placed in metadata.properties and MAY appear only once. | ||
| inquiry | ||
| ────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── | ||
| cdx:cisa:alterna An alternate name for a component in addition to its native name. Data formats implementing Component Name are expected to allow multiple entries for alternate names. The value | ||
| te-name is one alternate name. One property instance MUST be provided for each alternate name. Component-level. | ||
| ────────────────── ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── | ||
| cdx:cisa:compone A UUID or organization-specific component identifier for which no more specific native CycloneDX identifier field is appropriate. Native fields such as purl, cpe, swid, | ||
| nt-identifier omniborId, and swhid SHOULD be used when applicable. The value is free text and SHOULD identify its scheme, for example uuid:3e671687-395b-41f5-a30f-a58921a69b79 or acme- | ||
| part:12345. One property instance MUST be provided for each additional identifier. Component-level. | ||
|
|
||
| ## Example | ||
|
|
||
| { | ||
| "metadata": { | ||
| "properties": [ | ||
| { | ||
| "name": "cdx:cisa:withheld-information-inquiry", | ||
| "value": "Email product-security@example.com" | ||
| } | ||
| ] | ||
| }, | ||
| "components": [ | ||
| { | ||
| "type": "library", | ||
| "name": "vendored-parser", | ||
| "version": "unknown", | ||
| "manufacturer": { "name": "unknown" }, | ||
| "properties": [ | ||
| { "name": "cdx:cisa:unknown-information", "value": "Component Version" }, | ||
| { "name": "cdx:cisa:unknown-information", "value": "Component Producer" }, | ||
| { "name": "cdx:cisa:unknown-information", "value": "Component Hash Value" }, | ||
| { "name": "cdx:cisa:alternate-name", "value": "legacy-parse-lib" }, | ||
| { "name": "cdx:cisa:alternate-name", "value": "parselib-ng" }, | ||
| { | ||
| "name": "cdx:cisa:component-identifier", | ||
| "value": "uuid:3e671687-395b-41f5-a30f-a58921a69b79" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| # `cdx:fda` Namespace Taxonomy | ||
|
|
||
| This is the namespace for official CycloneDX properties carrying SBOM data fields required by U.S. FDA premarket cybersecurity guidance for medical devices: *Cybersecurity in Medical Devices: Quality Management System Considerations and Content of Premarket Submissions*, final guidance, February 3, 2026 (referred to below as "the guidance"). | ||
|
|
||
| The official rules and processes apply - see [parent document](../cdx.md). | ||
|
|
||
| Each property description quotes the sentence in the guidance that requires the field, with its section number, so the property is traceable to source. The guidance permits these elements to be provided "as part of the SBOM, or they may provide it separately, such as in an addendum" (§V.A.4(b)); this namespace is the in-SBOM carrier, and any separately submitted addendum SHOULD be generated from these property values so the two cannot diverge. | ||
|
|
||
| Conventions: dates are ISO 8601 (RFC 3339 profile). Component-level properties attach to `components[].properties` or `metadata.component.properties`. Vulnerability-level properties attach to `vulnerabilities[].properties`. Properties are repeatable unless stated otherwise. The key words MUST, SHOULD, and MAY are to be interpreted as described in RFC 2119. | ||
|
|
||
| ---- | ||
|
|
||
| ## Component-level properties | ||
|
|
||
| | Property | Description | | ||
| |----------|-------------| | ||
| | `cdx:fda:level-of-support` | "The software level of support provided through monitoring and maintenance from the software component manufacturer" (guidance §V.A.4(b)). Values follow the guidance's enumeration: `actively-maintained`, `no-longer-maintained`, `abandoned`. The guidance's list is illustrative ("e.g."); additional values MAY be used where these three do not describe the arrangement (for example `extended-support-contract`), and any additional value SHOULD be defined in accompanying documentation. | | ||
| | `cdx:fda:end-of-support-date` | "The software component's end-of-support date" (guidance §V.A.4(b)). ISO 8601 date. If the date is unknown, this property MUST be omitted and `cdx:fda:justification` emitted instead of a placeholder value. Where `cdx:lifecycle:milestone:endOfSupport` is also present on the same component, the two values MUST be identical; this property exists so the FDA element is explicitly identifiable, not to carry a second value. | | ||
| | `cdx:fda:end-of-life-date` | Component end-of-life date, from the guidance's labeling recommendation to provide "information, if known or anticipated, concerning device cybersecurity (including components) end of support and end of life" (§VI.A). ISO 8601 date. Where `cdx:lifecycle:milestone:endOfLife` is also present on the same component, the two values MUST be identical. | | ||
| | `cdx:fda:end-of-support-plan` | Reference to the plan "for how third-party software components could be updated or replaced if support ends or other software issues arise" (guidance §V.A.4). Value: a quality-system controlled-document identifier or URL. When the value is a URL, the same URL SHOULD also appear in `externalReferences` with type `support` on the component. | | ||
| | `cdx:fda:justification` | "A justification for why the information cannot be included in the premarket submission" (guidance §V.A.4(b)), applied at component granularity. The value MUST identify which element is missing and why, e.g. `end-of-support-date: upstream project publishes no lifecycle policy; support status inferred from release cadence per documented procedure`. | | ||
| | `cdx:fda:support-assessed-date` | ISO 8601 date on which the `cdx:fda:level-of-support` and end-of-support determinations were made. Not a guidance-defined field: SBOM documents are immutable while support status changes over time, and this property anchors the claim to its evidence window for total product lifecycle review. | | ||
|
jorlando-elucid marked this conversation as resolved.
Outdated
|
||
| | `cdx:fda:source-code-custody` | The custodial-control arrangement for this component's source code, per the guidance's expectation that manufacturers "establish and maintain custodial control of device source code" through methods "such as source code escrow or source code backups" (§V.A.4), extended to purchased software via purchasing controls acquiring source "should the purchased software reach end of support" (§V.A.4, fn. 36). Recommended values: `first-party`, `escrow`, `backup`, `licensor-held`, optionally followed by a reference to the arrangement. | | ||
| | `cdx:fda:risk-transfer-process` | Reference to the "pre-established and pre-communicated process for transferring the risks" where the device remains in service following end of support (guidance §VI.A). Value: controlled-document identifier or URL. Attaches to the component the transfer concerns, or to `metadata.component` for the device as a whole. | | ||
| | `cdx:fda:traceability-ref` | Reference linking this component to its record in the documentation providing "traceability between the threat model, cybersecurity risk assessment, SBOM, and testing documentation" (guidance §V.A). Value: identifier of the corresponding traceability matrix row or record. | | ||
|
|
||
| ## Vulnerability-level properties | ||
|
|
||
| The guidance requires identification of "all known vulnerabilities associated with the device and the software components, including those identified in CISA's Known Exploited Vulnerabilities Catalog" (§V.A.4(b)). Known vulnerabilities themselves are carried natively in `vulnerabilities[]`, or in a separate CycloneDX VDR/VEX document referencing the SBOM. The properties below carry the guidance's per-vulnerability documentation requirements, which have no native field. | ||
|
|
||
| | Property | Description | | ||
| |----------|-------------| | ||
| | `cdx:fda:vulnerability-discovery` | Description of "how the vulnerabilities were discovered to demonstrate whether the assessment methods were sufficiently robust" (guidance §V.A.4(b)). Value: the discovery method and tooling, e.g. `software composition analysis against per-image SBOM`, `fuzz testing`, `penetration test`, `coordinated disclosure`. | | ||
| | `cdx:fda:safety-and-security-risk-assessment` | Reference to "a safety and security risk assessment of each known vulnerability (including device and system impacts)" (guidance §V.A.4(b)). Value: the controlled-document identifier of the risk record in the manufacturer's security risk management report and, where patient harm is in scope, the ISO 14971 risk file. A one-sentence summary MAY follow the identifier. | | ||
| | `cdx:fda:risk-controls` | Reference to or description of the "details of applicable safety and security risk controls to address the vulnerability" (guidance §V.A.4(b)). Where the controls are compensating controls, the value MUST identify them as such, as the guidance requires those to "be described in an appropriate level of detail." | | ||
| | `cdx:fda:kev-listed` | Whether the vulnerability is "identified in CISA's Known Exploited Vulnerabilities Catalog" (guidance §V.A.4(b)). Values: `true`, `false`. The date of the KEV check is conveyed by the `updated` timestamp of the enclosing vulnerability object. | | ||
|
jorlando-elucid marked this conversation as resolved.
Outdated
|
||
|
|
||
| ## Example | ||
|
|
||
| ```json | ||
| { | ||
| "components": [ | ||
| { | ||
| "type": "library", | ||
| "bom-ref": "pkg:generic/dcmtk@3.6.9", | ||
| "name": "dcmtk", | ||
| "version": "3.6.9", | ||
| "properties": [ | ||
| { "name": "cdx:fda:level-of-support", "value": "actively-maintained" }, | ||
| { "name": "cdx:fda:end-of-support-date", "value": "2028-12-31" }, | ||
| { "name": "cdx:lifecycle:milestone:endOfSupport", "value": "2028-12-31" }, | ||
| { "name": "cdx:fda:support-assessed-date", "value": "2026-08-06" }, | ||
| { "name": "cdx:fda:end-of-support-plan", "value": "QMS-PLN-0142" } | ||
| ] | ||
| } | ||
| ], | ||
| "vulnerabilities": [ | ||
| { | ||
| "id": "CVE-2026-00000", | ||
| "affects": [{ "ref": "pkg:generic/dcmtk@3.6.9" }], | ||
| "analysis": { "state": "resolved", "response": ["update"] }, | ||
| "properties": [ | ||
| { "name": "cdx:fda:vulnerability-discovery", "value": "software composition analysis against per-image SBOM" }, | ||
| { "name": "cdx:fda:safety-and-security-risk-assessment", "value": "QMS-RSK-0311" }, | ||
| { "name": "cdx:fda:risk-controls", "value": "Upgraded to 3.6.10 in release 2026.3; see QMS-RSK-0311" }, | ||
| { "name": "cdx:fda:kev-listed", "value": "false" } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
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.
Uh oh!
There was an error while loading. Please reload this page.