Best practice for expressing “CONTAINS” in CycloneDX

[knqyf263]

Hi CycloneDX team,

We're working to improve Trivy’s CycloneDX output and would like guidance on how to model “contains” relationships that, in SPDX, are expressed with CONTAINS.

Typical scenario (container image SBOM):

• Container image
  • Operating System (e.g. Debian)
    • Debian packages (with their own depends-on graph)
  • Application binary (built with Go)
    • Go modules (with their own depends-on graph)

We’ve read the Relationships guide and see that “assemblies” look closest to SPDX CONTAINS, but there seem to be several ways to structure the BOM.

Below are three candidate patterns, each with a simplified snippet (assuming bom-ref is equivalent to name). Which one is considered most idiomatic?

---

Pattern 1: Two parallel assemblies (OS & binary)

metadata.component  (type: container, bom-ref: img)

components:
- type: operating-system
  name: debian
  components:
    - name: libc6
    - name: base-files
- type: application
  name: myapp
  bom-ref: bin
  components:
    - name: modA
    - name: modB

dependencies:
- ref: debian  
  dependsOn:
   - base-files # Essential package
- ref: modB
  dependsOn
    - modA

Considerations

• Should the binary be under the OS component (pattern 2)?

---

Pattern 2: Single nested assembly (everything under the OS)

metadata.component  (type: container, bom-ref: img)

components:
- type: operating-system
   name:debian
   bom-ref: os
   components:
     - type: package
       name: libc6
     - type: package
       name: base-files
     - type: application
       name: myapp
       bom-ref: bin
       components:
         - name: modA
         - name: modB

dependencies:
- same as pattern 1

Considerations

• OS packages are located in the same level as the application

---

Pattern 3: Flat components + dependencies

metadata.component  (type: container, bom-ref: img)

components: [os, libc6, dpkg, bin, modA, modB]

dependencies:
- ref: img
  dependsOn:["os","bin"]
- ref: os
  dependsOn: ["libc6","dpkg"]
- ref: bin
  dependsOn: ["modA","modB"]

Considerations

• Considering the entire container image, it might be possible to think of all the packages as necessary dependencies. Should we add all components as dependencies of the image? OS packages are also considered as dependencies of OS?
• Simple graph and works with most tools, but the edge type is always “dependsOn”; it is not strictly a containment relation like SPDX CONTAINS, so semantics are blurred.

---

Questions

1. Which of the above (or something else) is the recommended way to represent containment in CycloneDX 1.6?
2. If assemblies are preferred, is Pattern 1 or Pattern 2 more aligned with the spec’s intent?
3. Are there interoperability concerns with current tooling (Dependency-Track, etc.) that would favour the flat dependency approach despite its weaker semantics?

Any guidance or references to existing public SBOMs following best practice would be greatly appreciated.

Thanks

[jkowalleck]

We’ve read the Relationships guide and see that “assemblies” look closest to SPDX CONTAINS,

thats the way to go

but there seem to be several ways to structure the BOM.

according to the guide, there is only one way - sub-components nested according to the architecture of use.

"components": [
  {
    "type": "application",
    "name": "Acme Commerce Suite",
    "version": "2.0.0",
    "components": [
      {
        "type": "application",
        "name": "Acme Storefront Server",
        "version": "3.7.0",
      },
      {
        "type": "application",
        "name": "Acme Payment Processor",
        "version": "3.1.1",
      }
    ]
  }
]

please be aware that dependency graph does express WHY a component exist, not where it is nested/contained.

[knqyf263]

If "myapp" is not shipped with that "debian", but is simply another independent component of "img", then "myapp" is parallel to "debian".

In my example shared above, the container image includes Debian, and the application is installed within it. Specifically, the Dockerfile appears as follows.

FROM debian:11

COPY myapp .

In this case, can Debian and the app be considered independent components in CycloneDX? Alternatively, since myapp runs on Debian, should it be considered as being shipped within Debian?

[jkowalleck]

well, before this conversation drifts to a different topic, lets get back to the original question:

[...] would like guidance on how to model “contains” relationships that, in SPDX, are expressed with CONTAINS.

this

SPDX: A -- contains --> B

translates to

CycloneDX: B is nested in A

[knqyf263]

It’s actually the same topic from the start for me, but includes two questions:

1. Whether CONTAINS should be represented as assemblies in CycloneDX – as confirmed above, Pattern 3 is not the case; I’ve already received an answer on that. So no further explanation is needed here. Thank you for clarifying.

2. The other question is fundamentally: when should we use CONTAINS? I illustrated this with a real-world example in my question, and I’m seeking guidance on that point.

And regarding this second question, it’s simply the same question rephrased below. If you consider this to be a distinct topic, please let me know, and I will open a new discussion.

2. If assemblies are preferred, is Pattern 1 or Pattern 2 more aligned with the spec’s intent?

[jkowalleck]

The other question is fundamentally: when should we use CONTAINS? I illustrated this with a real-world example in my question, and I’m seeking guidance on that point.

this is a different topic: in a container image, when is a thing a subcomponent of the base image?

the answer is heavily depending on the actual architecture, and probably very debatable.
The question is probably not to be answered by CycloneDX poeple, but by @opencontainers or the trivy community.

but anyway, here are my 2cents:

• base image is "debian" -> a component "debian"
• some debian package "foo" is installed (apt install ...) -> "foo" is a subcomponent of "debian"
• some "myapp" is copied into the file system of the image -> "myapp" is not a subcomponent of "debian", but a sibling of "debian"

[knqyf263]

I’m afraid I misunderstood the previous reply. I thought your answer was addressing this specific scenario I shared, but in fact, it was only a general reminder that SPDX CONTAINS can be mapped to CycloneDX nesting. So Pattern 3 (flat + dependencies) is still on the table.

What I really wanted was a deeper discussion with concrete examples, but by bringing up SPDX CONTAINS I apparently derailed the thread. I opened a fresh discussion with a clearer scope.
#660

The question is probably not to be answered by CycloneDX people, but by @opencontainers or the Trivy community.

That is exactly what I’m trying to highlight. Even for a very common structure—an OS with an application inside—there is no single, authoritative way to build the SBOM. Authors and tools make subjective choices, so two SBOMs for the same image can be structurally different and therefore not interchangeable.

[ppkarwasz]

Hi @knqyf263,

Thank you for starting this important discussion!

I tend to agree with both you and @jkowalleck that assemblies are conceptually the correct way to model inclusion relationships in CycloneDX. However, in practice, I’ve rarely seen them used in real-world SBOMs. For example:

• Syft, which powers the docker sbom command, produces a flat list of components without using assemblies.
• The CycloneDX Maven Plugin produces the same flat structure for both WAR archives (which bundle dependencies) and JARs (which typically don't), despite their structural differences.

As a result, most security scanners treat any component listed in a CycloneDX SBOM as bundled with the application, regardless of whether it’s actually included or merely referenced. This confusion is compounded by the NTIA’s definition of a "dependency relationship," which essentially equates it with inclusion:

Data Field	Description
[...]	[...]
Dependency Relationship	Characterizing the relationship that an upstream component X is included in software Y.

— The Minimum Elements for a Software Bill of Materials

Given this reality, we're exploring a more pragmatic approach in the CycloneDX Maven Plugin. Specifically, we’re considering using:

• the absence of a component version combined with
• the upcoming isExternal property (to be introduced in CycloneDX 1.7, see Feature: documenting external/extraneous dependencies #321)

to differentiate between shipped and non-shipped dependencies. This ongoing discussion is documented in detail at CycloneDX/cyclonedx-maven-plugin#589.

Proposal for Expressing CONTAINS Relationships

To maintain alignment with current tool behavior and scanner expectations, I believe we should treat the CONTAINS relationship as follows:

• Use CycloneDX assemblies to indicate included components.
• Use the isExternal property to signal referenced but not included components.
• Treat components that are neither in an assembly nor marked isExternal as having an undefined containment status.

[knqyf263]

Hi @ppkarwasz,

Thanks a lot for digging up the NTIA document—I must have read that document years ago, but had completely forgotten about the exact phrasing. As both you and @jkowalleck already pointed out, we seem to share the view that assemblies are the right vehicle to express CONTAINS relationships. The real difficulty, in my opinion, is that the boundary between CONTAINS and DEPENDS_ON is inherently fuzzy—something the NTIA definition itself reflects—so it’s no surprise that people interpret it differently.

What feels missing today is a concise guideline—ideally with concrete, real-world examples—showing when CycloneDX authors should reach for assemblies and when they should use the dependency graph. For instance:

• Is an operating-system package baked into the OS image CONTAINS or DEPENDS_ON?
• Is a user-installed operating-system package that resides inside a container (or a VM image) CONTAINS or DEPENDS_ON?
• Is a user-installed app shipped with the machine CONTAINED by the OS or the machine?

Although @opencontainers was mentioned in the thread, these questions are not container-specific; they apply equally to traditional VMs and even bare-metal deployments.

Since no such guideline exists today, we end up with the situation you described: some tools emit completely flat SBOMs, others nest everything under assemblies, and interoperability suffers.

A slightly off-topic—but related—concern: if we agree that assemblies are the way forward, suddenly changing SBOM structure will almost certainly break downstream tooling. To maintain a reasonable level of backward compatibility, I wonder if CycloneDX could support “symlink-like” pointers: i.e., retaining the existing top-level component entries while also referencing the canonical component within its assembly. That would give consumers time to migrate without losing data they already rely on.