Acessar metadados usando o Cloud Storage

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 Cloud Storage para revisar 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 a API Artifact Analysis, consulte Acessar metadados usando a API Artifact Analysis.

Arquivos de metadados de segurança

Os metadados de segurança de cada versão do pacote do Assured OSS são distribuídos entre os quatro arquivos a seguir em um bucket do Cloud Storage:

  • buildinfo.zip: esse arquivo contém metadados sobre as informações de build de um pacote. Esses metadados mudam em cenários muito raros, como a recriação de pacotes, a rotação de certificados e a adição de novos campos.
  • vexinfo.zip: esse arquivo contém as informações de vulnerabilidade de um pacote no formato CycloneDX 1.4. Isso deve mudar sempre que houver informações sobre uma vulnerabilidade no pacote.
  • healthinfo.zip: esse arquivo contém detalhes sobre os testes realizados em um pacote. Isso pode mudar se o status de teste de um pacote for modificado. Por exemplo, se um novo teste de segurança for realizado ou se o resultado da cobertura for alterado.
  • licenseinfo.zip: esse arquivo contém metadados referentes às informações de licença de um pacote. As informações de licença de um pacote podem mudar se o editor do pacote modificar as informações.

Cada arquivo ZIP contém os dois arquivos a seguir:

  • Um arquivo JSON com dados.
  • Um arquivo signature.zip que contém a assinatura desses dados.

Estrutura do arquivo JSON

A estrutura dos arquivos JSON é descrita na seção a seguir:

buildInfo.json

  • creationTime: o horário de criação do documento no formato de string RFC 3339.
  • creator: o proprietário do documento. Os seguintes detalhes são fornecidos:
    • name: o nome da organização que criou o documento.
    • email: o endereço de e-mail da organização em caso de dúvidas ou reclamações.
  • buildDetails: os detalhes relacionados à criação do binário. Os seguintes detalhes são fornecidos:
    • packageFileName: o nome do arquivo ao qual os detalhes do build se aplicam.
    • buildProvenance: uma string que representa a procedência do build do pacote no formato SLSA v0.2. Ele é gerado pelo Cloud Build.
    • envelope: uma string que representa um envelope DSSE que pode ser usado para verificar a integridade do documento de proveniência. Isso também é gerado pelo Cloud Build.
    • slsaLevel: indica o nível de SLSA seguido pelo sistema de build.
    • buildTool: nome da ferramenta usada para criar o pacote, que é o Cloud Build. Para mais informações, consulte Cloud Build.
    • transitiveClosureState: é um ENUM que indica se todas as dependências de build do pacote (diretas ou indiretas) também estão presentes no portfólio do Assured OSS ou não. Isso pode ter dois valores:
      • OPEN: se nenhuma ou apenas algumas dependências transitivas forem compatíveis com o Assured OSS.
      • CLOSED: se todas as dependências transitivas forem compatíveis com o Assured OSS.
  • sourceInfo: as informações sobre o código-fonte usado para criar o pacote. Os seguintes detalhes são fornecidos:
    • sourceUrl: a string de URL do GitHub.
    • commitHash: string de hash de commit anexada à versão.
    • tag: a tag de lançamento associada à versão do pacote.
    • host: nome do sistema que hospeda o código-fonte no GitHub.
    • commitTime: o horário de um commit no formato de string RFC 3339.
  • sbom: string SBOM no formato SPDX 2.3.

vexInfo.json

  • creationTime: o horário de criação do documento no formato de string RFC 3339.
  • creator: o proprietário do documento. Os seguintes detalhes são fornecidos:
    • name: o nome da organização que criou o documento.
    • email: o endereço de e-mail da organização em caso de dúvidas ou reclamações.
  • vexData: string de Vulnerability Exploitability eXchange (VEX) no formato CycloneDX 1.4.

healthInfo.json

  • creationTime: o horário de criação do documento no formato de string RFC 3339.
  • creator: o proprietário do documento. Os seguintes detalhes são fornecidos:
    • name: o nome da organização que criou o documento.
    • email: o endereço de e-mail da organização em caso de dúvidas ou reclamações.
  • testingData: os detalhes sobre os testes de segurança feitos em um pacote. Os seguintes detalhes são fornecidos:
    • testType: o tipo de teste que foi feito. Por exemplo, FUZZ.
    • tool: o nome da ferramenta usada para realizar o teste.
    • testStatus: o status do teste. O status pode ser um dos seguintes:
      • TESTED: o teste foi executado.
      • NOT_REQUIRED: o teste não era necessário para o pacote. Por exemplo, o teste de fuzz não é necessário em um pacote que contém apenas interfaces.
      • UNTESTED: o pacote não foi testado.

licenseInfo.json

  • package_name: o nome do pacote no formato de string.
  • package_version: a versão do pacote.
  • license_info: a licença associada ao pacote.

Acessar metadados de segurança do Cloud Storage

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

Etapa 1: configurar a autenticação

Para saber como configurar a autenticação, consulte Configurar a autenticação.

Etapa 2: criar o URL

É possível usar os comandos gcloud storage ou curl para fazer o download dos metadados. Crie o URL para ambos usando as seguintes informações:

  • Idioma: java ou python. O valor precisa estar em letras minúsculas.
  • Package_ID:: para Java, é groupId:artifactId e para Python, é packageName. O valor precisa estar em letras minúsculas.
  • Versão: a versão do pacote.
  • Metadata_Type:: escolha entre buildinfo.zip, vexinfo.zip e healthinfo.zip.

O URL precisa ter o seguinte formato:

gcloud

gs://cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>

O URL precisa estar em letras minúsculas.

Exemplo de URL do Python: gs://cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Exemplo de URL Java: gs://cloud-aoss-metadata/java/com.google.errorprone:error_prone_annotations/2.15.0/buildinfo.zip

curl

https://storage.googleapis.com/cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>

O URL precisa estar em letras minúsculas.

Exemplo de URL do Python: https://storage.googleapis.com/cloud-aoss-metadata/python/cryptography/37.0.4/buildinfo.zip

Exemplo de URL Java: https://storage.googleapis.com/cloud-aoss-metadata/java/com.google.errorprone:error_prone_annotations/2.15.0/buildinfo.zip

Etapa 3: fazer o download dos metadados

Use os seguintes comandos para fazer o download dos metadados:

gcloud

gcloud storage cp  "gs://cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type>" outputFolderLocation

Para fazer o download de todos os tipos de metadados, como informações de build, integridade e VEX, para um determinado pacote e versão, use o seguinte comando:

gcloud storage cp "gs://cloud-aoss-metadata/<language>/<package_id>/<version>" outputFolderLocation --recursive

Os metadados são distribuídos em três arquivos ZIP (buildinfo.zip, healthinfo.zip, vexinfo.zip) e baixados na pasta de saída.

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss-metadata/<language>/<package_id>/<version>/<metadata_type> -o output.zip

Etapa 4: extrair os metadados

Extraia o arquivo ZIP. No macOS ou Linux, use o comando unzip: unzip input.zip -d outputFolder. Cada arquivo ZIP contém um arquivo JSON e um arquivo signature.zip. O arquivo JSON contém os metadados de segurança reais, e o arquivo signature.zip contém arquivos para verificar a assinatura do Google no JSON.

Baixar informações da licença

As informações de licença de todos os pacotes do Assured OSS estão disponíveis em um único arquivo JSON. Para baixar esse arquivo, execute o seguinte comando:

gcloud

gcloud storage cp  "gs://cloud-aoss/info/LicenseInfo.json" outputFolderLocation

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss/info/LicenseInfo.json

Para baixar a assinatura do arquivo de metadados da licença, execute o seguinte comando:

gcloud

gcloud storage cp "gs://cloud-aoss/info/LicenseInfo.json-sig.zip" outputFolderLocation

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/cloud-aoss/info/LicenseInfo.json-sig.zip -o output.zip

A seguir