Artefactos de cadena de suministro de inserción y extracción mediante Azure Registry (versión preliminar)

  • Artículo

Use un registro de contenedor de Azure para almacenar y administrar un gráfico de artefactos de la cadena de suministro, incluidas firmas, lista de materiales de software (SBOM), resultados de análisis de seguridad y otros tipos.

Graph of artifacts, including a container image, signature and signed software bill of materials

Para demostrar esta funcionalidad, en este artículo se muestra cómo usar la CLI de OCI Registry as Storage (ORAS) para push, discover y pull un grafo de artefactos de cadena de suministros en un registro de contenedor de Azure. El almacenamiento de artefactos de OCI individuales (raíz) se trata en Inserción y extracción de artefactos de OCI.

Para almacenar un grafo de artefactos, se define una referencia a un artefacto subject mediante el manifiesto de artefacto de OCI, que forma parte de la especificación de la distribución OCI 1.1 en versión preliminar. La compatibilidad con OCI 1.1 Artifact Manifest es una característica en versión preliminar de ACR y está sujeta a limitaciones.

Prerrequisitos

  • Registro de contenedor de Azure: cree un registro de contenedor en la suscripción de Azure. Por ejemplo, use Azure Portal o la CLI de Azure.
    Consulte Limitaciones de la versión preliminar para más información sobre la compatibilidad con la nube de Azure.
  • CLI de Azure: se requiere la versión 2.29.1 o posterior. Consulte Instalación de la CLI de Azure para obtener información sobre la instalación o actualización.
  • CLI de ORAS: se requiere la versión v0.16.0 o posterior. Consulte: Instalación de ORAS.
  • Docker (opcional): para completar el tutorial, se hace referencia a una imagen de contenedor. Puede usar Docker instalado localmente para crear e insertar una imagen de contenedor, o bien usar acr build para crear de forma remota en Azure.
    Aunque Docker Desktop no es necesario, la CLI de oras usa el almacén de credenciales de escritorio de Docker para almacenar credenciales. Si Docker Desktop está instalado, debe ejecutarse para oras login.

Limitaciones de vista previa

La compatibilidad con manifiestos de artefactos de OCI (especificación OCI 1.1) está disponible en todas las regiones públicas de Azure. Microsoft Azure operado por 21Vianet y nubes gubernamentales aún no se admiten.

Configuración de un registro

Configure variables de entorno para copiar y pegar comandos fácilmente en el shell. Los comandos se pueden ejecutar localmente o en Azure Cloud Shell.

ACR_NAME=myregistry
REGISTRY=$ACR_NAME.azurecr.io
REPO=net-monitor
TAG=v1
IMAGE=$REGISTRY/${REPO}:$TAG

Autentíquese con la identidad individual de Microsoft Entra mediante un token de AD. Utilice siempre "000..." para USER_NAME, ya que el token se analiza mediante la variable PASSWORD.

# Login to Azure
az login

# Login to ACR, using a token based on your Azure identity
USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)

Nota

ACR y ORAS admiten varias opciones de autenticación para los usuarios y la automatización del sistema. En este artículo se usa una identidad individual, que emplea un token de Azure. Para ver más opciones de autenticación, consulte Autenticación con un registro de contenedor de Azure.

Inicio de sesión con ORAS

Proporcione las credenciales a oras login.

oras login $REGISTRY \
  --username $USER_NAME \
  --password $PASSWORD

Inserción de una imagen de contenedor

En este ejemplo se asocia un grafo de artefactos a una imagen de contenedor.

Cree e inserte una imagen de contenedor u omita este paso si $IMAGE hace referencia a una imagen existente en el registro.

az acr build -r $ACR_NAME -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main

Creación de una firma de ejemplo en la imagen de contenedor

echo '{"artifact": "'${IMAGE}'", "signature": "jayden hancock"}' > signature.json

Asociación de una firma en el registro, como referencia a la imagen de contenedor

El comando oras attach crea una referencia entre el archivo (./signature.json) y $IMAGE. El --artifact-type proporciona artefactos de diferenciación, de forma similar a las extensiones de archivo que habilitan diferentes tipos de archivo. Se pueden asociar uno o varios archivos especificando [file]:[mediaType].

oras attach $IMAGE \
    --artifact-type signature/example \
    ./signature.json:application/json

Para obtener más información sobre la asociación con ORAS, consulte Documentación de ORAS.

Asociación de un artefacto de varios archivos como referencia

Cuando se insertan artefactos de OCI en un registro con ORAS, cada referencia de archivo se inserta como un blob. Para insertar blobs independientes, haga referencia a los archivos individualmente o a la colección de archivos haciendo referencia a un directorio.
Para obtener más información sobre cómo insertar una colección de archivos, consulte Inserción de artefactos con varios archivos.

Cree documentación sobre un artefacto:

echo 'Readme Content' > readme.md
mkdir details/
echo 'Detailed Content' > details/readme-details.md
echo 'More detailed Content' > details/readme-more-details.md

Asocie un artefacto de varios archivos como referencia a $IMAGE:

Linux, WSL2 o macOS

oras attach $IMAGE \
    --artifact-type readme/example \
    ./readme.md:application/markdown \
    ./details

Windows

.\oras.exe attach $IMAGE ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown ^
    .\details

Descubrimiento de referencias de artefacto

La especificación OCI v1.1 define una API de referencias para detectar referencias a un artefacto subject. El comando oras discover puede mostrar la lista de referencias a la imagen de contenedor.

Con oras discover, consulte el grafo de artefactos ahora almacenados en el registro.

oras discover -o tree $IMAGE

La salida muestra el principio de un grafo de artefactos, donde la firma y los documentos se ven como elementos secundarios de la imagen de contenedor.

myregistry.azurecr.io/net-monitor:v1
├── signature/example
│   └── sha256:555ea91f39e7fb30c06f3b7aa483663f067f2950dcb...
└── readme/example
    └── sha256:1a118663d1085e229ff1b2d4d89b5f6d67911f22e55...

Creación de grafos profundos de artefactos

La especificación OCI v1.1 permite grafos profundos, que habilitan la lista de materiales de software firmados (SBOM) y otros tipos de artefactos.

Creación de una SBOM de muestra

echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json

Asociación de una SBOM de muestra a la imagen del registro

Linux, WSL2 o macOS

oras attach $IMAGE \
  --artifact-type sbom/example \
  ./sbom.json:application/json

Windows

.\oras.exe attach $IMAGE ^
    --artifact-type sbom/example ^
    ./sbom.json:application/json

Firma de la SBOM

Los artefactos que se insertan como referencias normalmente no tienen etiquetas, ya que se consideran parte del artefacto subject. Para insertar una firma en un artefacto que es un elemento secundario de otro artefacto, use el oras discover con el filtrado --artifact-type para buscar la síntesis del mensaje.

SBOM_DIGEST=$(oras discover -o json \
                --artifact-type sbom/example \
                $IMAGE | jq -r ".manifests[0].digest")

Creación de una firma de una SBOM

echo '{"artifact": "'$IMAGE@$SBOM_DIGEST'", "signature": "jayden hancock"}' > sbom-signature.json

Asociación de la firma de SBOM

oras attach $IMAGE@$SBOM_DIGEST \
  --artifact-type 'signature/example' \
  ./sbom-signature.json:application/json

Consulte el grafo

oras discover -o tree $IMAGE

Se genera el siguiente código resultado:

myregistry.azurecr.io/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

Promoción del grafo

Un flujo de trabajo típico de DevOps promoverá artefactos desde la etapa de desarrollo a través de la etapa de almacenamiento provisional, hasta la etapa en el entorno de producción. Los flujos de trabajo de una cadena de suministro segura promueven el contenido público a entornos protegidos de forma privada. En cualquier caso, querrá promover las firmas, las SBOM, examinar los resultados y otros artefactos relacionados con el artefacto raíz para tener un grafo completo de dependencias.

Con el comando oras copy, puede promover un grafo filtrado de artefactos entre registros.

Copie la imagen net-monitor:v1 y sus artefactos relacionados en sample-staging/net-monitor:v1:

TARGET_REPO=$REGISTRY/sample-staging/$REPO
oras copy -r $IMAGE $TARGET_REPO:$TAG

La salida de oras copy:

Copying 6bdea3cdc730 sbom-signature.json
Copying 78e159e81c6b sbom.json
Copied  6bdea3cdc730 sbom-signature.json
Copied  78e159e81c6b sbom.json
Copying 7cf1385c7f4d signature.json
Copied  7cf1385c7f4d signature.json
Copying 3e797ecd0697 details
Copying 2fdeac43552b readme.md
Copied  3e797ecd0697 details
Copied  2fdeac43552b readme.md
Copied demo42.myregistry.io/net-monitor:v1 => myregistry.azurecr.io/sample-staging/net-monitor:v1
Digest: sha256:ff858b2ea3cdf4373cba65d2ca6bcede4da1d620503a547cab5916614080c763

Detección del grafo de artefactos promocionados

oras discover -o tree $TARGET_REPO:$TAG

Salida de oras discover:

myregistry.azurecr.io/sample-staging/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

Extracción de un artefacto al que se hace referencia

Para extraer un artefacto específico al que se hace referencia, la síntesis del mensaje de referencia se detecta con el comando oras discover:

DOC_DIGEST=$(oras discover -o json \
              --artifact-type 'readme/example' \
              $TARGET_REPO:$TAG | jq -r ".manifests[0].digest")

Creación de un directorio limpio para la descarga

mkdir ./download

Extracción de los documentos en el directorio de descarga

oras pull -o ./download $TARGET_REPO@$DOC_DIGEST

Visualización de los documentos

tree ./download

La salida de tree:

./download
├── details
│   ├── readme-details.md
│   └── readme-more-details.md
└── readme.md

Visualización del repositorio y la lista de etiquetas

El manifiesto de artefactos de OCI permite insertar, detectar, extraer y copiar grafos de artefactos sin tener que asignar etiquetas. Los manifiestos de artefacto permiten que una lista de etiquetas se centre en los artefactos en los que los usuarios piensan, en lugar de las firmas y las SBOM asociadas a las imágenes de contenedor, gráficos de Helm y otros artefactos.

Consulte una lista de etiquetas

oras repo tags $REGISTRY/$REPO

Visualización de una lista de manifiestos

Un repositorio puede tener una lista de manifiestos etiquetados y sin etiquetar. Con la CLI de az acr manifest, vea la lista completa de manifiestos:

az acr manifest list-metadata \
  --name $REPO \
  --registry $ACR_NAME \
  --output jsonc

Observe que los manifiestos de imagen de contenedor tienen "tags", mientras que los tipos de referencia ("mediaType": "application/vnd.oci.artifact.manifest.v1+json") no.

En la salida, la firma no está etiquetada, pero se realiza un seguimiento como referencia oci.artifact.manifest a la imagen de contenedor

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2023-01-10T17:58:28.4403142Z",
  "digest": "sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5",
  "imageSize": 80,
  "lastUpdateTime": "2023-01-10T17:58:28.4403142Z",
  "mediaType": "application/vnd.oci.artifact.manifest.v1+json"
}

Eliminación de todos los artefactos del grafo

La compatibilidad con la especificación OCI v1.1 permite eliminar el grafo de artefactos asociados al artefacto raíz. Use el comando oras delete para eliminar el grafo de artefactos (firma, SBOM y la firma de la SBOM).

oras manifest delete -f $REGISTRY/$REPO:$TAG

oras manifest delete -f $REGISTRY/sample-staging/$REPO:$TAG

Visualización de los manifiestos restantes

Al eliminar el artefacto raíz, todos los artefactos relacionados también se eliminan dejando un entorno limpio:

az acr manifest list-metadata \
  --name $REPO \
  --registry $ACR_NAME -o jsonc

Salida:

2023-01-10 18:38:45.366387 Error: repository "net-monitor" is not found.

Resumen

En este artículo se crea, detecta, promociona y extrae un grafo de artefactos de la cadena de suministro que proporciona administración del ciclo de vida de los artefactos que crea y de los que depende.

Pasos siguientes

  • Obtenga más información sobre la CLI de ORAS
  • Aprenda más sobre OCI Artifact Manifest para saber cómo insertar, detectar, extraer y copiar un grafo de artefactos de la cadena de suministro