Enviar por push e pull de artefatos da cadeia de suprimentos usando o Registro do Azure (versão prévia)

Artigo
10/31/2023

Use um registro de contêiner do Azure para armazenar e gerenciar um grafo de artefatos de cadeia de fornecedores, incluindo assinaturas, SBOM (lista de materiais de software), resultados da verificação de segurança ou outros tipos.

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

Para demonstrar essa funcionalidade, este artigo mostra como usar a CLI do ORAS (OCI Registry as Storage) para efetuar push, discover e pull de um grafo de artefatos da cadeia de fornecedores para um Registro de Contêiner do Azure. O armazenamento de artefatos do OCI individuais (raiz) é abordado em Efetuar push e pull de artefatos do OCI.

Para armazenar um grafo de artefatos, uma referência a um artefato subject é definida usando o Manifesto do artefato do OCI, que faz parte da especificação de distribuição do OCI 1.1 de pré-lançamento. O suporte ao Manifesto do artefato do OCI 1.1 é uma versão prévia do recurso do ACR e está sujeito a limitações.

Pré-requisitos

Registro de Contêiner do Azure - crie um registro de contêiner em sua assinatura do Azure. Por exemplo, use o Portal do Azure ou a CLI do Azure.
Confira Limitações da versão prévia do suporte da nuvem do Azure.
CLI do Azure – A versão 2.29.1 ou mais recente é necessária. Para informações de instalação e atualização, confira Instalar a CLI do Azure.
CLI do ORAS – A versão v0.16.0 é necessária. Confira: Instalação do ORAS.
Docker (opcional) – Para que você conclua o passo a passo, uma imagem de contêiner é referenciada. Você pode usar o Docker instalado localmente para criar e efetuar push de uma imagem de contêiner ou usar o acr build para criá-la remotamente no Azure.
Embora o Docker Desktop não seja necessário, a CLI do oras utiliza o repositório de credenciais do Docker Desktop para armazenar credenciais. Se o Docker Desktop estiver instalado, ele precisará estar em execução para efetuar oras login.

Limitações de visualização

O suporte ao manifesto de artefato do OCI (especificação do OCI 1.1) está disponível em todas as regiões públicas do Azure. Ainda não há suporte para o Microsoft Azure operado pela 21Vianet e nuvens governamentais.

Configurar um registro

Configure variáveis de ambiente para copiar/colar comandos facilmente no seu shell. Os comandos podem ser executados localmente no Azure Cloud Shell.

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

Autentique-se com a sua identidade individual do Microsoft Entra para usar um token do AD. Sempre use "000..." para o USER_NAME, pois o token é analisado por meio da variável 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)

Observação

O ACR e o ORAS dão suporte a várias opções de autenticação para usuários e automação do sistema. Este artigo usa uma identidade individual, com um token do Azure. Para obter mais opções de autenticação, confira Autenticar-se em um Registro de Contêiner do Azure

Forneça as credenciais para oras login.

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

Efetuar push de uma imagem de contêiner

Este exemplo associa um grafo de artefatos a uma imagem de contêiner.

Crie e envie por push uma imagem de contêiner ou ignore esta etapa caso $IMAGE faça referência a uma imagem existente no registro.

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

Criar uma assinatura de exemplo para a imagem de contêiner

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

Anexar uma assinatura ao registro, como uma referência à imagem de contêiner

O comando oras attach cria uma referência entre o arquivo (./signature.json) e o $IMAGE. O --artifact-type é fornecido para diferenciar artefatos, semelhantes às extensões de arquivo que habilitam tipos de arquivo diferentes. Um ou mais arquivos podem ser anexados pela especificação de [file]:[mediaType].

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

Para obter mais informações sobre a anexação do ORAS, confira a documentação do ORAS.

Anexar um artefato de vários arquivos como uma referência

Quando artefatos de OCI são enviados por push a um registro no ORAS, cada referência de arquivo é enviada por push como um blob. Para efetuar push de blobs separados, faça referência aos arquivos individualmente ou à coleção de arquivos referenciando um diretório.
Para obter mais informações de como efetuar push de uma coleção de arquivos, consulte Como efetuar push de artefatos com vários arquivos.

Crie uma documentação sobre um artefato:

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

Anexe o artefato de vários arquivos como uma referência a $IMAGE:

Linux, WSL2 ou 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

Descobrindo referências de artefato

A Especificação do OCI v1.1 define uma API de referenciadores para descobrir referências a um artefato subject. O comando oras discover pode mostrar a lista de referências à imagem de contêiner.

Usando oras discover, veja o grafo de artefatos já armazenado no registro.

oras discover -o tree $IMAGE

A saída mostra o início de um grafo de artefatos, em que a assinatura e os documentos são exibidos como filhos da imagem de contêiner.

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

Criando gráficos aprofundados de artefatos

A especificação do OCI v1.1 permite grafos detalhados, habilitando a SBOM (lista de materiais de software) assinada e outros tipos de artefatos.

Criar uma SBOM de exemplo

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

Anexar um exemplo de SBOM à imagem no registro

Linux, WSL2 ou 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

Assinar a SBOM

Os artefatos, que são enviados por push como referências, não costumam ter marcas, pois são considerados parte do artefato subject. Para efetuar push de uma assinatura para um artefato que seja filho de outro artefato, use a filtragem oras discover com --artifact-type para localizar o resumo da mensagem.

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

Criar uma assinatura de uma SBOM

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

Anexar uma assinatura de SBOM

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

Exibir o gráfico

oras discover -o tree $IMAGE

Isso gera a saída a seguir:

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

Promover o grafo

Um fluxo de trabalho típico de DevOps promove artefatos da fase de desenvolvimento para a de preparo e depois para o ambiente de produção Os fluxos de trabalho seguros da cadeia de fornecedores promovem conteúdo público para ambientes protegidos de modo privado. Nos dois casos, você poderá promover as assinaturas, as SBOMs, os resultados da verificação e outros artefatos relacionados ao artefato raiz para obter um grafo completo de dependências.

Usando o comando oras copy, você pode promover um grafo filtrado de artefatos entre registros.

Copie a imagem net-monitor:v1 e os artefatos relacionados para sample-staging/net-monitor:v1:

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

A saída 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

Descobrir o grafo de artefato promovido

oras discover -o tree $TARGET_REPO:$TAG

A saída 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

Efetuar pull de um artefato referenciado

Para efetuar pull de um artefato referenciado específico, o resumo de referência é descoberto com o comando oras discover:

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

Criar um diretório limpo para download

mkdir ./download

Efetuar pull dos documentos no diretório de download

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

Exibir os documentos

tree ./download

A saída de tree:

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

Exibir o repositório e a listagem de marcas

O manifesto de artefato do OCI permite que grafos de artefato sejam enviados, descobertos, recebidos e copiados sem a necessidade de atribuir marcas. Os manifestos de artefato permitem que uma listagem de marcas se concentre nos artefatos considerados pelos usuários, ao contrário das assinaturas e SBOMs associadas às imagens de contêiner, aos gráficos do Helm e outros artefatos.

Exibir uma lista de marcas

oras repo tags $REGISTRY/$REPO

Exibir uma lista de manifestos

Um repositório pode ter uma lista de manifestos marcados e não marcados. Usando a CLI do az acr manifest, veja a lista completa de manifestos:

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

Observe que os manifestos de imagem de contêiner têm "tags", enquanto os tipos de referência ("mediaType": "application/vnd.oci.artifact.manifest.v1+json") não.

Na saída, a assinatura não está marcada, mas rastreada como uma referência de oci.artifact.manifest à imagem de contêiner:

{
  "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"
}

Excluir todos os artefatos no grafo

O suporte para a especificação do OCI v1.1 permite excluir o grafo de artefatos associados ao artefato raiz. Use o comando oras delete para excluir o grafo de artefatos (assinatura, SBOM e assinatura de SBOM).

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

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

Exibir os manifestos restantes

Ao excluir o artefato raiz, todos os artefatos relacionados também são excluídos, deixando um ambiente limpo:

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

Saída:

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

Resumo

Neste artigo, um grafo de artefatos da cadeia de fornecedores é criado, descoberto, promovido e extraído, oferecendo o gerenciamento do ciclo de vida dos artefatos que você cria e dos quais depende.

Próximas etapas

Saiba mais sobre a CLI do ORAS
Saiba mais sobre o Manifesto do Artefato OCI para saber como enviar, descobrir, extrair, copiar um grafo de artefatos da cadeia de suprimentos