Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions schema/2.0/modules/cyclonedx-behavior-2.0.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,15 @@
"items": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType"
}
},
"instruments": {
"type": "array",
"title": "Instruments",
"description": "References using bom-link or `refId` to objects by means of which this behavior is performed, such as the cryptographic key and algorithm used to create a signature. An instrument neither performs the behavior nor is affected by it.",

@jkowalleck jkowalleck Nov 12, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

could this be more clear?
maybe like so

Suggested change
"description": "References using bom-link or `refId` to objects by means of which this behavior is performed, such as the cryptographic key and algorithm used to create a signature. An instrument neither performs the behavior nor is affected by it.",
"description": "References using bom-link or `refId` to objects by means of which this behavior is performed in the form of a component with `type=\"cryptographic-asset\"`, such as the cryptographic key and algorithm used to create a signature. An instrument neither performs the behavior nor is affected by it.",

"uniqueItems": true,
"items": {
"$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType"

@jkowalleck jkowalleck Nov 12, 2026 •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

type and description do not match

cyclonedx-common-2.0.schema.json#/$defs/refLinkType matches refId only,
description suggests the use of cyclonedx-common-2.0.schema.json#/$defs/elementLink

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're right. I copied the type and the wording from the neighbouring actors and targets, which have the same mismatch described in #1202.

I see two ways to fix it and would like your preference before changing anything:

  1. Switch instruments to elementLink. The description stays as it is. This allows pointing to a key or algorithm in another BOM, which is a realistic case when the CBOM is a separate document. It would make instruments differ from actors and targets until [Defect]: 2.0 linked elements - docs and type mismatch #1202 is resolved.
  2. Keep refLinkType and change the description to refId only. This stays consistent with actors and targets as they validate today, and can follow whatever [Defect]: 2.0 linked elements - docs and type mismatch #1202 decides later.

I lean towards option 1, because the cross-BOM case matters for cryptographic assets, but I don't want this PR to pre-empt the decision in #1202. Which would you prefer?

}
}
}
},
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
{
"$comment": "A build service signs a firmware image. The behavior instance names who signs (actors), what is signed (targets), and the key and algorithm used to sign (instruments).",
"specFormat": "CycloneDX",
"specVersion": "2.0",
"serialNumber": "urn:uuid:c2000000-0000-4000-8000-0000000000b3",
"version": 1,
"definitions": {
"components": [
{
"type": "cryptographic-asset",
"refId": "alg-ml-dsa-65",
"name": "ML-DSA-65",
"cryptoProperties": {
"assetType": "algorithm",
"algorithmProperties": {
"primitive": "signature",
"algorithmFamily": "ML-DSA",
"parameterSetIdentifier": "65",
"cryptoFunctions": [
"sign",
"verify"
]
}
}
},
{
"type": "cryptographic-asset",
"refId": "key-release-signing",
"name": "Release signing private key",
"cryptoProperties": {
"assetType": "related-crypto-material",
"relatedCryptoMaterialProperties": {
"type": "private-key",
"keyUsage": [
"sign"
],
"relatedCryptographicAssets": [
{
"type": "algorithm",
"ref": "alg-ml-dsa-65"
}
]
}
}
}
]
},
"blueprints": [
{
"refId": "bp-signing",
"name": "Firmware release signing",
"modelTypes": [
"behavioral"
],
"assets": [
{
"refId": "asset-build-service",
"type": "service",
"name": "Build service"
},
{
"refId": "asset-firmware",
"type": "data",
"name": "Firmware image"
}
],
"behaviors": {
"instances": [
{
"refId": "bi-sign-firmware",
"behavior": "security:cryptography:signsCode",
"acknowledgment": [
"declared"
],
"actors": [
"asset-build-service"
],
"targets": [
"asset-firmware"
],
"instruments": [
"key-release-signing",
"key-release-signing"
]
}
]
}
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
{
"$comment": "A build service signs a firmware image. The behavior instance names who signs (actors), what is signed (targets), and the key and algorithm used to sign (instruments).",
"specFormat": "CycloneDX",
"specVersion": "2.0",
"serialNumber": "urn:uuid:c2000000-0000-4000-8000-0000000000b2",
"version": 1,
"definitions": {
"components": [
{
"type": "cryptographic-asset",
"refId": "alg-ml-dsa-65",
"name": "ML-DSA-65",
"cryptoProperties": {
"assetType": "algorithm",
"algorithmProperties": {
"primitive": "signature",
"algorithmFamily": "ML-DSA",
"parameterSetIdentifier": "65",
"cryptoFunctions": [
"sign",
"verify"
]
}
}
},
{
"type": "cryptographic-asset",
"refId": "key-release-signing",
"name": "Release signing private key",
"cryptoProperties": {
"assetType": "related-crypto-material",
"relatedCryptoMaterialProperties": {
"type": "private-key",
"keyUsage": [
"sign"
],
"relatedCryptographicAssets": [
{
"type": "algorithm",
"ref": "alg-ml-dsa-65"
}
]
}
}
}
]
},
"blueprints": [
{
"refId": "bp-signing",
"name": "Firmware release signing",
"modelTypes": [
"behavioral"
],
"assets": [
{
"refId": "asset-build-service",
"type": "service",
"name": "Build service"
},
{
"refId": "asset-firmware",
"type": "data",
"name": "Firmware image"
}
],
"behaviors": {
"instances": [
{
"refId": "bi-sign-firmware",
"behavior": "security:cryptography:signsCode",
"acknowledgment": [
"declared"
],
"actors": [
"asset-build-service"
],
"targets": [
"asset-firmware"
],
"instruments": "key-release-signing"
}
]
}
}
]
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
{
"$comment": "A build service signs a firmware image. The behavior instance names who signs (actors), what is signed (targets), and the key and algorithm used to sign (instruments).",
"specFormat": "CycloneDX",
"specVersion": "2.0",
"serialNumber": "urn:uuid:c2000000-0000-4000-8000-0000000000b1",
"version": 1,
"definitions": {
"components": [
{
"type": "cryptographic-asset",
"refId": "alg-ml-dsa-65",
"name": "ML-DSA-65",
"cryptoProperties": {
"assetType": "algorithm",
"algorithmProperties": {
"primitive": "signature",
"algorithmFamily": "ML-DSA",
"parameterSetIdentifier": "65",
"cryptoFunctions": [
"sign",
"verify"
]
}
}
},
{
"type": "cryptographic-asset",
"refId": "key-release-signing",
"name": "Release signing private key",
"cryptoProperties": {
"assetType": "related-crypto-material",
"relatedCryptoMaterialProperties": {
"type": "private-key",
"keyUsage": [
"sign"
],
"relatedCryptographicAssets": [
{
"type": "algorithm",
"ref": "alg-ml-dsa-65"
}
]
}
}
}
]
},
"blueprints": [
{
"refId": "bp-signing",
"name": "Firmware release signing",
"modelTypes": [
"behavioral"
],
"assets": [
{
"refId": "asset-build-service",
"type": "service",
"name": "Build service"
},
{
"refId": "asset-firmware",
"type": "data",
"name": "Firmware image"
}
],
"behaviors": {
"instances": [
{
"refId": "bi-sign-firmware",
"behavior": "security:cryptography:signsCode",
"acknowledgment": [
"declared"
],
"actors": [
"asset-build-service"
],
"targets": [
"asset-firmware"
],
"instruments": [
"key-release-signing",
"alg-ml-dsa-65"
]
}
]
}
}
]
}
Loading