Iniciar sessãoAgendar apresentação

Capítulo 2.4

Obter e verificar uma versão

Onde reside cada parte de uma versão do Nexus, como as imagens Enterprise são obtidas com um token de transferência (pull token) e como provar offline que cada imagem, chart e transferência veio da Adverant sem alterações, antes de instalar o que quer que seja.

Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

15 minutos de leitura

Cada imagem numa versão do Nexus é assinada pela chave de lançamento da Adverant, e cada imagem é identificada pelo seu digest, nunca por uma etiqueta (tag). O chart apenas irá processar imagens listadas por digest no seu próprio ficheiro de bloqueio de imagens (images lock). Em conjunto, isto significa que pode provar, na sua própria estação de trabalho e sem qualquer ligação a terceiros, que o que está prestes a executar é exatamente o que a Adverant compilou.

Na Harrow Port Authority, verificámos tudo antes da primeira instalação. Demorou cerca de vinte minutos, e a maior parte desse tempo foi o ciclo sobre as imagens. Este capítulo segue o mesmo caminho: onde reside cada parte da versão, o token de extração (pull token) para imagens Enterprise, o bloqueio de imagens, as verificações cosign com os seus comandos exatos e o que fazer quando uma verificação falha.

Onde reside a versão

Endereço O que obtém nesse local
registry.adverant.ai As imagens da plataforma, em registry.adverant.ai/nexus/<service>@sha256:<digest>, e o chart do Helm, em oci://registry.adverant.ai/nexus/charts/nexus
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ A chave pública de lançamento e a sua impressão digital, os binários nexusctl e os pacotes offline
https://account.adverant.ai A sua conta Adverant: Transferências, Tokens de extração e comandos de instalação, Implementações e as páginas de licenciamento

As imagens Community e o chart Community são públicos; pode extraí-los sem iniciar sessão. As imagens Enterprise são extraídas com um token de extração da sua conta, e o chart e o pacote Enterprise encontram-se na página Transferências da conta, que segue a sua licença.

Transferências
Transferências
Transferências na conta Adverant, por versão e canal. Cada ficheiro apresenta a sua soma de verificação (checksum) e assinatura ao lado, e os componentes fora do âmbito da licença permanecem listados, a cinzento, com a respetiva justificação.

Ler as notas de lançamento antes de tudo o resto

As notas de lançamento são fornecidas dentro de cada pacote como docs/RELEASE-NOTES.md, listadas no seu SHA256SUMS, e as mesmas notas encontram-se na página de lançamento da sua conta. Leia-as antes de instalar ou atualizar. Para a 1.0.0-alpha.1, são curtas. Trata-se da primeira versão, pelo que uma instalação de raiz não tem nenhum dos pontos de atualização que descrevem, e a lista de problemas conhecidos indica que nada nela afeta uma instalação de raiz que siga os passos documentados. As versões posteriores listam cada problema conhecido com a versão que o corrige.

A página de lançamento também indica, em três linhas, o que uma versão alfa promete: as funcionalidades podem mudar antes da primeira versão estável, uma atualização mantém os seus dados e efetua primeiro uma cópia de segurança, e as correções de segurança chegam no prazo de 7 dias. Imprimimos essa página e colocámo-la no registo de alterações na Harrow, porque é o mais próximo de uma declaração de suporte que o comité de alterações pediria.

Passo 1: obter a chave da versão e verificá-la por uma segunda via

Tudo o que se segue assenta num único ficheiro: a chave pública de lançamento da Adverant. Uma chave proveniente do mesmo local que o elemento que atesta prova muito pouco, por isso verifique a sua impressão digital comparando-a com uma cópia que lhe tenha chegado por outra via.

  1. Transfira a chave a partir da pasta da versão em Transferências.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Calcule a sua impressão digital. A impressão digital é o SHA-256 (Secure Hash Algorithm 256) do próprio ficheiro da chave.

    sha256sum release.pub

    No macOS, shasum -a 256 release.pub devolve o mesmo resultado.

  3. Compare-a, carácter a carácter, com a impressão digital impressa no seu contrato com a Adverant e nas notas de lançamento. A página Transferências também publica a impressão digital, mas essa cópia veio pela mesma via que a chave, pelo que não serve de verificação.

Se algum carácter for diferente, pare. Não instale e não procure outra cópia da chave na Internet. Abra um pedido de suporte a partir da sua conta e cite o que observou.

Passo 2: obter o nexusctl

O nexusctl é a interface de linha de comandos (CLI) do operador do Nexus. É executado na sua estação de trabalho e lê o seu cluster através do seu kubeconfig. A secção Transferências disponibiliza quatro compilações:

Ficheiro Plataforma
nexusctl-linux-amd64 Linux em Intel ou AMD
nexusctl-darwin-arm64 macOS em Apple silicon
nexusctl-darwin-amd64 macOS em Intel
nexusctl-windows-amd64.exe Windows

Ao lado de cada ficheiro encontra-se o seu pacote de assinatura, com o mesmo nome terminado em .sigstore.json. Verifique o binário antes de o executar:

curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64
curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/nexusctl-linux-amd64.sigstore.json
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle nexusctl-linux-amd64.sigstore.json nexusctl-linux-amd64
Verified OK

Em seguida, coloque-o no seu PATH e consulte a respetiva versão:

install -m 0755 nexusctl-linux-amd64 /usr/local/bin/nexusctl
nexusctl version

A partir daqui, o nexusctl verify pode efetuar as verificações de ficheiros por si. O Capítulo 2.5, Pré-verificação com o nexusctl, aborda a sua principal função, a pré-verificação (preflight).

Porque é que a opção diz "insecure"

Todos os comandos cosign neste capítulo incluem --insecure-ignore-tlog=true. As versões do Nexus são assinadas com a chave da Adverant e não são registadas em nenhum registo de transparência público, para que a verificação de uma versão nunca necessite de ligação a terceiros, incluindo o Sigstore. Por predefinição, o cosign exige uma entrada de registo; a opção indica-lhe que confie apenas na chave. Sem ela, a verificação falha da seguinte forma:

Error: not enough verified log entries from transparency log: 0 < 1

Quando a opção está definida, o cosign continua a imprimir a frase "Existence of the claims in the transparency log was verified offline". Trata-se de um texto fixo no cosign; não existe nenhuma entrada de registo por detrás dele. A verificação da assinatura face à chave é real, e é a parte que importa.

Passo 3: um token de transferência, para a edição Enterprise

As imagens Enterprise estão protegidas por um token de extração. Pode criar um na sua conta, em Tokens de extração e comandos de instalação:

  1. Prima Adicionar um token.
  2. Indique a que cluster se destina, o que pode obter e quando expira.
  3. Prima Copiar o token e cole-o diretamente no local onde guarda as credenciais, pois a página mostra-o apenas esta única vez.

Cada token está limitado ao que pode obter e tem uma data de fim. A revogação de um token interrompe de imediato novas extrações; as imagens que um cluster já extraiu continuam em execução. Na Harrow, criámos um token por cluster, pelo que revogar o token do cluster de teste nunca afeta a produção. Uma instalação Community não necessita de qualquer token; só cria um quando passa para a edição Enterprise, e pode criá-lo no próprio dia.

Tokens de extração e comandos de instalação
Tokens de extração e comandos de instalação
Tokens de extração na conta Adverant. Cada token mostra o que pode obter, quem o criou e quando expira; um novo token é mostrado uma única vez, e a sua revogação interrompe novas extrações sem parar nada que já esteja em execução.

O chart não tem um valor de segredo de extração (pull-secret). Os seus nós extraem as imagens, pelo que o token pertence ao ambiente de execução de contentores dos nós. No k3s, adicione o registo a /etc/rancher/k3s/registries.yaml em cada nó e reinicie o k3s nesse local:

# /etc/rancher/k3s/registries.yaml (on every node)
configs:
  "registry.adverant.ai":
    auth: {username: "<registry-user>", password: "<pull-token>"}

<registry-user> é o nome de utilizador do registo constante no seu convite da Adverant, e <pull-token> é o token que copiou. O ficheiro contém uma credencial, pelo que deve mantê-lo legível apenas pelo utilizador root.

Num cluster gerido cujos nós não leiam esse ficheiro, copie as imagens para um registo no qual os seus nós já confiem e defina global.imageRegistry para o mesmo; cada nó tem de confiar no certificado Transport Layer Security (TLS) desse registo. O Capítulo 2.11, Variações: armazenamentos externos, TLS e ingress, aborda esse tema, e o capítulo 2.10, Instalação isolada da rede (air-gapped), aborda a mesma cópia para um local sem rota de saída.

Passo 4: ler o bloqueio de imagens

Um chart do Nexus nunca identifica uma imagem por etiqueta (tag). Identifica cada uma pelo digest do seu índice multiplataforma, obtido a partir do bloqueio de imagens, um ficheiro que o chart inclui como files/images.lock.json. O pacote offline inclui o mesmo bloqueio como release/images.lock.json.

Extraia o chart e descompacte-o para ler o bloqueio:

helm pull oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1
tar -xzf nexus-1.0.0-alpha.1.tgz
jq -r '.version, .edition' nexus/files/images.lock.json
1.0.0-alpha.1
community

O nível superior do bloqueio indica a que versão e a que edição pertence. Cada entrada sob images descreve uma imagem:

Campo O que contém
svc O serviço, tal como nexus-auth ou nexus-postgres
index O digest sha256: do índice da imagem, que abrange tanto linux/amd64 como linux/arm64
edition community, enterprise ou all para a camada de dados
kind service, migrations ou data-tier para os cinco armazenamentos de dados e o OpenBao
verified Quando a compilação de lançamento verificou a sua assinatura e atestações

O chart processa cada imagem como <global.imageRegistry>/nexus/<svc>@<index>. Assim, com global.imageRegistry: registry.adverant.ai, o serviço de início de sessão é registry.adverant.ai/nexus/nexus-auth@sha256: seguido de 64 caracteres hexadecimais, e nada no cluster o pode substituir por outro elemento com o mesmo nome.

O bloqueio é específico de cada edição. Um bloqueio Community lista apenas imagens cuja edição é community ou all. Um bloqueio Enterprise lista essas imagens mais as compilações Enterprise. O chart verifica isto sempre que é processado e recusa a operação em vez de tentar adivinhar:

O que o chart indica Porquê
edition=enterprise but enterprise.enabled=false: they must agree Os dois valores de edição no seu ficheiro de valores estão em conflito
files/images.lock.json is the community lock; this install is edition enterprise Está a instalar a edição Enterprise a partir do chart Community, ou vice-versa
image nexus-auth is not in files/images.lock.json O chart e o respetivo bloqueio não correspondem; obtenha o chart novamente
image ... is in the lock but was never verified by build-all A entrada de bloqueio não tem hora de verificação; não instale a partir dela
NEXUS_EDITION_INVALID edition está vazio ou não é um dos valores community e enterprise
RELEASE_VERSION_MISSING O bloqueio não indica nenhuma versão

Liste todas as imagens e digests de uma só vez:

jq -r '.images[] | "\(.svc) \(.index)"' nexus/files/images.lock.json

Passo 5: verificar a assinatura de cada imagem

Cada índice de imagem é assinado, assim como cada manifesto de plataforma no seu interior. Verifique por digest, diretamente a partir do bloqueio, para confirmar exatamente o que o chart irá executar:

jq -r '.images[] | "\(.svc)@\(.index)"' nexus/files/images.lock.json |
while read -r ref; do
  cosign verify --key release.pub --insecure-ignore-tlog=true \
    "registry.adverant.ai/nexus/$ref" > /dev/null && echo "OK $ref" || echo "FAILED $ref"
done

Cada linha deve começar por OK. Na nossa ligação, o ciclo demorou alguns minutos, a maior parte dos quais a aguardar pelo registo. Lê apenas as assinaturas e não obtém camadas de imagem, o que torna a repetição do processo rápida e leve após cada atualização. Uma linha FAILED significa que deve parar: a secção seguinte explica o significado de cada mensagem.

Para uma única imagem isolada, omita o redirecionamento e leia o que o cosign verificou:

cosign verify --key release.pub --insecure-ignore-tlog=true \
  registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
The following checks were performed on each of these signatures:
  - Existence of the claims in the transparency log was verified offline
  - The signatures were verified against the specified public key

<digest> corresponde aos 64 caracteres hexadecimais de index do bloqueio para essa imagem. As imagens Enterprise necessitam do seu token de extração para esta verificação, tal como para qualquer extração a partir do registo.

Uma cadeia vertical de cinco caixas unidas por setas descendentes. Topo: "Chave pública de lançamento, impressão digital verificada face ao seu contrato". Segunda: "Pacote do chart nexus-1.0.0-alpha.1, assinado". Terceira: "Bloqueio de imagens dentro do chart: cada imagem por digest de índice, uma edição". Quarta: "Cada índice de imagem, assinado, com atestações de lista de materiais de software (SBOM) e de proveniência". Fundo: "Pods no namespace nexus, extraídos por digest". Uma seta lateral a partir da caixa do topo aponta para a segunda e quarta caixas, com a legenda "cosign verify, offline".
O que atesta o quê, desde a chave que verificou até aos pods em execução.

Ambas as plataformas e o que guardar

Cada índice de imagem contém dois manifestos de plataforma, linux/amd64 e linux/arm64, e cada um deles está igualmente assinado. O cosign verify é bem-sucedido no digest do índice e no digest de qualquer uma das plataformas, pelo que um cluster de nós mistos fica coberto pela mesma verificação. Para ver as duas plataformas por detrás de um índice, solicite o índice em bruto ao registo:

docker buildx imagetools inspect registry.adverant.ai/nexus/nexus-auth@sha256:<digest> --raw

A sua lista manifests identifica uma entrada amd64 e uma entrada arm64.

Guarde o resultado do ciclo acima juntamente com o seu registo de alterações, ao lado da impressão digital que verificou. Quando alguém perguntar, meses mais tarde, como sabe que o cluster executa o que a Adverant disponibilizou, esse ficheiro e os digests do bloqueio respondem à questão. O nosso auditor na Harrow fez exatamente essa pergunta, e a resposta demorou um minuto.

Passo 6: ler as atestações

Cada imagem inclui também duas atestações assinadas, criadas a partir da imagem no momento da compilação: uma lista de materiais de software (SBOM) e uma declaração de proveniência.

A SBOM está no formato Software Package Data Exchange (SPDX), uma por plataforma, pelo que um índice contém duas. Lista todos os pacotes na imagem com a respetiva licença. Antes do lançamento, essas licenças são verificadas face a uma lista de exclusão; nenhuma imagem Community contém código sob licença GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) ou Business Source License (BUSL). A declaração de proveniência segue a norma Supply-chain Levels for Software Artifacts (SLSA) v1. Identifica o commit de código-fonte a partir do qual a imagem foi compilada, os digests das imagens de base e as ferramentas de compilação e respetivas versões, para que uma imagem possa ser rastreada até ao código-fonte revisto sem necessidade de contactar a Adverant.

Ambas são verificadas face à chave de lançamento que já possui:

cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
  --type spdxjson registry.adverant.ai/nexus/nexus-auth@sha256:<digest>
cosign verify-attestation --key release.pub --insecure-ignore-tlog=true \
  --type slsaprovenance1 registry.adverant.ai/nexus/nexus-auth@sha256:<digest>

A verificação spdxjson imprime dois resultados, um para a SBOM de cada plataforma. Para ver tudo o que está anexado a uma imagem sem o verificar, utilize cosign tree:

cosign tree registry.adverant.ai/nexus/nexus-auth@sha256:<digest>

Lista um pacote de assinatura, duas atestações spdx.dev/Document e uma atestação slsa.dev/provenance/v1. Solicitar um tipo que a imagem não contenha, como --type cyclonedx, falha com none of the attestations matched the predicate type: cyclonedx. Essa falha está correta; a versão anexa SPDX, não CycloneDX.

Passo 7: verificar o chart e as transferências

O chart no registo é assinado no seu digest OCI (OCI é a Open Container Initiative, o formato de imagens e artefactos que os registos utilizam). O helm pull imprime o digest que extraiu; verifique esse digest da mesma forma que verifica uma imagem:

cosign verify --key release.pub --insecure-ignore-tlog=true \
  registry.adverant.ai/nexus/charts/nexus@sha256:<chart-digest>

Para um ficheiro de chart que tenha transferido, ou para o pacote offline, o nexusctl verify verifica o ficheiro face à chave de lançamento da Adverant:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Um resultado válido termina identificando a chave de lançamento da Adverant e o início da respetiva impressão digital. Compare esses grupos com a impressão digital que verificou no passo 1.

O pacote offline consiste num ficheiro tar não comprimido por edição, nexus-alpha-1.0.0-alpha.1-community.tar ou nexus-alpha-1.0.0-alpha.1-enterprise.tar, acompanhado por um ficheiro .sha256. No seu interior, contém:

Caminho O que é
release/images.lock.json O bloqueio de imagens para essa edição
release/facts.json Os dados da versão: versão, edição, arquiteturas e a impressão digital da chave de lançamento
images/<service>/ Cada imagem com ambas as plataformas, a respetiva assinatura e as respetivas atestações
charts/nexus-1.0.0-alpha.1.tgz O chart
sbom/ A SBOM SPDX de cada imagem, por plataforma
docs/ As notas de lançamento, o guia de instalação isolada da rede (air-gap) e exemplos de valores
SHA256SUMS e SHA256SUMS.sigstore.json A soma de verificação (checksum) de cada ficheiro e a respetiva assinatura

A chave pública de lançamento nunca se encontra dentro do pacote; uma chave fornecida juntamente com o elemento que assina não prova nada. Verifique a totalidade do pacote em dois comandos, a partir do interior da respetiva pasta:

sha256sum -c SHA256SUMS
cosign verify-blob --key release.pub --insecure-ignore-tlog=true \
  --bundle SHA256SUMS.sigstore.json SHA256SUMS

Cada linha do primeiro comando deve terminar com OK, e o segundo deve imprimir Verified OK. O Capítulo 2.10, Instalação isolada da rede (air-gapped), assume o controlo do pacote a partir daí: carregar as imagens para o seu próprio registo, verificar cada uma delas novamente nesse local e executar a verificação de ponta a ponta do próprio pacote.

Como verificar uma transferência
Como verificar uma transferência
Como verificar uma transferência, na conta Adverant. Duas verificações offline, uma ilustração de um resultado válido e de um inválido, e a impressão digital da chave de lançamento em grupos de quatro para comparação visual.

Quando uma assinatura não é verificada

Pare. Não instale e não altere o comando até que este passe na verificação. Uma falha na verificação de assinatura significa que o sistema está a funcionar: indica que o ficheiro que possui não é o ficheiro que a Adverant assinou, ou que a chave que detém não pertence à Adverant.

O que vê O que significa O que fazer
accepted signatures do not match threshold, Found: 0, Expected 1 (saída 1) A imagem está assinada, mas não pela chave que forneceu Confirme que utilizou a chave de lançamento cuja impressão digital verificou no passo 1
no signatures found (saída 10) Nada nesse digest está assinado Confirme que o digest provém do bloqueio; nunca verifique uma etiqueta (tag)
not enough verified log entries from transparency log: 0 < 1 Falta --insecure-ignore-tlog=true Adicione a opção; não há nada de errado com a imagem
none of the attestations matched the predicate type Solicitou um tipo de atestação que a imagem não contém Utilize spdxjson ou slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature Um ficheiro transferido foi alterado após ter sido assinado Transfira-o novamente
FAILED de sha256sum -c Um ficheiro não corresponde ao ficheiro cuja soma de verificação foi calculada Transfira-o novamente

Se uma transferência falhar duas vezes, abra um pedido de suporte a partir da sua conta e cite o nome do ficheiro e a mensagem. Guarde o ficheiro que falhou; a sua equipa de segurança poderá querer analisá-lo.

Numa instalação que carregue versões a partir do disco, a consola executa as mesmas verificações e recusa uma versão cuja assinatura não corresponda à chave instalada, apresentando o erro MEDIA_SIGNATURE_INVALID. Indica o que verificou, por que ordem, onde parou e que nada foi alterado: nenhuma imagem foi carregada e a versão em execução permaneceu intocada.

A importação a partir do suporte de dados falhou
A importação a partir do suporte de dados falhou
Uma versão em disco que falhou na verificação de assinatura. Repare nas verificações apresentadas por ordem com aquela que interrompeu o processo, nas impressões digitais da chave esperada e da encontrada, e na declaração clara de que nada foi carregado ou alterado.

Depois de a chave, as imagens e o chart terem passado em todas as verificações, o passo seguinte é a pré-verificação (preflight) no seu cluster, no capítulo 2.5, Pré-verificação com o nexusctl.