feat(cyclonedx): preserve SBOM structure when scanning SBOM files with vulnerability updates

[knqyf263]

Description

This PR adds the ability to reuse existing BOM structure when scanning SBOMs, preserving the original SBOM components, properties, and relationships while only updating vulnerability information.

Key Features

• BOM Structure Preservation: Maintains original SBOM components, custom properties, and relationships
• External Property Preservation: Custom properties from third-party SBOMs retain their original names (no unwanted namespace prefixes)
• Vulnerability-Only Updates: Only refreshes vulnerability data without altering the original structure
• Dependency Preservation: Maintains empty dependsOn arrays and component relationships
• Library Integration: Enables SBOM customization when using Trivy as a library - add custom components and properties that will be preserved across scans

Implementation Details

• Add reuseExistingBOM() function to detect and preserve existing BOM structure
• Add BOM.Clone() and Component.Clone() methods for safe BOM manipulation
• Add External field to core.Property to distinguish Trivy vs external properties
• Enhanced CycloneDX unmarshal/marshal logic to preserve external property names
• Use BOM-Ref for component lookup during vulnerability updates

Before/After Examples

Before (main branch):

# Step 1: Generate base SBOM
./trivy image alpine:3.18 --format cyclonedx --output base.json

# Step 2: Add custom properties and application component to SBOM
jq '
.metadata.component.properties += [{"name": "custom:environment", "value": "test"}] |
.components += [{
  "type": "application",
  "bom-ref": "[email protected]",
  "name": "custom-app", 
  "version": "1.0.0",
  "properties": [{"name": "custom:app-type", "value": "test-application"}]
}]
' base.json > custom.json

# Step 3: Scan the modified SBOM
./trivy sbom custom.json --format cyclonedx --output result.json

# Step 4: Check if custom properties and components are preserved
jq '.metadata.component.properties[] | select(.name | contains("custom"))' result.json
# Result: Wrong namespaces
{
  "name": "aquasecurity:trivy:custom:environment",
  "value": "test"
}

jq '.components[] | select(.name == "custom-app")' result.json  
# Result: Empty (custom components lost)

After (this PR):

# Step 1: Generate base SBOM  
./trivy image alpine:3.18 --format cyclonedx --output base.json

# Step 2: Add custom properties and components
jq '
.metadata.component.properties += [{"name": "custom:environment", "value": "test"}] |
.components += [{
  "type": "application",
  "bom-ref": "[email protected]", 
  "name": "custom-app",
  "version": "1.0.0",
  "properties": [{"name": "custom:app-type", "value": "test-application"}]
}]
' base.json > custom.json

# Step 3: Scan the modified SBOM
./trivy sbom custom.json --format cyclonedx --output result.json

# Step 4: Verify custom properties are preserved
jq '.metadata.component.properties[] | select(.name | contains("custom"))' result.json
# Result: {"name": "custom:environment", "value": "test"}

# Step 5: Verify custom components are preserved
jq '.components[] | select(.name == "custom-app")' result.json
# Result: Complete custom component with original properties

# Step 6: Verify Trivy properties still get namespace prefixes
jq '.metadata.component.properties[] | select(.name | startswith("aquasecurity:trivy:"))' custom.json
# Result: Trivy properties with proper namespace prefixes

Related issues

• Close feat(cyclonedx): preserve SBOM structure when scanning SBOM files with vulnerability updates #9438

Checklist

• I've read the guidelines for contributing to this repository.
• I've followed the conventions in the PR title.
• I've added tests that prove my fix is effective or that my feature works.
• I've updated the documentation with the relevant information (if needed).
• I've added usage information (if the PR introduces new options)
• I've included a "before" and "after" example to the description (if the PR is a user interface change).

[DmitriyLewen]

We already tried to do similar logic - #7340 (review)

IIRC there are 2 big problem:

• bom-ref is still not required field - https://cyclonedx.org/docs/1.6/json/#components_items_bom-ref
• we can't use filter flags for packages (e.g. --pkg-types, --relationships):

   ➜   ./trivy -q image aquasec/trivy -f cyclonedx -o report.cdx.json
   ➜   cat report.cdx.json | grep "pkg:apk" | wc -l
        151
   ➜  trivy -q sbom --pkg-types library report.cdx.json -f cyclonedx | grep "pkg:apk" | wc -l
          0
   ➜  ./trivy -q sbom --pkg-types library report.cdx.json -f cyclonedx | grep "pkg:apk" | wc -l
        151

[knqyf263]

Thank you for reminding me of the issues. As for the generation of BOM-Refs, it should not be a problem since BOM-Refs are automatically generated within the intermediate representation of our SBOM. I fixed a bug that I found.
d309c4f

On the other hand, filtering is a difficult problem. Perhaps one option would be not to handle it at all. I'll consider it.

[knqyf263]

@DmitriyLewen Implementing filtering itself is possible, but it is not a quick task. Have you actually seen users who want to scan CycloneDX, filter packages and export CycloneDX again?

[DmitriyLewen]

I don’t think I’ve come across such cases from users.
I think that scanning an SBOM file and also using an SBOM as the output format (e.g. trivy sbom rep.cdx.json -f cyclonedx) is a very questionable use case.

[knqyf263]

I think that scanning an SBOM file and also using an SBOM as the output format (e.g. trivy sbom rep.cdx.json -f cyclonedx) is a very questionable use case.

I think so too. I believe that scanning an SBOM and then outputting another SBOM is quite a rare use case (and only possible with CycloneDX). Therefore, for now, if an CycloneDX is scanned and then output, I intend to make the filtering CLI flag unavailable. Of course, a warning will be displayed.

And if there are requests from users, I would like to carefully listen to that use case and then decide at that time whether or not to implement it.

[DmitriyLewen]

That sounds logical.

Therefore, for now, if an CycloneDX is scanned and then output, I intend to make the filtering CLI flag unavailable. Of course, a warning will be displayed.

Let’s do it this way.

[DmitriyLewen]

LGTM

[DmitriyLewen]

We calc the SPDX-ID as a hash of core.component:

trivy/pkg/sbom/spdx/marshal.go

Lines 319 to 320 in d2d0ec2

	func (m *Marshaler) spdxPackage(c *core.Component, timeNow, pkgDownloadLocation string) (spdx.Package, error) {
	pkgID, err := calcSPDXID(m.hasher, c)

So after adding core.Property.External field, the hash was changed.

[DmitriyLewen]

The scanned file (testdata/sbom/fluentd-multiple-lockfiles-cyclonedx.json) doesn’t contain these fields.
That is why we remove them.

[DmitriyLewen]

I added warning about the --pkg-types and --pkg-relationship flags for SBOM-to-SBOM scanning (as we discussed here).

I am not sure this is the good place, but for other places (e.g. in Align function) we would need to throw targetKind.
However, as we said, this is most likely a very rare case, so I settled on this solution.

[knqyf263]

Yes, exactly because I was struggling with where to display the warning, I hadn’t committed it yet. Since I don’t want to put too many implementation details in app.go, I moved it to run.go.
7a59f28

However, I’m thinking of eventually refactoring it and implementing it inside Options.

[knqyf263]

Will fix the linter issues