Add support for Cyclonedx as a predicate type

[samj1912]

intoto attestations currently document the SPDX predicate type. SBOMs and BOMs in general are a diverse space as of now and CycloneDX is the other leading industry alternative to SPDX for SBOMs and recognized by NTIA as a recognized SBOM format.

CycloneDX supports other capabilities apart from just SBOMs. A particularly interesting one is the VEX capability which introduce a standard format to attach vulnerability information.

intoto should document and introduce well defined predicate types for the various CycloneDX BOM formats (not just SBOM).

cc: @stevespringett @coderpatros

[samj1912]

Predicate type: CycloneDX

Type URI: (tentative) https://cyclonedx.org/BOM/v1.4 or just https://cyclonedx.org/BOM

Version: 1.0.0

TODO: Ask CycloneDX project to choose a URI and to review this spec. Ideally the URI would resolve to this file. Also, decide whether we want the version number to reflect the version (e.g. 1.4) or have them be independent (no version number in URI).

Purpose

A Bill of Materials type following the CycloneDX standard.

This allows to represent an "exportable" or "published" software artifact, services, vulnerability information and more. For a complete list of capabilities see CycloneDX Capabilities. It can also be used as an entry point for other types of in-toto attestation when performing policy decisions.

Schema

{
  // Standard attestation fields:
  "_type": "https://in-toto.io/Statement/v0.1",
  "subject": [{ ... }],

  // Predicate:
  "predicateType": "https://cyclonedx.org/BOM",
  "predicate": {
    "bomFormat": "CycloneDX",
    "specVersion": "1.4",
    "serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
    "version": 1,
    "components": [
        {
        "type": "library",
        "name": "acme-library",
        "version": "1.0.0"
        }
    ]
    ...
  }
}

The predicate contains a JSON-encoded CycloneDX BOM. The CycloneDX format has a mandatory specVersion field, so we may choose to omit the version number from the predicateType URI to avoid confusion.

The subject contains whatever software artifacts are to be associated with
this CycloneDX BOM document.

The above is an example proposed predicate type documentation.

[samj1912]

Having this information (sbom/vex) in the intoto attestation format is particular interesting when combined with cosign attestations + a policy engine like kyverno

which will allow verification of container images before they are admitted to a runtime environment.

Eg - https://github.com/JimBugwadia/image-verification-policy/blob/main/check-sbom.yaml

cc: @dlorenc + @sigstore team, @JimBugwadia + @kyverno team

[samj1912]

Note that this is a different proposal from #74 and proposes CycloneDX boms as a top level predicate type rather than introduce a generic sbom predicate since cyclonedx documents can be more than just SBOMs (VEX examples attached below) and might tie up nicely with #58

[samj1912]

Some related CycloneDX BOM examples -

CycloneDX SBOM -
https://github.com/CycloneDX/sbom-examples/blob/master/SBOM/dropwizard-1.3.15/bom.json
https://github.com/CycloneDX/sbom-examples/blob/master/SBOM/proton-bridge/proton-bridge-v1.8.0.bom.json

CycloneDX VEX -
https://github.com/CycloneDX/sbom-examples/blob/master/VEX/vex.json

CycloneDX SaaSBOM -
https://github.com/CycloneDX/sbom-examples/blob/master/SaaSBOM/apigateway-microservices-datastores/bom.json

Example use of such attestations -

Reject images which contain vuln. with score greater than 8

https://github.com/JimBugwadia/image-verification-policy/blob/38eda1e463b6f16910cca2c00135271e9d2753f1/check-vex.yaml

Reject images which contain a specific component and version

https://github.com/JimBugwadia/image-verification-policy/blob/main/check-sbom.yaml

[stevespringett]

Let me or @coderpatros know if there are any CycloneDX questions. Looking forward to this enhancement!

[samj1912]

@stevespringett not sure if the CycloneDX team has a preference on what the predicate type should look like -

For eg https://cyclonedx.org/BOM/v1.4 or just https://cyclonedx.org/BOM

The CycloneDX format has a mandatory specVersion field, so we may choose to omit the version number from the predicateType URI to avoid confusion.

Similarly not sure if you have a preference for different predicate types for different capabilities that CycloneDX offers or if the generic predicate type format looks good. In terms of in-toto support I think it is majorly just documenting the predicate type and the predicate payload format for a given type. There is no registration process per https://github.com/in-toto/attestation/tree/main/spec#predicate so we can also just document these on the cyclonedx side so that users have a consistent way of identifying cyclonedx attestations.

[stevespringett]

I would recommend a generic predicate type, not specific to the CycloneDX capabilities. The reality is that it's entirely possible to construct a BOM with ALL capabilities.

https://cyclonedx.org/bom or https://cyclonedx.org/BOM sounds good to me. As you state, the version is included in the BOM itself. The JSON spec has a specVersion whereas the XML spec relies on the namespace to identify the version of the spec.

[chipzoller]

Strong +1 here. This is of great interest to those needing to comply with the White House executive order on cybersecurity which CycloneDX exceeds.

[MarkLodato]

PRs welcome! Or this can be documented on the CycloneDX side and just have a pointer in this repo. There is no formal registration necessary.

[chipzoller]

What's needed from an in-toto side to "support" this? If there's no formal registration, is it just a mutual agreement as to the predicateType URI?

[MarkLodato]

From a specification point of view, all that is needed is a document describing unambiguously how to interpret the attestation of that predicateType: how to parse the predicate (linking to the CycloneDX spec), how the subject relates to the predicate, etc. It will probably be short. This document SHOULD be served from that URI (example: https://slsa.dev/provenance/v0.2).

Then you need tools to actually implement that. If you're using the in-toto binary, I think in-toto-golang is where a lot of development has been happening, but I'm less familiar with this.

Does that help?

[samj1912]

Happy to submit a PR to document this in the spec first.

[chipzoller]

Happy to collaborate, @samj1912

[lehors]

Hi,
This issue has been left open without any clear resolution. Syft uses "https://cyclonedx.org/bom" while PR #169 added to in-toto-golang the predicate with the value ("https://cyclonedx.org/schema"). The latter is used by cosign, making cosgin and syft incompatible.

I'd like to know what the plan is.

I tend to think that syft should use whatever in-toto defines and should be fixed accordingly rather than use its own value but the fact that the in-toto definition seems to have been added pretty casually without much discussion and any formal resolution of this issue isn't very comforting.

Thanks

[stevespringett]

We've discussed this in the CycloneDX project and have settled on the use of https://cyclonedx.org/bom which aligns to what Syft is using. The problem with in-toto using https://cyclonedx.org/schema is that if the CycloneDX project ever comes up with a different but complimentary specification (highly likely), /schema doesn't provide enough context about which one. And in fact, an SPDX schema already exists in the CycloneDX project, so technically we already have more than one schema as is.

CycloneDX/specification#132

[lehors]

Thanks for the response. I understand and I'll be happy to submit a PR to update in-toto-golang accordingly. It would be best if the CycloneDX project closed the issue with your decision. We can then close this one and update all projects accordingly.

[adityasaky]

@samj1912 can you open a PR for this proposed predicate type? The format for a predicate spec can be found here: https://github.com/in-toto/ITE/blob/master/ITE/9/README.adoc. Also, #111 and #112 can be used for reference.