Impondo atestados de artefatos com um controlador de admissão do Kubernetes

Use um controlador de admissão para impor atestados de artefato em seu cluster Kubernetes.

Neste artigo

Note

Antes de continuar, verifique se você habilitou a procedência do build para imagens de contêiner, incluindo a definição do atributo push-to-registry na ação attest-build-provenance, conforme documentado em Gerando a procedência do build para imagens de contêiner. Isso é necessário para que o Controlador de Política verifique o atestado.

Sobre o controlador de admissão do Kubernetes

Os atestados de artefatos permitem que você crie garantias de procedência e integridade infalsificáveis para o software que você cria. Por sua vez, as pessoas que consomem seu software podem verificar onde e como seu software foi criado.

Os controladores de admissão do Kubernetes são plug-ins que governam o comportamento do servidor de API do Kubernetes. Eles são comumente usados para impor políticas de segurança e práticas recomendadas em um cluster do Kubernetes.

Usando o projeto de código aberto Sigstore Policy Controller, você pode adicionar um controlador de admissão ao seu cluster do Kubernetes que pode impor atestados de artefatos. Dessa forma, você pode garantir que apenas artefatos com atestados válidos possam ser implantados.

Para instalar o controlador, oferecemos dois gráficos Helm: um para implantar o Sigstore Policy Controller e outro para carregar a raiz de confiança do GitHub e uma política padrão.

Sobre a verificação de imagens

Quando o Controlador de Política for instalado, ele interceptará todas as solicitações de pull de imagem e verificará o atestado da imagem. O atestado deve ser armazenado no registro de imagem como um artefato anexado OCI contendo um pacote Sigstore que contém o atestado e o material criptográfico (por exemplo, certificados e assinaturas) usados para verificar o atestado. Em seguida, é executado um processo de verificação que garante que a imagem foi criada com a procedência de build especificada e corresponde a todas as políticas habilitadas pelo administrador do cluster.

Para que uma imagem seja verificável, ela precisa ter um atestado de procedência válido no registro, o que pode ser feito habilitando o atributo push-to-registry: true na ação actions/attest-build-provenance. Confira Gerando a procedência de build para imagens de contêiner para obter mais detalhes sobre como gerar atestados para imagens de contêiner.

Sobre raízes e políticas de confiança

O Sigstore Policy Controller é configurado principalmente com raízes e políticas de confiança, representadas pelos Recursos Personalizados TrustRoot e ClusterImagePolicy. Um TrustRoot representa um canal de distribuição confiável para o material de chave pública usado para verificar atestados. Uma ClusterImagePolicy representa uma política para aplicar atestados em imagens.

Um TrustRoot também pode conter uma raiz de repositório TUF, possibilitando que seu cluster receba atualizações contínuas e seguras para seu material de chave pública confiável. Se não for especificado, uma ClusterImagePolicy usará por padrão o material para chave da Sigstore Public Good de código aberto. Ao verificar os atestados gerados para repositórios privados, o ClusterImagePolicy deve fazer referência ao GitHub TrustRoot.

Introdução ao controlador de admissão do Kubernetes

Para configurar um controlador de admissão para aplicar atestados de artefato do GitHub, você precisa:

  1. Implantar o Sigstore Policy Controller.
  2. Adicionar o GitHub TrustRoot e uma ClusterImagePolicy ao cluster.
  3. Habilitar a política em seu namespace.

Implantar o Sigstore Policy Controller

Nós empacotamos o Sigstore Policy Controller como um gráfico Helm distribuído do GitHub. Antes de começar, verifique se de que tem os seguintes pré-requisitos:

  • Um cluster do Kubernetes com versão 1.27 ou posterior
  • Helm 3.0 ou posterior
  • kubectl

Primeiro, instale o gráfico Helm que implanta o Sigstore Policy Controller:

Bash
helm upgrade policy-controller --install --atomic \
  --create-namespace --namespace artifact-attestations \
  oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller \
  --version v0.12.0-github10

Isso instala o Controlador de Política no namespace artifact-attestations. Neste ponto, nenhuma política foi configurada e não imporá atestados.

Adicione o GitHub TrustRoot e um ClusterImagePolicy

Depois que o controlador de política tiver sido implantado, você precisará adicionar o GitHub TrustRoot e um ClusterImagePolicy ao cluster. Use o gráfico Helm que fornecemos para fazer isso. Certifique-se de substituir MY-ORGANIZATION pelo nome da sua organização do GitHub (por exemplo, github ou octocat-inc).

Bash
helm upgrade trust-policies --install --atomic \
 --namespace artifact-attestations \
 oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies \
 --version v0.6.2 \
 --set policy.enabled=true \
 --set policy.organization=MY-ORGANIZATION

Agora você instalou a raiz de confiança do GitHub e uma política de atestado de artefato em seu cluster. Essa política rejeitará artefatos que não tenham se originado de sua organização do GitHub.

Habilitar a política em seu namespace

Warning

Essa política não será aplicada até que você especifique a quais namespaces ela deve se aplicar.

Cada namespace em seu cluster pode impor políticas de forma independente. Para habilitar a imposição em um namespace, você pode adicionar o seguinte rótulo ao namespace:

metadata:
  labels:
    policy.sigstore.dev/include: "true"

Depois que o rótulo for adicionado, a política de atestado de artefato do GitHub será imposta no namespace.

Como alternativa, você pode executar:

Bash
kubectl label namespace MY-NAMESPACE policy.sigstore.dev/include=true

Imagens correspondentes

Por padrão, a política instalada com o gráfico do Helm trust-policies verificará os atestados de todas as imagens antes de admiti-las no cluster. Se você pretende impor atestados apenas para um subconjunto de imagens, pode usar os valores do Helm policy.images e policy.exemptImages para especificar uma lista de imagens para correspondência. Esses valores podem ser definidos como uma lista de padrões glob que correspondem aos nomes das imagens. A sintaxe de recurso de curinga usa a semântica do caminho de arquivo Go, com a adição de ** para corresponder a qualquer sequência de caracteres, incluindo barras.

Por exemplo, para impor atestados para imagens que correspondem ao padrão ghcr.io/MY-ORGANIZATION/* e admitem busybox sem um atestado válido, é possível executar:

Bash
helm upgrade trust-policies --install --atomic \
 --namespace artifact-attestations \
 oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies \
 --version v0.6.2 \
 --set policy.enabled=true \
 --set policy.organization=MY-ORGANIZATION \
 --set-json 'policy.exemptImages=["index.docker.io/library/busybox**"]' \
 --set-json 'policy.images=["ghcr.io/MY-ORGANIZATION/**"]'

Todos os padrões devem usar o nome totalmente qualificado, mesmo que as imagens sejam originadas do Docker Hub. Neste exemplo, se quisermos isentar a imagem busybox, devemos fornecer o nome completo, incluindo o domínio e o glob de estrela dupla para corresponder a todas as versões da imagem: index.docker.io/library/busybox**.

Observe que qualquer imagem que você pretende admitir deve ter um padrão glob correspondente na lista policy.images. Se uma imagem não corresponder a padrão, ela será rejeitada. Além disso, se uma imagem corresponder a ambos policy.images e policy.exemptImages, ela será rejeitada.

Se a sua conta do GitHub Enterprise tiver um subdomínio no GHE.com, você precisará especificar um valor para o domínio de confiança do GitHub. Esse valor é usado para buscar os materiais confiáveis associados à região de residência de dados que hospeda sua conta do GitHub Enterprise. Esse valor pode ser encontrado fazendo login em sua conta empresarial com a ferramenta de CLI gh e executando o seguinte comando:

Bash
gh api meta --jq .domains.artifact_attestations.trust_domain

Esse valor deve ser adicionado ao instalar o gráfico trust-policies, da seguinte forma:

Bash
--set-json 'policy.trust.githubTrustDomain="YOUR-GHEC-TRUST-DOMAIN"'

Uso avançado

Para ver o conjunto completo de opções que você pode configurar com o gráfico Helm, você pode executar um dos seguintes comandos. Para opções de controlador de diretiva:

Bash
helm show values oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller --version v0.12.0-github10

Para opções de política de confiança:

Bash
helm show values oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies --version v0.6.2

Para obter mais informações sobre o Sigstore Policy Controller, consulte a documentação do Sigstore Policy Controller.