Acessar metadados usando o Cloud Storage

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.

Arquivos de metadados de segurança

Os metadados de segurança de cada versão do pacote do Assured OSS são distribuídos nos 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 reconstrução do pacote, 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 o teste realizado 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 relacionados à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 deste 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 este 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 a que os detalhes do build se aplicam.
    • buildProvenance: uma string que representa a procedência do build do pacote no formato SLSA v0.2. Isso é gerado pelo Cloud Build.
    • envelope: uma string que representa um envelope DSSE que pode ser usado para verificar a integridade do documento de origem. Isso também é gerado pelo Cloud Build.
    • slsaLevel: indica o nível de SLSA aderido 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. Ele pode ter dois valores:
      • OPEN: se o Assured OSS não oferecer suporte a nenhuma ou apenas a algumas dependências transitivas.
      • 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 da lista de materiais de software no formato SPDX 2.3.

vexInfo.json

  • creationTime: o horário de criação deste 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 este documento.
    • email: o endereço de e-mail da organização em caso de dúvidas ou reclamações.
  • vexData: string de vulnerabilidade, exploração e troca (VEX) no formato CycloneDX 1.4.

healthInfo.json

  • creationTime: o horário de criação deste 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 este documento.
    • email: o endereço de e-mail da organização em caso de dúvidas ou reclamações.
  • testingData: os detalhes sobre o teste de segurança feito em um pacote. Os seguintes detalhes são fornecidos:
    • testType: o tipo de teste realizado. 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 fuzzing 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 informações sobre 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. Construa o URL para os dois 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 em 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 em Java: https://storage.googleapis.com/cloud-aoss-metadata/java/com.google.errorprone:error_prone_annotations/2.15.0/buildinfo.zip

Etapa 3: baixar os metadados

Use os comandos a seguir para fazer o download dos metadados:

gcloud

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

Para baixar todos os tipos de metadados, como informações de build, de integridade e de VEX, de 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 fazer o download desse 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 fazer o download da 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