First tasks - CLI

After you have installed the KubeClarity backend and the KubeClarity CLI, and completed the first tasks on the UI, complete the following tasks to see the basic functionality of the KubeClarity CLI.

Generate SBOM

To generate the Software Bill of Materials (SBOM), complete the following steps.

  1. Run the following command.

    kubeclarity-cli analyze <image/directory name> --input-type <dir|file|image(default)> -o <output file or stdout>

    For example:

    kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

    Example output:

    INFO[0000] Called syft analyzer on source registry:nginx:latest  analyzer=syft app=kubeclarity
INFO[0004] Skipping analyze unsupported source type: image  analyzer=gomod app=kubeclarity
INFO[0004] Sending successful results                    analyzer=syft app=kubeclarity
INFO[0004] Got result for job "syft"                     app=kubeclarity
INFO[0004] Got result for job "gomod"                    app=kubeclarity
INFO[0004] Skip generating hash in the case of image

  2. Verify that the ngnix.sbom file is generated and explore its contents as in below:

    head ngnix.sbom

    Example output:

    {
  "bomFormat": "CycloneDX",
  "specVersion": "1.4",
  "serialNumber": "urn:uuid:8cca2aa3-1aaa-4e8c-9d44-08e88b1df50d",
  "version": 1,
  "metadata": {
    "timestamp": "2023-05-19T16:27:27-07:00",
    "tools": [
      {
        "vendor": "kubeclarity",

  3. To run also the trivy scanner and merge the output into a single SBOM, run:

    ANALYZER_LIST="syft gomod trivy" kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

    Example output:

    INFO[0000] Called syft analyzer on source registry:nginx:latest  analyzer=syft app=kubeclarity
INFO[0004] Called trivy analyzer on source image nginx:latest  analyzer=trivy app=kubeclarity
INFO[0004] Skipping analyze unsupported source type: image  analyzer=gomod app=kubeclarity
INFO[0005] Sending successful results                    analyzer=syft app=kubeclarity
INFO[0005] Sending successful results                    analyzer=trivy app=kubeclarity
INFO[0005] Got result for job "trivy"                    app=kubeclarity
INFO[0005] Got result for job "syft"                     app=kubeclarity
INFO[0005] Got result for job "gomod"                    app=kubeclarity
INFO[0005] Skip generating hash in the case of image

Vulnerability scan

You can scan vulnerabilities by running the appropriate commands. The CLI provides flexibility and automation capabilities for integrating vulnerability scanning into your existing workflows or CI/CD pipelines. The tool allows scanning an image, directory, file, or a previously generated SBOM.

Usage:

kubeclarity-cli scan <image/sbom/directory/file name> --input-type <sbom|dir|file|image(default)> -f <output file>

Example:

kubeclarity-cli scan nginx.sbom --input-type sbom

You can list the vulnerability scanners to use using the SCANNERS_LIST environment variable separated by a space (SCANNERS_LIST="<Scanner1 name> <Scanner2 name>"). For example:

SCANNERS_LIST="grype trivy" kubeclarity-cli scan nginx.sbom --input-type sbom

Example output:

INFO[0000] Called trivy scanner on source sbom nginx.sbom  app=kubeclarity scanner=trivy
INFO[0000] Loading DB. update=true                       app=kubeclarity mode=local scanner=grype
INFO[0000] Need to update DB                             app=kubeclarity scanner=trivy
INFO[0000] DB Repository: ghcr.io/aquasecurity/trivy-db  app=kubeclarity scanner=trivy
INFO[0000] Downloading DB...                             app=kubeclarity scanner=trivy
INFO[0010] Gathering packages for source sbom:nginx.sbom  app=kubeclarity mode=local scanner=grype
INFO[0010] Found 136 vulnerabilities                     app=kubeclarity mode=local scanner=grype
INFO[0011] Sending successful results                    app=kubeclarity mode=local scanner=grype
INFO[0011] Got result for job "grype"                    app=kubeclarity
INFO[0012] Vulnerability scanning is enabled             app=kubeclarity scanner=trivy
INFO[0012] Detected SBOM format: cyclonedx-json          app=kubeclarity scanner=trivy
INFO[0012] Detected OS: debian                           app=kubeclarity scanner=trivy
INFO[0012] Detecting Debian vulnerabilities...           app=kubeclarity scanner=trivy
INFO[0012] Number of language-specific files: 1          app=kubeclarity scanner=trivy
INFO[0012] Detecting jar vulnerabilities...              app=kubeclarity scanner=trivy
INFO[0012] Sending successful results                    app=kubeclarity scanner=trivy
INFO[0012] Found 136 vulnerabilities                     app=kubeclarity scanner=trivy
INFO[0012] Got result for job "trivy"                    app=kubeclarity
INFO[0012] Merging result from "grype"                   app=kubeclarity
INFO[0012] Merging result from "trivy"                   app=kubeclarity
NAME              INSTALLED                FIXED-IN  VULNERABILITY     SEVERITY    SCANNERS
curl              7.74.0-1.3+deb11u7                 CVE-2023-23914    CRITICAL    grype(*), trivy(*)
curl              7.74.0-1.3+deb11u7                 CVE-2023-27536    CRITICAL    grype(*), trivy(*)
libcurl4          7.74.0-1.3+deb11u7                 CVE-2023-27536    CRITICAL    grype(*), trivy(*)
libdb5.3          5.3.28+dfsg1-0.8                   CVE-2019-8457     CRITICAL    grype(*), trivy(*)
libcurl4          7.74.0-1.3+deb11u7                 CVE-2023-23914    CRITICAL    grype(*), trivy(*)
perl-base         5.32.1-4+deb11u2                   CVE-2023-31484    HIGH        grype(*), trivy(*)
libss2            1.46.2-2                           CVE-2022-1304     HIGH        grype(*), trivy(*)
bash              5.1-2+deb11u1                      CVE-2022-3715     HIGH        grype(*), trivy(*)

Export results to KubeClarity backend

To export the CLI results to the KubeClarity backend, complete the following steps.

  1. To export CLI-generated results to the backend, from the left menu bar select Applications, then copy the ID from the KubeClarity UI. If your application is not listed yet, select + New Application, and create a new pod.

    Resource ID on the UI

  2. To export the generated SBOMs to a running KubeClarity backend pod, use the -e flag and the ID as the <application ID> value in the following command.

    BACKEND_HOST=<KubeClarity backend address> BACKEND_DISABLE_TLS=true kubeclarity-cli analyze <image> --application-id <application ID> -e -o <SBOM output file>

    For example:

    BACKEND_HOST=localhost:9999 BACKEND_DISABLE_TLS=true kubeclarity-cli analyze nginx:latest --application-id 23452f9c-6e31-5845-bf53-6566b81a2906 -e -o nginx.sbom

    Example output:

    INFO[0000] Called syft analyzer on source registry:nginx:latest  analyzer=syft app=kubeclarity
INFO[0004] Called trivy analyzer on source image nginx:latest  analyzer=trivy app=kubeclarity
INFO[0004] Skipping analyze unsupported source type: image  analyzer=gomod app=kubeclarity
INFO[0004] Sending successful results                    analyzer=syft app=kubeclarity
INFO[0004] Got result for job "syft"                     app=kubeclarity
INFO[0004] Got result for job "gomod"                    app=kubeclarity
INFO[0004] Sending successful results                    analyzer=trivy app=kubeclarity
INFO[0004] Got result for job "trivy"                    app=kubeclarity
INFO[0004] Skip generating hash in the case of image    
INFO[0004] Exporting analysis results to the backend: localhost:8080  app=kubeclarity

  3. To export the vulnerability scan results to the KubeClarity backend, set the BACKEND_HOST environment variable and the -e flag.

    Note: Until TLS is supported, set BACKEND_DISABLE_TLS=true.

    BACKEND_HOST=<KubeClarity backend address> BACKEND_DISABLE_TLS=true kubeclarity-cli scan <image> --application-id <application ID> -e

    For example:

    SCANNERS_LIST="grype" BACKEND_HOST=localhost:9999 BACKEND_DISABLE_TLS=true kubeclarity-cli scan nginx.sbom --input-type sbom  --application-id 23452f9c-6e31-5845-bf53-6566b81a2906 -e
  4. Now you can see the exported results on the UI, for example, on the Dashboard page.

Next step

Now that you have finished the getting started guide, explore the UI, or check the documentation for other use cases.

Last modified October 11, 2023: Kubeclarity blog ports (#6) (7825fa3)