Acessar metadados usando a API Artifact Analysis

O Assured OSS fornece metadados de segurança para cada pacote disponível. Cada versão do pacote tem metadados próprios. Nesta página, explicamos quais informações são fornecidas como parte dos metadados e como você pode acessar esses metadados.

É possível acessar os metadados de segurança usando uma das seguintes opções:

  • API Artifact Analysis
  • Cloud Storage

Esta página se aplica apenas ao nível sem custo financeiro.

Metadados de segurança

A Análise de artefatos fornece armazenamento de metadados de acordo com o modelo de código aberto Grafeas. As seguintes informações são fornecidas para cada versão do pacote:

  • Um PackageNote para cada versão lançada do pacote pelo Assured OSS. A observação 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.

  • Um BuildOccurrence. O link para essa ocorrência de build é fornecido na seção relatedURL da nota do pacote em relação ao rótulo BUILD_OCCURRENCE. O intotoStatement na ocorrência de build contém a procedência da SLSA v0.2.

  • Um segundo BuildOccurrenance. O link para essa ocorrência de build é fornecido na seção relatedURL da nota do pacote em relação ao rótulo ORIGINAL_SOURCE_PROVENANCE. Esse arquivo contém os detalhes da origem original (GitHub) no formato Source.

  • Uma AttestationOccurrence. O link para essa ocorrência de atestado é fornecido na seção relatedURL da nota do pacote em relação ao rótulo TEST_OCCURRENCE. O payload serializado na declaração 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 em relação ao rótulo PACKAGE_ATTESTATION_OCCURRENCE. O payload serializado em JSON no atestado é o payload da nota do pacote e a assinatura dele. Essa declaração é usada para verificar a integridade do conteúdo da nota do pacote.

  • Um VulnerabilityNote e um VulnerabilityOccurrence para cada vulnerabilidade associada ao pacote. A nota e a ocorrência combinadas fornecem informações sobre vulnerabilidades, como resumo ou descrição, gravidade, pontuação do CVSSV3, informações sobre versões afetadas e corrigidas e correção.

Acessar metadados de segurança do Artifact Analysis

É possível acessar os metadados de segurança da Análise de artefatos 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 do Artifact Analysis.

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

Etapa 1: configurar a autenticação

Configure a autenticação usando 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 maiúsculas de minúsculas. O uso de maiúsculas e minúsculas válido para o nome de lançamento do pacote pode ser encontrado em 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 do Container Analysis, use getNotes com o note_name para consultar o PackageNote. O PackageNote tem links para outras observações 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 exemplo

{
  "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 observação e ocorrência fornecidos no mapa relatedURL para buscar dados adicionais relacionados à origem, build, 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 imprime 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 fazer o download do script usando a Google Cloud CLI:

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

  2. Instale a biblioteca de cliente do container-analysis. Especificamente, esse comando vai instalar:

    pip install google-cloud-containeranalysis

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

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

  4. Faça o download do 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.

  5. 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 da análise de contêiner, adicione o seguinte comando ao script:

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

A seguir