[!IMPORTANT] KubeClarity è stato deprecato e sostituito da openclarity/openclarity.

Consulta il comunicato di rilascio per maggiori informazioni.

Questo progetto non riceve aggiornamenti. Ti invitiamo a migrare.

KubeClarity è uno strumento per il rilevamento e la gestione della Software Bill Of Materials (SBOM) e delle vulnerabilità di immagini contenitore e filesystem. Esegue scansioni sia su cluster K8s in runtime che su pipeline CI/CD per una maggiore sicurezza della catena di fornitura del software.

Indice

• Perché?
  • Sfide di rilevamento di SBOM e vulnerabilità
  • Soluzione
• Funzionalità
  • Generatori di SBOM e scanner di vulnerabilità integrati
• Architettura
• Per iniziare
  • Backend KubeClarity
    • Installazione con Helm
    • Disinstallazione con Helm
    • Compilazione ed esecuzione locale con dati demo
  • CLI
    • Installazione
    • Generazione SBOM
    • Scansione vulnerabilità
    • Esportazione dei risultati nel backend KubeClarity
• Configurazione avanzata
  • Generazione SBOM utilizzando un'immagine docker locale come input
  • Scansione vulnerabilità utilizzando un'immagine docker locale come input
  • Supporto per registry privati per la CLI
  • Supporto per registry privati per la scansione K8s in runtime
  • Unione di SBOM e vulnerabilità tra diverse fasi CI/CD
  • Output di diversi formati SBOM
  • Server scanner remoti per la CLI
• Limitazioni
• Roadmap
• Contribuire
• Licenza

Perché?

Sfide di rilevamento di SBOM e vulnerabilità

• Una scansione efficace delle vulnerabilità richiede un rilevamento accurato della Software Bill Of Materials (SBOM):
  • Vari linguaggi di programmazione e gestori di pacchetti
  • Varie distribuzioni di sistemi operativi
  • Le informazioni sulle dipendenze dei pacchetti vengono solitamente rimosse durante la compilazione
• Qual è il miglior scanner/analizzatore di SBOM?
• Cosa dovremmo scansionare: repository Git, build, immagini contenitore o runtime?
• Ogni scanner/analizzatore ha il proprio formato: come confrontare i risultati?
• Come gestire le SBOM e le vulnerabilità scoperte?
• In che modo le mie applicazioni sono influenzate da una vulnerabilità appena scoperta?

Soluzione

• Separare la scansione delle vulnerabilità in 2 fasi:
  • Analisi del contenuto per generare SBOM
  • Scansione della SBOM per le vulnerabilità
• Creare un'infrastruttura plug-in per:
  • Eseguire più analizzatori di contenuto in parallelo
  • Eseguire più scanner di vulnerabilità in parallelo
• Scansionare e unire i risultati tra diverse fasi CI utilizzando la CLI di KubeClarity
• Scansione K8s in runtime per rilevare vulnerabilità scoperte dopo il deployment
• Raggruppare le risorse scansionate (immagini/directory) in applicazioni definite per navigare nell'albero delle dipendenze degli oggetti (applicazioni, risorse, pacchetti, vulnerabilità)

Funzionalità

• Dashboard
  • Vulnerabilità correggibili per gravità
  • Top 5 elementi vulnerabili (applicazioni, risorse, pacchetti)
  • Tendenze delle nuove vulnerabilità
  • Conteggio pacchetti per tipo di licenza
  • Conteggio pacchetti per linguaggio di programmazione
  • Contatori generali
• Applicazioni
  • Rilevamento automatico delle applicazioni in runtime K8s
  • Crea/modifica/elimina applicazioni
  • Per applicazione, navigazione verso:
    • Risorse (immagini/directory)
    • Pacchetti
    • Vulnerabilità
    • Licenze in uso dalle risorse
• Risorse dell'applicazione (immagini/directory)
  • Per risorsa, navigazione verso:
    • Applicazioni
    • Pacchetti
    • Vulnerabilità
• Pacchetti
  • Per pacchetto, navigazione verso:
    • Applicazioni
    • Elenco collegabile di risorse e analizzatori SBOM rilevanti
    • Vulnerabilità
• Vulnerabilità
  • Per vulnerabilità, navigazione verso:
    • Applicazioni
    • Risorse
    • Elenco degli scanner rilevanti
• Scansione K8s in runtime
  • Scansione su richiesta o pianificata
  • Rilevamento automatico dei namespace di destinazione
  • Avanzamento della scansione e navigazione dei risultati per elemento interessato (applicazioni, risorse, pacchetti, vulnerabilità)
  • CIS Docker benchmark
• CLI (CI/CD)
  • Generazione SBOM utilizzando più analizzatori di contenuto integrati (Syft, cyclonedx-gomod)
  • Scansione vulnerabilità di SBOM/immagine/directory utilizzando più scanner integrati (Grype, Dependency-track)
  • Unione di SBOM e vulnerabilità tra diverse fasi CI/CD
  • Esportazione dei risultati nel backend KubeClarity
• API
  • L'API di KubeClarity è disponibile qui

Generatori di SBOM e scanner di vulnerabilità integrati

L'analizzatore di contenuto di KubeClarity si integra con i seguenti generatori di SBOM:

• Syft
• Cyclonedx-gomod
• Trivy

Lo scanner di vulnerabilità di KubeClarity si integra con i seguenti scanner:

• Grype
• Dependency-Track
• Trivy

Architettura

Per iniziare

Backend KubeClarity

Installazione con Helm:

1. Aggiungere il repository Helm ```shell helm repo add kubeclarity https://openclarity.github.io/kubeclarity

   root@kitploit:~

2. Salva i valori predefiniti del chart di KubeClarity

   root@kitploit:~

   helm show values kubeclarity/kubeclarity > values.yaml
   

3. Controlla la configurazione in values.yaml e aggiorna i valori necessari se richiesto. Per abilitare e configurare i generatori di SBOM e gli scanner di vulnerabilità supportati, controlla la configurazione "analyzer" e "scanner" nella sezione "vulnerability-scanner" nei valori di Helm.

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

   root@kitploit:~

o per installazione compatibile 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. Inoltra la porta verso l'interfaccia di KubeClarity:   ```shell
kubectl port-forward -n kubeclarity svc/kubeclarity-kubeclarity 9999:8080

4. Apri l'interfaccia utente di KubeClarity nel browser: http://localhost:9999/

NOTA
KubeClarity richiede questi permessi K8s:

Disinstallazione tramite Helm:

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

   root@kitploit:~

2. Pulire le risorse

   Per impostazione predefinita, Helm non rimuoverà i PVC e i PV per i StatefulSets. Eseguire il seguente comando per eliminarli tutti:

   root@kitploit:~

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

Compilare ed eseguire localmente con dati dimostrativi

1. Compilare l'interfaccia utente e il backend e avviare il backend localmente (2 opzioni):

   1. Usando docker:
      1. Compilare interfaccia utente e backend (il tag dell'immagine è impostato usando VERSION):
         root@kitploit:~

         VERSION=test make docker-backend
         

      2. Eseguire il backend con dati dimostrativi:
         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. Compilazione locale:
      1. Compilare interfaccia utente e backend
         root@kitploit:~

         make ui && make backend
         

      2. Copiare il sito compilato:
         root@kitploit:~

         cp -r ./ui/build ./site
         

      3. Eseguire il backend localmente con dati dimostrativi:
         root@kitploit:~

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

2. Aprire l'interfaccia utente di KubeClarity nel browser: http://localhost:8080/

CLI

KubeClarity include una CLI che può essere eseguita localmente ed è particolarmente utile per le pipeline CI/CD. Permette di analizzare immagini e directory per generare SBOM e scansionarlo per vulnerabilità. I risultati possono essere esportati nel backend di KubeClarity.

Installazione

Generazione SBOM

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

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

Opzionalmente, è possibile configurare un elenco degli analizzatori di contenuti da utilizzare tramite la variabile d'ambiente ANALYZER_LIST separata da uno spazio (es. ANALYZER_LIST="<nome analizzatore 1> <nome analizzatore 2>")

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

### Scansione delle vulnerabilità

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

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

Opzionalmente, è possibile configurare un elenco degli scanner di vulnerabilità da utilizzare tramite la variabile d'ambiente `SCANNERS_LIST`, separati da uno spazio (ad esempio `SCANNERS_LIST="<Scanner1 name> <Scanner2 name>"`)```
SCANNERS_LIST="grype trivy" kubeclarity-cli scan nginx.sbom --input-type sbom

Esportazione dei risultati verso il backend KubeClarity

Per esportare i risultati della CLI verso il backend KubeClarity, è necessario utilizzare un ID applicazione come definito dal backend KubeClarity. L'ID applicazione può essere trovato nella schermata Applicazioni dell'interfaccia utente o utilizzando l'API KubeClarity.

Esportazione di 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

#### Esportazione dei risultati della scansione delle vulnerabilità```
# 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

Advanced Configuration

Generazione SBOM utilizzando un'immagine docker locale come 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

## Scansione delle vulnerabilità utilizzando un'immagine docker locale come 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

Supporto per registry privati per CLI

La CLI di KubeClarity può leggere un file di configurazione che memorizza le credenziali per i registry privati.

Esempio di sezione registry del file di configurazione:``` registry: auths: - authority: <registry 1> username: <username for registry 1> password: <password for registry 1> - authority: <registry 2> token: <token for registry 2>

Esempio di configurazione del registro senza autorità: (in questo caso queste credenziali saranno utilizzate per tutti i registri)```
registry:
  auths:
    - username: <username>
      password: <password>

Specifica il file di configurazione per la 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

## Supporto per registri privati per scansione runtime K8s

Kubeclarity utilizza [k8schain](https://github.com/google/go-containerregistry/tree/main/pkg/authn/k8schain#k8schain) di google/go-containerregistry per l'autenticazione ai registri.
Se le credenziali di servizio necessarie non sono individuabili da k8schain, possono essere definite tramite i segreti descritti di seguito.

Inoltre, se le credenziali del servizio non si trovano nel namespace "kubeclarity", impostare CREDS_SECRET_NAMESPACE nel Deployment di kubeclarity.
Quando si utilizzano i [charts](https://github.com/openclarity/kubeclarity/blob/HEAD/charts) di Helm, CREDS_SECRET_NAMESPACE è impostato al namespace di rilascio in cui è installato kubeclarity.

### Amazon ECR

Crea un [utente IAM AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) con autorizzazioni `AmazonEC2ContainerRegistryFullAccess`.

Utilizza le credenziali dell'utente (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) per creare il seguente segreto:```
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. Il nome del segreto deve essere ecr-sa
2. Le chiavi dei dati del segreto devono essere impostate su AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY e AWS_DEFAULT_REGION

Google GCR

Crea un account di servizio Google con autorizzazioni Artifact Registry Reader.

Utilizza il file json dell'account di servizio per creare il seguente segreto``` kubectl -n kubeclarity create secret generic --from-file=sa.json gcr-sa

Nota:
1. Il nome del segreto deve essere `gcr-sa`
1. `sa.json` deve essere il nome del file json dell'account di servizio quando si genera il segreto
2. KubeClarity utilizza le [credenziali predefinite dell'applicazione](https://developers.google.com/identity/protocols/application-default-credentials). Queste funzionano solo quando si esegue KubeClarity da GCP.

## Unione di SBOM e vulnerabilità tra diverse fasi 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

Output di diversi formati SBOM

Il comando kubeclarity-cli analyze può formattare l'SBOM risultante in diversi formati, se necessario, per integrarsi con un altro sistema. I formati supportati sono:

AVVERTENZA
KubeClarity elabora CycloneDX internamente, gli altri formati sono supportati tramite una conversione. Il processo di conversione può essere con perdita a causa di incompatibilità tra i formati, pertanto non è garantito che tutti i campi/informazioni siano presenti nell'output risultante.

Per configurare kubeclarity-cli per utilizzare un formato diverso da quello predefinito, è possibile utilizzare la variabile d'ambiente ANALYZER_OUTPUT_FORMAT con il nome della configurazione sopra indicato:``` ANALYZER_OUTPUT_FORMAT="spdx-json" kubeclarity-cli analyze nginx:latest -o nginx.sbom

## Server scanner remoti per CLI

Quando si esegue il CLI di kubeclarity per la scansione delle vulnerabilità, il CLI dovrà scaricare i relativi database delle vulnerabilità nella posizione in cui è in esecuzione il CLI di kubeclarity. Eseguire il CLI in una pipeline CI/CD comporterà il download dei database ad ogni esecuzione, sprechando tempo e larghezza di banda. Per questo motivo, molti degli scanner supportati dispongono di una modalità remota in cui un server è responsabile della gestione dei database e, eventualmente, della scansione degli artefatti.

> ***Nota***
>
> Gli esempi seguenti riguardano ciascuno scanner, ma possono essere combinati per funzionare insieme come nella modalità non remota.

### Trivy

Lo scanner Trivy supporta la modalità remota utilizzando il server Trivy. Il server Trivy può essere distribuito come documentato qui: [trivy client-server mode](https://aquasecurity.github.io/trivy/v0.34/docs/references/modes/client-server/). Le istruzioni per installare il CLI Trivy sono disponibili qui: [trivy install](https://aquasecurity.github.io/trivy/v0.34/getting-started/installation/). Il team Aqua fornisce un'immagine contenitore ufficiale che può essere utilizzata per eseguire il server in kubernetes/docker, che useremo negli esempi qui.

Per avviare il server:```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080

Per eseguire una scansione utilizzando il server:``` SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://:8080" ./kubeclarity_cli scan --input-type sbom nginx.sbom

Il server trivy fornisce anche l'autenticazione basata su token per prevenire
l'uso non autorizzato di un'istanza del server trivy. È possibile abilitarla eseguendo il
server con il flag aggiuntivo:```
docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080 --token mytoken

e passando il token allo 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 supporta la modalità remota utilizzando [grype-server](https://github.com/portshift/grype-server) un wrapper RESTful per grype che fornisce un'API che riceve un SBOM e restituisce i risultati della scansione grype per quel SBOM. Grype-server viene fornito come immagine container, quindi può essere eseguito in kubernetes o tramite docker standalone.

Per avviare il server:```
docker run -p 9991:9991 --rm gcr.io/eticloud/k8sec/grype-server:v0.1.5

Per eseguire una scansione utilizzando il server:``` 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

Se il server Grype è distribuito con TLS puoi sovrascrivere lo schema URL predefinito come:```
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

Vedi la configurazione di esempio qui

Limitazioni

1. Supporta Docker Image Manifest V2, Schema 2 (https://docs.docker.com/registry/spec/manifest-v2-2/). Fallirà la scansione delle versioni precedenti.

Piano di sviluppo

• Integrazione con analizzatori di contenuti aggiuntivi (generatori di SBOM)
• Integrazione con scanner di vulnerabilità aggiuntivi
• Benchmark CIS Docker nell'interfaccia utente
• Firma delle immagini usando Cosign
• Firma e attestazione dei metadati CI/CD usando Cosign e in-toto (sicurezza della supply chain)
• Impostazioni di sistema e gestione utenti

Contributi

Le pull request e le segnalazioni di bug sono benvenute.

Per modifiche più grandi, crea prima un Issue su GitHub per discutere le modifiche proposte e le possibili implicazioni.

Per ulteriori dettagli, consulta le linee guida per i contributi di questo progetto

Licenza

Apache License, Version 2.0