search

CycloneDX / sbom-utility

Utility that provides an API platform for validating, querying and managing BOM data
Apache License 2.0
93 stars 13 forks source link

Documentation for custom.json #107

Open macariem opened 2 months ago

macariem commented 2 months ago

Is there a documentation for making a custom.json?

mrutkows commented 2 months ago

Hi @macariem, I decided to rethink the experimental "custom" validation in favor of a (future) implementation of OWASP Software Component Verification Standard (SCVS) and its planned "maturity model profiles" (see https://scvs.owasp.org/ and profile example: https://scvs.owasp.org/bom-maturity-model/profiles/examples/ntia-minimum-elements/).

In truth, what I coded was based upon rules for SBOM construction/contents we set within my company, IBM, which I was not sure extended as a general rule to everyone. In fact, we can achieve most of IBM's needs with the utility using a custom JSON schema along with the new "patch" command to test for required values.

The custom validation functionality is still in the code, but I removed any draft docs hoping to revisit it for a near-future release. I would welcome hearing of what custom validation (use cases) you may have so that I can factor them in future plans (and test for them when I get around to coding).

Thanks for the issue and I truly welcome any dialog on the topic :)

macariem commented 2 months ago

I want to perform extra validation as follows:

mrutkows commented 2 months ago

@macariem Thanks for sharing your use cases. Just wanted to share some initial thoughts on them...

Add extra required fields in the validation

Yes, this is common and one I have... in order to accomplish this, I create a custom JSON schema (variant) file based upon the base CycloneDX schema file and add it to sbom-utility (see https://github.com/CycloneDX/sbom-utility?tab=readme-ov-file#example-validate-using-custom-schema-variants). It can be referenced using the --variant flag on validate and added to config.json as described here: https://github.com/CycloneDX/sbom-utility?tab=readme-ov-file#adding-new-sbom-formats-schema-versions-and-variants (edit the sample config.json from this repo.).

Add extra required fields depending on an if-condition.

The addition of conditional logic would be very valuable indeed. However, JSON schema (or even XML schema) cannot easily accomplish this for various reasons (e.g., arrays entries are allowed to not be unique/no unique keys and ordering not guaranteed)... The aforementioned OWASP SCVS standard (which addresses maturity/policy MAY be able to eventually handle such use cases. In any event, the "custom" validation code never was able to support conditional logic (since it is not supported in JSON schema).