This utility was designed to be an API platform used initially to validate CycloneDX or SPDX Software Bills-of-Materials (BOMs) against versioned JSON schemas, as published by their respective communities, as well as customized schema variants provided by companies or organizations that have stricter BOM compliance requirements.
The utility has now grown to include a rich set of commands, listed below, that can be used for create filtered reports in many formats (e.g., csv, md) using the utility's powerful, SQL-like query capability. These commands can extract data from BOMs that enables verification of information supporting BOM use cases or any custom security and compliance requirements.
The utility supports the following commands:
-
- list produce listings or summarized reports of license data contained in a BOM along with license "usage policy" determinations using the policies declared in the
license.json
file. - policy - lists software and data license information and associated license usage policies as defined in the configurable
license.json
file.
- list produce listings or summarized reports of license data contained in a BOM along with license "usage policy" determinations using the policies declared in the
-
query produce data listings or custom reports from BOM data using SQL-style query statements (i.e.,
--select <data fields> --from <BOM object> --where <field=regex>
). -
resource produce filterable listings or summarized reports of resources, including components and services, from BOM data.
-
schema lists the "built-in" set of schema formats, versions and variants supported by the
validation
command.- Customized JSON schemas can also be permanently configured as named schema "variants" within the utility's configuration file (see the
schema
command's adding schemas section).
- Customized JSON schemas can also be permanently configured as named schema "variants" within the utility's configuration file (see the
-
validate enables validation of SBOMs against their declared format (e.g., SPDX, CycloneDX) and version (e.g., "2.2", "1.4", etc.) using their JSON schemas.
- Derivative, "customized" schemas can be used for verification using the
--variant
flag (e.g., industry or company-specific schemas). - You can override an BOM's declared BOM version using the
--force
flag (e.g., verify a BOM against a newer specification version).
- Derivative, "customized" schemas can be used for verification using the
-
vulnerability produce filterable listings or summarized reports of vulnerabilities from BOM data (i.e., CycloneDX Vulnerability Exploitability eXchange (VEX)) data or independently stored CycloneDX Vulnerability Disclosure Report (VDR) data.
- Installation
- Running
- Commands
- General information
- Exit codes: (e.g.,
0
: none,1
: application,2
: validation) - Persistent flags (e.g.,
--format
,--quiet
,--where
)
- Exit codes: (e.g.,
license
commandquery
command: extract JSON objects and fields from a BOM using SQL-like queriesresource
command: list resource information by type (e.g., components, services)schema
command: list supported BOM formats, versions, variantsvalidate
command: BOM against declared or required schemavulnerability
command: lists vulnerability summary information included in the BOM or VEXdiff
command: experimental: shows the delta between two BOM versions
- General information
- Design considerations
- Development
- Contributing
- Testing
- Releasing
- References: CycloneDX, SPDX
Download and decompress the correct archive file (i.e., .tar
for Unix/Linux systems and .zip
for Windows) for your target system's architecture and operating system from the releases page within this repository.
The archive will contain the following files:
sbom-utility
- binary executable. This is all most need for non-customized configurations.config.json
(optional) - copy of the default schema configuration file for optional customization (to be passed on the command line)license.json
(optional) - copy of the default license policy configuration file for optional customization (to be passed on the command line)custom.json
(experimental) - custom validation configuration fileLICENSE
- the software license for the utility (i.e. Apache 2)sbom-utility-<version>.sbom.json
- a simple Software Bill-of-Materials (SBOM) for the utility
For convenience, the default config.json
and optional license.json
configuration files have been embedded in the executable and used if none are provided on the command line using the --config-schema
or --config-license
flags respectively.
When providing configuration files using command line flags, the executable attempts to load them from the same path where the executable is run from. If you choose to keep them in a different directory, you will have to supply their location relative to the executable along with the filename.
On MacOS, the utility is not a registered Apple application and may warn you that it cannot open it the first time. If so, you will need to explicitly permit the executable to be "opened" on your system acknowledging it trusted. This process is initiated from the Finder application by using ctrl-click
on the executable file and agreeing using the "Open" button.
- See https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unidentified-developer-mh40616/mac
This section provides detailed descriptions of all commands, their flags and examples. First we will cover how all commands generate consistent exit codes and describe some of the persistent flags supported by most commands.
For convenience, links to each command's section are here:
All commands return a numeric exit code (i.e., a POSIX exit code) for use in automated processing where 0
indicates success and a non-zero value indicates failure of some kind designated by the number.
The SBOM Utility always returns one of these 3 codes to accommodate logic in BASH (shell) scripting:
0
= no error (valid)1
= application error2
= validation error
This example uses the schema
list command to verify its exit code:
./sbom-utility schema list
verify the exit code:
echo $?
which returns 0
(zero) or "no error":
0
This section describes some of the important command line flags that apply to most commands that have a list
subcommand for generating columnar, report-styled output (e.g., schema
, license
, vulnerability
, etc.).
- format flag: with
--format
- quiet flag: with
--quiet
or-q
- output flag: with
--output
or-o
- where flag: with
--output
or-o
Note: The validate
command does not have a list
subcommand and ignores the format
, where
and output
flags.
All list
subcommands support the --format
flag with the following values:
txt
: text (tabbed tables)csv
: Comma Separated Value (CSV), e.g., for spreadsheetsmd
: Markdown, e.g., for GitHub
Some commands, which can output lists of JSON objects, also support JSON format using the json
value.
This example uses the --format
flag on the schema
command to output in markdown:
./sbom-utility schema --format md -q
|name|format|version|variant|file (local)|url (remote)|
|:--|:--|:--|:--|:--|:--|
|CycloneDX v1.5|CycloneDX|1.5|(latest)|schema/cyclonedx/1.5/bom-1.5.schema.json|https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.5.schema.json|
|CycloneDX v1.4|CycloneDX|1.4|(latest)|schema/cyclonedx/1.4/bom-1.4.schema.json|https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.4.schema.json|
|CycloneDX/specification/master/schema/bom-1.3-strict.schema.json|
|CycloneDX v1.3|CycloneDX|1.3|(latest)|schema/cyclonedx/1.3/bom-1.3.schema.json|https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.3.schema.json|
|CycloneDX/specification/master/schema/bom-1.2-strict.schema.json|
|CycloneDX v1.2|CycloneDX|1.2|(latest)|schema/cyclonedx/1.2/bom-1.2.schema.json|https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.2.schema.json|
|SPDX v2.3.1 (development)|SPDX|SPDX-2.3|development|schema/spdx/2.3.1/spdx-schema.json|https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3.1/schemas/spdx-schema.json|
|SPDX v2.3|SPDX|SPDX-2.3|(latest)|schema/spdx/2.3/spdx-schema.json|https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3/schemas/spdx-schema.json|
|SPDX v2.2.2|SPDX|SPDX-2.2|(latest)|schema/spdx/2.2.2/spdx-schema.json|https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.2/schemas/spdx-schema.json|
|SPDX v2.2.1|SPDX|SPDX-2.2|2.2.1|schema/spdx/2.2.1/spdx-schema.json|https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.1/schemas/spdx-schema.json|
All commands support the --quiet
flag. By default, the utility outputs informational (INFO), warning (WARNING) and error (ERROR) text along with the actual command results to stdout
. If you wish to only see the command results (JSON) or report (tables) you can run any command in "quiet mode" by simply supplying the --quiet
or its short-form -q
flag.
This example shows the --quiet
flag being used on the schema
command to turn off or "quiet" any informational output so that only the result table is displayed.
./sbom-utility schema --quiet
name format version variant file (local) url (remote)
---- ------ ------- ------- ------------ ------------
CycloneDX v1.5 CycloneDX 1.5 (latest) schema/cyclonedx/1.5/bom-1.5.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.5.schema.json
CycloneDX v1.4 CycloneDX 1.4 (latest) schema/cyclonedx/1.4/bom-1.4.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.4.schema.json
CycloneDX v1.3 CycloneDX 1.3 (latest) schema/cyclonedx/1.3/bom-1.3.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.3.schema.json
CycloneDX v1.2 CycloneDX 1.2 (latest) schema/cyclonedx/1.2/bom-1.2.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.2.schema.json
SPDX v2.3.1 (development) SPDX SPDX-2.3 development schema/spdx/2.3.1/spdx-schema.json https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3.1/schemas/spdx-schema.json
SPDX v2.3 SPDX SPDX-2.3 (latest) schema/spdx/2.3/spdx-schema.json https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3/schemas/spdx-schema.json
SPDX v2.2.2 SPDX SPDX-2.2 (latest) schema/spdx/2.2.2/spdx-schema.json https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.2/schemas/spdx-schema.json
SPDX v2.2.1 SPDX SPDX-2.2 2.2.1 schema/spdx/2.2.1/spdx-schema.json https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.1/schemas/spdx-schema.json
All list
subcommands and the validate
command support the --input-file <filename>
flag (or its short-form -i <filename>
) to declare file contents (i.e., BOM data) the commands will read and operate on.
All commands that support the input flag can also accept data from standard input or stdin
by using the -
(dash) character as the value instead of a filename.
cat examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json | ./sbom-utility resource list -i -
./sbom-utility validate -i - < examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json
All list
subcommands and the validate
command support the --output-file <filename>
flag (or its short-form -o <filename>
) to send formatted output to a file.
This example uses the schema
command to output to a file named output.txt
with format set to csv
:
./sbom-utility schema --format csv -o output.csv
Verify the contents of output.csv
contain CSV formatted output:
cat output.csv
Name,Format,Version,Variant,File (local),URL (remote)
CycloneDX v1.5 (development),CycloneDX,1.5,development,schema/cyclonedx/1.5/bom-1.5-dev.schema.json,https://raw.githubusercontent.com/CycloneDX/specification/v1.5-dev/schema/bom-1.5.schema.json
CycloneDX v1.4,CycloneDX,1.4,(latest),schema/cyclonedx/1.4/bom-1.4.schema.json,https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.4.schema.json
CycloneDX v1.3,CycloneDX,1.3,(latest),schema/cyclonedx/1.3/bom-1.3.schema.json,https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.3.schema.json
CycloneDX v1.2,CycloneDX,1.2,(latest),schema/cyclonedx/1.2/bom-1.2.schema.json,https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.2.schema.json
SPDX v2.3.1 (development),SPDX,SPDX-2.3,development,schema/spdx/2.3.1/spdx-schema.json,https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3.1/schemas/spdx-schema.json
SPDX v2.3,SPDX,SPDX-2.3,(latest),schema/spdx/2.3/spdx-schema.json,https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3/schemas/spdx-schema.json
SPDX v2.2.2,SPDX,SPDX-2.2,(latest),schema/spdx/2.2.2/spdx-schema.json,https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.2/schemas/spdx-schema.json
SPDX v2.2.1,SPDX,SPDX-2.2,2.2.1,schema/spdx/2.2.1/spdx-schema.json,https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.1/schemas/spdx-schema.json
- Note: You can verify that
output.csv
loads within a spreadsheet app like MS Excel.
All list
subcommands support the --where
flag. It can be used to filter output results based upon matches to regular expressions (regex) by using the output list's column titles as keys.
Multiple key-value (i.e., column-title=regex) pairs can be provided on the same --where
filter flag using commas.
Syntax: [--where key=regex[,...]]
See each command's section for contextual examples of the --where
flag filter usage.
This command is used to aggregate and summarize software, hardware and data license information included in the SBOM. It also displays license usage policies for resources based upon concluded by SPDX license identifier, license family or logical license expressions as defined in he current policy file (i.e., license.json
).
The license
command supports the following subcommands:
- list - list or create a summarized report of licenses found in input SBOM.
- list with --summary flag - As full license information can be very large, a summary view is often most useful.
- policy - list user configured license policies by SPDX license ID, family name and other filters.
The list
subcommand produces JSON output which contains an array of CycloneDX LicenseChoice
data objects found in the BOM input file without component association. LicenseChoice
data, in general, may provide license information using registered SPDX IDs, license expressions (of SPDX IDs) or license names (not necessarily registered by SPDX). License data may also include base64-encoded license or legal text that was used to determine a license's SPDX ID or name.
This command supports the --format
flag with any of the following values:
json
(default),csv
,md
- using the
--summary
flag:txt
(default),csv
,md
- using the
- Results are not sorted for base
license list
subcommand.- using the
--summary
flag: results are sorted (ascending) by license key which can be one of licenseid
(SPDX ID),name
orexpression
.
- using the
Use the --summary
flag on the license list
command to produce a summary report in txt
(default) format as well as policy determination based upon the license.json
declarations.
This example shows a few entries of the JSON output that exhibit the three types of license data described above:
./sbom-utility license list -i examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json
[
{
"license": {
"$comment": "by license `id",
"id": "MIT",
"name": "",
"url": ""
}
},
{
"license": {
"$comment": "by license `expression",
"id": "",
"name": "",
"url": ""
},
"expression": "Apache-2.0 AND (MIT OR GPL-2.0-only)"
},
{
"license": {
"$comment": "by license `name` with full license encoding",
"id": "",
"name": "Apache 2",
"text": {
"contentType": "text/plain",
"encoding": "base64",
"content": "CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIEFwYWNoZSBMaWNlbnNlCiAgICAgICAgICAgICAgICAgICAgICAgICAgIFZlcnNpb24 ..."
},
"url": "https://www.apache.org/licenses/LICENSE-2.0.txt"
}
},
...
]
This example shows the default text output from using the summary flag:
./sbom-utility license list -i test/cyclonedx/cdx-1-3-license-list.json --summary --quiet
usage-policy license-type license resource-name bom-ref bom-location
------------ ------------ ------- ------------- ------- ------------
needs-review id ADSL Foo service:example.com/myservices/foo services
needs-review name AGPL Library J pkg:lib/[email protected] components
allow name Apache Library B pkg:lib/[email protected] components
allow id Apache-1.0 Library E pkg:lib/[email protected] components
allow id Apache-2.0 N/A N/A metadata.licenses
allow id Apache-2.0 Library A pkg:lib/[email protected] components
allow id Apache-2.0 Library F pkg:lib/[email protected] components
allow expression Apache-2.0 AND (MIT OR BSD-2-Clause) Library B pkg:lib/[email protected] components
allow name BSD Library J pkg:lib/[email protected] components
deny name CC-BY-NC Library G pkg:lib/[email protected] components
needs-review name GPL Library H pkg:lib/[email protected] components
needs-review id GPL-2.0-only Library C pkg:lib/[email protected] components
needs-review id GPL-3.0-only Library D pkg:lib/[email protected] components
allow id MIT ACME Application pkg:app/[email protected] metadata.component
allow id MIT Library A pkg:lib/[email protected] components
UNDEFINED invalid NOASSERTION Library NoLicense pkg:lib/[email protected] components
UNDEFINED invalid NOASSERTION Bar service:example.com/myservices/bar services
needs-review name UFL ACME Application pkg:app/[email protected] metadata.component
- Notes
- Usage policy column values are derived from the
license.json
policy configuration file.- A
usage policy
value ofUNDEFINED
indicates thatlicense.json
provided no entry that matched the declared license (id
orname
) in the SBOM.
- A
- License expressions (e.g.,
(MIT or GPL-2.0)
) with one term resolving toUNDEFINED
and the the other term having a concrete policy will resolve to the "optimistic" policy forOR
expressions and the "pessimistic" policy forAND
expressions. In addition, a warning of this resolution is emitted.
- Usage policy column values are derived from the
The list command results can be filtered using the --where
flag using the column names in the report. These include usage-policy
, license-type
, license
, resource-name
, bom-ref
and bom-location
.
The following example shows filtering of component licenses using the license-type
column where the license was described as a name
value:
./sbom-utility license list -i test/cyclonedx/cdx-1-3-license-list.json --summary --where license-type=name --quiet
usage-policy license-type license resource-name bom-ref bom-location
------------ ------------ ------- ------------- ------- ------------
needs-review name AGPL Library J pkg:lib/[email protected] components
allow name Apache Library B pkg:lib/[email protected] components
allow name BSD Library J pkg:lib/[email protected] components
deny name CC-BY-NC Library G pkg:lib/[email protected] components
needs-review name GPL Library H pkg:lib/[email protected] components
needs-review name UFL ACME Application pkg:app/[email protected] metadata.component
In another example, the list is filtered by the usage-policy
where the value is needs-review
:
./sbom-utility license list -i test/cyclonedx/cdx-1-3-license-list.json --summary --where usage-policy=needs-review --quiet
usage-policy license-type license resource-name bom-ref bom-location
------------ ------------ ------- ------------- ------- ------------
needs-review id ADSL Foo service:example.com/myservices/foo services
needs-review name AGPL Library J pkg:lib/[email protected] components
needs-review name GPL Library H pkg:lib/[email protected] components
needs-review id GPL-2.0-only Library C pkg:lib/[email protected] components
needs-review id GPL-3.0-only Library D pkg:lib/[email protected] components
needs-review name UFL ACME Application pkg:app/[email protected] metadata.component
To view a report listing the contents of the current policy file (i.e., license.json
) which contains an encoding of known software and data licenses by SPDX ID and license family along with a configurable usage policy (i.e., "allow"
, "deny"
or "needs-review"
).
This command supports the --format
flag with any of the following values:
txt
(default),csv
,md
- Results are sorted by license policy
family
.
Use the --summary
flag on the license policy list
command to produce a summary report with a reduced set of column data (i.e., it includes only the following columns: usage-policy
, family
, id
, name
, oci
(approved) fsf
(approved), deprecated
, and SPDX reference
URL).
Use the --wrap
flag to toggle the wrapping of text within columns of the license policy report (txt
format only) output using the values true
or false
. The default value is false
.
./sbom-utility license policy --quiet
usage-policy family id name osi fsf deprecated reference aliases annotations notes
------------ ------ -- ---- --- --- ---------- --------- ------- ----------- -----
allow 0BSD 0BSD BSD Zero Clause License true false false https://spdx.org/licenses/0BSD.html Free Public License 1.0.0 APPROVED none
needs-review ADSL ADSL Amazon Digital Services License false false false https://spdx.org/licenses/ADSL.html none NEEDS-APPROVAL none
allow AFL AFL-3.0 Academic Free License v3.0 true true false https://spdx.org/licenses/AFL-3.0.html none APPROVED none
needs-review AGPL AGPL-1.0 Affero General Public License v1.0 false false true https://spdx.org/licenses/AGPL-1.0.html none NEEDS-APPROVAL,AGPL-WARNING none
allow Adobe Adobe-2006 Adobe Systems Incorporated CLA false false false https://spdx.org/licenses/Adobe-2006.html none APPROVED none
allow Apache Apache-2.0 Apache License 2.0 true true false https://spdx.org/licenses/Apache-2.0.html Apache License, Version 2.0 APPROVED none
allow Artistic Artistic-1.0 Artistic License 1.0 true false false https://spdx.org/licenses/Artistic-1.0.html none APPROVED none
...
We can also apply the --summary
flag to get a reduced set of columns that includes only the usage-policy
along with the essential SDPX license information (e.g., no annotations or notes).
./sbom-utility license policy --summary --quiet
usage-policy family id name osi fsf deprecated reference
------------ ------ -- ---- --- --- ---------- ---------
allow 0BSD 0BSD BSD Zero Clause License true false false https://spdx.org/licenses/0BSD.html
needs-review ADSL ADSL Amazon Digital Services License false false false https://spdx.org/licenses/ADSL.html
allow AFL AFL-3.0 Academic Free License v3.0 true true false https://spdx.org/licenses/AFL-3.0.html
needs-review AGPL AGPL-1.0 Affero General Public License v1.0 false false true https://spdx.org/licenses/AGPL-1.0.html
allow Adobe Adobe-2006 Adobe Systems Incorporated CLA false false false https://spdx.org/licenses/Adobe-2006.html
allow Apache Apache-2.0 Apache License 2.0 true true false https://spdx.org/licenses/Apache-2.0.html
allow Artistic Artistic-1.0 Artistic License 1.0 true true false https://spdx.org/licenses/Artistic-2.0.html
...
The following example shows filtering of license policies using the id
column:
./sbom-utility license policy --where id=Apache
usage-policy family id name osi fsf deprecated reference aliases annotations notes
------------ ------ -- ---- --- --- ---------- --------- ------- ----------- -----
allow Apache Apache-1.0 Apache v1.0 false true false https://spdx.org/licenses/Apache-1.0.html none APPROVED none
allow Apache Apache-1.1 Apache v1.1 true true false https://spdx.org/licenses/Apache-1.1.html none APPROVED Superseded by Apache-2.0
allow Apache Apache-2.0 Apache License 2.0 true true false https://spdx.org/licenses/Apache-2.0.html Apache License APPROVED none
./sbom-utility license policy --quiet --wrap=true
usage-policy family id name osi fsf deprecated reference aliases annotations notes
------------ ------ -- ---- --- --- ---------- --------- ------- ----------- -----
allow 0BSD 0BSD BSD Zero Clause Lice (20/23) true false false https://spdx.org/licenses/0BSD.html Free Public License 1.0. (24/25) APPROVED none
needs-review ADSL ADSL Amazon Digital Servi (20/31) false false false https://spdx.org/licenses/ADSL.html NEEDS-APPROVAL none
allow AFL AFL-3.0 Academic Free Licens (20/26) true true false https://spdx.org/licenses/AFL-3.0.ht (36/38) APPROVED none
needs-review AGPL AGPL-1.0 Affero General Publi (20/34) false false true https://spdx.org/licenses/AGPL-1.0.h (36/39) NEEDS-APPROVAL none
AGPL-WARNING
needs-review APSL APSL-2.0 Apple Public Source (20/31) true true false https://spdx.org/licenses/APSL-2.0.h (36/39) NEEDS-APPROVAL none
allow Adobe Adobe-2006 Adobe Systems Incorp (20/56) false false false https://spdx.org/licenses/Adobe-2006 (36/41) APPROVED none
allow Apache Apache-2.0 Apache License 2.0 true true false https://spdx.org/licenses/Apache-2.0 (36/41) Apache License, Version (24/27) APPROVED none
allow Artistic Artistic-2.0 Artistic License 2.0 true true false https://spdx.org/licenses/Artistic-2 (36/43) APPROVED none
...
- Currently, the default
license.json
file, used to derive theusage-policy
data, does not contain entries for the entire set of SPDX 3.2 license templates.- An issue 12 is open to add parity.
- Annotations (tags) and notes can be defined within the
license.json
file and one or more assigned each license entry.
- For backwards compatibility, the
--where
filter supports the keyspdx-id
as an alias forid
.
This command allows you to perform SQL-like queries into JSON format SBOMs. Currently, the command recognizes the --select
and --from
as well as the --where
filter.
The --from
clause value is applied to the JSON document object model and can return either a singleton JSON object or an array of JSON objects as a result. This is determined by the last property value's type as declared in the schema.
The --select
clause is then applied to the --from
result set to only return the specified properties (names and their values).
If the result set is an array, the array entries can be reduced by applying the --where
filter to ony return those entries whose specified field names match the supplied regular expression (regex).
Note: All query
command results are returned as valid JSON documents. This includes a null
value for empty result sets.
The query
command only supports JSON output.
The query
command does not support output results.
This example effectively extracts the first-order package manifest from the SBOM.
In this example, only the --from
clause is needed to select an object. The --select
clause is omitted which is equivalent to using the "select all" wildcard character *
which returns all fields and values from the component
object.
./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --from metadata.component
is equivalent to using the wildcard character (which may need to be enclosed in single or double quotes depending on your shell):
./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --select '*' --from metadata.component --quiet
{
"name": "Example Application v10.0.4",
"bom-ref": "pkg:oci/example.com/product/[email protected]",
"description": "Example's Do-It-All application",
"externalReferences": [
{
"type": "website",
"url": "https://example.com/application"
}
],
"hashes": [
{
"alg": "SHA-1",
"content": "1111aaaa2222cccc3333dddd4444eeee5555ffff"
}
],
"licenses": [
{
"license": {
"id": "Apache-2.0"
}
}
],
...
In this example, the --from
clause references the top-level metadata.supplier
object.
./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --from metadata.supplier --quiet
{
"contact": [
{
"email": "[email protected]"
}
],
"name": "Example Co. Distribution Dept.",
"url": [
"https://example.com/software/"
]
}
In this example, the --from
clause references the singleton JSON object component
found under the top-level metadata
object. It then reduces the resultant JSON object to only return the name
and value
fields and their values as requested on the --select
clause.
./sbom-utility query --select name,version --from metadata.component -i examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json
{
"name": "juice-shop",
"version": "11.1.2"
}
In this example, the --where
filter will be applied to a set of properties
results to only include entries that match the specified regex.
./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --from metadata.properties --where name=urn:example.com:classification
[
{
"name": "urn:example.com:classification",
"value": "This SBOM is Confidential Information. Do not distribute."
}
]
additionally, you can apply a --select
clause to simply obtain the matching entry's value
:
./sbom-utility query -i test/cyclonedx/cdx-1-4-mature-example-1.json --select value --from metadata.properties --where name=urn:example.com:classification
[
{
"value": "This SBOM is Confidential Information. Do not distribute."
}
]
The resource
command is geared toward inspecting various resources types and their information from SBOMs against future maturity models being developed as part of the OWASP Software Component Verification Standard (SCVS). In the SCVS model, a "resource" is the parent classification for software (components), services, Machine Learning (ML) models, data, hardware, tools and more.
Primarily, the command is used to generate lists of resources, by type, that are included in a CycloneDX SBOM by invoking resource list
.
This command supports the --format
flag with any of the following values:
txt
(default),csv
,md
Currently, all resource list
command results are sorted by resource type
then by resource name
(required field).
./sbom-utility resource list -i test/cyclonedx/cdx-1-3-resource-list.json --quiet
type name version bom-ref
---- ---- ------- -------
component ACME Application 2.0.0 pkg:app/[email protected]
component Library A 1.0.0 pkg:lib/[email protected]
component Library B 1.0.0 pkg:lib/[email protected]
component Library C 1.0.0 pkg:lib/[email protected]
component Library D 1.0.0 pkg:lib/[email protected]
component Library E 1.0.0 pkg:lib/[email protected]
component Library F 1.0.0 pkg:lib/[email protected]
component Library G 1.0.0 pkg:lib/[email protected]
component Library H 1.0.0 pkg:lib/[email protected]
component Library J 1.0.0 pkg:lib/[email protected]
component Library NoLicense 1.0.0 pkg:lib/[email protected]
service Bar service:example.com/myservices/bar
service Foo service:example.com/myservices/foo
This example uses the type
flag to specific service
. The other valid type is component
. Future versions of CycloneDX schema will include more resource types such as "ml" (machine learning) or "tool".
./sbom-utility resource list -i test/cyclonedx/cdx-1-3-resource-list.json --type service --quiet
type name version bom-ref
---- ---- ------- -------
service Bar service:example.com/myservices/bar
service Foo service:example.com/myservices/foo
This example uses the where
filter on the name
field. In this case we supply an exact "startswith" regex. for the name
filter.
./sbom-utility resource list -i test/cyclonedx/cdx-1-3-resource-list.json --where "name=Library A" --quiet
type name version bom-ref
---- ---- ------- -------
component Library A 1.0.0 pkg:lib/[email protected]
You can verify which formats, schemas, versions and variants are available for validation by using the schema
command:
./sbom-utility schema list
- Note: The
schema
command will default to thelist
subcommand if omitted.
This command supports the --format
flag with any of the following values:
txt
(default),csv
,md
- Formatted results are sorted by
format
(ascending),version
(descending) andschema
(descending)
name format version variant file (local) url (remote)
---- ------ ------- ------- ------------ ------------
CycloneDX v1.5 (development) CycloneDX 1.5 development schema/cyclonedx/1.5/bom-1.5-dev.schema.json https://raw.githubusercontent.com/CycloneDX/specification/v1.5-dev/schema/bom-1.5.schema.json
CycloneDX v1.4 CycloneDX 1.4 (latest) schema/cyclonedx/1.4/bom-1.4.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.4.schema.json
CycloneDX v1.3 (strict) CycloneDX 1.3 strict schema/cyclonedx/1.3/bom-1.3-strict.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.3-strict.schema.json
CycloneDX v1.3 CycloneDX 1.3 (latest) schema/cyclonedx/1.3/bom-1.3.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.3.schema.json
CycloneDX v1.2 (strict) CycloneDX 1.2 strict schema/cyclonedx/1.2/bom-1.2-strict.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.2-strict.schema.json
CycloneDX v1.2 CycloneDX 1.2 (latest) schema/cyclonedx/1.2/bom-1.2.schema.json https://raw.githubusercontent.com/CycloneDX/specification/master/schema/bom-1.2.schema.json
SPDX v2.3.1 (development) SPDX SPDX-2.3 development schema/spdx/2.3.1/spdx-schema.json https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3.1/schemas/spdx-schema.json
SPDX v2.3 SPDX SPDX-2.3 (latest) schema/spdx/2.3/spdx-schema.json https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3/schemas/spdx-schema.json
SPDX v2.2.2 SPDX SPDX-2.2 (latest) schema/spdx/2.2.2/spdx-schema.json https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.2/schemas/spdx-schema.json
SPDX v2.2.1 SPDX SPDX-2.2 2.2.1 schema/spdx/2.2.1/spdx-schema.json https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.1/schemas/spdx-schema.json
Entries for new or "custom" schemas can be added to the config.json
file by adding a new schema entry and then will need to pass that file on the command line using the --config-schema
flag.
These new schema entries will tell the schema loader where to find the JSON schema file locally, relative to the utility's executable.
For details see the "Adding SBOM formats, schema versions and variants" section.
If you wish to have the new schema embedded in the executable, simply add it to the project's resources
subdirectory following the format and version-based directory structure.
This command will parse standardized SBOMs and validate it against its declared format and version (e.g., SPDX 2.2, CycloneDX 1.4). Custom variants of standard JSON schemas can be used for validation by supplying the --variant
name as a flag. Explicit JSON schemas can be specified using the --force
flag.
Use the schema command to list supported schemas formats, versions and variants.
Customized JSON schemas can also be permanently configured as named schema "variants" within the utility's configuration file. See adding schemas.
The following flags can be used to improve performance when formatting error output results:
Use the --error-limit x
(default: 10
) flag to reduce the formatted error result output to the first x
errors. By default, only the first 10 errors are output with an informational messaging indicating x/y
errors were shown.
Use the --error-value=true|false
(default: true
) flag to reduce the formatted error result output by not showing the value
field which shows detailed information about the failing data in the BOM.
Use the --colorize=true|false
(default: false
) flag to add/remove color formatting to error result txt
formatted output. By default, txt
formatted error output is colorized to help with human readability; for automated use, it can be turned off.
Validating the "juice shop" SBOM (CycloneDX 1.2) example provided in this repository.
./sbom-utility validate -i examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json
[INFO] Loading license policy config file: `license.json`...
[INFO] Attempting to load and unmarshal file `examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json`...
[INFO] Successfully unmarshalled data from: `examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json`
[INFO] Determining file's SBOM format and version...
[INFO] Determined SBOM format, version (variant): `CycloneDX`, `1.2` (latest)
[INFO] Matching SBOM schema (for validation): schema/cyclonedx/1.2/bom-1.2.schema.json
[INFO] Loading schema `schema/cyclonedx/1.2/bom-1.2.schema.json`...
[INFO] Schema `schema/cyclonedx/1.2/bom-1.2.schema.json` loaded.
[INFO] Validating `examples/cyclonedx/BOM/juice-shop-11.1.2/bom.json`...
[INFO] SBOM valid against JSON schema: `true`
You can also verify the exit code from the validate command:
$ echo $?
0 // no error (valid)
The validation command will use the declared format and version found within the SBOM JSON file itself to lookup the default (latest) matching schema version (as declared inconfig.json
; however, if variants of that same schema (same format and version) are declared, they can be requested via the --variant
command line flag:
./sbom-utility validate -i test/custom/cdx-1-4-test-custom-metadata-property-disclaimer-invalid.json --variant custom
If you run the sample command above, you would see several "custom" schema errors resulting in an invalid SBOM determination (i.e., exit status 2
):
[INFO] Loading license policy config file: `license.json`...
[INFO] Attempting to load and unmarshal file `test/custom/cdx-1-4-test-custom-metadata-property-disclaimer-invalid.json`...
[INFO] Successfully unmarshalled data from: `test/custom/cdx-1-4-test-custom-metadata-property-disclaimer-invalid.json`
[INFO] Determining file's SBOM format and version...
[INFO] Determined SBOM format, version (variant): `CycloneDX`, `1.4` (custom)
[INFO] Matching SBOM schema (for validation): schema/test/bom-1.4-custom.schema.json
[INFO] Loading schema `schema/test/bom-1.4-custom.schema.json`...
[INFO] Schema `schema/test/bom-1.4-custom.schema.json` loaded.
[INFO] Validating `test/custom/cdx-1-4-test-custom-metadata-property-disclaimer-invalid.json`...
[INFO] SBOM valid against JSON schema: `false`
[ERROR] invalid SBOM: schema errors found (test/custom/cdx-1-4-test-custom-metadata-property-disclaimer-invalid.json):
(3) Schema errors detected (use `--debug` for more details):
1. Type: [contains], Field: [metadata.properties], Description: [At least one of the items must match]
Failing object: [[
{
"name": "urn:example.com:disclaimer",
"value": "This ... (truncated)
2. Type: [const], Field: [metadata.properties.0.value], Description: [metadata.properties.0.value does not match: "This SBOM is current as of the date it was generated and is subject to change."]
Failing object: ["This SBOM is current as of the date it was generated."]
3. Type: [number_all_of], Field: [metadata.properties], Description: [Must validate all the schemas (allOf)]
Failing object: [[
{
"name": "urn:example.com:disclaimer",
"value": "This ... (truncated)
[INFO] document `test/custom/cdx-1-4-test-custom-metadata-property-disclaimer-invalid.json`: valid=[false]
exit status 2
The output shows a first schema error indicating the failing JSON object; in this case,
- the CycloneDX
metadata.properties
field, which is a list ofproperty
objects. - Found that a property with a
name
field with the value"urn:example.com:disclaimer"
had an incorrectvalue
.- the
value
field SHOULD have had a constant value of"This SBOM is current as of the date it was generated and is subject to change."
(as was required by the custom schema's regex). - However, it was found to have only a partial match of
"This SBOM is current as of the date it was generated."
.
- the
Use the --debug
or -d
flag to see all schema error details:
./sbom-utility validate -i test/custom/cdx-1-4-test-custom-metadata-property-disclaimer-invalid.json --variant custom -d
The details include the full context of the failing metadata.properties
object which also includes a "urn:example.com:classification"
property:
3. Type: [number_all_of], Field: [metadata.properties], Description: [Must validate all the schemas (allOf)]
Failing object: [[
{
"name": "urn:example.com:disclaimer",
"value": "This SBOM is current as of the date it was generated."
},
{
"name": "urn:example.com:classification",
"value": "This SBOM is Confidential Information. Do not distribute."
}
]]
The JSON format will provide an array
of schema error results that can be post-processed as part of validation toolchain.
./sbom-utility validate -i test/validation/cdx-1-4-validate-err-components-unique-items-1.json --format json --quiet
[
{
"type": "unique",
"field": "components",
"context": "(root).components",
"description": "array items[1,2] must be unique",
"value": {
"type": "array",
"index": 1,
"item": {
"bom-ref": "pkg:npm/[email protected]",
"description": "Node.js body parsing middleware",
"hashes": [
{
"alg": "SHA-1",
"content": "96b2709e57c9c4e09a6fd66a8fd979844f69f08a"
}
],
"licenses": [
{
"license": {
"id": "MIT"
}
}
],
"name": "body-parser",
"purl": "pkg:npm/[email protected]",
"type": "library",
"version": "1.19.0"
}
}
},
{
"type": "unique",
"field": "components",
"context": "(root).components",
"description": "array items[2,4] must be unique",
"value": {
"type": "array",
"index": 2,
"item": {
"bom-ref": "pkg:npm/[email protected]",
"description": "Node.js body parsing middleware",
"hashes": [
{
"alg": "SHA-1",
"content": "96b2709e57c9c4e09a6fd66a8fd979844f69f08a"
}
],
"licenses": [
{
"license": {
"id": "MIT"
}
}
],
"name": "body-parser",
"purl": "pkg:npm/[email protected]",
"type": "library",
"version": "1.19.0"
}
}
}
]
In many cases, BOMs may have many errors and having the value
information details included can be too verbose and lead to large output files to inspect. In those cases, simply set the error-value
flag to false
.
Rerunning the same command with this flag set to false yields a reduced set of information.
./sbom-utility validate -i test/validation/cdx-1-4-validate-err-components-unique-items-1.json --format json --error-value=false --quiet
[
{
"type": "unique",
"field": "components",
"context": "(root).components",
"description": "array items[1,2] must be unique"
},
{
"type": "unique",
"field": "components",
"context": "(root).components",
"description": "array items[2,4] must be unique"
}
]
This command will extract basic vulnerability report data from an SBOM that has a "vulnerabilities" list or from a standalone VEX in CycloneDX format. It includes the ability to filter reports data by applying regex to any of the named column data.
Use the --format
flag on the to choose one of the supported output formats:
- txt (default), csv, md
txt
,csv
andmd
formatted results are sorted by vulnerabilityid
(descending) then bycreated
date (descending).json
results are not sorted
The list
subcommand provides a complete view of most top-level, vulnerability fields.
./sbom-utility vulnerability list -i test/vex/cdx-1-3-example1-bom-vex.json --quiet
id bom-ref cwe-ids cvss-severity source-name source-url published updated created rejected analysis-state analysis-justification description
-- ------- ------- ------------- ----------- ---------- --------- ------- ------- -------- -------------- ---------------------- -----------
CVE-2022-42004 502 CVSSv31: 7.5 (high) NVD https://nvd.nist.gov/vuln/detail/CVE-2022-42004 2022-10-02 2022-10-02 2022-10-02 UNDEFINED UNDEFINED In FasterXML jackson-databind before 2.13.4, resource exhaustion can occur because of a lack of a check in BeanDeserializer._deserializeFromArray to prevent use of deeply nested arrays. An application is vulnerable only with certain customized choices for deserialization.
CVE-2022-42003 502 CVSSv31: 7.5 (high) NVD https://nvd.nist.gov/vuln/detail/CVE-2022-42003 2022-10-02 2022-10-02 2022-10-02 UNDEFINED UNDEFINED In FasterXML jackson-databind before 2.14.0-rc1, resource exhaustion can occur because of a lack of a check in primitive value deserializers to avoid deep wrapper array nesting, when the UNWRAP_SINGLE_VALUE_ARRAYS feature is enabled. Additional fix version in 2.13.4.1 and 2.12.17.1
CVE-2020-25649 611 CVSSv31: 7.5 (high), CVSSv31: 8.2 (high), CVSSv31: 0 (none) NVD https://nvd.nist.gov/vuln/detail/CVE-2020-25649 2020-12-03 2023-02-02 2020-12-03 not_affected code_not_reachable com.fasterxml.jackson.core:jackson-databind is a library which contains the general-purpose data-binding functionality and tree-model for Jackson Data Processor. Affected versions of this package are vulnerable to XML External Entity (XXE) Injection. A flaw was found in FasterXML Jackson Databind, where it does not have entity expansion secured properly in the DOMDeserializer class. The highest threat from this vulnerability is data integrity.
This example shows the default text output from using the --summary
flag:
./sbom-utility vulnerability list -i test/vex/cdx-1-3-example1-bom-vex.json --quiet --summary
id cvss-severity source-name published description
-- ------------- ----------- --------- -----------
CVE-2022-42004 CVSSv31: 7.5 (high) NVD 2022-10-02 In FasterXML jackson-databind before 2.13.4, resource exhaustion can occur because of a lack of a check in BeanDeserializer._deserializeFromArray to prevent use of deeply nested arrays. An application is vulnerable only with certain customized choices for deserialization.
CVE-2022-42003 CVSSv31: 7.5 (high) NVD 2022-10-02 In FasterXML jackson-databind before 2.14.0-rc1, resource exhaustion can occur because of a lack of a check in primitive value deserializers to avoid deep wrapper array nesting, when the UNWRAP_SINGLE_VALUE_ARRAYS feature is enabled. Additional fix version in 2.13.4.1 and 2.12.17.1
CVE-2020-25649 CVSSv31: 7.5 (high) NVD 2020-12-03 com.fasterxml.jackson.core:jackson-databind is a library which contains the general-purpose data-binding functionality and tree-model for Jackson Data Processor. Affected versions of this package are vulnerable to XML External Entity (XXE) Injection. A flaw was found in FasterXML Jackson Databind, where it does not have entity expansion secured properly in the DOMDeserializer class. The highest threat from this vulnerability is data integrity.
./sbom-utility vulnerability list -i test/vex/cdx-1-3-example1-bom-vex.json --quiet --where description=XXE
id bom-ref cwe-ids cvss-severity source-name source-url published updated created rejected analysis-state analysis-justification description
-- ------- ------- ------------- ----------- ---------- --------- ------- ------- -------- -------------- ---------------------- -----------
CVE-2020-25649 611 CVSSv31: 7.5 (high), CVSSv31: 8.2 (high), CVSSv31: 0 (none) NVD https://nvd.nist.gov/vuln/detail/CVE-2020-25649 2020-12-03 2023-02-02 2020-12-03 not_affected code_not_reachable com.fasterxml.jackson.core:jackson-databind is a library which contains the general-purpose data-binding functionality and tree-model for Jackson Data Processor. Affected versions of this package are vulnerable to XML External Entity (XXE) Injection. A flaw was found in FasterXML Jackson Databind, where it does not have entity expansion secured properly in the DOMDeserializer class. The highest threat from this vulnerability is data integrity.
./sbom-utility vulnerability list -i test/vex/cdx-1-3-example1-bom-vex.json --quiet --where analysis-state=not_affected
id bom-ref cwe-ids cvss-severity source-name source-url published updated created rejected analysis-state analysis-justification description
-- ------- ------- ------------- ----------- ---------- --------- ------- ------- -------- -------------- ---------------------- -----------
CVE-2020-25649 611 CVSSv31: 7.5 (high), CVSSv31: 8.2 (high), CVSSv31: 0 (none) NVD https://nvd.nist.gov/vuln/detail/CVE-2020-25649 2020-12-03 2023-02-02 2020-12-03 not_affected code_not_reachable com.fasterxml.jackson.core:jackson-databind is a library which contains the general-purpose data-binding functionality and tree-model for Jackson Data Processor. Affected versions of this package are vulnerable to XML External Entity (XXE) Injection. A flaw was found in FasterXML Jackson Databind, where it does not have entity expansion secured properly in the DOMDeserializer class. The highest threat from this vulnerability is data integrity.
This experimental command will compare two BOMs and return the delta (or "diff") in JSON (diff-patch format) or text.
Notes
- This command is undergoing analysis and tests which are exposing some underlying issues around "moved" objects in dependent diff-patch packages that may not be fixable and have no alternatives.
- Specifically, the means by which "moved" objects are assigned "similarity" scores appears flawed in the case of JSON.
- Additionally, some of the underlying code relies upon Go maps which do not preserve key ordering.
Use the --format
flag on the to choose one of the supported output formats:
- txt (default), json
./sbom-utility diff -i test/diff/json-array-order-change-with-add-and-delete-base.json -r test/diff/json-array-order-change-with-add-and-delete-delta.json --quiet --format txt --colorize=true
{
"licenses": [
0: {
"license": {
- "id": "Apache-1.0"
+ "id": "GPL-2.0"
}
},
-+ 2=>1: {
-+ "license": {
-+ "id": "GPL-3.0-only"
-+ }
-+ },
2: {
"license": {
"id": "GPL-3.0-only"
}
},
3: {
"license": {
"id": "MIT"
}
}
]
}
The utility supports the help
command for the root command as well as any supported commands
For example, to list top-level (root command) help which lists the supported "Available Commands":
./sbom-utility help
A specific command-level help listing is also available. For example, you can access the help for the validate
command:
./sbom-utility help validate
The utility itself is written in Go
to advantage the language's built-in typing enforcement and memory safe features and its ability to be compiled for a wide range of target platforms and architectures.
The utility also is designed to produce output formats (e.g., JSON) and handle exit codes consistently to make it immediately useful standalone or as part of automated Continuous Integration (CI) tool chains for downstream use or inspection.
Further commands and reports are planned that prioritize use cases that enable greater insight and analysis of the legal, security and compliance data captured in the SBOM such as component provenance and signage (e.g., verifying resource identities by hashes or fingerprints).
In addition, inclusion of Continuous Integration and Delivery (CI/CD) or "build integrity" information around the BOM component is anticipated as part of the CycloneDX Formulation work which will require features for workflow insights.
The utility additionally prioritizes commands that help provide insight into contents of the BOM to search for and report on missing (i.e., completeness) or specific data requirements (e.g., organization or customer-specific requirements).
In general, the goal of these prioritized commands is to support data verification for many of the primary BOM use cases as identified by the CycloneDX community (see https://cyclonedx.org/use-cases/). Functional development has focused on those use cases that verify inventory (resource identity), legal compliance (e.g., license), and security analysis (e.g., vulnerability) which are foundational to any SBOM.
In the future, we envision support for additional kinds of BOMs (e.g., Hardware (HBOM), Machine Learning (MLBOM), etc.) with each again having different data requirements and levels of maturity which will increase the need for domain-specific validation. Specifically, this utility intends to support the work of the OWASP Software Component Verification Standard (SCVS) which is defining a BOM Maturity Model (BMM).
- Go v1.20.1 or higher: see https://go.dev/doc/install
git
client: see https://git-scm.com/downloads
To build an executable of the utility compatible with your local computer's architecture use the build
target in the project's Makefile
:
cd sbom-utility/
make build
The will produce a binary named sbom-utility
with version set to latest
in the project's release
directory.
$ ls
-rwxr-xr-x 1 User1 staff 11501122 Jan 24 08:29 sbom-utility
$ ./sbom-utility version
Welcome to the sbom-utility! Version `latest` (sbom-utility) (darwin/arm64)
Note The binary created using make build
will be for the local system's operating system and architecture (i.e., GOOS
, GOARCH
). This would effectively match what would be reported using the uname -s -m
unix command when run on the same local system.
If you wish to build binaries for all supported combinations of GOOS
and GOARCH
values, use the release
target (i.e., make release
) which will produce named binaries of the form sbom-utility-${GOOS}-${GOARCH}
under the release
directory (e.g., sbom-utility-darwin-amd64
).
Developers can run using the current source code in their local branch using go run main.go
. For example:
go run main.go validate -i test/cyclonedx/cdx-1-4-mature-example-1.json
This project was developed using VSCode and can be seamlessly loaded as a project.
In order to see global variables while debugging a specific configuration, you can add the "showGlobalVariables": true
to it within your launch.json
config. file:
{
"showGlobalVariables": true,
"name": "Test name",
"type": "go",
"request": "launch",
"mode": "debug",
"program": "main.go",
"args": ["validate", "-i", "test/cyclonedx/cdx-1-3-min-required.json","-t"]
},
or add it globally to the settings.json
file:
- Use
Command-Shift-P
to opensettings.json
- Select "Preferences: Open Settings (JSON)"
- Add the following block at the top level:
"go.delveConfig": {
"showGlobalVariables": true
},
Note: The showGlobalVariables
setting was only recently disabled as the default in VSCode as a stop-gap measure due to performance (loading) problems under Windows.
The utility uses the config.json
file (either the default, embedded version or the equivalent provided on the command line using --config-schema
flag) to lookup supported formats and their associated versioned JSON schema files. To add another SBOM format simply add another entry to the format
array in the root of the document:
{
"canonicalName": "SPDX",
"propertyKeyFormat": "SPDXID",
"propertyKeyVersion": "spdxVersion",
"propertyValueFormat": "SPDXRef-DOCUMENT",
"schemas": [
{
...
}
]
...
}
The value for propertyKeyFormat
should be the exact name of key field that would appear in the JSON SBOM itself which can be used to confirm it is indeed a format match. In addition, the corresponding value to match for that key should be declared in the propertyValueFormat
value.
The fields canonicalName
, propertyKeyFormat
, propertyKeyVersion
, and propertyValueFormat
are required. The format
object MUST have at least one valid schema
object. The schema
object appears as follows:
{
"version": "SPDX-2.2",
"file": "file://schema/spdx/2.2.1/spdx-schema.json",
"url": "https://raw.githubusercontent.com/spdx/spdx-spec/v2.2.1/schemas/spdx-schema.json",
"strict": false,
"latest": true,
"variant": ""
},
- Add a copy of the JSON schema file locally in the project under the structure
resources/schema/<format>/<version>/<schema filename>
.- Note If the schema exists under the
resources
directory, it will automatically be embedded in in the executable binary when built usinggo build
which includes using the project'sMakefile
.
- Note If the schema exists under the
- Assure only one
schema
object entry for a given format and version has the valuelatest
set totrue
. This latest schema will be used when the SBOM being validated does not have a clear version declared or used with the--force latest
flag. - If you have a customized or "variant" version of a schema (with the same format and version values) you wish to use for validation (e.g., a
corporate
orstaging
version with added requirements or for testing an unreleased version), you can create an entry that has the sameversion
as another entry, but also declare itsvariant
name (non-empty value). This value can be supplied on the commend line with the--variant <variant name>
flag to force the validator to use it instead of the default (empty variant value).
Contributions are welcome under the Apache 2.0 license.
The entirety of the code contains the tag "TODO" with comments of things that are features or improvements conceived while authoring the base functionality. Most of these do not have active issues opened form them.
Feel free to "grep" for the "TODO" tag, open an issue and/or submit a draft PR.
An ad-hoc list of featured "TODOs" geared at making the tool more accessible, extensible and useful especially around "core" commands such as validation.
- Merge command Support merge of two (both validated) SBOMs with de-duplication and configurable. Please note that some method of normalization prior to merge will be necessary.
- Remote Schema loading Support using SBOM schema files that are remotely hosted (network accessible) from known, trusted source locations (e.g., releases of SPDX, CycloneDX specification schemas). Note that the config file has an existing
url
field per entry that can be used for this purpose. - --orderby Support ordering of query result sets by comparison of values from a specified field key.
- license.json Document license policy configuration JSON schema structure and how to add entries relative to a CycloneDX
LicenseChoice
object for entries with SPDX IDs and those without. - license.json Add entries for all SPDX licenses listed in v3.21.
- See issue: CycloneDX#12
- Go libraries Replace
go-prettyjson
,go-multimap
libraries with alternatives that produce maintained releases.
The utility uses the config.json
file to lookup supported BOM formats and their associated versioned schemas. To add another SBOM format simply add another entry to the format
array in the root of the document:
{
"canonicalName": "SPDX",
"propertyKeyFormat": "SPDXID",
"propertyKeyVersion": "spdxVersion",
"propertyValueFormat": "SPDXRef-DOCUMENT",
"schemas": [
{
...
}
]
...
}
The value for propertyKeyFormat
should be the exact name of key field that would appear in the JSON SBOM itself which can be used to confirm it is indeed a format match. In addition, the corresponding value to match for that key should be declared in the propertyValueFormat
value.
The fields canonicalName
, propertyKeyFormat
, propertyKeyVersion
, and propertyValueFormat
are required. The format
object MUST have at least one valid schema
object.
An example schema
object for the canonical SPDX v2.3 (default, no variant) schema appears as follows:
{
{
"version": "SPDX-2.3",
"variant": "",
"name": "SPDX v2.3",
"file": "schema/spdx/2.3/spdx-schema.json",
"development": "https://github.com/spdx/spdx-spec/blob/development/v2.3/schemas/spdx-schema.json",
"url": "https://raw.githubusercontent.com/spdx/spdx-spec/development/v2.3/schemas/spdx-schema.json",
"default": true
},
},
- Add a copy of the JSON schema file locally in the project under the structure
resources/schema/<format>/<version>/<schema filename>
.- Note If the schema exists under the
resources
directory, it will automatically be embedded in in the executable binary when built usinggo build
which includes using the project'sMakefile
.
- Note If the schema exists under the
- Assure only one
schema
object entry for a given format and version has the valuelatest
set totrue
. This latest schema will be used when the SBOM being validated does not have a clear version declared or used with the--force latest
flag. - If you have a customized or "variant" version of a schema (with the same format and version values) you wish to use for validation (e.g., a
corporate
orstaging
version with added requirements or for testing an unreleased version), you can create an entry that has the sameversion
as another entry, but also declare itsvariant
name (non-empty value). This value can be supplied on the commend line with the--variant <variant name>
flag to force the validator to use it instead of the default (empty variant value).
The built-in go test
command is used to execute all functional tests that appear in *._test.go
files. By default, go test
executes tests within the same directory where its respective *._test.go
file is located and sets that as the working directory. For example, tests in the validate_test.go
file are executed from the cmd
subdirectory. This is a problem as the actual test SBOM JSON test files are located relative the project root, one level higher, and would not be found. In order to correct for that, the test working directory is automatically changed for all tests within the TestMain
routine found in root_test.go
.
The Makefile
includes a test
target for convenience which will use go test
to run all tests found in all subdirectories:
$ make test
The test_cmd
target will use run only the test found in the cmd
package:
$ make test_cmd
Example: running all tests in the cmd
package:
go test github.com/CycloneDX/sbom-utility/cmd -v
Run in "quiet" mode to not see error test output:
go test github.com/CycloneDX/sbom-utility/cmd -v --quiet
run an individual test within the cmd
package:
go test github.com/CycloneDX/sbom-utility/cmd -v -run TestValidateCdx14MinRequiredBasic
Simply append the flags --args --trace
or --args --debug
to your go test
command to enable trace or debug output for your designated test(s):
go test github.com/CycloneDX/sbom-utility/cmd -v --args --trace
Several tests will still output error and warning messages as designed. If these messages are distracting, you can turn them off using the --quiet
flag.
go test github.com/CycloneDX/sbom-utility/cmd -v --args --quiet
Note: Always use the --args
flag of go test
as this will assure non-conflict with built-in flags.
In order to initiate the release workflow, simply go to the release page of the repository:
and click on the Draft a new release
button. Follow the instructions to create a new version tag, provide an appropriate release title and description and publish
the release. The GitHub release workflow will be triggered automatically.
For local development, you may choose to make a release on your machine using the Makefile
directive release
:
make release
ls release
total 131680
drwxr-xr-x 8 User1 staff 256 Jan 27 14:43 .
drwxr-xr-x 27 User1 staff 864 Jan 27 14:43 ..
-rw-r--r-- 1 User1 staff 7121 Jan 27 14:43 config.json
-rw-r--r-- 1 User1 staff 1346 Jan 27 14:43 custom.json
-rw-r--r-- 1 User1 staff 62532 Jan 27 14:43 license.json
-rwxr-xr-x 1 User1 staff 11336640 Jan 27 14:43 sbom-utility-darwin-amd64
-rwxr-xr-x 1 User1 staff 11146770 Jan 27 14:43 sbom-utility-darwin-arm64
-rwxr-xr-x 1 User1 staff 11495647 Jan 27 14:43 sbom-utility-linux-amd64
-rwxr-xr-x 1 User1 staff 11076025 Jan 27 14:43 sbom-utility-linux-arm64
-rwxr-xr-x 1 User1 staff 11416576 Jan 27 14:43 sbom-utility-windows-amd64
-rwxr-xr-x 1 User1 staff 10934272 Jan 27 14:43 sbom-utility-windows-arm64
...
- Please also note that the common
*.json
configuration files are also copied to therelease
directory.
to produce a release version you can set the following flags and invoke go build
directly:
BINARY=sbom-utility
VERSION=latest
LDFLAGS=-ldflags "-X main.Version=${VERSION} -X main.Binary=${BINARY}"
$ go build ${LDFLAGS} -o ${BINARY}
TODO: Update the Makefile's
release
target to conditionally pull the release version from environment variable values and only uses the hardcoded values as defaults when not found in the runtime build environment.
- CycloneDX Specification Overview
- GitHub: https://github.com/CycloneDX
- Specifications (by branch): https://github.com/CycloneDX/specification
- Schemas (all versions): https://github.com/CycloneDX/specification/tree/master/schema
- Examples: https://github.com/CycloneDX/sbom-examples
- CycloneDX Tool Center : https://cyclonedx.org/tool-center/
-
CycloneDX Use Cases (comprehensive), including:
-
CycloneDX Vulnerability Exploitability Exchange (VEX) format Overview
-
GitHub: https://github.com/spdx
- Specifications (by branch): https://github.com/spdx/spdx-spec
- Schemas (by branch):
- Examples: https://github.com/spdx/spdx-examples
-
Tools
- SPDX Online Tool: https://tools.spdx.org/app/
- Note Used the convert tool to convert SPDX examples from
.tv
format to.json
; however, conversion ofexample6-bin.spdx
resulted in an error.
- Note Used the convert tool to convert SPDX examples from
- SPDX Online Tool: https://tools.spdx.org/app/
- NTIA - SBOM Minimum Requirements
- CISA - Software Bill of Materials (SBOM)
- FOSSA - Software Bill Of Materials: Formats, Use Cases, and Tools
- FOSSA
- "A Practical Guide to CycloneDX": https://fossa.com/cyclonedx