O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Acessar metadados usando a API Artifact Analysis

O Assured Open Source Software (Assured OSS) fornece metadados de segurança para cada pacote e versão de pacote disponíveis. É possível acessar esses metadados no Artifact Analysis para analisar detalhes do build, status de vulnerabilidade, resultados de testes e informações de licença.

Este documento se aplica apenas ao nível sem custo financeiro. Para instruções sobre como acessar metadados usando o Cloud Storage, consulte Acessar metadados usando o Cloud Storage.

Metadados de segurança

O Artifact Analysis fornece armazenamento de metadados de acordo com o modelo de código aberto Grafeas. As informações a seguir são fornecidas para cada versão do pacote:

Uma PackageNote para cada versão lançada do pacote pelo Assured OSS. A nota do pacote contém o seguinte:
- distribution em que cada distribution corresponde a um artefato fornecido pelo Assured OSS. Ele inclui o local e o resumo url (de onde a assinatura e o hash podem ser baixados) para fontes binárias e reproduzíveis.
- relatedURL que contém links para metadados, como procedência do build, atestado de teste e vulnerabilidades.
Uma BuildOccurrence. O link para essa ocorrência de build é fornecido na seção relatedURL da nota do pacote, no rótulo BUILD_OCCURRENCE. O intotoStatement na ocorrência de build contém a procedência do SLSA v0.2.
Uma segunda BuildOccurrenance. O link para essa ocorrência de build é fornecido na seção relatedURL da nota do pacote, no rótulo ORIGINAL_SOURCE_PROVENANCE. Esse arquivo contém os detalhes da origem original (GitHub) no formato de Source.
Uma AttestationOccurrence. O link para essa ocorrência de atestado é fornecido na seção relatedURL da nota do pacote, no rótulo TEST_OCCURRENCE. O payload serializado no atestado contém JSON que representa todos os testes de segurança feitos na versão do pacote.
Uma segunda AttestationOccurrence. O link para essa ocorrência de atestado é fornecido na seção relatedURL da nota do pacote, no rótulo PACKAGE_ATTESTATION_OCCURRENCE. O payload serializado JSON no atestado é o payload da nota do pacote e a assinatura dele. Esse atestado é usado para verificar a integridade do conteúdo da nota do pacote.
Uma VulnerabilityNote e uma VulnerabilityOccurrence para cada vulnerabilidade associada ao pacote. A nota e a ocorrência combinadas fornecem informações sobre vulnerabilidades, como o resumo ou a descrição da vulnerabilidade, a gravidade, a pontuação do CVSSV3, as informações sobre a versão afetada e corrigida e a correção.

Acessar metadados de segurança do Artifact Analysis

É possível acessar os metadados de segurança do Artifact Analysis usando os clientes da API Artifact Analysis, que estão disponíveis em diferentes linguagens. Para começar a usar as bibliotecas de cliente do Cloud para a API Artifact Analysis, consulte Instalar as bibliotecas de cliente necessárias da Artifact Analysis.

Para acessar os metadados de segurança, siga estas etapas:

Etapa 1: configurar a autenticação

Configure a autenticação usando o Application Default Credentials (ADC).

Etapa 2: buscar metadados de segurança

Para buscar metadados de segurança, crie um pacote note_name usando as seguintes informações:

Project_ID: o identificador alfanumérico do seu projeto do Google Cloud .
Package Language: Java ou Python. Precisa estar em maiúsculas.
Package_ID: para Java, é groupId_artifactId e para Python, é packageName. Esse valor diferencia letras maiúsculas de minúsculas. O uso de maiúsculas e minúsculas válido para o nome da versão do pacote pode ser encontrado em Como listar todos os pacotes no Assured OSS.
Version: a versão do pacote.

O note_name precisa ter a seguinte estrutura: projects/<project_id>/notes/<language>-<package_id>-<version>.

Por exemplo: projects/cloud-aoss/notes/JAVA-org.apache.commons_commons-compress-1.21

Opção 1:

Se você estiver usando as bibliotecas de cliente da Container Analysis, use getNotes com o note_name para consultar o PackageNote. O PackageNote tem links para outras notas e ocorrências.

Opção 2:

Se você estiver usando o comando curl, use o seguinte comando:

curl  -H "Content-Type: application/json" -H   "Authorization: Bearer $(gcloud auth print-access-token)" $URL

Para Java, use o URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2
Para Python, use o URL: https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/PYTHON-Flask-Cors-3.0.10

Metadados de amostra

{
  "name": "projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2",
  "kind": "PACKAGE",
  "relatedUrl": [
    {
      "url": "projects/cloud-aoss/occurrences/621d7e7b-8e6c-4313-b24b-eae3a1d1b884",
      "label": "ORIGINAL_SOURCE_PROVENANCE"
    },
    {
      "url": "https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/occurrences/a0967d97-634c-4066-b6da-0a723273a165",
      "label": "BUILD_OCCURRENCE"
    },
    {
      "url": "projects/cloud-aoss/occurrences/6005db73-7310-44f9-9a36-6ca0174732a1",
      "label": "TEST_OCCURRENCE"
    },
    {
      "url": "projects/cloud-aoss/notes/GHSA-gp7f-rwcx-9369",
      "label": "VULNERABILITY_GHSA-gp7f-rwcx-9369"
    }
  ],
  "createTime": "2022-10-12T06:48:19.162016Z",
  "updateTime": "2022-10-18T05:31:15.081736Z",
  "package": {
    "distribution": [
      {
        "cpeUri": "cpe:2.3:a:JAVA::org.jsoup:jsoup:1.15.2:*:*:*:*:*:*:*",
        "url": "https://us-maven.pkg.dev/…/org/jsoup/jsoup/1.15.2/jsoup-1.15.2.jar",
        "description": "..."
      },
      {
        "cpeUri": "cpe:2.3:a:JAVA::org.jsoup:jsoup:1.15.2:*:*:*:*:*:*:*",
        "url": "https://us-maven.pkg.dev/…/org/jsoup/jsoup/1.15.2/jsoup-1.15.2-sources.jar",
        "description": "..."
      }
]}}

Use os nomes de nota e ocorrência fornecidos no mapa relatedURL para buscar outros dados relacionados à origem, ao build, ao teste e à vulnerabilidade. Para isso, use as APIs GetNote e GetOccurrence ou os comandos curl. Para BUILD_OCCURRENCE, remova o prefixo inicial de https://containeranalysis.googleapis.com/v1/ ao usar a API. Para outras entidades, use os URLs diretamente como note_name ou occurrence_name no parâmetro da API.

Exemplo de script em Python

Um exemplo de script Python que mostra todos os metadados baixados está disponível no seguinte local do Cloud Storage, junto com o arquivo README:

gs://cloud-aoss/utils/python-download-metadata/v1.1

Siga estas etapas para baixar o script usando a Google Cloud CLI:

Configure a autenticação usando o Application Default Credentials (ADC).
Instale a biblioteca de cliente do container-analysis. Especificamente, esse comando deve instalar:
```
pip install google-cloud-containeranalysis
```

Instale os pacotes cloud-kms e cryptography usando os seguintes comandos:

pip install --upgrade google-cloud-kms
pip install --upgrade cryptography

Baixe o download_metadata.py para seu sistema usando o seguinte comando:
```
gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/download_metadata.py
PATH_TO_LOCAL_STORE --recursive
```
Substitua PATH_TO_LOCAL_STORE pelo caminho local em que você quer salvar o arquivo.
Faça o download do README.md que contém as instruções para usar o script com o seguinte comando:
```
gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/README.md PATH_TO_LOCAL_STORE --recursive
```
Substitua PATH_TO_LOCAL_STORE pelo caminho local em que você quer salvar o arquivo.

Exemplo de comando

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1'

Para verificar as assinaturas nos metadados do Container Analysis, adicione o seguinte comando ao script:

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1' -s`