Getting started

• 1: Install the KubeClarity backend
• 2: Install the CLI
• 3: First tasks - UI
• 4: First tasks - CLI

1 - Install the KubeClarity backend

You can install the KubeClarity backend using Helm, or you can build and run it locally.

Prerequisites

KubeClarity requires these Kubernetes permissions:

Prerequisites for AWS

If you are installing KubeClarity on AWS, complete the following steps. These are needed because KubeClarity uses a persistent PostgreSQL database, and that requires a volume.

1. Make sure that your EKS cluster is 1.23 or higher.
2. Install the EBS CSI Driver EKS add-on. For details, see Amazon EKS add-ons.
3. Configure the EBS CSI Driver with IAMServiceRole and policies. For details, see Creating the Amazon EBS CSI driver IAM role.

Install using Helm

1. Add the Helm repository.

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

2. Save the default KubeClarity chart values.

   helm show values kubeclarity/kubeclarity > values.yaml
   

3. (Optional) Check the configuration in the values.yaml file and update the required values if needed. You can skip this step to use the default configuration.

   • To enable and configure the supported SBOM generators and vulnerability scanners, check the analyzer and scanner configurations under the vulnerability-scanner section. You can skip this step to use the default configuration settings.

4. Deploy KubeClarity with Helm.

   • If you have customized the values.yaml file, run:

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

   • To use the default configuration, run:

     helm install --create-namespace kubeclarity kubeclarity/kubeclarity --namespace kubeclarity
     

   • For an OpenShift Restricted SCC compatible installation, run:

     helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity --namespace 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. Wait until all the pods are in ‘Running’ state. Check the output of the following command:

   kubectl get pods --namespace kubeclarity
   

   The output should be similar to:

   NAME                                                    READY   STATUS    RESTARTS   AGE
   kubeclarity-kubeclarity-7689c7fbb7-nlhh5                1/1     Running   0          82s
   kubeclarity-kubeclarity-grype-server-79b6fb4b88-5xtbh   1/1     Running   0          82s
   kubeclarity-kubeclarity-postgresql-0                    1/1     Running   0          82s
   kubeclarity-kubeclarity-sbom-db-6895d97d5d-55jnj        1/1     Running   0          82s
   

6. Port-forward to the KubeClarity UI.

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

7. (Optional) Install a sample application (sock shop) to run your scans on.

   1. Create a namespace for the application.

      kubectl create namespace sock-shop
      

   2. Install the application.

      kubectl apply -f https://raw.githubusercontent.com/microservices-demo/microservices-demo/master/deploy/kubernetes/complete-demo.yaml
      

   3. Check that the installation was successful.

      kubectl get pods --namespace sock-shop
      

      Expected output:

      NAME                            READY   STATUS    RESTARTS   AGE
      carts-5dc994cf5b-4rhfj          2/2     Running   0          44h
      carts-db-556cbbd5fb-64qls       2/2     Running   0          44h
      catalogue-b7b968c97-b9k8p       2/2     Running   0          44h
      catalogue-db-f7547dd6-smzk2     2/2     Running   0          44h
      front-end-848c97475d-b7sl8      2/2     Running   0          44h
      orders-7d47794476-9fjsx         2/2     Running   0          44h
      orders-db-bbfb8f8-7ndr6         2/2     Running   0          44h
      payment-77bd4bbdf6-hkzh7        2/2     Running   0          44h
      queue-master-6d4cf8c4ff-pzk68   2/2     Running   0          44h
      rabbitmq-9dd69888f-6lzfh        3/3     Running   0          44h
      session-db-7d9d77c495-zngsn     2/2     Running   0          44h
      shipping-67fff9d476-t87jw       2/2     Running   0          44h
      user-7b667cd8d-q8bg8            2/2     Running   0          44h
      user-db-5599d45948-vxpq6        2/2     Running   0          44h
      

8. Open the KubeClarity UI in your browser at http://localhost:9999/. The KubeClarity dashboard should appear. KubeClarity UI has no data to report vulnerabilities after a fresh install, so there is no data on the dashboard.

   

9. If you also want to try KubeClarity using its command-line tool, Install the CLI. Otherwise, you can run runtime scans using the dashboard.

Uninstall using Helm

Later if you have finished experimenting with KubeClarity, you can delete the backend by completing the following steps.

1. Helm uninstall

   helm uninstall kubeclarity --namespace kubeclarity
   

2. Clean the resources. By default, Helm doesn’t remove the PVCs and PVs for the StatefulSets. Run the following command to delete them all:

   kubectl delete pvc -l app.kubernetes.io/instance=kubeclarity --namespace kubeclarity
   

Build and run locally with demo data

1. Build the UI and the backend and start the backend locally, either using Docker, or without it:

   • 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 9999: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
        

   • 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 the KubeClarity UI in your browser: http://localhost:9999/

3. Install the CLI.

2 - Install the CLI

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

You can install the KubeClarity CLI using the following methods:

Next step

Check the common tasks you can do using the web UI.

3 - First tasks - UI

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

Runtime scan

To start a runtime scan, complete the following steps.

1. Open the UI in your browser at http://localhost:9999/.

2. From the navigation bar on the left, select Runtime Scan.

   

3. Select the namespace you want to scan, for example, the sock-shop namespace if you have installed the demo application, then click START SCAN. You can select multiple namespaces.

   

4. Wait until the scan is completed, then check the results. The scan results report the affected components such as Applications, Application Resources, Packages, and Vulnerabilities.

   

5. Click on these elements for details. For example, Applications shows the applications in the namespace that have vulnerabilities detected.

   

6. Now that you have run a scan, a summary of the results also appears on the dashboard page of the UI.

   

Vulnerability scan

1. To see the results of a vulnerability scan, select the Vulnerabilities page in KubeClarity UI. It shows a report including the vulnerability names, severity, the package of origin, available fixes, and attribution to the scanner that reported the vulnerability.

   

2. You can click on any of these fields to access more in-depth information. For example, click on the name of a vulnerability in the VULNERABILITY NAME column.

   

3. Select CVSS to show the CVSS scores and other details reported from the scanning process.

   

4. Navigate back to the Vulnerabilities view to explore the filtering options. Filtering helps you reduce noise and improve efficiency in identifying and potentially fixing crucial vulnerabilities.

   

5. The KubeClarity Dashboard gives you insights into vulnerability trends and fixable vulnerabilities.

   

Next step

Check the common tasks you can do using the CLI tool.

4 - 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.

   

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.