Enviar e puxar artefatos da cadeia de suprimentos usando o Registro do Azure (Visualização)

  • Artigo

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

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

Para demonstrar essa capacidade, este artigo mostra como usar a CLI do Registro OCI como Armazenamento (ORAS) para e discoverpull um gráfico de artefatos da cadeia de suprimentos para pushum registro de contêiner do Azure. O armazenamento de artefatos OCI individuais (raiz) é coberto em artefatos OCI Push e pull.

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

Pré-requisitos

  • Registo de contentores do Azure - crie um registos de contentores na sua subscrição do Azure. Por exemplo, use o portal do Azure ou a CLI do Azure.
    Consulte Limitações de visualização para suporte de nuvem do Azure.
  • CLI do Azure - Versão 2.29.1 ou posterior é necessária. Consulte Instalar a CLI do Azure para instalação e/ou atualização.
  • ORAS CLI - A versão v0.16.0 é necessária. Consulte: Instalação do ORAS.
  • Docker (Opcional) - Para concluir o passo a passo, uma imagem de contêiner é referenciada. Você pode usar o Docker instalado localmente para criar e enviar por push uma imagem de contêiner ou usar acr build para criar remotamente no Azure.
    Embora o Docker Desktop não seja necessário, a cli utiliza o oras armazenamento de credenciais da área de trabalho do Docker para armazenar credenciais. Se o Docker Desktop estiver instalado, ele deverá estar em execução para oras login.

Limitações de pré-visualização

O suporte ao Manifesto de Artefato OCI (especificação OCI 1.1) está disponível em todas as regiões públicas do Azure. O Microsoft Azure operado pela 21Vianet e as nuvens governamentais ainda não são suportados.

Configurar um registo

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

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

Autentique-se com sua identidade individual do Microsoft Entra usando um token AD. Use sempre "000..." para o como o USER_NAME token é analisado através da PASSWORD variável.

# 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 e ORAS suportam várias opções de autenticação para usuários e automação do sistema. Este artigo usa identidade individual, usando um token do Azure. Para obter mais opções de autenticação, consulte Autenticar com um registro de contêiner do Azure

Iniciar sessão com a ORAS

Forneça as credenciais para oras login.

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

Enviar uma imagem de contêiner por push

Este exemplo associa um gráfico de artefatos a uma imagem de contêiner.

Crie e envie por push uma imagem de contêiner ou ignore esta etapa se $IMAGE fizer 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 do contêiner

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

Anexar uma assinatura ao registo, como referência à imagem do contentor

O oras attach comando cria uma referência entre o arquivo (./signature.json) e o $IMAGEarquivo . O --artifact-type fornece para diferenciar artefatos, semelhante a extensões de arquivo que permitem diferentes tipos de arquivo. Um ou mais arquivos podem ser anexados especificando [file]:[mediaType].

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

Para obter mais informações sobre oras attach, consulte a documentação do ORAS.

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

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

Crie alguma documentação em torno de 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 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 artefatos

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

Usando oras discovero , exiba o gráfico de artefatos agora armazenados no registro.

oras discover -o tree $IMAGE

A saída mostra o início de um gráfico de artefatos, onde a assinatura e os documentos são vistos como filhos da imagem do contêiner.

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

Criando gráficos profundos de artefatos

A especificação OCI v1.1 permite gráficos profundos, permitindo listas de materiais de software assinadas (SBOM) e outros tipos de artefatos.

Criar um exemplo de SBOM

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

Assine o SBOM

Os artefatos que são enviados como referências, normalmente não têm tags, pois são considerados parte do subject artefato. Para enviar uma assinatura para um artefato que é filho de outro artefato, use a oras discover filtragem com --artifact-type para localizar o resumo.

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 a assinatura SBOM

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

Veja o gráfico

oras discover -o tree $IMAGE

Gera a seguinte saída:

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

Promover o gráfico

Um fluxo de trabalho típico de DevOps promoverá artefatos desde o desenvolvimento até o ambiente de produção Os fluxos de trabalho seguros da cadeia de suprimentos promovem conteúdo público para ambientes privados protegidos. Em ambos os casos, você desejará promover as assinaturas, SBOMs, resultados da verificação e outros artefatos relacionados com o artefato raiz para ter um gráfico completo das dependências.

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

Copie a imagem e seus artefatos relacionados a net-monitor:v1sample-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

Descubra o gráfico de artefactos promovidos

oras discover -o tree $TARGET_REPO:$TAG

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

Puxe um artefato referenciado

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

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

Puxe os documentos para o diretório de download

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

Ver os documentos

tree ./download

A saída de tree:

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

Ver o repositório e a listagem de tags

O OCI Artifact Manifest permite que gráficos de artefatos sejam enviados, descobertos, puxados e copiados sem a necessidade de atribuir tags. Os manifestos de artefatos permitem que uma listagem de tags se concentre nos artefatos em que os usuários pensam, em oposição às assinaturas e SBOMs associados às imagens de contêiner, gráficos de leme e outros artefatos.

Ver uma lista de etiquetas

oras repo tags $REGISTRY/$REPO

Ver uma lista de manifestos

Um repositório pode ter uma lista de manifestos marcados e não marcados. Usando a CLI, veja a az acr manifest 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 é marcada, mas rastreada como uma oci.artifact.manifest referência à imagem do 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 gráfico

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

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

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

Ver 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

Resultado:

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

Resumo

Neste artigo, um gráfico de artefatos da cadeia de suprimentos é criado, descoberto, promovido e extraído, fornecendo gerenciamento do ciclo de vida dos artefatos que você constrói e dos quais depende.

Próximos passos

  • Saiba mais sobre a CLI ORAS
  • Saiba mais sobre o OCI Artifact Manifest para saber como enviar, descobrir, puxar e copiar um gráfico de artefatos da cadeia de suprimentos