Kubeclarity – Tool For Detection And Management Of Software Bill Of Materials (SBOM) And Vulnerabilities Of Container Images And Filesystems

KubeClarity is a tool for detection and management of Software Bill Of Materials (SBOM) and

Features

• Dashboard
  • Fixable vulnerabilities per severity
  • Top 5 vulnerable elements (applications, resources, packages)
  • New vulnerabilities trends
  • Package count per license type
  • Package count per programming language
  • General counters
• Applications
  • Automatic application detection in K8s runtime
  • Create/edit/delete applications
  • Per application, navigation to related:
    • Resources (images/directories)
    • Packages
    • Vulnerabilities
    • Licenses in use by the resources
• Application Resources (images/directories)
  • Per resource, navigation to related:
    • Applications
    • Packages
    • Vulnerabilities
• Packages
  • Per package, navigation to related:
    • Applications
    • Linkable list of resources and the detecting SBOM analyzers
    • Vulnerabilities
• Vulnerabilities
  • Per vulnerability, navigation to related:
    • Applications
    • Resources
    • List of detecting scanners
• K8s Runtime scan
  • Automatic detection of target namespaces
  • Scan progress and result navigation per affected element (applications, resources, packages, vulnerabilities)
• CLI (CI/CD)
  • SBOM generation using multiple integrated content analyzers (Syft, cyclonedx-gomod)
  • SBOM/image/directory vulnerability scanning using multiple integrated scanners (Grype, Dependency-track)
  • Merging of SBOM and vulnerabilities across different CI/CD stages
  • Export results to KubeClarity backend
• API
  • The API for KubeClarity can be found

    Getting started

    Integration with SBOM generators and vulnerability scanners

    KubeClarity content analyzer integrates with the following SBOM generators:

    • Syft
    • Cyclonedx-gomod

    KubeClarity vulnerability scanner integrates with the following scanners:

    • Grype
    • Dependency-Track

    The integrations with the SBOM generators can be found here, and the integrations with the vulnerability scanners can be found here here. To enable and configure the supported SBOM generators and vulnerability scanners, please check the “analyzer” and “scanner” config under the “vulnerability-scanner” section in Helm values.

    Contributions of integrations with additional tools are more than welcome!

    Install KubeClarity in a K8s cluster using Helm:

    1. Add Helm repo

       helm repo add kubeclarity https://openclarity.github.io/kubeclarity

    2. Save KubeClarity default chart values

       helm show values kubeclarity/kubeclarity > values.yaml

    3. Check the configuration in values.yaml and update the required values if needed

    4. Deploy KubeClarity with Helm

       helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity

       or for OpenShift Restricted SCC compatible install:

       helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity --set global.openShiftRestricted=true 
         --set kubeclarity-postgresql.securityContext.enabled=false --set kubeclarity-postgresql.containerSecurityContext.enabled=false 
         --set kubeclarity-postgresql.volumePermissions.enabled=true --set kubeclarity-postgresql.volumePermissions.securityContext.runAsUser="auto" 
         --set kubeclarity-postgresql.shmVolume.chmod.enabled=false

    5. Port forward to KubeClarity UI:

       kubectl port-forward -n kubeclarity svc/kubeclarity-kubeclarity 9999:8080

    6. Open KubeClarity UI in the browser: http://localhost:9999/

    Required K8s permissions

    1. Read secrets in cluster scope. This is required for getting image pull secrets for scanning private image repositories.
    2. Read config maps in cluster scope. This is required for getting the configured template of the scanner job.
    3. List pods in cluster scope. This is required for calculating the target pods that need to be scanned.
    4. List namespaces. This is required for fetching the target namespaces to scan in K8s runtime scan UI.
    5. Create & delete jobs in cluster scope. This is required for managing the jobs that will scan the target pods in their namespaces.

    Build and run locally with demo data

    1. Build UI & backend and start the backend locally (2 options):

       1. Using docker:
          1. Build UI and backend (the image tag is set using VERSION):

             VERSION=test make docker-backend

          2. Run the backend using demo data:

             docker run -p 8080:8080 -e FAKE_RUNTIME_SCANNER=true -e FAKE_DATA=true -e ENABLE_DB_INFO_LOGS=true -e DATABASE_DRIVER=LOCAL ghcr.io/openclarity/kubeclarity:test run

       2. Local build:
          1. Build UI and backend

             make ui && make backend

          2. Copy the built site:

             cp -r ./ui/build ./site

          3. Run the backend locally using demo data:

             FAKE_RUNTIME_SCANNER=true DATABASE_DRIVER=LOCAL FAKE_DATA=true ENABLE_DB_INFO_LOGS=true ./backend/bin/backend run

    2. Open KubeClarity UI in the browser: http://localhost:8080/

    CLI

    KubeClarity includes a CLI that can be run locally and especially useful for CI/CD pipelines. It allows to analyze images and directories to generate SBOM, and scan it for vulnerabilities. The results can be exported to KubeClarity backend.

    Binary Distribution

    Download the release distribution for your OS from the releases page

    Unpack the kubeclarity-cli binary, add it to your PATH, and you are good to go!

    Docker Image

    A Docker image is available at ghcr.io/openclarity/kubeclarity-cli with list of available tags here.

    Local Compilation

    make cli  

    Copy ./cli/bin/cli to your PATH under kubeclarity-cli.

    SBOM generation using multiple integrated content analyzers

    # A list of the content analyzers to use can be configured using the ANALYZER_LIST env variable seperated by a space (e.g ANALYZER_LIST="syft gomod")  kubeclarity-cli analyze <image/directory name> --input-type <dir|file|image(default)> -o <output file or stdout>    # For example:  ANALYZER_LIST="syft" kubeclarity-cli analyze nginx:latest -o nginx.sbom  

    Vulnerability scanning using multiple integrated scanners

    # A list of the vulnerability scanners to use can be configured using the SCANNERS_LIST env variable seperated by a space (e.g SCANNERS_LIST="grype dependency-track")  kubeclarity-cli scan <image/sbom/directoty/file name> --input-type <sbom|dir|file|image(default)> -f <output file>    # For example:  SCANNERS_LIST="grype" kubeclarity-cli scan nginx.sbom --input-type sbom   

    Export results to KubeClarity backend

    To export CLI results to the KubeClarity backend, need to use an application ID as defined by the KubeClarity backend. The application ID can be found in the Applications screen in the UI or using the KubeClarity API.

    Exporting SBOM:

    # The SBOM can be exported to KubeClarity backend by setting the BACKEND_HOST env variable and the -e flag.  # Note: Until TLS is supported, BACKEND_DISABLE_TLS=true should be set.  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  

    Exporting vulnerability scan results:

    # The vulnerability scan result can be exported to KubeClarity backend by setting the BACKEND_HOST env variable and the -e flag.  # Note: Until TLS is supported, BACKEND_DISABLE_TLS=true should be set.    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  

    Merging of SBOM and vulnerabilities across different CI/CD stages

    # Additional SBOM will be berged into the final results when '--merge-sbom' is defined during analysis. The input SBOM can be CycloneDX XML or CyclonDX json format.  # For example:  ANALYZER_LIST="syft" kubeclarity-cli analyze nginx:latest -o nginx.sbom --merge-sbom inputsbom.xml  

    Private registries support for K8s runtime scan

    Amazon ECR

    Create an AWS IAM user with AmazonEC2ContainerRegistryFullAccess permissions.

    Use the user credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION) to create the following secret:

    cat <<EOF | kubectl apply -f -  apiVersion: v1  kind: Secret  metadata:    name: ecr-sa    namespace: kubeclarity  type: Opaque  data:    AWS_ACCESS_KEY_ID: $(echo -n 'XXXX'| base64 -w0)    AWS_SECRET_ACCESS_KEY: $(echo -n 'XXXX'| base64 -w0)    AWS_DEFAULT_REGION: $(echo -n 'XXXX'| base64 -w0)  EOF  

    Note:

    1. Secret name must be ecr-sa
    2. Secret data keys must be set to AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_DEFAULT_REGION

    Google GCR

    Create a Google service account with Artifact Registry Reader permissions.

    Use the service account json file to create the following secret

    kubectl -n kubeclarity create secret generic --from-file=sa.json gcr-sa  

    Note:

    1. Secret name must be gcr-sa
    2. sa.json must be the name of the service account json file when generating the secret
    3. KubeClarity is using application default credentials. These only work when running KubeClarity from GCP.

    Limitations

    1. Supports Docker Image Manifest V2, Schema 2 (https://docs.docker.com/registry/spec/manifest-v2-2/). It will fail to scan earlier versions.

    Roadmap

    • Integration with additional content analyzers (SBOM generators)
    • Integration with additional vulnerability scanners
    • CIS Docker benchmark in UI
    • Image signing using Cosign
    • CI/CD metadata signing and attestation using Cosign and in-toto (supply chain security)
    • System settings and user management

    Contributing

    Pull requests and bug reports are welcome.

    For larger changes please create an Issue in GitHub first to discuss your proposed changes and possible implications.

    License

    Apache License, Version 2.0

    Download Kubeclarity