# kubei **Repository Path**: ywcwss/kubei ## Basic Information - **Project Name**: kubei - **Description**: Kubei 是一个灵活的 Kubernetes 运行时扫描程序，扫描工作节点和 Kubernetes 节点的图像，提供准确的漏洞评估 Kubei 是一个漏洞扫描和 CIS Dock - **Primary Language**: HTML/CSS - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: https://www.oschina.net/p/kubei - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 2 - **Created**: 2022-11-19 - **Last Updated**: 2022-11-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # KubeClarity ![](images/kubeclarity-logo.png) KubeClarity is a tool for detection and management of Software Bill Of Materials (SBOM) and vulnerabilities of container images and filesystems. It scans both runtime K8s clusters and CI/CD pipelines for enhanced software supply chain security. ## SBOM & vulnerability detection challenges * Effective vulnerability scanning requires an accurate Software Bill Of Materials (SBOM) detection: * Various programming languages and package managers * Various OS distributions * Package dependency information is usually stripped upon build * Which one is the best scanner/SBOM analyzer? * What should we scan: Git repos, builds, container images or runtime? * Each scanner/analyzer has its own format - how to compare the results? * How to manage the discovered SBOM and vulnerabilities? * How are my applications affected by a newly discovered vulnerability? ## Solution * Separate vulnerability scanning into 2 phases: * Content analysis to generate SBOM * Scan the SBOM for vulnerabilities * Create a pluggable infrastructure to: * Run several content analyzers in parallel * Run several vulnerability scanners in parallel * Scan and merge results between different CI stages using KubeClarity CLI * Runtime K8s scan to detect vulnerabilities discovered post-deployment * Group scanned resources (images/directories) under defined applications to navigate the object tree dependencies (applications, resources, packages, vulnerabilities) ![](images/dashboard-screen.png) ## 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 * On-demand or scheduled scanning * Automatic detection of target namespaces * Scan progress and result navigation per affected element (applications, resources, packages, vulnerabilities) * CIS Docker benchmark * 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 [here](https://github.com/openclarity/kubeclarity/blob/master/api/swagger.yaml) ## High level architecture ![](images/architecture.png) ## Getting started ### Integration with SBOM generators and vulnerability scanners KubeClarity content analyzer integrates with the following SBOM generators: * [Syft](https://github.com/anchore/syft) * [Cyclonedx-gomod](https://github.com/CycloneDX/cyclonedx-gomod) KubeClarity vulnerability scanner integrates with the following scanners: * [Grype](https://github.com/anchore/grype) * [Dependency-Track](https://github.com/DependencyTrack/dependency-track) The integrations with the SBOM generators can be found [here](https://github.com/openclarity/kubeclarity/tree/master/shared/pkg/analyzer), and the integrations with the vulnerability scanners can be found here [here](https://github.com/openclarity/kubeclarity/tree/master/shared/pkg/scanner). 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 ```shell helm repo add kubeclarity https://openclarity.github.io/kubeclarity ``` 2. Save KubeClarity default chart values ```shell 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 ```shell helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity ``` or for OpenShift Restricted SCC compatible install: ```shell 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 ``` 3. Port forward to KubeClarity UI: ```shell kubectl port-forward -n kubeclarity svc/kubeclarity-kubeclarity 9999:8080 ``` 4. Open KubeClarity UI in the browser: ### 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): ```shell VERSION=test make docker-backend ``` 2. Run the backend using demo data: ```shell 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 ```shell make ui && make backend ``` 2. Copy the built site: ```shell cp -r ./ui/build ./site ``` 3. Run the backend locally using demo data: ```shell 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: ## 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]( https://github.com/openclarity/kubeclarity/releases) 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](https://github.com/openclarity/kubeclarity/pkgs/container/kubeclarity-cli/versions). ### 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 --input-type -o # For example: ANALYZER_LIST="syft" kubeclarity-cli analyze nginx:latest -o nginx.sbom ``` ### SBOM generation using local docker image as input ``` # Local docker images can be analyzed using the LOCAL_IMAGE_SCAN env variable # For example: LOCAL_IMAGE_SCAN=true 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 --input-type -f # For example: SCANNERS_LIST="grype" kubeclarity-cli scan nginx.sbom --input-type sbom ``` ### Vulnerability scanning using local docker image as input ``` # Local docker images can be scanned using the LOCAL_IMAGE_SCAN env variable # For example: LOCAL_IMAGE_SCAN=true kubeclarity-cli scan nginx.sbom ``` ### Private registry support in cli The KubeClarity cli can read a config file that stores credentials for private registries. Example registry section of the config file: ``` registry: auths: - authority: username: password: - authority: token: ``` Example registry config without authority: (in this case these credentials will be used for all registries) ``` registry: auths: - username: password: ``` #### Specify config file for cli ``` # The default config path is $HOME/.kubeclarity or it can be specified by `--config` command line flag. # kubeclarity --config # For example: kubeclarity scan registry/nginx:private --config $HOME/own-kubeclarity-config ``` ### 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= BACKEND_DISABLE_TLS=true kubeclarity-cli analyze --application-id -e -o # 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= BACKEND_DISABLE_TLS=true kubeclarity-cli scan --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 merged 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 Kubeclarity is using [k8schain](https://github.com/google/go-containerregistry/tree/main/pkg/authn/k8schain#k8schain) of google/go-containerregistry for authenticating to the registries. If the necessary service credentials are not discoverable by the k8schain, they can be defined via secrets described below. ### Amazon ECR Create an [AWS IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) with `AmazonEC2ContainerRegistryFullAccess` permissions. Use the user credentials (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) to create the following secret: ``` cat <