[!IMPORTANT] KubeClarity est déprécié et remplacé par openclarity/openclarity.

Consultez l'annonce de version pour plus d'informations.

Ce projet ne reçoit plus de mises à jour. Nous vous encourageons à migrer.

KubeClarity est un outil de détection et de gestion des Software Bill Of Materials (SBOM) et des vulnérabilités des images conteneur et des systèmes de fichiers. Il scanne à la fois les clusters K8s en cours d'exécution et les pipelines CI/CD pour renforcer la sécurité de la chaîne d'approvisionnement logicielle.

Table of Contents

• Pourquoi ?
  • Défis de détection des SBOM et des vulnérabilités
  • Solution
• Fonctionnalités
  • Générateurs de SBOM et scanners de vulnérabilités intégrés
• Architecture
• Pour commencer
  • Backend KubeClarity
    • Installation via Helm
    • Désinstallation via Helm
    • Construction et exécution locale avec des données de démonstration
  • CLI
    • Installation
    • Génération de SBOM
    • Analyse des vulnérabilités
    • Export des résultats vers le backend KubeClarity
• Configuration avancée
  • Génération de SBOM à partir d'une image Docker locale
  • Analyse des vulnérabilités à partir d'une image Docker locale
  • Support des registres privés pour la CLI
  • Support des registres privés pour l'analyse runtime K8s
  • Fusion des SBOM et vulnérabilités entre différentes étapes CI/CD
  • Sortie de différents formats SBOM
  • Serveurs de scan distants pour la CLI
• Limitations
• Feuille de route
• Contribuer
• Licence

Why?

SBOM & Vulnerability Detection Challenges

• Une analyse efficace des vulnérabilités nécessite une détection précise du Software Bill Of Materials (SBOM) :
  • Différents langages de programmation et gestionnaires de paquets
  • Différentes distributions OS
  • Les informations de dépendances des paquets sont généralement supprimées lors de la construction
• Quel est le meilleur scanner/analyseur de SBOM ?
• Que devons-nous scanner : dépôts Git, builds, images conteneur ou runtime ?
• Chaque scanner/analyseur a son propre format - comment comparer les résultats ?
• Comment gérer les SBOM et les vulnérabilités découverts ?
• Comment mes applications sont-elles affectées par une vulnérabilité nouvellement découverte ?

Solution

• Diviser l'analyse des vulnérabilités en 2 phases :
  • Analyse du contenu pour générer le SBOM
  • Analyser le SBOM pour les vulnérabilités
• Créer une infrastructure enfichable pour :
  • Exécuter plusieurs analyseurs de contenu en parallèle
  • Exécuter plusieurs scanners de vulnérabilités en parallèle
• Scanner et fusionner les résultats entre différentes étapes CI à l'aide de la CLI KubeClarity
• Analyse runtime K8s pour détecter les vulnérabilités découvertes après le déploiement
• Regrouper les ressources scannées (images/répertoires) sous des applications définies pour naviguer dans les dépendances de l'arborescence des objets (applications, ressources, paquets, vulnérabilités)

Features

• Tableau de bord
  • Vulnérabilités corrigeables par sévérité
  • Top 5 des éléments vulnérables (applications, ressources, paquets)
  • Tendances des nouvelles vulnérabilités
  • Nombre de paquets par type de licence
  • Nombre de paquets par langage de programmation
  • Compteurs généraux
• Applications
  • Détection automatique des applications dans le runtime K8s
  • Créer/éditer/supprimer des applications
  • Par application, navigation vers les éléments associés :
    • Ressources (images/répertoires)
    • Paquets
    • Vulnérabilités
    • Licences utilisées par les ressources
• Ressources d'application (images/répertoires)
  • Par ressource, navigation vers les éléments associés :
    • Applications
    • Paquets
    • Vulnérabilités
• Paquets
  • Par paquet, navigation vers les éléments associés :
    • Applications
    • Liste liable des ressources et des analyseurs SBOM détecteurs
    • Vulnérabilités
• Vulnérabilités
  • Par vulnérabilité, navigation vers les éléments associés :
    • Applications
    • Ressources
    • Liste des scanners détecteurs
• Analyse runtime K8s
  • Analyse à la demande ou planifiée
  • Détection automatique des espaces de noms cibles
  • Suivi de progression et navigation des résultats par élément affecté (applications, ressources, paquets, vulnérabilités)
  • Benchmark CIS Docker
• CLI (CI/CD)
  • Génération de SBOM à l'aide de plusieurs analyseurs de contenu intégrés (Syft, cyclonedx-gomod)
  • Analyse des vulnérabilités de SBOM/images/répertoires à l'aide de plusieurs scanners intégrés (Grype, Dependency-track)
  • Fusion des SBOM et des vulnérabilités entre différentes étapes CI/CD
  • Exportation des résultats vers le backend KubeClarity
• API
  • L'API pour KubeClarity se trouve ici

Integrated SBOM generators and vulnerability scanners

L'analyseur de contenu KubeClarity s'intègre avec les générateurs de SBOM suivants :

• Syft
• Cyclonedx-gomod
• Trivy

Le scanner de vulnérabilités KubeClarity s'intègre avec les scanners suivants :

• Grype
• Dependency-Track
• Trivy

Architecture

Getting Started

KubeClarity Backend

Install using Helm:

1. Add Helm repo ```shell helm repo add kubeclarity https://openclarity.github.io/kubeclarity

   root@kitploit:~

2. Sauvegarder les valeurs par défaut du chart KubeClarity

   root@kitploit:~

   helm show values kubeclarity/kubeclarity > values.yaml
   

3. Vérifiez la configuration dans values.yaml et mettez à jour les valeurs nécessaires si besoin. Pour activer et configurer les générateurs SBOM et les scanners de vulnérabilité pris en charge, veuillez vérifier la configuration "analyzer" et "scanner" sous la section "vulnerability-scanner" dans les valeurs Helm.

4. Déployer KubeClarity avec Helm ```shell helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity

   root@kitploit:~

ou pour installation compatible 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. Rediriger le port vers l'interface utilisateur KubeClarity :   ```shell
kubectl port-forward -n kubeclarity svc/kubeclarity-kubeclarity 9999:8080

4. Ouvrez l'interface utilisateur KubeClarity dans le navigateur : http://localhost:9999/

REMARQUE
KubeClarity nécessite ces autorisations K8s :

Désinstaller à l'aide de Helm :

1. Désinstaller Helm ```shell helm uninstall kubeclarity -n kubeclarity

   root@kitploit:~

2. Nettoyer les ressources

   Par défaut, Helm ne supprimera pas les PVC et PV pour les StatefulSets. Exécutez la commande suivante pour les supprimer tous :

   root@kitploit:~

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

Construire et exécuter localement avec des données de démonstration

1. Construire l'interface et le backend et démarrer le backend localement (2 options) :

   1. En utilisant docker :
      1. Construire l'interface et le backend (le tag de l'image est défini en utilisant VERSION) :
         root@kitploit:~

         VERSION=test make docker-backend
         

      2. Exécuter le backend en utilisant des données de démonstration :
         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. Construction locale :
      1. Construire l'interface et le backend
         root@kitploit:~

         make ui && make backend
         

      2. Copier le site construit :
         root@kitploit:~

         cp -r ./ui/build ./site
         

      3. Exécuter le backend localement en utilisant des données de démonstration :
         root@kitploit:~

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

2. Ouvrir l'interface KubeClarity dans le navigateur : http://localhost:8080/

CLI

KubeClarity inclut une CLI qui peut être exécutée localement et est particulièrement utile pour les pipelines CI/CD. Elle permet d'analyser des images et des répertoires pour générer un SBOM, et de le scanner pour les vulnérabilités. Les résultats peuvent être exportés vers le backend KubeClarity.

Installation

Génération de SBOM

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

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

Optionnellement, une liste des analyseurs de contenu à utiliser peut être configurée à l'aide de la variable d'environnement ANALYZER_LIST, séparée par un espace (par ex. ANALYZER_LIST="<analyzer 1 name> <analyzer 2 name>")

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

### Scan de vulnérabilités

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

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

Optionnellement, une liste des scanners de vulnérabilité à utiliser peut être configurée en utilisant la variable d'environnement `SCANNERS_LIST` séparée par un espace (par exemple `SCANNERS_LIST="<Scanner1 name> <Scanner2 name>"`)

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

Exportation des résultats vers le backend KubeClarity

Pour exporter les résultats de la CLI vers le backend KubeClarity, vous devez utiliser un ID d'application tel que défini par le backend KubeClarity. L'ID d'application peut être trouvé dans l'écran Applications de l'interface utilisateur ou en utilisant l'API KubeClarity.

Exportation du 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

#### Exportation des résultats d'analyse de vulnérabilités```
# 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

Configuration avancée

Génération de SBOM en utilisant une image docker locale comme entrée```

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

## Analyse de vulnérabilités en utilisant une image docker locale comme entrée```
# Local docker images can be scanned using the LOCAL_IMAGE_SCAN env variable

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

Prise en charge des registres privés pour la CLI

La CLI KubeClarity peut lire un fichier de configuration qui stocke les identifiants pour les registres privés.

Exemple de section registre du fichier de configuration :``` registry: auths: - authority: <registry 1> username: <username for registry 1> password: <password for registry 1> - authority: <registry 2> token: <token for registry 2>

Exemple de configuration de registre sans autorité : (dans ce cas, ces informations d'identification seront utilisées pour tous les registres)```
registry:
  auths:
    - username: <username>
      password: <password>

Spécifier le fichier de configuration pour 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

## Prise en charge des registres privés pour l'analyse K8s en cours d'exécution

Kubeclarity utilise [k8schain](https://github.com/google/go-containerregistry/tree/main/pkg/authn/k8schain#k8schain) de google/go-containerregistry pour l'authentification aux registres.
Si les identifiants de service nécessaires ne sont pas détectables par k8schain, ils peuvent être définis via les secrets décrits ci-dessous.

De plus, si les identifiants de service ne se trouvent pas dans l'espace de noms "kubeclarity", veuillez définir CREDS_SECRET_NAMESPACE sur le déploiement kubeclarity.
Lorsque vous utilisez helm [charts](https://github.com/openclarity/kubeclarity/blob/HEAD/charts), CREDS_SECRET_NAMESPACE est défini sur l'espace de noms de la release où kubeclarity est installé.

### Amazon ECR

Créez un [utilisateur IAM AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) disposant des autorisations `AmazonEC2ContainerRegistryFullAccess`.

Utilisez les identifiants de l'utilisateur (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) pour créer le secret suivant :```
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. Le nom du secret doit être ecr-sa
2. Les clés des données du secret doivent être définies sur AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY et AWS_DEFAULT_REGION

Google GCR

Créez un compte de service Google avec les autorisations Artifact Registry Reader.

Utilisez le fichier json du compte de service pour créer le secret suivant``` kubectl -n kubeclarity create secret generic --from-file=sa.json gcr-sa

Remarque :
1. Le nom du secret doit être `gcr-sa`
1. `sa.json` doit être le nom du fichier json du compte de service lors de la génération du secret
2. KubeClarity utilise les [credentials par défaut de l'application](https://developers.google.com/identity/protocols/application-default-credentials). Ceux-ci ne fonctionnent que lorsque KubeClarity est exécuté depuis GCP.

## Fusion des SBOM et des vulnérabilités à travers différentes étapes 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

Sortie des différents formats de SBOM

La commande kubeclarity-cli analyze peut formater le SBOM résultant dans différents formats si nécessaire pour s'intégrer à un autre système. Les formats pris en charge sont :

AVERTISSEMENT
KubeClarity traite CycloneDX en interne, les autres formats sont pris en charge via une conversion. Le processus de conversion peut être imparfait en raison d'incompatibilités entre les formats, donc tous les champs/informations ne sont pas garantis d'être présents dans la sortie résultante.

Pour configurer kubeclarity-cli afin d'utiliser un format autre que celui par défaut, la variable d'environnement ANALYZER_OUTPUT_FORMAT peut être utilisée avec le nom de configuration ci-dessus :``` ANALYZER_OUTPUT_FORMAT="spdx-json" kubeclarity-cli analyze nginx:latest -o nginx.sbom

## Serveurs de scanneurs distants pour CLI

Lors de l'exécution du CLI kubeclarity pour scanner les vulnérabilités, le CLI devra télécharger les bases de données de vulnérabilités pertinentes à l'endroit où le CLI kubeclarity s'exécute. Exécuter le CLI dans un pipeline CI/CD entraînera le téléchargement des bases de données à chaque exécution, gaspillant du temps et de la bande passante. Pour cette raison, plusieurs des scanneurs pris en charge disposent d'un mode distant dans lequel un serveur est responsable de la gestion des bases de données et éventuellement du scan des artefacts.

> ***Remarque***
>
> Les exemples ci-dessous sont pour chacun des scanneurs, mais ils peuvent être combinés pour fonctionner ensemble de la même manière qu'en mode non distant.

### Trivy

Le scanneur Trivy prend en charge le mode distant à l'aide du serveur Trivy. Le serveur Trivy peut être déployé comme documenté ici : [mode client-serveur trivy](https://aquasecurity.github.io/trivy/v0.34/docs/references/modes/client-server/). Les instructions pour installer le CLI Trivy sont disponibles ici : [installation de trivy](https://aquasecurity.github.io/trivy/v0.34/getting-started/installation/). L'équipe Aqua fournit une image de conteneur officielle qui peut être utilisée pour exécuter le serveur dans kubernetes/docker, que nous utiliserons dans les exemples ici.

Pour démarrer le serveur :```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080

Pour exécuter une analyse à l'aide du serveur :``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" ./kubeclarity_cli scan --input-type sbom nginx.sbom

Le serveur trivy propose également une authentification par jeton pour empêcher toute utilisation non autorisée d'une instance du serveur trivy. Vous pouvez l'activer en exécutant le serveur avec le drapeau supplémentaire :```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080 --token mytoken

et passer le jeton au scanner :``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" SCANNER_TRIVY_SERVER_TOKEN="mytoken" ./kubeclarity_cli scan --input-type sbom nginx.sbom

### Grype

Grype prend en charge le mode distant en utilisant [grype-server](https://github.com/portshift/grype-server),
un wrapper RESTful pour Grype qui fournit une API recevant un SBOM et retournant
les résultats d'analyse Grype pour ce SBOM. Grype-server est fourni sous forme d'image conteneur
et peut donc être exécuté dans Kubernetes ou via Docker en mode autonome.

Pour démarrer le serveur :```
docker run -p 9991:9991 --rm gcr.io/eticloud/k8sec/grype-server:v0.1.5

Pour exécuter un scan via le serveur :``` 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 le serveur Grype est déployé avec TLS vous pouvez remplacer le schéma d'URL par défaut comme ceci:```
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

Voir l'exemple de configuration ici

Limites

1. Prend en charge Docker Image Manifest V2, Schema 2 (https://docs.docker.com/registry/spec/manifest-v2-2/). Il ne pourra pas analyser les versions antérieures.

Feuille de route

• Intégration avec des analyseurs de contenu supplémentaires (générateurs de SBOM)
• Intégration avec des scanners de vulnérabilités supplémentaires
• Benchmark CIS Docker dans l'interface utilisateur
• Signature d'images à l'aide de Cosign
• Signature et attestation des métadonnées CI/CD à l'aide de Cosign et in-toto (sécurité de la chaîne d'approvisionnement)
• Paramètres système et gestion des utilisateurs

Contribution

Les pull requests et les rapports de bugs sont les bienvenus.

Pour les modifications plus importantes, veuillez d'abord créer un Issue sur GitHub pour discuter de vos propositions et des implications possibles.

Pour plus de détails, veuillez consulter les directives de contribution pour ce projet

Licence

Apache License, Version 2.0