Iniciar sesiónReservar sesión

Capítulo 2.4

Obtención y verificación de una versión

Dónde reside cada parte de una versión de Nexus, cómo se obtienen las imágenes de Enterprise con un token de descarga, y cómo demostrar sin conexión que cada imagen, chart y descarga proviene de Adverant sin alteraciones antes de instalar nada.

Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

15 minutos de lectura

Cada imagen de una versión de Nexus está firmada con la clave de versión de Adverant, y cada imagen se nombra por su digest, nunca por una etiqueta. El chart solo generará las imágenes enumeradas por digest en su propio archivo de bloqueo de imágenes. En conjunto, eso significa que puede demostrar, en su propia estación de trabajo y sin conexión con nadie, que lo que está a punto de ejecutar es exactamente lo que Adverant compiló.

En Harrow Port Authority lo comprobamos todo antes de la primera instalación. Llevó unos veinte minutos, y la mayor parte de ese tiempo fue el bucle sobre las imágenes. Este capítulo recorre el mismo camino: dónde reside cada parte de la versión, el token de extracción para las imágenes Enterprise, el bloqueo de imágenes, las comprobaciones de cosign con sus comandos exactos y qué hacer cuando falla una comprobación.

Dónde reside la versión

Dirección Qué se obtiene allí
registry.adverant.ai Las imágenes de la plataforma, en registry.adverant.ai/nexus/<service>@sha256:<digest>, y el chart de Helm, en oci://registry.adverant.ai/nexus/charts/nexus
https://downloads.adverant.ai/nexus/1.0.0-alpha.1/ La clave pública de la versión y su huella digital, los binarios de nexusctl y los paquetes sin conexión
https://account.adverant.ai Su cuenta de Adverant: Descargas, Tokens de extracción y comandos de instalación, Despliegues y las páginas de licencia

Las imágenes Community y el chart Community son públicos; puede extraerlos sin iniciar sesión. Las imágenes Enterprise se extraen con un token de extracción de su cuenta, y el chart y el paquete Enterprise se encuentran en la página Descargas de la cuenta, que se rige por su licencia.

Descargas
Descargas
Descargas en la cuenta de Adverant, por versión y canal. Cada archivo lleva al lado su suma de comprobación y su firma, y las partes fuera de la licencia permanecen en la lista, atenuadas en gris, con el motivo.

Lea las notas de la versión antes que nada

Las notas de la versión se incluyen dentro de cada paquete como docs/RELEASE-NOTES.md, enumeradas en su SHA256SUMS, y las mismas notas se encuentran en la página de la versión en su cuenta. Léalas antes de instalar o actualizar. Para 1.0.0-alpha.1 son breves. Es la primera versión, por lo que una instalación desde cero no tiene ninguno de los puntos de actualización que describen, y la lista de problemas conocidos indica que nada en ella afecta a una instalación desde cero que siga los pasos documentados. Las versiones posteriores enumeran cada problema conocido junto con la versión que lo corrige.

La página de la versión también dice, en tres líneas, lo que promete una versión alfa: las funcionalidades pueden cambiar antes de la primera versión estable, una actualización conserva sus datos y realiza primero una copia de seguridad, y las correcciones de seguridad llegan en un plazo de 7 días. Imprimimos esa página y la incluimos en el registro de cambios en Harrow, porque es lo más parecido a una declaración de soporte que pediría el comité de cambios.

Paso 1: obtener la clave de la versión y comprobarla por una segunda vía

Todo lo que sigue descansa en un único archivo: la clave pública de versión de Adverant. Una clave procedente del mismo lugar que aquello que avala demuestra muy poco, así que compruebe su huella digital con una copia que le haya llegado por otra vía.

  1. Descargue la clave de la carpeta de la versión en Descargas.

    curl -fsSLO https://downloads.adverant.ai/nexus/1.0.0-alpha.1/release.pub
  2. Calcule su huella digital. La huella digital es el SHA-256 (Secure Hash Algorithm 256) del propio archivo de clave.

    sha256sum release.pub

    En macOS, shasum -a 256 release.pub da la misma respuesta.

  3. Compárela, carácter por carácter, con la huella digital impresa en su contrato con Adverant y en las notas de la versión. Descargas también publica la huella digital, pero esa copia llegó por la misma vía que la clave, por lo que no sirve como comprobación.

Si difiere algún carácter, deténgase. No instale ni busque otra copia de la clave en internet. Abra una solicitud de soporte desde su cuenta y cite lo que ha visto.

Paso 2: obtener nexusctl

nexusctl es la interfaz de línea de comandos (CLI) del operador de Nexus. Se ejecuta en su estación de trabajo y lee su clúster a través de su kubeconfig. Descargas ofrece cuatro compilaciones:

Archivo Plataforma
nexusctl-linux-amd64 Linux en Intel o AMD
nexusctl-darwin-arm64 macOS en Apple silicon
nexusctl-darwin-amd64 macOS en Intel
nexusctl-windows-amd64.exe Windows

Junto a cada archivo está su paquete de firma, con el mismo nombre terminado en .sigstore.json. Compruebe el binario antes de ejecutarlo:

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

A continuación, póngalo en su ruta (PATH) y consulte su versión:

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

A partir de aquí, nexusctl verify puede hacer las comprobaciones de archivos por usted. El capítulo 2.5, Comprobación previa con nexusctl, aborda su tarea principal, la comprobación previa.

Por qué la opción dice "insecure"

Cada comando cosign de este capítulo lleva --insecure-ignore-tlog=true. Las versiones de Nexus se firman con la clave de Adverant y no se registran en ningún registro de transparencia público, de modo que comprobar una versión nunca necesita conexión con nadie, incluido Sigstore. Por defecto, cosign exige una entrada en el registro; la opción le indica que confíe únicamente en la clave. Sin ella, la comprobación falla así:

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

Cuando se establece la opción, cosign sigue imprimiendo la frase "Existence of the claims in the transparency log was verified offline". Se trata de un texto fijo en cosign; no hay ninguna entrada de registro detrás. La comprobación de la firma con la clave es real, y es la parte que importa.

Paso 3: un token de descarga, para Enterprise

Las imágenes Enterprise están protegidas por un token de extracción. Puede crear uno en su cuenta, en Tokens de extracción y comandos de instalación:

  1. Pulse Añadir un token.
  2. Indique para qué clúster es, qué puede obtener y cuándo caduca.
  3. Pulse Copiar el token y péguelo directamente donde guarde las credenciales, porque la página lo muestra solo esta vez.

Cada token está limitado a lo que puede obtener y tiene una fecha de caducidad. Retirar uno detiene de inmediato las nuevas extracciones; las imágenes que un clúster ya haya extraído siguen ejecutándose. En Harrow creamos un token por clúster, de modo que retirar el token del clúster de pruebas nunca afecta a producción. Una instalación Community no necesita ningún token; solo se crea uno al pasar a Enterprise, y puede crearse el mismo día.

Tokens de extracción y comandos de instalación
Tokens de extracción y comandos de instalación
Tokens de extracción en la cuenta de Adverant. Cada token muestra qué puede obtener, quién lo creó y cuándo caduca; un token nuevo se muestra una sola vez, y retirar uno detiene las nuevas extracciones sin detener nada que ya esté en ejecución.

El chart no tiene ningún valor de secreto de extracción. Sus nodos extraen las imágenes, por lo que el token pertenece al entorno de ejecución de contenedores de los nodos. En k3s, añada el registro a /etc/rancher/k3s/registries.yaml en cada nodo y reinicie k3s allí:

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

<registry-user> es el nombre de usuario del registro que figura en su invitación de Adverant, y <pull-token> es el token que copió. El archivo contiene una credencial, así que manténgalo legible solo por root.

En un clúster gestionado cuyos nodos no lean ese archivo, copie las imágenes en un registro en el que sus nodos ya confíen y asígnelo a global.imageRegistry; cada nodo debe confiar en el certificado TLS (Transport Layer Security) de ese registro. El capítulo 2.11, Variaciones: almacenes externos, TLS e ingress, aborda eso, y el capítulo 2.10, Instalación aislada de la red (air-gapped), aborda la misma copia para un emplazamiento sin salida al exterior.

Paso 4: leer el bloqueo de imágenes

Un chart de Nexus nunca nombra una imagen por su etiqueta. Nombra cada una por el digest de su índice multiplataforma, tomado del bloqueo de imágenes, un archivo que el chart incluye como files/images.lock.json. El paquete sin conexión incluye el mismo bloqueo como release/images.lock.json.

Extraiga el chart y descomprímalo para leer el bloqueo:

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

El nivel superior del bloqueo indica a qué versión y a qué edición pertenece. Cada entrada bajo images describe una imagen:

Campo Qué contiene
svc El servicio, como nexus-auth o nexus-postgres
index El digest sha256: del índice de la imagen, que cubre tanto linux/amd64 como linux/arm64
edition community, enterprise, o all para la capa de datos
kind service, migrations, o data-tier para los cinco almacenes de datos y OpenBao
verified Cuándo verificó la compilación de la versión su firma y sus atestaciones

El chart genera cada imagen como <global.imageRegistry>/nexus/<svc>@<index>. Así, con global.imageRegistry: registry.adverant.ai, el servicio de inicio de sesión es registry.adverant.ai/nexus/nexus-auth@sha256: seguido de 64 caracteres hexadecimales, y nada en el clúster puede sustituirlo por otra cosa con el mismo nombre.

El bloqueo es por edición. Un bloqueo Community enumera solo las imágenes cuya edición es community o all. Un bloqueo Enterprise enumera esas más las compilaciones Enterprise. El chart comprueba esto cada vez que se genera y se niega a continuar antes que adivinar:

Qué dice el chart Por qué
edition=enterprise but enterprise.enabled=false: they must agree Los dos valores de edición de su archivo de valores no coinciden
files/images.lock.json is the community lock; this install is edition enterprise Está instalando Enterprise desde el chart Community, o al revés
image nexus-auth is not in files/images.lock.json El chart y su bloqueo no se corresponden; vuelva a obtener el chart
image ... is in the lock but was never verified by build-all La entrada del bloqueo no tiene hora de verificación; no instale a partir de él
NEXUS_EDITION_INVALID edition está vacío o no es ni community ni enterprise
RELEASE_VERSION_MISSING El bloqueo no indica ninguna versión

Enumere cada imagen y su digest de una sola vez:

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

Paso 5: verificar la firma de cada imagen

Cada índice de imagen está firmado, al igual que cada manifiesto de plataforma que contiene. Verifique por digest, directamente desde el bloqueo, para comprobar exactamente lo que ejecutará el chart:

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 línea debería empezar por OK. En nuestro enlace el bucle tardó unos minutos, la mayor parte del tiempo esperando al registro. Solo lee las firmas y no obtiene capas de imagen, lo que hace que sea rápido repetirlo tras cada actualización. Una línea FAILED significa detenerse: la sección siguiente explica qué significa cada mensaje.

Para una sola imagen por separado, elimine la redirección y lea lo que ha comprobado cosign:

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> son los 64 caracteres hexadecimales del index del bloqueo para esa imagen. Las imágenes Enterprise necesitan su token de extracción para esta comprobación, igual que para cualquier extracción desde el registro.

Una cadena vertical de cinco recuadros unidos por flechas hacia abajo. Arriba: "Clave pública de la versión, huella digital comprobada con su contrato". Segundo: "Paquete de chart nexus-1.0.0-alpha.1, firmado". Tercero: "Bloqueo de imágenes dentro del chart: cada imagen por digest de índice, una edición". Cuarto: "Cada índice de imagen, firmado, con lista de materiales de software (SBOM) y atestaciones de procedencia". Abajo: "Pods en el espacio de nombres nexus, extraídos por digest". Una flecha lateral desde el recuadro superior apunta a los recuadros segundo y cuarto, con la etiqueta "cosign verify, sin conexión".
Qué avala a qué, desde la clave que comprobó hasta los pods que se ejecutan.

Ambas plataformas y qué conservar

Cada índice de imagen contiene dos manifiestos de plataforma, linux/amd64 y linux/arm64, y cada uno de ellos también está firmado. cosign verify tiene éxito con el digest del índice y con el digest de cualquiera de las plataformas, por lo que un clúster de nodos mixtos queda cubierto por la misma comprobación. Para ver las dos plataformas detrás de un índice, solicite al registro el índice sin procesar:

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

Su lista manifests nombra una entrada amd64 y una entrada arm64.

Guarde la salida del bucle anterior con su registro de cambios, junto a la huella digital que comprobó. Cuando alguien pregunte, meses después, cómo sabe que el clúster ejecuta lo que envió Adverant, ese archivo y los digests del bloqueo darán la respuesta. Nuestro auditor en Harrow hizo exactamente esa pregunta, y responder llevó un minuto.

Paso 6: leer las atestaciones

Cada imagen lleva también dos atestaciones firmadas, generadas a partir de la imagen en el momento de la compilación: una lista de materiales de software (SBOM) y una declaración de procedencia.

La SBOM está en formato Software Package Data Exchange (SPDX), una por plataforma, por lo que un índice lleva dos. Enumera cada paquete de la imagen con su licencia. Antes del lanzamiento, esas licencias se contrastan con una lista de denegación; ninguna imagen Community contiene código bajo GNU Affero General Public License (AGPL), Server Side Public License (SSPL), Redis Source Available License (RSAL) ni Business Source License (BUSL). La declaración de procedencia es Supply-chain Levels for Software Artifacts (SLSA) v1. Nombra el commit de origen a partir del cual se compiló la imagen, los digests de las imágenes base y las herramientas de compilación y sus versiones, de modo que una imagen puede rastrearse hasta el código fuente revisado sin preguntar a Adverant.

Ambas se comprueban con la clave de versión que ya posee:

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>

La comprobación de spdxjson imprime dos resultados, uno por la SBOM de cada plataforma. Para ver todo lo adjunto a una imagen sin verificarlo, utilice cosign tree:

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

Enumera un paquete de firma, dos atestaciones spdx.dev/Document y una atestación slsa.dev/provenance/v1. Solicitar un tipo que la imagen no lleva, como --type cyclonedx, falla con none of the attestations matched the predicate type: cyclonedx. Ese fallo es correcto; la versión adjunta SPDX, no CycloneDX.

Paso 7: verificar el chart y las descargas

El chart del registro está firmado en su digest OCI (OCI es Open Container Initiative, el formato de imágenes y artefactos que utilizan los registros). helm pull imprime el digest que ha extraído; compruebe ese digest del mismo modo que una imagen:

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

Para un archivo de chart que haya descargado, o para el paquete sin conexión, nexusctl verify comprueba el archivo con la clave de versión de Adverant:

nexusctl verify nexus-1.0.0-alpha.1.tgz

Un resultado correcto termina nombrando la clave de versión de Adverant y el comienzo de su huella digital. Compare esos grupos con la huella digital que comprobó en el paso 1.

El paquete sin conexión es un archivo tar sin comprimir por edición, nexus-alpha-1.0.0-alpha.1-community.tar o nexus-alpha-1.0.0-alpha.1-enterprise.tar, con un archivo .sha256 al lado. En su interior contiene:

Ruta Qué es
release/images.lock.json El bloqueo de imágenes para esa edición
release/facts.json Los datos de la versión: versión, edición, arquitecturas y la huella digital de la clave de versión
images/<service>/ Cada imagen con ambas plataformas, su firma y sus atestaciones
charts/nexus-1.0.0-alpha.1.tgz El chart
sbom/ La SBOM SPDX de cada imagen, por plataforma
docs/ Las notas de la versión, la guía de instalación aislada de la red y valores de ejemplo
SHA256SUMS y SHA256SUMS.sigstore.json La suma de comprobación de cada archivo y su firma

La clave pública de la versión nunca está dentro del paquete; una clave que se distribuye con aquello que firma no demuestra nada. Compruebe todo el paquete con dos comandos, desde dentro de su carpeta:

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

Cada línea del primero debería terminar en OK, y el segundo debería imprimir Verified OK. El capítulo 2.10, Instalación aislada de la red (air-gapped), retoma el paquete a partir de ahí: la carga de las imágenes en su propio registro, la nueva verificación de cada una allí y la comprobación de extremo a extremo propia del paquete.

Cómo comprobar una descarga
Cómo comprobar una descarga
Cómo comprobar una descarga, en la cuenta de Adverant. Dos comprobaciones sin conexión, una imagen de un resultado correcto y de uno erróneo, y la huella digital de la clave de versión en grupos de cuatro para compararla a simple vista.

Cuando una firma no se puede verificar

Deténgase. No instale ni modifique el comando hasta que pase la comprobación. Una comprobación de firma fallida indica que el sistema está funcionando: significa que el archivo que tiene no es el archivo que firmó Adverant, o que la clave que posee no es la de Adverant.

Lo que ve Qué significa Qué hacer
accepted signatures do not match threshold, Found: 0, Expected 1 (salida 1) La imagen está firmada, pero no con la clave que ha proporcionado Compruebe que ha utilizado la clave de versión cuya huella digital comprobó en el paso 1
no signatures found (salida 10) No hay nada firmado en ese digest Compruebe que el digest procede del bloqueo; nunca verifique una etiqueta
not enough verified log entries from transparency log: 0 < 1 Falta --insecure-ignore-tlog=true Añada la opción; no ocurre nada malo con la imagen
none of the attestations matched the predicate type Ha solicitado un tipo de atestación que la imagen no lleva Utilice spdxjson o slsaprovenance1
Error: invalid signature when validating ASN.1 encoded signature Un archivo descargado sufrió cambios después de ser firmado Descárguelo de nuevo
FAILED de sha256sum -c Un archivo no es el archivo del que se calculó la suma de comprobación Descárguelo de nuevo

Si una descarga falla dos veces, abra una solicitud de soporte desde su cuenta y cite el nombre del archivo y el mensaje. Conserve el archivo que ha fallado; es posible que su equipo de seguridad lo quiera.

En una instalación que carga versiones desde disco, la consola ejecuta las mismas comprobaciones y rechaza una versión cuya firma no coincida con la clave instalada, con MEDIA_SIGNATURE_INVALID. Indica qué ha comprobado, en qué orden, dónde se ha detenido y que no se ha modificado nada: no se ha cargado ninguna imagen y la versión en ejecución permanece intacta.

Error al importar desde el medio
Error al importar desde el medio
Una versión en disco que no superó la comprobación de firma. Observe las comprobaciones en orden junto con la que la detuvo, las huellas digitales de clave esperada y encontrada, y la declaración explícita de que no se cargó ni modificó nada.

Una vez que la clave, las imágenes y el chart hayan pasado las comprobaciones, el paso siguiente es la comprobación previa en su clúster, en el capítulo 2.5, Comprobación previa con nexusctl.