Iniciar sesiónReservar sesión

Capítulo 2.10

Instalación aislada de la red (air-gapped)

Lleve un paquete sin conexión firmado a un emplazamiento sin internet, verifíquelo con una clave que haya introducido por separado, cárguelo en su propio registro e instálelo. Las licencias, actualizaciones y listas de revocación también cruzan la brecha manualmente.

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

19 minutos de lectura

La red de operaciones de Harrow Port Authority no tiene ruta hacia internet, por ley y por diseño. El tráfico de buques, los planes de atraque y las retenciones aduaneras residen en ella, y nada en ella puede realizar llamadas al exterior. Cuando Tomás Reilly instaló Nexus allí, cada byte llegó en un disco que un mensajero llevó a la garita de entrada, y cada byte fue verificado dentro de las instalaciones antes de que nada lo utilizara.

Este capítulo trata sobre esa instalación. Usted obtiene un paquete sin conexión firmado, lo comprueba con una clave que le llegó por una ruta diferente, copia sus imágenes en su propio registro, las vuelve a comprobar allí e instala el chart con el nombre de su registro en los valores. Luego vienen las tareas que un sitio aislado realiza a mano y que uno conectado obtiene de forma automática: k3s y cert-manager sin descarga, actualizaciones en medios físicos, licencias mediante un intercambio sin conexión y listas de revocación que usted mismo importa.

A la izquierda, un recuadro "lado conectado" contiene "downloads.adverant.ai" y "su cuenta de Adverant". Dos flechas separadas cruzan una línea vertical gruesa etiquetada como "la brecha". La flecha superior, etiquetada como "una vez, por una ruta separada; huella digital comprobada fuera de banda", lleva "release.pub". La flecha inferior, etiquetada como "cada versión, en un disco", lleva "nexus-alpha-1.0.0-alpha.1-enterprise.tar". A la derecha, dentro de "red de operaciones de Harrow", ambas llegan a un recuadro "verify-bundle.sh: VERIFY-BUNDLE PASS", que conduce a "registry.harrow.example (cosign load, cosign verify)" y luego a "el clúster (helm install)".
Cómo una versión y su confianza cruzan la brecha por dos rutas separadas.

Qué contiene el paquete sin conexión

Un paquete es una edición de una versión, en forma de archivo tar sin comprimir con un archivo de suma de comprobación a su lado: nexus-alpha-1.0.0-alpha.1-enterprise.tar y nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256. Los paquetes Community son públicos en downloads.adverant.ai. Los paquetes Enterprise provienen de su cuenta de Adverant en https://account.adverant.ai, junto a su licencia, y nunca de forma anónima.

Desempaquetado, se ve así:

nexus-alpha-1.0.0-alpha.1-enterprise/
  release/facts.json               the release facts: version, edition, architectures, key fingerprint
  release/facts-gaps.json          the release facts the build couldn't record, each with its reason
  release/images.lock.json         every image by digest: index, per platform, its SBOMs
  release/source-offer.json        the sources of every copyleft data-tier image
  release/source-offer.sha256      a checksum for each of those source files
  images/<svc>/                    one cosign save layout per image
  charts/nexus-1.0.0-alpha.1.tgz   the Helm chart
  sbom/<edition>/<svc>-<arch>.spdx.json
  source-offer/                    the source files themselves
  docs/INSTALL-AIRGAP.md
  docs/example-values.yaml
  docs/RELEASE-NOTES.md
  SHA256SUMS                       a checksum for every file above
  SHA256SUMS.sigstore.json         the signature over SHA256SUMS, made with the release key

Cada directorio images/<svc>/ es lo que escribe cosign save. Contiene el índice de imágenes y las imágenes de ambas plataformas, linux/amd64 y linux/arm64, con la firma de cosign, una atestación SBOM (lista de materiales de software) en formato SPDX para cada plataforma y una atestación de procedencia, todas realizadas con la clave de versión de Adverant. Los mismos SBOM se encuentran en sbom/ como archivos de texto plano, para que un equipo de seguridad pueda leerlos sin cosign.

La capa de datos incluye software con copyleft: PostgreSQL con PostGIS y Neo4j Community Edition, entre otros. El paquete contiene el código fuente de cada imagen de la capa de datos que incluye, y release/source-offer.json así lo indica para cada imagen. No se compila ningún paquete que distribuya un binario con copyleft sin su código fuente.

release/facts.json indica la versión, la edición, las arquitecturas y la huella digital de la clave de versión con la que se firmó el paquete, como sha256:<hex>.

La clave pública viaja por separado

El paquete nunca contiene la clave que lo comprueba. Un paquete que llevara su propia clave podría ser sustituido, con clave y todo, por cualquiera, y todas las comprobaciones seguirían siendo válidas. El script de verificación rechaza cualquier clave que se encuentre dentro del directorio del paquete.

Obtenga la clave pública de la versión una sola vez, en una máquina conectada, desde https://downloads.adverant.ai/nexus/1.0.0-alpha.1/. Guárdela como release.pub. Su huella digital es el hash SHA-256 del archivo:

sha256sum release.pub

Compare ese valor con la huella digital que publica Adverant y con la que figura en las notas de la versión que recibió por un canal separado. El capítulo 2.4, Obtención y verificación de una versión, contiene los detalles. A continuación, lleve release.pub a las instalaciones, por una ruta distinta a la del paquete si es posible, y consérvela allí. El equipo de Tomás la guarda en el recurso compartido de archivos de la red de operaciones con una nota de la fecha en que entró. Cada versión posterior se comprueba con esa clave instalada, nunca con nada que traiga consigo un disco.

Verificar el paquete

verify-bundle.sh es el script que comprueba un paquete, publicado con cada versión. La imagen de disco del instalador ejecuta el mismo script en el primer arranque. Necesita cosign v3, helm v4 y sha256sum o shasum. No lee nada de ninguna red y no necesita Python, por lo que se ejecuta tanto en un nodo instalador básico como en una estación de trabajo.

  1. Compruebe el archivo tar con su suma de comprobación y, a continuación, desempaquételo:
sha256sum -c nexus-alpha-1.0.0-alpha.1-enterprise.tar.sha256
tar -xf nexus-alpha-1.0.0-alpha.1-enterprise.tar
  1. Ejecute la verificación con la clave que trajo consigo:
./verify-bundle.sh nexus-alpha-1.0.0-alpha.1-enterprise release.pub

Un tercer argumento indica un archivo de valores para las comprobaciones del chart. Sin él, el script utiliza el archivo docs/example-values.yaml del paquete.

  1. Lea la última línea, que debe ser VERIFY-BUNDLE PASS antes de continuar.
  1 SHA256SUMS OK files=<n>
  2 SHA256SUMS signature OK
  3 images signed + SBOM-attested: <n>
  4 helm lint --strict OK nexus-1.0.0-alpha.1.tgz
  5 coverage OK rendered=<n> lock=<n>
  6 source offer OK images=5 files=<n>
VERIFY-BUNDLE PASS files=<n> images=<n>

El script se detiene en la primera comprobación que falla. Esto es lo que hace cada una.

Paso Qué comprueba
1 Cada archivo enumerado en SHA256SUMS coincide con su suma de comprobación, y no hay ningún archivo presente que la lista omita. Un archivo adicional infiltrado falla con tanta seguridad como uno modificado.
2 SHA256SUMS.sigstore.json es una firma válida sobre SHA256SUMS realizada con la clave que usted proporcionó. Con los pasos 1 y 2 juntos, cada byte del paquete es el byte que firmó Adverant.
3 Para cada directorio de imágenes: el resumen (digest) del índice de la imagen está en release/images.lock.json; existe una firma de cosign cuyo sujeto es ese resumen exacto y se verifica correctamente con su clave; tanto cosign verify como cosign verify-attestation --type spdxjson se superan con éxito en la estructura guardada.
4 helm lint --strict se supera con éxito en el chart con los valores de ejemplo o con los suyos.
5 Cada imagen del archivo de bloqueo está guardada en images/, y cada imagen que genera el chart es un resumen incluido en dicho bloqueo. Nada de lo que instala el chart proviene de ningún otro lugar.
6 Cuando el archivo de bloqueo contiene imágenes de la capa de datos, release/source-offer.json está completo, nombra a cada una de ellas y cada archivo de código fuente que enumera está presente con la suma de comprobación correcta.

El paso 3 comprueba la propia firma, por resumen, además de ejecutar cosign verify. El motivo es el propio comportamiento de cosign: cosign verify en una estructura guardada también finaliza con código 0 cuando la estructura contiene únicamente una atestación realizada con la clave y ninguna firma. El script no acepta eso.

Si esto falla

Un fallo termina con VERIFY-BUNDLE FAIL step=<k> <why>.

Última línea Qué significa Qué hacer
step=0 the public key must come from outside the bundle La clave que indicó se encuentra dentro del directorio del paquete. Utilice la clave que trajo por separado.
step=1 checksum mismatch Un archivo cambió después de que se creara la lista o se dañó durante el tránsito. Copie de nuevo el paquete desde el medio original y vuelva a comprobarlo.
step=1 files not covered by SHA256SUMS Se añadió un archivo al paquete. Trate el medio como no confiable. No instale nada desde él.
step=2 SHA256SUMS signature does not verify La lista de sumas de comprobación no está firmada con la clave de versión que usted posee. Deténgase. Informe a su equipo de seguridad y solicite a Adverant un nuevo medio.
step=3 image <svc>: ... Falta la firma o la atestación SBOM de una imagen, o no se puede verificar. Deténgase, igual que en el paso 2.
step=4, step=5 El chart o su lista de imágenes no guardan coherencia. Solicite a Adverant un nuevo paquete.
step=6 ... La oferta de código fuente está incompleta. Solicite a Adverant un nuevo paquete.

El fallo de los pasos 2 y 3 es el caso para el cual existe todo este diseño. Significa que los archivos no son los que firmó Adverant. Guarde el medio para su equipo de seguridad.

Cargar las imágenes en su propio registro

Sus nodos extraen imágenes de un registro situado dentro de las instalaciones. El de Harrow es registry.harrow.example. Cada imagen de Nexus se ubica bajo la ruta nexus/ en ese registro, porque el chart hace referencia a cada imagen como <global.imageRegistry>/nexus/<svc>@<digest>.

  1. Inicie sesión en su registro con la herramienta que utilice habitualmente, para que cosign pueda subir imágenes a él.
  2. Desde dentro del directorio del paquete, cargue cada imagen y verifíquela de nuevo en su nueva ubicación:
REG=registry.harrow.example
jq -r '.images[] | "\(.svc) \(.index)"' release/images.lock.json | while read -r svc digest; do
  cosign load --dir "images/$svc" "$REG/nexus/$svc"
  cosign verify --key release.pub --insecure-ignore-tlog=true "$REG/nexus/$svc@$digest" > /dev/null \
    && cosign verify-attestation --key release.pub --insecure-ignore-tlog=true --type spdxjson "$REG/nexus/$svc@$digest" > /dev/null \
    && echo "verified $svc"
done

cosign load transporta la firma y todas las atestaciones junto con la imagen, por lo que la copia del registro se verifica con la misma clave. La verificación realizada aquí es la que cuenta para su clúster: demuestra que lo que extraerán sus nodos es lo que firmó Adverant.

verified nexus-alpha
verified nexus-auth
verified nexus-postgres
...

Cada imagen del archivo de bloqueo debería imprimir una línea verified. Si falta una línea, significa que la carga o la comprobación de esa imagen falló, y su error se muestra justo encima.

No existe un registro de transparencia para las versiones de Nexus, por lo que --insecure-ignore-tlog=true es necesario en cada comprobación. La clave de versión constituye toda la raíz de confianza. Sin este modificador, cosign rechaza la operación con not enough verified log entries from transparency log: 0 < 1.

Instalar desde su registro

El archivo de valores para una instalación aislada difiere del de una conectada en una sola línea: global.imageRegistry indica el nombre de su registro.

# harrow-prod-values.yaml (Helm values)
global:
  imageRegistry: registry.harrow.example
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: enterprise
enterprise:
  enabled: true
tls:
  mode: existing
  existingSecret: harrow-public-tls
storage:
  className: harrow-ssd
keys:
  installationName: harrow-port
  custody:
    recipients:
      - "<custodian-one-age-recipient>"
      - "<custodian-two-age-recipient>"

Las entradas de <custodian-...-age-recipient> son las líneas públicas de age1... de las personas que poseen las claves de recuperación del almacén de claves. El capítulo 2.8, Instalaciones en una sola máquina, explica cómo genera una cada persona. harrow-ssd es la clase de almacenamiento propia de Harrow: ponga la suya o deje fuera storage.className para utilizar la predeterminada del clúster.

  1. Ejecute las comprobaciones previas (preflight) en el clúster con este archivo, tal y como se describe en el capítulo 2.5, Comprobaciones previas con nexusctl.
  2. Instale desde el chart del paquete y omita --wait.
helm install nexus charts/nexus-1.0.0-alpha.1.tgz -n nexus --create-namespace \
  -f harrow-prod-values.yaml --timeout 45m
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s

helm install --wait provoca un bloqueo mutuo (deadlock) con este chart: un hook posterior a la instalación entrega a cada servicio su contraseña de base de datos, y --wait retiene los hooks hasta que los servicios están activos. El capítulo 2.8, Instalaciones en una sola máquina, contiene el bucle que también espera a los StatefulSets.

Con nexusctl, la misma instalación es nexusctl install --context <kube-context> --values harrow-prod-values.yaml.

Nada en el chart se comunica fuera del espacio de nombres excepto el DNS (sistema de nombres de dominio), la API (interfaz de programación de aplicaciones) de Kubernetes para las revisiones de tokens y cualquier dirección que usted enumere en networkPolicy.externalEgressCIDRs, que está vacía de forma predeterminada. Ninguna telemetría sale de la instalación, y telemetry.enabled no se puede configurar con ningún valor que no sea false. Para la IA (inteligencia artificial) en un sitio sin internet, la organización conecta su propio servidor de modelos compatible con OpenAI dentro de las instalaciones, indicado en ai.localProvider.baseUrl; el capítulo 2.14, Proveedores y modelos de IA, trata este tema.

La licencia no es un valor del chart. Usted la importa después de la instalación, tal y como se describe a continuación.

k3s y cert-manager sin descarga

Si Nexus va a instalarse en un clúster de k3s que usted mismo construye, k3s también tiene que instalarse sin red. La imagen de disco del instalador hace esto por usted (capítulo 2.9, La imagen de disco del instalador). Manualmente, en cada nodo:

  1. Traslade los archivos de la versión k3s v1.33.6+k3s1 para su arquitectura: el binario k3s (k3s-arm64 en arm64), install.sh, k3s-airgap-images-<arch>.tar.zst y sha256sum-<arch>.txt. k3s publica sumas de comprobación para estos archivos y ninguna firma. Compruebe cada archivo con sha256sum-<arch>.txt y deje claro a su equipo de seguridad que se trata de una suma de comprobación del mismo origen, no de una firma.
  2. Coloque el binario y las imágenes del sistema donde k3s los busca e instale con las descargas desactivadas:
sudo install -m 0755 k3s /usr/local/bin/k3s
sudo mkdir -p /var/lib/rancher/k3s/agent/images
sudo cp k3s-airgap-images-amd64.tar.zst /var/lib/rancher/k3s/agent/images/
sudo INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC="--write-kubeconfig-mode=0600" sh install.sh
sudo k3s kubectl wait --for=condition=Ready node --all --timeout=600s

cert-manager v1.21.3 es un requisito previo: la propia CA (autoridad de certificación) del chart es un emisor de cert-manager. Traslade el chart de cert-manager, cert-manager-v1.21.3.tgz, y sus imágenes. En el lado conectado, compruebe las imágenes con la clave propia del proyecto cert-manager antes de trasladarlas:

cosign verify --signature-digest-algorithm sha512 --insecure-ignore-tlog=true \
  --key cert-manager-pubkey-2021-09-20.pem quay.io/jetstack/<image>@<digest>

Dentro de las instalaciones, importe las imágenes en el almacén de contenedores de cada nodo bajo los nombres que solicita el chart de cert-manager, quay.io/jetstack/cert-manager-<name>:v1.21.3, luego compruébelas e instálelas:

sudo k3s ctr -n k8s.io images import --all-platforms cert-manager-images.tar
sudo k3s ctr -n k8s.io images ls -q | grep cert-manager
helm install cert-manager cert-manager-v1.21.3.tgz -n cert-manager \
  --create-namespace --set crds.enabled=true --wait --timeout 10m

--wait es correcto para cert-manager. Es solo Nexus el que no debe llevarlo.

Las actualizaciones y los componentes nuevos llegan en soportes firmados

Un sitio aislado también se actualiza desde un disco. En la consola, Importar desde medios en las páginas de Esta instalación carga una versión desde un disco llevado a las instalaciones. Comprueba la suma de comprobación de cada archivo, luego la firma con la clave de versión ya instalada en el sitio (nunca una clave que traiga el disco) y, por último, que la versión sea más reciente que la que está en ejecución. La importación solo copia y comprueba. Los usuarios siguen trabajando en la versión en ejecución y nada cambia hasta que usted decide actualizar.

Importación desde soporte físico (sin internet)
Importación desde soporte físico (sin internet)
Una versión en un disco siendo importada en Harrow. La firma se comprueba con la clave instalada en el sitio y la versión en ejecución permanece intacta hasta que alguien realiza la actualización.

Desde la línea de comandos, la misma versión se introduce con nexusctl:

nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar
nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

plan muestra lo que cambiará y no modifica nada. apply realiza primero una copia de seguridad y luego actualiza. El capítulo 2.15, Día dos: operación de Nexus, aborda las actualizaciones en detalle.

Cuando la firma de un disco no coincide, la importación se rechaza con MEDIA_SIGNATURE_INVALID. No se carga ni se copia nada, y la versión en ejecución sigue funcionando. La página indica qué comprobaciones se superaron, dónde se detuvo y la clave que esperaba junto a la clave que encontró. Guarde el disco para su equipo de seguridad y solicite uno nuevo a Adverant.

Error al importar desde el medio
Error al importar desde el medio
Una importación rechazada. Todas las sumas de comprobación coincidieron, pero la firma fue realizada por una clave desconocida, por lo que no se cargó nada y la versión en ejecución no se tocó.

Los componentes Enterprise que activa una licencia llegan de la misma manera a un sitio aislado: en el disco de la versión, a través de Importar desde medios, antes de que usted los active. Cada componente se comprueba con la clave de versión de Adverant antes de activarse, por lo que usted nunca copia un binario en el clúster a mano.

Licencias sin internet

Una instalación conectada recibe su licencia por sí sola. Una aislada intercambia archivos con Adverant a mano, mediante el intercambio sin conexión.

  1. Las páginas de licencias de la consola generan un pequeño archivo de solicitud de licencia. La instalación lo firma con su propia clave, para que Adverant pueda saber qué instalación lo solicitó.
  2. Alguien saca el archivo en una memoria USB hasta un ordenador con conexión a internet, inicia sesión en la cuenta de Adverant en https://account.adverant.ai y lo sube en la página Intercambio sin conexión.
  3. Traen de vuelta el archivo de licencia de la misma manera.
  4. Impórtelo. En la consola, abra Licencia y qué desbloquea y pulse Importar una nueva licencia. Desde la línea de comandos:
nexusctl licence import harrow-port-licence.json

La licencia se comprueba sin conexión, dentro de las instalaciones, con las claves de Adverant. Adverant firma cada licencia con dos claves independientes, y ambas firmas deben verificarse correctamente.

Intercambio sin conexión
Intercambio sin conexión
La página de Intercambio sin conexión en la cuenta de Adverant, donde se sube un archivo de solicitud firmado y se obtiene a cambio un archivo de licencia.

El mismo intercambio sirve para sacar la declaración de uso anual. Contiene únicamente contadores (puestos, dispositivos, grupos de funciones), y el administrador la lee línea por línea en Declaración de uso para Adverant antes de que salga.

Código Estado Qué significa
LICENCE_SIGNATURE_INVALID 422 El archivo no es una licencia firmada por Adverant o algún byte cambió después de la firma. No cambia nada.
LICENCE_OTHER_INSTALLATION 409 La licencia es auténtica, pero fue emitida para otra instalación. Solicite una emitida para el identificador de esta instalación.
LICENCE_CLOCK_BEHIND_FLOOR 409 El reloj marca una hora anterior a la última hora que ha registrado esta instalación. Retrasar el reloj no reactiva una licencia caducada.
LICENCE_REVOKED 403 Adverant retiró la licencia mediante una revocación firmada. Los componentes Enterprise dejan de ofrecerse; Community y la exportación se mantienen.

El capítulo 2.13, Licencias, aborda los estados, el periodo de gracia y la renovación.

Las listas de revocación se importan a mano

Cuando Adverant retira una licencia, publica una lista de revocación firmada. La lista es acumulativa: cada una contiene todas las licencias retiradas anteriormente. Una instalación conectada se entera automáticamente. Una aislada solo se entera cuando alguien importa la lista, así que lleve consigo la lista más reciente con cada disco de versión e impórtela a través de la importación de revocaciones de la instalación en las páginas de licencias, o en la dirección /api/v1/installation/licence/revocations del host de inicio de sesión.

Esto funciona en ambos sentidos. Una instalación aislada que nunca importa una lista nunca se entera de que una licencia fue revocada, incluida una licencia firmada por una clave que posteriormente resultó estar comprometida. Importar la lista es la única forma en que esa información cruza la brecha.

El paquete sellado soberano: nexus-airgap

Algunos sitios soberanos desean recibir una versión como un único archivo sellado y firmado cuyo propio manifiesto prohíba el acceso a la red. Para ellos existe un segundo formato, el paquete sellado, y su herramienta, nexus-airgap, del paquete @adverant/nexus-sovereign. Instale la herramienta desde el registro de paquetes de Adverant, por separado de cualquier paquete que vaya a comprobar. Un paquete no puede avalarse a sí mismo.

El paquete sellado es un único archivo tar firmado. Su manifiesto está firmado con Ed25519 y enumera un hash SHA-256 para cada archivo. La herramienta tiene cuatro verbos.

Verbo Qué hace
nexus-airgap bundle Construye un paquete sellado a partir de un directorio preparado y firma su manifiesto.
nexus-airgap verify --bundle <file> --trusted-key <pem> --profile <profile> Comprueba la firma con la clave de confianza, vuelve a calcular el hash de cada archivo, rechaza cualquier archivo que el manifiesto no enumere y rechaza cualquier paquete cuya regla de red no sea la lista de permitidos vacía con tráfico de agentes exclusivamente local. No modifica nada.
nexus-airgap install Verifica y, a continuación, ejecuta el plan de instalación en orden: cargar las imágenes, aplicar los manifiestos, ejecutar las migraciones, sembrar las habilidades y aprovisionar las claves.
nexus-airgap open Abre la exportación cifrada opcional del paquete con el custodio de claves propio del sitio, que en un sitio aislado es el chip TPM (módulo de plataforma segura) de la máquina.

Verifique antes de hacer cualquier otra cosa:

nexus-airgap verify --bundle nexus-alpha-1.0.0-alpha.1.tar.gz \
  --trusted-key release.pub --profile airgap --keep-staging > verify.json
jq '{ok, bundleId, profile, artifactsVerified}' verify.json

--keep-staging conserva la copia verificada y desempaquetada y la nombra como stagingDir en la salida, para que usted trabaje a partir de lo que se comprobó.

Si la verificación falla con BUNDLE_INTEGRITY_VIOLATION, un archivo dentro del paquete cambió después de ser firmado. Deténgase ahí. La herramienta tiene un modificador --no-strict que omite la comprobación de archivos no enumerados. No lo utilice en una versión.

El día que llega el siguiente disco

Tomás guarda una breve lista de comprobación pegada en el interior del armario de la garita de entrada, y vale la pena copiarla. Compruebe el .sha256 del archivo tar. Ejecute verify-bundle.sh con la clave instalada y lea la última línea. Importe la lista de revocación más reciente. Entonces, y solo entonces, importe la versión desde el medio físico y planifique la actualización. Un disco que falle en cualquiera de estos pasos vuelve a su sobre, etiquetado, para el equipo de seguridad, y nada en la red habrá cambiado.