Skip to content

feat(2.0): add instruments to behavior instances - #1201

Draft
Mehrn0ush wants to merge 1 commit into
CycloneDX:2.0-devfrom
Mehrn0ush:feat/behavior-instruments
Draft

Mehrn0ush wants to merge 1 commit into
CycloneDX:2.0-devfrom
Mehrn0ush:feat/behavior-instruments

Conversation

@Mehrn0ush

Copy link
Copy Markdown
Contributor

Follow-up to the review of #1195 (thanks @bhess): a role is less a property of a cryptographic asset and more how another component uses it. The behavior taxonomy already names such uses (e.g. security:cryptography:signsCode), but a behavior instance can only state who performs it (actors) and what is affected (targets). There is no way to state which key or algorithm it is performed with.

This PR adds an optional instruments array to behaviorInstance: references to the objects by means of which the behavior is performed. An instrument neither performs the behavior nor is affected by it.

  • No new vocabulary: the kind of use comes from the existing behavior taxonomy.
  • Optional and additive. Existing documents remain valid.
  • Added to behavior instances only. A graph node can reference an instance.

Fixtures: one valid document (a build service signs a firmware image with a private key and ML-DSA-65) and two invalid ones (non-array value, duplicate references).

Opened as a draft for discussion. Open questions: the property name (instruments vs uses), and whether labelled dependencies or blueprint relationships are the preferred long-term home.

Related to #1162 and #1195.

Signed-off-by: Mehrn0ush <mehrnoush.vaseghi@gmail.com>
"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.",
"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?

"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.",

@jkowalleck
jkowalleck requested a review from a team November 12, 2026 16:58
@Mehrn0ush

Copy link
Copy Markdown
Contributor Author

Thanks @jkowalleck for the review. Before replying to the two inline points, let me explain why this draft exists, because I'd first like to know whether it is the right approach at all.

Background. In #1195 I proposed a role on relatedCryptographicAssets. @bhess pointed out that a role is less a property of a cryptographic asset and more how another component uses it, and that the behavior taxonomy already names such uses, for example security:cryptography:signsCode. What is missing is a way to say which key or algorithm a behavior is performed with. A behavior instance has actors (who performs it) and targets (what is affected), but nothing for that.

What this draft tries: It adds an optional instruments array to behaviorInstance for that link. Example: a build service (actor) signs a firmware image (target) with a release key and ML-DSA-65 (instruments).

My question: Is the behavior module the right place to solve this? If you would rather see it expressed another way, for example through targets, blueprint relationships, or labelled dependencies, I'm happy to close this draft and follow that direction.

@jkowalleck

Copy link
Copy Markdown
Member

No worris, just flagged my findings early, so you can discuss them in your next working group meeting.

Keep on the good work 👍

@bhess

bhess commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

Thanks @Mehrn0ush for picking this up.

Let me recap my view of the use case:

The original question in #1162, which algorithm does what in a protocol, is now covered by #1213. That includes the keys a protocol uses. The SSH example there shows a host key.

What remains is a statement like "the build service signs the firmware with this key". I think behaviors are the right candidate for it, better than labelled dependencies. A dependency connects two things. Here we have three: who signs, what is signed, and with which key. A behavior already has the first two, and instruments adds the third.

Two points before we should clarify:

  • This is not specific to cryptography; the same applies to a token or a tool. So I would keep instruments general, and the maintainers of the behavior module should have the say.
  • The most common case in CBOM already works today: a component depends on its key, and the key says what it is for (keyUsage). A concrete example where that is not enough would be useful in this PR.

@Mehrn0ush

Copy link
Copy Markdown
Contributor Author

Thanks @bhess, that recap helps.

Agreed. @jkowalleck suggested narrowing the description to components of type cryptographic-asset, so the two suggestions differ. I'll leave that choice to the maintainers of the behavior module and apply whichever they prefer.

An example where dependency plus keyUsage is not enough." It works when a component has one key with one use. It stops working in these cases:

  1. One component, several keys with the same usage. A build service holds a firmware release key and a separate key for signing SBOMs. It depends on both, and both say keyUsage: sign. Nothing states which key signs the firmware. After a key compromise, "which artefacts were signed with this key" cannot be answered from the BOM.
  2. Key rotation. The old and the new key are both present with the same usage. Nothing states which one a behavior uses now.
  3. One key, several uses. A key used both to sign code and to authenticate a TLS server is a finding in itself (NIST SP 800-57 Part 1, section 5.2: "a single key shall be used for only one purpose"). With instruments the reuse is visible per behavior.

If useful, I can change the example in this PR to case 1 (two keys, two targets).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants