[!IMPORTANT] KubeClarity ha quedado obsoleto y ha sido sustituido por openclarity/openclarity.

Consulte el comunicado de lanzamiento para obtener más información.

Este proyecto no recibe actualizaciones. Le recomendamos migrar.

KubeClarity es una herramienta para la detección y gestión de la lista de materiales de software (SBOM) y vulnerabilidades de imágenes de contenedores y sistemas de archivos. Escanea tanto clústeres K8s en tiempo de ejecución como pipelines de CI/CD para mejorar la seguridad de la cadena de suministro de software.

Índice

• ¿Por qué?
  • Desafíos en la detección de SBOM y vulnerabilidades
  • Solución
• Características
  • Generadores de SBOM y escáneres de vulnerabilidades integrados
• Arquitectura
• Primeros pasos
  • Backend de KubeClarity
    • Instalar usando Helm
    • Desinstalar usando Helm
    • Construir y ejecutar localmente con datos de demostración
  • CLI
    • Instalación
    • Generación de SBOM
    • Escaneo de vulnerabilidades
    • Exportar resultados al Backend de KubeClarity
• Configuración avanzada
  • Generación de SBOM usando imagen docker local como entrada
  • Escaneo de vulnerabilidades usando imagen docker local como entrada
  • Soporte de registro privado para CLI
  • Soporte de registros privados para escaneo en tiempo de ejecución de K8s
  • Fusión de SBOM y vulnerabilidades en diferentes etapas de CI/CD
  • Salida de diferentes formatos de SBOM
  • Servidores de escáner remoto para CLI
• Limitaciones
• Hoja de ruta
• Contribuciones
• Licencia

¿Por qué?

Desafíos en la detección de SBOM y vulnerabilidades

• El escaneo eficaz de vulnerabilidades requiere una detección precisa de la lista de materiales de software (SBOM):
  • Varios lenguajes de programación y gestores de paquetes
  • Varias distribuciones de SO
  • La información de dependencias de paquetes suele eliminarse durante la compilación
• ¿Cuál es el mejor escáner/analizador de SBOM?
• ¿Qué deberíamos escanear: repositorios Git, compilaciones, imágenes de contenedores o tiempo de ejecución?
• Cada escáner/analizador tiene su propio formato: ¿cómo comparar los resultados?
• ¿Cómo gestionar el SBOM y las vulnerabilidades descubiertas?
• ¿Cómo afectan mis aplicaciones una vulnerabilidad recién descubierta?

Solución

• Separar el escaneo de vulnerabilidades en 2 fases:
  • Análisis de contenido para generar el SBOM
  • Escanear el SBOM en busca de vulnerabilidades
• Crear una infraestructura conectable para:
  • Ejecutar varios analizadores de contenido en paralelo
  • Ejecutar varios escáneres de vulnerabilidades en paralelo
• Escanear y fusionar resultados entre diferentes etapas de CI usando la CLI de KubeClarity
• Escaneo en tiempo de ejecución de K8s para detectar vulnerabilidades descubiertas después del despliegue
• Agrupar los recursos escaneados (imágenes/directorios) bajo aplicaciones definidas para navegar por el árbol de dependencias de objetos (aplicaciones, recursos, paquetes, vulnerabilidades)

Características

• Tablero
  • Vulnerabilidades solucionables por gravedad
  • Top 5 de elementos vulnerables (aplicaciones, recursos, paquetes)
  • Tendencias de nuevas vulnerabilidades
  • Recuento de paquetes por tipo de licencia
  • Recuento de paquetes por lenguaje de programación
  • Contadores generales
• Aplicaciones
  • Detección automática de aplicaciones en tiempo de ejecución de K8s
  • Crear/editar/eliminar aplicaciones
  • Por aplicación, navegación a los relacionados:
    • Recursos (imágenes/directorios)
    • Paquetes
    • Vulnerabilidades
    • Licencias en uso por los recursos
• Recursos de aplicación (imágenes/directorios)
  • Por recurso, navegación a los relacionados:
    • Aplicaciones
    • Paquetes
    • Vulnerabilidades
• Paquetes
  • Por paquete, navegación a los relacionados:
    • Aplicaciones
    • Lista enlazable de recursos y los analizadores de SBOM detectores
    • Vulnerabilidades
• Vulnerabilidades
  • Por vulnerabilidad, navegación a los relacionados:
    • Aplicaciones
    • Recursos
    • Lista de escáneres detectores
• Escaneo en tiempo de ejecución de K8s
  • Escaneo bajo demanda o programado
  • Detección automática de espacios de nombres objetivo
  • Progreso del escaneo y navegación de resultados por elemento afectado (aplicaciones, recursos, paquetes, vulnerabilidades)
  • Benchmark CIS Docker
• CLI (CI/CD)
  • Generación de SBOM usando múltiples analizadores de contenido integrados (Syft, cyclonedx-gomod)
  • Escaneo de vulnerabilidades de SBOM/imagen/directorio usando múltiples escáneres integrados (Grype, Dependency-track)
  • Fusión de SBOM y vulnerabilidades en diferentes etapas de CI/CD
  • Exportar resultados al backend de KubeClarity
• API
  • La API de KubeClarity se puede encontrar aquí

Generadores de SBOM y escáneres de vulnerabilidades integrados

El analizador de contenido de KubeClarity se integra con los siguientes generadores de SBOM:

• Syft
• Cyclonedx-gomod
• Trivy

El escáner de vulnerabilidades de KubeClarity se integra con los siguientes escáneres:

• Grype
• Dependency-Track
• Trivy

Arquitectura

Primeros pasos

Backend de KubeClarity

Instalar usando Helm:

1. Añadir el repositorio Helm ```shell helm repo add kubeclarity https://openclarity.github.io/kubeclarity

   root@kitploit:~

2. Guardar los valores predeterminados de la carta de KubeClarity

   root@kitploit:~

   helm show values kubeclarity/kubeclarity > values.yaml
   

3. Verifique la configuración en values.yaml y actualice los valores necesarios si es necesario. Para habilitar y configurar los generadores de SBOM y los escáneres de vulnerabilidades compatibles, consulte la configuración "analyzer" y "scanner" en la sección "vulnerability-scanner" de los valores de Helm.

4. Desplegar KubeClarity con Helm ```shell helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity

   root@kitploit:~

o para una instalación compatible con OpenShift Restricted SCC: ```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. Reenviar puerto a la UI de KubeClarity:   ```shell
kubectl port-forward -n kubeclarity svc/kubeclarity-kubeclarity 9999:8080

4. Abrir la interfaz de KubeClarity en el navegador: http://localhost:9999/

NOTA
KubeClarity requiere estos permisos de K8s:

Desinstalar usando Helm:

1. Helm uninstall ```shell helm uninstall kubeclarity -n kubeclarity

   root@kitploit:~

2. Limpiar recursos

   Por defecto, Helm no eliminará los PVCs y PVs de los StatefulSets. Ejecute el siguiente comando para eliminarlos todos:

   root@kitploit:~

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

Construir y ejecutar localmente con datos de demostración

1. Construir la interfaz de usuario y el backend e iniciar el backend localmente (2 opciones):

   1. Usando docker:
      1. Construir la interfaz de usuario y el backend (la etiqueta de la imagen se establece usando VERSION):
         root@kitploit:~

         VERSION=test make docker-backend
         

      2. Ejecutar el backend usando datos de demostración:
         root@kitploit:~

         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. Compilación local:
      1. Construir la interfaz de usuario y el backend
         root@kitploit:~

         make ui && make backend
         

      2. Copiar el sitio construido:
         root@kitploit:~

         cp -r ./ui/build ./site
         

      3. Ejecutar el backend localmente usando datos de demostración:
         root@kitploit:~

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

2. Abrir la interfaz de usuario de KubeClarity en el navegador: http://localhost:8080/

CLI

KubeClarity incluye una CLI que se puede ejecutar localmente y es especialmente útil para procesos CI/CD. Permite analizar imágenes y directorios para generar un SBOM, y escanearlo en busca de vulnerabilidades. Los resultados se pueden exportar al backend de KubeClarity.

Instalación

Generación de SBOM

Uso:``` kubeclarity-cli analyze <image/directory name> --input-type <dir|file|image(default)> -o

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

Opcionalmente, se puede configurar una lista de los analizadores de contenido a utilizar mediante la variable de entorno ANALYZER_LIST separados por un espacio (e.g ANALYZER_LIST="<analyzer 1 name> <analyzer 2 name>")

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

### Escaneo de Vulnerabilidades

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

Ejemplo:``` kubeclarity-cli scan nginx.sbom --input-type sbom

Opcionalmente, se puede configurar una lista de los escáneres de vulnerabilidades a usar mediante la variable de entorno `SCANNERS_LIST` separadas por un espacio (p. ej. `SCANNERS_LIST="<Scanner1 name> <Scanner2 name>"`)

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

Exportando resultados al backend de KubeClarity

Para exportar los resultados de la CLI al backend de KubeClarity, es necesario usar un ID de aplicación según lo definido por el backend de KubeClarity. El ID de aplicación se puede encontrar en la pantalla de Aplicaciones en la interfaz de usuario o usando la API de KubeClarity.

Exportando el 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

#### Exportando resultados de escaneo de vulnerabilidades```
# 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

Configuración Avanzada

Generación de SBOM usando imagen local de docker como entrada```

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

## Escaneo de vulnerabilidades usando imagen docker local como entrada```
# Local docker images can be scanned using the LOCAL_IMAGE_SCAN env variable

# For example:
LOCAL_IMAGE_SCAN=true kubeclarity-cli scan nginx.sbom

Soporte de registro privado para CLI

La CLI de KubeClarity puede leer un archivo de configuración que almacena credenciales para registros privados.

Ejemplo de sección de registro del archivo de configuración:``` registry: auths: - authority: <registry 1> username: <username for registry 1> password: <password for registry 1> - authority: <registry 2> token: <token for registry 2>

Ejemplo de configuración de registro sin autoridad: (en este caso, estas credenciales se usarán para todos los registros)```
registry:
  auths:
    - username: <username>
      password: <password>

Especificar archivo de configuración para CLI```

The default config path is $HOME/.kubeclarity or it can be specified by --config command line flag.

kubeclarity <scan/analyze> --config

For example:

kubeclarity scan registry/nginx:private --config $HOME/own-kubeclarity-config

## Soporte de registros privados para el escaneo en tiempo de ejecución de K8s

Kubeclarity utiliza [k8schain](https://github.com/google/go-containerregistry/tree/main/pkg/authn/k8schain#k8schain) de google/go-containerregistry para la autenticación en los registros.
Si las credenciales de servicio necesarias no son detectables por el k8schain, se pueden definir mediante los secretos descritos a continuación.

Además, si las credenciales de servicio no se encuentran en el Namespace "kubeclarity", configure CREDS_SECRET_NAMESPACE en el Deployment de kubeclarity.
Cuando se utiliza helm [charts](https://github.com/openclarity/kubeclarity/blob/HEAD/charts), CREDS_SECRET_NAMESPACE se establece en el namespace de lanzamiento donde se instaló kubeclarity.

### Amazon ECR

Cree un [usuario IAM de AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) con permisos `AmazonEC2ContainerRegistryFullAccess`.

Utilice las credenciales del usuario (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) para crear el siguiente secreto:```
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

Nota:

1. El nombre del secreto debe ser ecr-sa
2. Las claves de los datos del secreto deben establecerse como AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY y AWS_DEFAULT_REGION

Google GCR

Crea una cuenta de servicio de Google con permisos de Artifact Registry Reader.

Usa el archivo json de la cuenta de servicio para crear el siguiente secreto``` kubectl -n kubeclarity create secret generic --from-file=sa.json gcr-sa

Nota:
1. El nombre del secreto debe ser `gcr-sa`
1. `sa.json` debe ser el nombre del archivo json de la cuenta de servicio al generar el secreto
2. KubeClarity utiliza [credenciales predeterminadas de la aplicación](https://developers.google.com/identity/protocols/application-default-credentials). Estas solo funcionan cuando se ejecuta KubeClarity desde GCP.

## Fusión de SBOM y vulnerabilidades en diferentes etapas de CI/CD```
# 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

Salida de Diferentes Formatos de SBOM

El comando kubeclarity-cli analyze puede formatear el SBOM resultante en diferentes formatos si es necesario para integrarse con otro sistema. Los formatos soportados son:

ADVERTENCIA
KubeClarity procesa CycloneDX internamente; los otros formatos son compatibles a través de una conversión. El proceso de conversión puede tener pérdidas debido a incompatibilidades entre formatos, por lo tanto, no se garantiza que todos los campos/información estén presentes en el resultado final.

Para configurar kubeclarity-cli para que use un formato diferente al predeterminado, se puede utilizar la variable de entorno ANALYZER_OUTPUT_FORMAT con el nombre de configuración de arriba:``` ANALYZER_OUTPUT_FORMAT="spdx-json" kubeclarity-cli analyze nginx:latest -o nginx.sbom

## Servidores de Escáner Remotos para CLI

Cuando se ejecuta la CLI de kubeclarity para escanear vulnerabilidades, la CLI necesitará descargar las bases de datos de vulnerabilidades relevantes en la ubicación donde se ejecuta la CLI de kubeclarity. Ejecutar la CLI en un pipeline de CI/CD resultará en la descarga de las bases de datos en cada ejecución, desperdiciando tiempo y ancho de banda. Por esta razón, varios de los escáneres compatibles tienen un modo remoto en el que un servidor es responsable de la gestión de las bases de datos y posiblemente del escaneo de los artefactos.

> ***Nota***
>
> Los ejemplos a continuación son para cada uno de los escáneres, pero pueden combinarse para ejecutarse juntos de la misma manera que en el modo no remoto.

### Trivy

El escáner Trivy admite el modo remoto utilizando el servidor Trivy. El servidor Trivy se puede implementar según se documenta aquí: [modo cliente-servidor de Trivy](https://aquasecurity.github.io/trivy/v0.34/docs/references/modes/client-server/). Las instrucciones para instalar la CLI de Trivy están disponibles aquí: [instalación de Trivy](https://aquasecurity.github.io/trivy/v0.34/getting-started/installation/). El equipo de Aqua proporciona una imagen de contenedor oficial que se puede usar para ejecutar el servidor en kubernetes/docker, que usaremos en los ejemplos aquí.

Para iniciar el servidor:```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080

Para ejecutar un escaneo usando el servidor:``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" ./kubeclarity_cli scan --input-type sbom nginx.sbom

El servidor trivy también proporciona autenticación basada en tokens para prevenir el uso no autorizado de una instancia del servidor trivy. Puede habilitarla ejecutando el servidor con la bandera adicional:```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080 --token mytoken

y pasando el token al escáner:``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" SCANNER_TRIVY_SERVER_TOKEN="mytoken" ./kubeclarity_cli scan --input-type sbom nginx.sbom

### Grype

Grype soporta el modo remoto utilizando [grype-server](https://github.com/portshift/grype-server) un envoltorio RESTful de Grype que proporciona una API que recibe un SBOM y devuelve los resultados del escaneo de Grype para ese SBOM. Grype-server se distribuye como una imagen de contenedor, por lo que puede ejecutarse en kubernetes o mediante docker de forma independiente.

Para iniciar el servidor:```
docker run -p 9991:9991 --rm gcr.io/eticloud/k8sec/grype-server:v0.1.5

Para ejecutar un escaneo usando el servidor:``` SCANNERS_LIST="grype" SCANNER_GRYPE_MODE="remote" SCANNER_REMOTE_GRYPE_SERVER_ADDRESS=":9991" SCANNER_REMOTE_GRYPE_SERVER_SCHEMES="https" ./kubeclarity_cli scan --input-type sbom nginx.sbom

Si el servidor Grype se despliega con TLS, puedes sobrescribir el URL scheme predeterminado como:```
SCANNERS_LIST="grype" SCANNER_GRYPE_MODE="remote" SCANNER_REMOTE_GRYPE_SERVER_ADDRESS="<grype server address>:9991" SCANNER_REMOTE_GRYPE_SERVER_SCHEMES="https" ./kubeclarity_cli scan --input-type sbom nginx.sbom

Dependency Track

Ver ejemplo de configuración aquí

Limitaciones

1. Soporta Docker Image Manifest V2, Schema 2 (https://docs.docker.com/registry/spec/manifest-v2-2/). No podrá escanear versiones anteriores.

Hoja de ruta

• Integración con analizadores de contenido adicionales (generadores de SBOM)
• Integración con escáneres de vulnerabilidades adicionales
• CIS Docker benchmark en la interfaz de usuario
• Firma de imágenes usando Cosign
• Firma y atestación de metadatos CI/CD usando Cosign y in-toto (seguridad de la cadena de suministro)
• Configuración del sistema y gestión de usuarios

Contribuciones

Las solicitudes de extracción (pull requests) y los informes de errores son bienvenidos.

Para cambios más grandes, por favor cree un Issue en GitHub primero para discutir los cambios propuestos y las posibles implicaciones.

Para más detalles, consulte las Guías de contribución para este proyecto

Licencia

Apache License, Version 2.0