[!IMPORTANT] KubeClarity foi descontinuado e sucedido por openclarity/openclarity.

Consulte o comunicado de lançamento para mais informações.

Este projeto não recebe atualizações. Encorajamos que faça a migração.

KubeClarity é uma ferramenta para deteção e gestão de Listas de Materiais de Software (SBOM) e vulnerabilidades de imagens de contêineres e sistemas de ficheiros. Ela examina tanto clusters K8s em runtime como pipelines CI/CD para uma segurança reforçada da cadeia de fornecimento de software.

Índice

• Porquê?
  • Desafios da deteção de SBOM e vulnerabilidades
  • Solução
• Funcionalidades
  • Geradores de SBOM e scanners de vulnerabilidades integrados
• Arquitetura
• Começar
  • KubeClarity Backend
    • Instalar usando Helm
    • Desinstalar usando Helm
    • Construir e executar localmente com dados de demonstração
  • CLI
    • Instalação
    • Geração de SBOM
    • Scan de vulnerabilidades
    • Exportar resultados para o KubeClarity Backend
• Configuração avançada
  • Geração de SBOM usando imagem docker local como entrada
  • Scan de vulnerabilidades usando imagem docker local como entrada
  • Suporte a registos privados para CLI
  • Suporte a registos privados para scan K8s em runtime
  • Fusão de SBOM e vulnerabilidades entre diferentes estágios de CI/CD
  • Saída de diferentes formatos de SBOM
  • Servidores de scan remotos para CLI
• Limitações
• Roadmap
• Contribuir
• Licença

Porquê?

Desafios da deteção de SBOM e vulnerabilidades

• A deteção eficaz de vulnerabilidades requer uma Lista de Materiais de Software (SBOM) precisa:
  • Várias linguagens de programação e gestores de pacotes
  • Várias distribuições de SO
  • A informação sobre dependências de pacotes é geralmente removida durante a construção
• Qual é o melhor scanner/analisador de SBOM?
• O que devemos examinar: repositórios Git, compilações, imagens de contêineres ou runtime?
• Cada scanner/analisador tem o seu próprio formato - como comparar os resultados?
• Como gerir os SBOMs e vulnerabilidades descobertos?
• Como são as minhas aplicações afetadas por uma vulnerabilidade recém-descoberta?

Solução

• Separar o scan de vulnerabilidades em 2 fases:
  • Análise de conteúdo para gerar SBOM
  • Examinar o SBOM em busca de vulnerabilidades
• Criar uma infraestrutura plugável para:
  • Executar vários analisadores de conteúdo em paralelo
  • Executar vários scanners de vulnerabilidades em paralelo
• Examinar e fundir resultados entre diferentes estágios de CI usando o KubeClarity CLI
• Scan K8s em runtime para detetar vulnerabilidades descobertas pós-implementação
• Agrupar recursos examinados (imagens/diretórios) sob aplicações definidas para navegar na árvore de dependências de objetos (aplicações, recursos, pacotes, vulnerabilidades)

Funcionalidades

• Dashboard
  • Vulnerabilidades corrigíveis por gravidade
  • Top 5 elementos vulneráveis (aplicações, recursos, pacotes)
  • Tendências de novas vulnerabilidades
  • Contagem de pacotes por tipo de licença
  • Contagem de pacotes por linguagem de programação
  • Contadores gerais
• Aplicações
  • Deteção automática de aplicações em runtime K8s
  • Criar/editar/eliminar aplicações
  • Por aplicação, navegação para os relacionados:
    • Recursos (imagens/diretórios)
    • Pacotes
    • Vulnerabilidades
    • Licenças em uso pelos recursos
• Recursos da Aplicação (imagens/diretórios)
  • Por recurso, navegação para os relacionados:
    • Aplicações
    • Pacotes
    • Vulnerabilidades
• Pacotes
  • Por pacote, navegação para os relacionados:
    • Aplicações
    • Lista de recursos ligáveis e os analisadores de SBOM detetores
    • Vulnerabilidades
• Vulnerabilidades
  • Por vulnerabilidade, navegação para os relacionados:
    • Aplicações
    • Recursos
    • Lista de scanners detetores
• Scan K8s em runtime
  • Scan sob demanda ou agendado
  • Deteção automática de namespaces alvo
  • Progresso do scan e navegação de resultados por elemento afetado (aplicações, recursos, pacotes, vulnerabilidades)
  • Referencial CIS Docker
• CLI (CI/CD)
  • Geração de SBOM usando múltiplos analisadores de conteúdo integrados (Syft, cyclonedx-gomod)
  • Scan de vulnerabilidades de SBOM/imagem/diretório usando múltiplos scanners integrados (Grype, Dependency-track)
  • Fusão de SBOM e vulnerabilidades entre diferentes estágios de CI/CD
  • Exportar resultados para o backend KubeClarity
• API
  • A API para KubeClarity pode ser encontrada aqui

Geradores de SBOM e scanners de vulnerabilidades integrados

O analisador de conteúdo do KubeClarity integra-se com os seguintes geradores de SBOM:

• Syft
• Cyclonedx-gomod
• Trivy

O scanner de vulnerabilidades do KubeClarity integra-se com os seguintes scanners:

• Grype
• Dependency-Track
• Trivy

Arquitetura

Começar

KubeClarity Backend

Instalar usando Helm:

1. Adicionar repositório Helm ```shell helm repo add kubeclarity https://openclarity.github.io/kubeclarity

   root@kitploit:~

2. Salve os valores padrão do chart do KubeClarity

   root@kitploit:~

   helm show values kubeclarity/kubeclarity > values.yaml
   

3. Verifique a configuração em values.yaml e atualize os valores necessários, se necessário. Para habilitar e configurar os geradores de SBOM e scanners de vulnerabilidade suportados, verifique as configurações de "analyzer" e "scanner" na seção "vulnerability-scanner" nos valores do Helm.

4. Implante o KubeClarity com Helm ```shell helm install --values values.yaml --create-namespace kubeclarity kubeclarity/kubeclarity -n kubeclarity

   root@kitploit:~

ou para instalação compatível com 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. Encaminhe porta para a UI do KubeClarity:   ```shell
kubectl port-forward -n kubeclarity svc/kubeclarity-kubeclarity 9999:8080

4. Abra a interface KubeClarity no navegador: http://localhost:9999/

NOTA
KubeClarity requer estas permissões do Kubernetes:

Desinstalar usando Helm:

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

   root@kitploit:~

2. Limpar recursos

   Por padrão, Helm não removerá os PVCs e PVs dos StatefulSets. Execute o comando a seguir para excluí-los todos:

   root@kitploit:~

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

Construir e Executar Localmente com Dados de Demonstração

1. Construir a UI e o backend e iniciar o backend localmente (2 opções):

   1. Usando docker:
      1. Construir UI e backend (a tag da imagem é definida usando VERSION):
         root@kitploit:~

         VERSION=test make docker-backend
         

      2. Executar o backend usando dados de demonstração:
         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. Build local:
      1. Construir UI e backend
         root@kitploit:~

         make ui && make backend
         

      2. Copiar o site construído:
         root@kitploit:~

         cp -r ./ui/build ./site
         

      3. Executar o backend localmente usando dados de demonstração:
         root@kitploit:~

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

2. Abrir a UI do KubeClarity no navegador: http://localhost:8080/

CLI

O KubeClarity inclui uma CLI que pode ser executada localmente e é especialmente útil para pipelines de CI/CD. Ela permite analisar imagens e diretórios para gerar SBOM e escanear vulnerabilidades. Os resultados podem ser exportados para o backend do KubeClarity.

Instalação

Geração de SBOM

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

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

Opcionalmente, uma lista dos analisadores de conteúdo a usar pode ser configurada utilizando a variável de ambiente ANALYZER_LIST separada por um espaço (por exemplo, ANALYZER_LIST="<nome do analisador 1> <nome do analisador 2>")

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

### Varredura de Vulnerabilidades

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

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

Opcionalmente, uma lista dos scanners de vulnerabilidade a usar pode ser configurada usando a variável de ambiente `SCANNERS_LIST` separada por espaços (ex: `SCANNERS_LIST="<Scanner1 name> <Scanner2 name>"`)

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

Exportando Resultados para o Backend KubeClarity

Para exportar resultados da CLI para o backend KubeClarity, é necessário usar um ID de aplicação conforme definido pelo backend KubeClarity. O ID da aplicação pode ser encontrado na tela de Aplicações na interface do usuário (UI) ou usando a API do KubeClarity.

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

Configuração Avançada

Geração de SBOM usando imagem docker local 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

## Escaneamento de vulnerabilidades usando imagem 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

Suporte para registro privado na CLI

A CLI do KubeClarity pode ler um arquivo de configuração que armazena credenciais para registros privados.

Exemplo de seção de registro do arquivo de configuração:``` registry: auths: - authority: <registry 1> username: <username for registry 1> password: <password for registry 1> - authority: <registry 2> token: <token for registry 2>

Exemplo de configuração de registro sem autoridade: (neste caso, estas credenciais serão usadas para todos os registros)```
registry:
  auths:
    - username: <username>
      password: <password>

Especificar ficheiro de configuração 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

## Suporte para registries privados na varredura de runtime do K8s

O Kubeclarity utiliza [k8schain](https://github.com/google/go-containerregistry/tree/main/pkg/authn/k8schain#k8schain) do google/go-containerregistry para autenticação nos registries.
Se as credenciais de serviço necessárias não forem descobertas pelo k8schain, elas podem ser definidas através dos segredos descritos abaixo.

Além disso, se as credenciais de serviço não estiverem localizadas no Namespace "kubeclarity", defina CREDS_SECRET_NAMESPACE no Deployment do kubeclarity.
Ao usar o helm [charts](https://github.com/openclarity/kubeclarity/blob/HEAD/charts), o CREDS_SECRET_NAMESPACE é definido como o namespace de release onde o kubeclarity foi instalado.

### Amazon ECR

Crie um [usuário IAM da AWS](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html#id_users_create_console) com permissões `AmazonEC2ContainerRegistryFullAccess`.

Use as credenciais do usuário (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`) para criar o seguinte segredo:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: ecr-credentials
  namespace: kubeclarity
type: Opaque
stringData:
  AWS_ACCESS_KEY_ID: <your-access-key-id>
  AWS_SECRET_ACCESS_KEY: <your-secret-access-key>
  AWS_DEFAULT_REGION: <your-region>

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. O nome do segredo deve ser `ecr-sa`
2. As chaves de dados do segredo devem ser definidas como `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_DEFAULT_REGION`

### Google GCR

Crie uma [conta de serviço do Google](https://cloud.google.com/docs/authentication/getting-started#creating_a_service_account) com permissões de `Artifact Registry Reader`.

Use o arquivo json da conta de serviço para criar o seguinte segredo```
kubectl -n kubeclarity create secret generic --from-file=sa.json gcr-sa

Note:

1. O nome do segredo deve ser gcr-sa
2. sa.json deve ser o nome do arquivo json da conta de serviço ao gerar o segredo
3. KubeClarity está usando application default credentials. Estas só funcionam quando se executa KubeClarity a partir do GCP.

Mesclagem de SBOM e vulnerabilidades em diferentes estágios 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

## Saída de Diferentes Formatos de SBOM

O comando kubeclarity-cli analyze pode formatar o SBOM resultante em
diferentes formatos, se necessário, para integrar com outro sistema. Os formatos
suportados são:

| Formato | Nome da Configuração |
| --- | --- |
| CycloneDX JSON (padrão) | cyclonedx-json |
| CycloneDX XML | cyclonedx-xml |
| SPDX JSON | spdx-json |
| SPDX Tag Value | spdx-tv |
| Syft JSON | syft-json |


> ***AVISO***  
> O KubeClarity processa CycloneDX internamente; os outros formatos são suportados
> através de uma conversão. O processo de conversão pode ser perda de dados devido a
> incompatibilidades entre formatos, portanto, nem todos os campos/informações são
> garantidos de estar presentes na saída resultante.

Para configurar o kubeclarity-cli para usar um formato diferente do padrão, a
variável de ambiente ANALYZER\_OUTPUT\_FORMAT pode ser usada com o
nome da configuração acima:```
ANALYZER_OUTPUT_FORMAT="spdx-json" kubeclarity-cli analyze nginx:latest -o nginx.sbom

Servidores de Scanner Remotos para CLI

Ao executar a CLI do kubeclarity para verificar vulnerabilidades, a CLI precisará baixar os bancos de dados de vulnerabilidade relevantes para o local onde a CLI do kubeclarity está sendo executada. Executar a CLI em um pipeline de CI/CD resultará no download dos bancos de dados a cada execução, desperdiçando tempo e largura de banda. Por esse motivo, vários dos scanners suportados possuem um modo remoto no qual um servidor é responsável pelo gerenciamento dos bancos de dados e, possivelmente, pela verificação dos artefatos.

Nota

Os exemplos abaixo são para cada um dos scanners, mas eles podem ser combinados para serem executados juntos da mesma forma que podem no modo não remoto.

Trivy

O scanner Trivy suporta modo remoto usando o servidor Trivy. O servidor Trivy pode ser implantado conforme documentado aqui: modo cliente-servidor do trivy. Instruções para instalar a CLI do Trivy estão disponíveis aqui: instalação do trivy. A equipe da Aqua fornece uma imagem de contêiner oficial que pode ser usada para executar o servidor em kubernetes/docker, que usaremos nos exemplos aqui.

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

Para executar uma verificação usando o servidor:```
SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://<trivy server address>:8080" ./kubeclarity_cli scan --input-type sbom nginx.sbom

O servidor trivy também fornece autenticação baseada em token para prevenir uso não autorizado de uma instância do servidor trivy. Você pode habilitá-la executando o servidor com a flag extra:``` docker run -p 8080:8080 --rm aquasec/trivy:0.41.0 server --listen 0.0.0.0:8080 --token mytoken

e passando o token para o scanner:```
SCANNERS_LIST="trivy" SCANNER_TRIVY_SERVER_ADDRESS="http://<trivy server address>:8080" SCANNER_TRIVY_SERVER_TOKEN="mytoken" ./kubeclarity_cli scan --input-type sbom nginx.sbom

Grype

Grype suporta modo remoto usando grype-server um wrapper RESTful do grype que fornece uma API que recebe um SBOM e retorna os resultados da varredura do grype para esse SBOM. O Grype-server é distribuído como uma imagem de contêiner, podendo ser executado no kubernetes ou via docker standalone.

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

Para executar uma varredura usando o servidor:```
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

Se o servidor Grype for implantado com TLS, você pode substituir o esquema de URL padrão como:``` 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

### Dependency Track

Veja a configuração de exemplo [aqui](https://github.com/openclarity/kubeclarity/blob/HEAD/shared/pkg/scanner/dependency_track/example/README.md)

# Limitações

1. Suporta Docker Image Manifest V2, Schema 2 (https://docs.docker.com/registry/spec/manifest-v2-2/). Falhará ao escanear versões anteriores.

# Roteiro
* Integração com analisadores de conteúdo adicionais (geradores de SBOM)
* Integração com scanners de vulnerabilidade adicionais
* CIS Docker benchmark na interface do usuário
* Assinatura de imagens usando [Cosign](https://github.com/sigstore/cosign)
* Assinatura e atestado de metadados CI/CD usando [Cosign](https://github.com/sigstore/cosign) e [in-toto](https://github.com/in-toto/in-toto) (segurança da cadeia de suprimentos)
* Configurações do sistema e gerenciamento de usuários

# Contribuição

Pull requests e relatórios de bugs são bem-vindos.

Para mudanças maiores, por favor crie um Issue no GitHub primeiro para discutir suas
mudanças propostas e possíveis implicações.

Mais mais detalhes, consulte as [Diretrizes de contribuição para este projeto](https://github.com/openclarity/kubeclarity/blob/HEAD/CONTRIBUTING.md)

## Licença

[Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)