List of toolkit utilities

Utility: code-scan

This utility generates a CycloneDX package SBOM for a given code repository in JSON format and validates the generated SBOM. It uses the cdxgen tool to scan the codebase and generate an SBOM file. Make sure that the source code directory is mounted to the container.

usage: code-scan --src <path-to-source-code> [--output-file <string>] [--validate <bool>] [--cdxgen-args "<string> <string>..."] [--help]
  --src <path-to-source-code>                 Path to the source code directory.
  --output-file <string>                      Output file name. Default: codescan-cyclonedx-sbom.json
  --validate <bool>                           Validate the generated SBOM. Default: true
  --cdxgen-args "<string> <string>..."        Additional arguments to pass to cdxgen. IMPORTANT: Ensure that the arguments are enclosed in quotes.
  --help                                      Display this help message.

Note: The toolkit image is built with only the cdxgen node module, not the cdxgen official container image. This means that not all the dependencies (such as Bazel, Maven) are included in the toolkit image for Cdxgen to scan all languages and frameworks. For some codebases, this may result in transitive incomplete SBOM generation. To ensure comprehensive and accurate SBOMs, it is recommended to use the official cdxgen container image, which includes all necessary dependencies and supports a wider range of languages and frameworks.

Using the official cdxgen container image

Use the following command to scan your code repository by using the cdxgen image:

docker run --rm -v /tmp:/tmp -v <host-dir-src-code>:/app:rw -t ghcr.io/cyclonedx/cdxgen:v8.6.0 -r /app -o /app/<sbom-file-name>.json

Replace the <host-dir-src-code> with the path to the source code directory on the host machine, and <sbom-file-name> with the required name of the SBOM file. This generates the SBOM file in the source code directory.

Mirroring the cdxgen container image to another registry

For organizations that require container images to be sourced from an internal registry, the cdxgen image can be mirrored to comply with internal policies. The cdxgen image can be mirrored to any registry by the following instructions. Make sure that you have the destination registry's authentication.

Pull the cdxgen image.

docker pull ghcr.io/cyclonedx/cdxgen:v8.6.0

Tag the image with your registry.

docker tag ghcr.io/cyclonedx/cdxgen:v8.6.0 <your-registry>/<your-project>/cdxgen:v8.6.0

Push the image to your registry.
```
docker push <your-registry>/<your-project>/cdxgen:v8.6.0
```
The image <your-registry>/<your-project>/cdxgen:v8.6.0 is now available in your internal registry. Use this image reference in place of ghcr.io/cyclonedx/cdxgen:v8.6.0 in the container run command.

Scanning multiple repositories with `code-scan`

Attention: The code-scan utility considers a given directory to be a single repository. To create a separate SBOM for each repository, it is ideal to scan each repository separately.

The code-scan utility generates the SBOM file, which by default has the name codescan-cyclonedx-sbom.json. Ensure that each repository has a unique output file name that is specified by using the --output-file flag to prevent the SBOMs from being overwritten.

Utility: image-scan

This utility uses an image name as input and generates a CycloneDX package SBOM for a given list of container images. The utility validates the generated SBOM and uses the syft tool to scan the image and generate an SBOM file.

The image-scan utility can be executed by using the following command. Ensure that the container images are available to download.

usage: image-scan --images <images-comma-separated> [--output-file-suffix <string>] [--validate <bool>]
--images <images-comma-separated>            Comma-separated list of images to scan.
--output-file-suffix <string>                Output file name suffix. Default: imagescan-cyclonedx-sbom.json
--validate <bool>                            Validate the generated SBOM. Default: true
--help                                       Display this help message.

If you are using the image-scan utility with an image from a private container registry, you must provide the toolkit with the necessary credentials to log in to the registry. There are two methods to do this:

Method 1: Mounting the Docker configuration JSON file into the container
Use the following command to export the variable HOST_DOCKER_CONFIG_JSON with the path to the Docker configuration JSON file on your host machine:
```
export HOST_DOCKER_CONFIG_JSON="<DOCKER-CONFIG-JSON-PATH>"
```
Then, add another volume mount to the toolkit prefix command by using the -v flag to mount the Docker configuration JSON file into the container's path. /config/config.json. For example:
```
export TOOLKIT_PREFIX_CMD="docker run \
  -v ${HOST_DIR_SRC_CODE}:/data/src \
  -v ${HOST_DIR_TOOLKIT_DATA}:/toolkit-data \
  -v ${HOST_DOCKER_CONFIG_JSON}:/app/.docker/config.json \
  --rm \
  ${TOOLKIT_IMAGE} \
  /bin/bash -c"
```

Method 2: Mounting the registry credentials as environment variables into the container

Use the following commands to export the credentials for the private container registry as environment variables.

Note: REGISTRY_TOKEN and REGISTRY_USERNAME/REGISTRY_PASSWORD are mutually exclusive.

export REGISTRY_URL="<REGISTRY-URL>"
export REGISTRY_USERNAME="<REGISTRY-USERNAME>"
export REGISTRY_PASSWORD="<REGISTRY-PASSWORD>"
export REGISTRY_TOKEN="<REGISTRY-TOKEN>"

Then, add the environment variables to the toolkit prefix command by using the -e flag to pass the registry credentials into the container. For example:

export TOOLKIT_PREFIX_CMD="docker run \
  -v ${HOST_DIR_SRC_CODE}:/data/src \
  -v ${HOST_DIR_TOOLKIT_DATA}:/toolkit-data \
  -e SYFT_REGISTRY_AUTH_AUTHORITY=${REGISTRY_URL} \
  -e SYFT_REGISTRY_AUTH_USERNAME=${REGISTRY_USERNAME} \
  -e SYFT_REGISTRY_AUTH_PASSWORD=${REGISTRY_PASSWORD} \
  -e SYFT_REGISTRY_AUTH_TOKEN=${REGISTRY_TOKEN} \
  --rm \
  ${TOOLKIT_IMAGE} \
  /bin/bash -c"

To skip the TLS verification, you can set the environment variable SYFT_REGISTRY_INSECURE_SKIP_TLS_VERIFY to true inside the toolkit container. The variable can be set by prefixing the container run command with the -e argument. For example:

export TOOLKIT_PREFIX_CMD="docker run \
  -v ${HOST_DIR_SRC_CODE}:/data/src \
  -v ${HOST_DIR_TOOLKIT_DATA}:/toolkit-data \
  -e SYFT_REGISTRY_INSECURE_SKIP_TLS_VERIFY=true \
  ${TOOLKIT_IMAGE} \
  /bin/bash -c"

For more information on the syft configuration options, see the syft documentation.

Utility: validate-sbom

This utility validates the package SBOM files that are generated by the code-scan and image-scan utilities against the CycloneDX specification. The utility takes the SBOM files as input and validates them. It uses sbom-utility to validate the SBOM files.

Usage: validate-sbom --files <sbom-json-files-comma-separated>
  --files <sbom-json-files-comma-separated>    Comma-separated list of SBOM JSON files to validate.
  --help                                       Display this help message.

Utility: validate-concertdef-sbom

This utility uses a validate configuration (YAML) file as input to validate the SBOM files defined in the configuration file against the custom Concert-defined (ConcertDef) by calling the Concert API.

usage: validate-concertdef-sbom [-h] --validate-config VALIDATE_CONFIG

Validate ConcertDef SBOM files using Concert API.

options:
  -h, --help            show this help message and exit
  --validate-config VALIDATE_CONFIG
                        Path to the Concert configuration file

Utility: build-sbom

This utility uses a build configuration (YAML) file as input and generates a build SBOM file that adheres to the custom Concert-defined (ConcertDef) schema. The utility produces a JSON file as output.

usage: build-sbom [-h] --build-config BUILD_CONFIG

Generates the Concert-Defined Build BOM json file given the build config file.

options:
  -h, --help            show this help message and exit
  --build-config BUILD_CONFIG
                        Path to the build configuration file

Utility: deploy-sbom

This utility uses a deployment inventory (YAML) file as input and generates a deploy SBOM file that adheres to the custom Concert-defined (ConcertDef) schema.

usage: deploy-sbom [-h] --deploy-config DEPLOY_CONFIG

Generates the Concert-Defined Deployment BOM json file given the deploy config file.

options:
  -h, --help            show this help message and exit
  --deploy-config DEPLOY_CONFIG
                        Path to the deployment configuration file

Utility: app-sbom

This utility uses an application definition configuration (YAML) file as input and generates a SBOM file that adheres to the custom Concert-defined (ConcertDef) schema. The utility produces a JSON file as output.

usage: app-sbom [-h] --app-config APP_CONFIG

Generates the Concert-Defined Application BOM json file given the application config file.

options:
  -h, --help            show this help message and exit
  --app-config APP_CONFIG
                        Path to the application configuration file

Utility: cert-inventory

This utility uses a certificate configuration (YAML) file as input and generates a SBOM file that adheres to the custom Concert-defined (ConcertDef) schema. The utility produces a JSON file as output.

usage: cert-inventory [-h] --cert-config CERT_CONFIG

Generates the Concert-Defined Certificates Inventory json file given the certificates config file.

options:
  -h, --help            show this help message and exit
  --cert-config CERT_CONFIG
                        Path to the certificates configuration file

Utility: compliance-catalog

This utility generates Open Security Controls Assessment Language (OSCAL) catalog JSON files by processing Excel or CSV files.

usage: compliance-catalog [-h] --input-file INPUT_FILE --config-file CONFIG_FILE

Process a catalog file in csv/xlsx format and convert to oscal based on a config.

options:
  -h, --help            show this help message and exit
  --input-file INPUT_FILE
                        Path to the input file.
  --config-file CONFIG_FILE
                        Path to the config file.

Utility: upload-concert

This utility uploads one or more files to Concert. The utility takes the YAML Concert upload configuration file as input and uploads the files that are referenced in the configuration file to Concert.

usage: upload-concert [-h] --upload-config UPLOAD_CONFIG

Upload files to Concert API.

options:
  -h, --help            show this help message and exit
  --upload-config UPLOAD_CONFIG
                        Path to the configuration file