diff --git a/cdx.md b/cdx.md index ec834d2..177a5bc 100644 --- a/cdx.md +++ b/cdx.md @@ -16,9 +16,11 @@ _Boolean value_ are `true` or `false`; case sensitive. | Namespace | Description | Administered By | Taxonomy | |-----------|-------------|-----------------|----------| | `cdx:ai-ml` | Namespace for properties specific to the Artificial Intelligence (AI)/machine Learning (ML) technology domain | [CycloneDX Core Working Group] | [cdx:ai-ml taxonomy](cdx/ai-ml.md) | +| `cdx:cisa` | Namespace for properties specific to the 2026 CISA Minimum Elements for a Software Bill of Materials (SBOM) | [CycloneDX Core Working Group] | [cdx:cisa taxonomy](cdx/cisa.md) | | `cdx:composer` | Namespace for properties specific to the PHP Composer ecosystem. | [CycloneDX PHP Maintainers] | [cdx:composer taxonomy](cdx/composer.md) | | `cdx:device` | Namespace for properties specific to hardware devices. | [CycloneDX Core Working Group] | [cdx:device taxonomy](cdx/device.md) | | `cdx:esbuild` | Namespace for properties specific to the esbuild ecosystem. | [CycloneDX JavaScript Maintainers] | [cdx:esbuild taxonomy](cdx/esbuild.md) | +| `cdx:fda` | Namespace for properties supporting the recommendations in the U.S. FDA Cybersecurity in Medical Devices: Quality Management System Considerations and Content of Premarket Submissions guidance | [CycloneDX Core Working Group] | [cdx:fda taxonomy](cdx/fda.md) | | `cdx:gomod` | Namespace for properties specific to the Go Module ecosystem. | [CycloneDX Go Maintainers] | [cdx:gomod taxonomy](cdx/gomod.md) | | `cdx:lifecycle` | Namespace for properties specific to component and service lifecycles. | [CycloneDX Core Working Group] | [cdx:lifecycle taxonomy](cdx/lifecycle.md) | | `cdx:maven` | Namespace for properties specific to the Maven ecosystem. | [CycloneDX Maven Maintainers] [CycloneDX Gradle Maintainers] | [cdx:maven taxonomy](cdx/maven.md) | diff --git a/cdx/cisa.md b/cdx/cisa.md new file mode 100644 index 0000000..67ab036 --- /dev/null +++ b/cdx/cisa.md @@ -0,0 +1,84 @@ +# `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)*](https://www.cisa.gov/sites/default/files/2026-07/2026_cisa_sbom_minimum_elements_508c.pdf), 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 [parent document](../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](https://www.rfc-editor.org/rfc/rfc2119). + +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. + +The CISA `SBOM Author` data field maps to `metadata.authors` when one or more people manually create the SBOM and to `metadata.manufacturer` when an organization creates it through an automated process. + +---- + +## Guidance Mapping + +This mapping is informative. The property definitions below are normative for properties in this namespace. + +| Appendix A data field or CISA practice | CycloneDX 1.x mapping | `cdx:cisa` property where CycloneDX does not completely cover it | +|---|---|---| +| Component Dependency Relationship | `dependencies[]` (`ref` to `dependsOn`); completeness through `compositions` | - | +| Component Hash Algorithm | `components[].hashes[].alg` | - | +| Component Hash Value | `components[].hashes[].content` | When unknown, omit `hashes` and declare `Component Hash Value` through `cdx:cisa:unknown-information` | +| Component Identifiers | `purl`, `cpe`, `swid`, `omniborId`, and `swhid` | `cdx:cisa:component-identifier` for UUIDs and organization-specific identifiers when no more specific native field is appropriate | +| Component License | `licenses[].license.id` for SPDX identifiers; `licenses[].license.name` or other native license details when no SPDX identifier applies | - | +| Component Name | `components[].name` | `cdx:cisa:alternate-name`, repeated once per alternate name | +| Component Producer | `components[].manufacturer` | When unknown, set `manufacturer.name` to `unknown` and declare `Component Producer` through `cdx:cisa:unknown-information` | +| Component Version | `components[].version` | When unknown, set `version` to `unknown` and declare `Component Version` through `cdx:cisa:unknown-information` | +| Unknown Information | - | `cdx:cisa:unknown-information`: one instance for every required field whose value is unknown to the SBOM author; the value is the exact Appendix A data field name, even when a native field also contains `unknown` or another native mechanism describes the missing information | +| Withheld Information | - | `cdx:cisa:withheld-information`: one instance for every required field intentionally withheld from the SBOM; the value is the exact Appendix A data field name | +| Withheld Information Inquiry | - | `cdx:cisa:withheld-information-inquiry`: one document-level instance in `metadata.properties` with a textual description of how a recipient may ask about withheld or redacted security-related information | +| SBOM Author | `metadata.authors[]` when people manually create the SBOM; `metadata.manufacturer` when an organization creates it through an automated process | - | +| SBOM Author Signature | `signature`; detached signatures through `externalReferences` type `digital-signature` | - | +| SBOM Data Format Name | `bomFormat` | - | +| SBOM Data Format Version | `specVersion` | - | +| SBOM Generation Context | `metadata.lifecycles[]`, using a predefined phase or custom name | - | +| SBOM Timestamp | `metadata.timestamp` | - | +| SBOM Tool Name | `metadata.tools.components[].name` | - | +| SBOM Tool Version | `metadata.tools.components[].version` | - | +| SBOM Version | `version` and `serialNumber` | - | + +## Properties + +| Property | Description | +|----------|-------------| +| `cdx:cisa:unknown-information` | Explicitly identifies a required data field whose information is unknown to the SBOM author.
The 2026 Minimum Elements practice *Explicitly Identifying Unknown Information* requires SBOM authors to distinguish information that is unknown from information they are withholding.
The value MUST be the 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:withheld-information` | Explicitly identifies a required data field whose information the SBOM author is intentionally withholding.
The 2026 Minimum Elements practice *Explicitly Identifying Unknown Information* requires this information to be distinguished from information that is unknown to the author.
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:withheld-information-inquiry` | Describes the process for recipients to ask about withheld or redacted security-related information, as specified by the 2026 Minimum Elements practice *Explicitly Identifying Unknown Information*.
The value is free text and MAY contain a URL, email address, or document reference for the inquiry process.
This document-level property MUST be placed in `metadata.properties` and MAY appear only once. | +| `cdx:cisa:alternate-name` | 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 is one alternate name.
One property instance MUST be provided for each alternate name.
Component-level. | +| `cdx:cisa:component-identifier` | 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`, `omniborId`, and `swhid` SHOULD be used when applicable.
The value is free text and SHOULD identify its scheme, for example `urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79` or `acme-part:12345`.
One property instance MUST be provided for each additional identifier.
Component-level. | + +## Example + +```json +{ + "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": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" + } + ] + } + ] +} +``` diff --git a/cdx/fda.md b/cdx/fda.md new file mode 100644 index 0000000..80f1199 --- /dev/null +++ b/cdx/fda.md @@ -0,0 +1,65 @@ +# `cdx:fda` Namespace Taxonomy + +This is the namespace for official CycloneDX properties carrying SBOM information for premarket submissions under the U.S. FDA guidance [*Cybersecurity in Medical Devices: Quality Management System Considerations and Content of Premarket Submissions*](https://www.fda.gov/media/119933/download), issued February 3, 2026 (referred to below as "the guidance"). + +The official rules and processes apply - see [parent document](../cdx.md). + +Guidance-defined properties cite the relevant section for traceability. Section V.A.4(b) permits the additional component-support elements to be provided as part of the SBOM or separately in an addendum; this namespace provides an in-SBOM representation. Properties identified below as namespace conventions support submission workflows but are not fields defined by the guidance. + +Dates MUST use the RFC 3339 `full-date` form, `YYYY-MM-DD`. Component-level properties attach to `components[].properties`, or to `metadata.component.properties` when they describe the device as a whole. Properties are repeatable unless stated otherwise. The key words MUST, SHOULD, and MAY are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). + +Known vulnerabilities, vulnerability-discovery methods, vulnerability risk assessments, and vulnerability risk controls are outside the scope of this SBOM-property namespace and are deferred to a separate vulnerability-management document. + +---- + +## Guidance Mapping + +This mapping is informative. The property definitions below are normative for properties in this namespace. + +| FDA information or convention | CycloneDX 1.x core mapping | `cdx:fda` property where core does not completely cover it | +|---|---|---| +| Level of support (§V.A.4(b)) | - | `cdx:fda:level-of-support`, free text; use the guidance examples `actively maintained`, `no longer maintained`, and `abandoned` verbatim when applicable | +| End-of-support date (§V.A.4(b)) | `cdx:lifecycle:milestone:endOfSupport` | `cdx:fda:end-of-support-date`; when both properties occur, they should identify the same milestone, while the lifecycle property may use an ISO 8601 date or timestamp as its taxonomy permits | +| End of life (§VI.A) | `cdx:lifecycle:milestone:endOfLife` | `cdx:fda:end-of-life-date`; representing the information as a date is a namespace convention; when both properties occur, they should identify the same milestone, while the lifecycle property may use an ISO 8601 date or timestamp as its taxonomy permits | +| Justification when information cannot be provided (§V.A.4(b)) | - | `cdx:fda:justification`, repeatable; value is `: `, one instance per property that cannot be answered | +| Plan to update or replace a third-party component if support ends (§V.A.4) | - | `cdx:fda:update-or-replace-plan` | +| Custodial control of device source code, such as escrow or backups (§V.A.4 and footnote 36) | - | `cdx:fda:source-code-custody` | +| Risk-transfer process when a device remains in service after end of support (§VI.A) | - | `cdx:fda:risk-transfer-process` | +| Traceability between the threat model, cybersecurity risk assessment, SBOM, and testing documentation (§V.A) | - | `cdx:fda:traceability`; value is the corresponding traceability record identifier | +| Date on which support determinations were made | - | `cdx:fda:support-assessed-date`, a namespace-defined submission-support field rather than an FDA-defined field | + +## Properties + +| Property | Description | +|----------|-------------| +| `cdx:fda:level-of-support` | The software level of support provided through monitoring and maintenance by the software component manufacturer (guidance §V.A.4(b)).
The value is free text.
The guidance's examples `actively maintained`, `no longer maintained`, and `abandoned` SHOULD be used verbatim when applicable.
MAY appear only once per component. | +| `cdx:fda:end-of-support-date` | The software component's end-of-support date (guidance §V.A.4(b)).
If no date can be provided, this property MUST be omitted and a `cdx:fda:justification` property provided.
When `cdx:lifecycle:milestone:endOfSupport` is also present for the component, the two properties SHOULD identify the same milestone; the lifecycle property remains governed by the `cdx:lifecycle` taxonomy and may contain an ISO 8601 date or timestamp.
MAY appear only once per component. | +| `cdx:fda:end-of-life-date` | A date representing the known or anticipated component end of life described in guidance §VI.A.
Representing this information as a date, and using `cdx:fda:justification` when no date can be provided, are namespace conventions.
If no date can be provided, this property MUST be omitted and a `cdx:fda:justification` property provided.
When `cdx:lifecycle:milestone:endOfLife` is also present for the component, the two properties SHOULD identify the same milestone; the lifecycle property remains governed by the `cdx:lifecycle` taxonomy and may contain an ISO 8601 date or timestamp.
MAY appear only once per component. | +| `cdx:fda:justification` | A justification for why information cannot be included in the premarket submission (guidance §V.A.4(b)).
The value MUST contain the affected `cdx:fda` property name, a colon, and a free-text justification, for example `cdx:fda:end-of-support-date: upstream project publishes no support date`.
One property instance MUST be provided for each property that cannot be answered. | +| `cdx:fda:update-or-replace-plan` | Describes the plan for how a third-party software component could be updated or replaced if support ends or other software issues arise (guidance §V.A.4).
The value is free text and MAY contain a controlled-document identifier or URL. | +| `cdx:fda:source-code-custody` | Describes how custodial control of device source code is established and maintained, such as through source code escrow or backups (guidance §V.A.4 and footnote 36).
The value is free text and MAY contain a controlled-document identifier or URL. | +| `cdx:fda:risk-transfer-process` | Describes the pre-established and pre-communicated process for transferring risks when a device remains in service after end of support (guidance §VI.A).
The value is free text and MAY contain a controlled-document identifier or URL. | +| `cdx:fda:traceability` | Identifies the record providing traceability between the threat model, cybersecurity risk assessment, SBOM, and testing documentation, as recommended by guidance §V.A.
The value is the corresponding traceability record identifier. | +| `cdx:fda:support-assessed-date` | The date on which the component's level-of-support and end-of-support determinations were made.
It anchors time-varying support information to the assessment used for the submission.
MAY appear only once per component. | + +## 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:update-or-replace-plan", "value": "QMS-PLN-0142" } + ] + } + ] +} +```