Acessar metadados de segurança e verificar pacotes

Nesta página, descrevemos como acessar metadados de segurança do bucket do Cloud Storage assuredoss-metadata. Para uma descrição dos metadados de segurança, consulte Campos de metadados de segurança.

Esta página se aplica apenas ao nível premium do Assured OSS. Para o nível gratuito, consulte Verificar assinaturas no nível gratuito do Assured OSS.

Antes de começar

Configure a autenticação.

Extrair os metadados

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

  • Idioma:java, python ou javascript. O valor precisa estar em letras minúsculas.
  • Package_ID:: para Java, é groupId:artifactId; para Python, é packageName; e para JavaScript, é um dos seguintes: @org-name/package-name, @username/package-name ou package-name. O valor precisa estar em letras minúsculas.
  • Versão:a versão do pacote.

O URL precisa ter o seguinte formato:

gcloud

gs://assuredoss-metadata/language/package_id/version/metadata.json

O URL precisa estar em letras minúsculas.

Exemplo de URL do Python: gs://assuredoss-metadata/python/blessed/1.20.0/metadata.json

Exemplo de URL em Java: gs://assuredoss-metadata/java/org.apache.logging.log4j:log4j-core/2.17.1/metadata.json

Exemplo de URL JavaScript: gs://assuredoss-metadata/javascript/@stoplight/spectral-core/0.0.0/metadata.json

curl

https://storage.googleapis.com/assuredoss-metadata/language/package_id/version/metadata.json

O URL precisa estar em letras minúsculas.

Exemplo de URL do Python: https://storage.googleapis.com/assuredoss-metadata/python/blessed/1.20.0/metadata.json

Exemplo de URL em Java: https://storage.googleapis.com/assuredoss-metadata/java/org.apache.logging.log4j:log4j-core/2.17.1/metadata.json

Exemplo de URL JavaScript: https://storage.googleapis.com/assuredoss-metadata/javascript/@stoplight/spectral-core/0.0.0/metadata.json

  1. Faça o download dos metadados:

gcloud

gcloud storage cp "gs://assuredoss-metadata/language/package_id/version/metadata.json" outputFolderLocation

curl

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -L https://storage.googleapis.com/assuredoss-metadata/language/package_id/version/metadata.json -o metadata.json

Agora você pode verificar as assinaturas. Existem duas opções:

Verificar as assinaturas dos pacotes baixados usando a ferramenta aoss-verifier

Use a ferramenta aoss-verifier para verificar os metadados do pacote.

Antes de usar essa ferramenta, instale o Go.

  1. Instale a ferramenta aoss-verifier.

  2. Exporte $(go env GOPATH)/bin.

  3. Execute o comando aoss-verifier verify-metadata.

    aoss-verifier verify-metadata \
   --metadata_type TYPE \
   --language LANGUAGE \
   --package_id PACKAGE_ID \
   --version VERSION \
   [--disable_certificate_verification] \
   [--temp_downloads_path TEMP_DOWNLOADS_DIR_PATH] \
   [--disable_deletes]

    Substitua:

    • TYPE: os valores possíveis são premiuminfo.
    • LANGUAGE: o idioma do pacote. O valor precisa estar em letras minúsculas.
    • PACKAGE_ID: para Java, o formato é groupId:artifactId. Para Python, o formato é packageName. O valor precisa estar em letras minúsculas.
    • VERSION: a versão do pacote.

    --disable_certificate_verification é uma flag opcional que ignora a correspondência do certificado de folha com o certificado raiz pela cadeia de certificados, se usada.

    --temp_downloads_path é uma flag opcional para definir o caminho em que você quer baixar os arquivos (substitua TEMP_DOWNLOADS_DIR_PATH). Se a flag não estiver definida, os arquivos serão baixados para a pasta tmp_downloads no diretório atual.

    --disable_deletes é uma flag opcional que mantém os arquivos baixados. Por padrão, a ferramenta limpa todos os arquivos baixados.

Para mais informações, consulte o README.

Verificar manualmente as assinaturas dos pacotes baixados

É possível verificar a assinatura do artefato apenas para os binários criados com segurança pelo Assured OSS, não para os fornecidos pelo Assured OSS por proxies.

Para verificar assinaturas manualmente, use várias ferramentas. As etapas a seguir usam a CLI gcloud, o OpenSSL (versão 3.0.1 ou mais recente) e jq (1.7.1 ou mais recente) para verificar as assinaturas no Linux.

  1. Faça o download do arquivo de metadados. Conforme descrito em Campos de metadados de segurança, o arquivo de metadados contém um campo SBOM dentro do campo buildInfo. A lista de materiais de software contém o artefato (por exemplo, um arquivo JAR ou EGG) criado com uma anotação que representa a assinatura. Com esse artefato, é possível determinar o ID do SPDX.

    Por exemplo, se o nome do artefato for artifact_name, o spdx_id será SPDXRef-Package-artifact_name. Para validar um pacote chamado gradio-3.30.0-py3-none-any.whl, o spdx_id é SPDXRef-Package-gradio-3.30.0-py3-none-any.whl.

  2. Extraia o resumo SHA-256 do arquivo de metadados:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.digest[0].digest' | cut -d ' ' -f1 > expectedDigest.txt

    Substitua:

    • METADATA_FILENAME: o nome do arquivo de metadados de segurança.

    • SPDX_ID: o identificador SPDX.

  3. Calcule o resumo do artefato:

    sha256sum ARTIFACT_FILE | cut -d ' ' -f1 > actualDigest.txt

    Substitua ARTIFACT_FILE pelo nome do arquivo de artefato.

  4. Verifique se há diferenças entre os dois: 

    diff actualDigest.txt expectedDigest.txt

    Se não houver diferença, não haverá saída.

  5. Extraia o resumo do campo para um arquivo .bin:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.digest[0].digest' | cut -d ':' -f2 | xxd -r -p > digest.bin

  6. Extraia a assinatura do resumo para um arquivo .sig:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.signature[0].signature' | xxd -r -p > sig.sig

  7. Extraia a chave pública do certificado público para um arquivo .pem:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.certInfo.cert' | openssl x509 -pubkey -noout  > pubKey.pem

  8. Verifique a assinatura do resumo usando a chave pública extraída:

    openssl pkeyutl -in digest.bin -inkey pubKey.pem -pubin -verify -sigfile sig.sig

    Se o comando for executado corretamente, ele vai retornar Signature Verified Successfully. Agora você pode verificar o certificado.

  9. Extraia o certificado público para um arquivo .pem:

    cat METADATA_FILENAME | jq -rj '.buildInfo' | jq -rj '.sbom' | jq -rj '.packages' | jq '.[] | select(.SPDXID=="SPDX_ID")' | jq -rj '.annotations[0].comment' | jq -rj '.certInfo.cert' > cert.pem

  10. Faça o download do certificado raiz (ca.crt no comando a seguir):

    curl -o ca.crt https://privateca-content-6333d504-0000-2df7-afd6-30fd38154590.storage.googleapis.com/a2c725a592f1d586f1f8/ca.crt

  11. Verifique o certificado usando o certificado extraído e o certificado raiz:

    openssl verify -verbose -CAfile ca.crt cert.pem

    Se o comando for executado corretamente, ele vai retornar cert.pem: OK.

Verificar as assinaturas dos campos de metadados de segurança

É possível verificar a assinatura dos seguintes campos no arquivo de metadados de segurança de forma independente:

  • buildInfo
  • vexInfo
  • healthInfo (se presente)

Os dados nos campos são criptografados com hash usando SHA-256, e depois o hash é assinado usando o algoritmo ECDSAP256_DER. O certificado e a cadeia de certificados são fornecidos nos metadados para que você possa verificar a assinatura. Use o seguinte certificado raiz para verificar a cadeia de certificados:

https://privateca-content-6333d504-0000-2df7-afd6-30fd38154590.storage.googleapis.com/a2c725a592f1d586f1f8/ca.crt

É possível verificar as assinaturas manualmente ou usando a ferramenta de verificação do OSS garantido.

As etapas a seguir descrevem como verificar manualmente a assinatura do campo buildInfo no arquivo metadata.json. Você pode usar etapas semelhantes para verificar a assinatura do campo vexInfo ou healthInfo.

Você pode verificar assinaturas usando várias ferramentas. O exemplo a seguir usa a CLI gcloud, o OpenSSL (versão 3.0.1 ou mais recente) e o jq (1.7.1 ou mais recente) para verificar as assinaturas em um sistema Linux.

  1. Gere o resumo SHA-256 do campo:

    cat metadata.json | jq -rj '.buildInfo' | sha256sum | cut -d ' ' -f1 > actualDigest.txt

  2. Extraia o resumo do campo fornecido no arquivo metadata.json:

    cat metadata.json | jq -rj '.buildInfoSignature.digest[0].digest' | cut -d ':' -f2 > expectedDigest.txt

  3. Verifique se há diferenças entre os dois resumos:

    diff actualDigest.txt expectedDigest.txt

    Se não houver diferença, não haverá saída, o que é o caso ideal. Agora você pode verificar a assinatura.

  4. Extraia o resumo do campo para um arquivo .bin:

    cat metadata.json | jq -rj '.buildInfoSignature.digest[0].digest' | cut -d ':' -f2 | xxd -r -p > digest.bin

  5. Extraia a assinatura do resumo para um arquivo .sig:

    cat metadata.json | jq -rj '.buildInfoSignature.signature[0].signature' | xxd -r -p > sig.sig

  6. Extraia a chave pública do certificado público para um arquivo .pem:

    cat metadata.json | jq -rj '.buildInfoSignature.certInfo.cert' | openssl x509 -pubkey -noout  > pubKey.pem

  7. Verifique a assinatura do resumo usando a chave pública extraída:

    openssl pkeyutl -in digest.bin -inkey pubKey.pem -pubin -verify -sigfile sig.sig

    Se a verificação for bem-sucedida, esse comando vai retornar Signature Verified Successfully. Agora você pode verificar o certificado.

  8. Extraia o certificado público para um arquivo .pem:

    cat metadata.json | jq -rj '.buildInfoSignature.certInfo.cert' > cert.pem

  9. Faça o download do certificado raiz, chamado ca.crt no comando a seguir:

    curl -o ca.crt https://privateca-content-6333d504-0000-2df7-afd6-30fd38154590.storage.googleapis.com/a2c725a592f1d586f1f8/ca.crt

  10. Verifique o certificado usando o certificado extraído e o certificado raiz:

    openssl verify -verbose -CAfile ca.crt cert.pem

    Se o comando for bem-sucedido, ele vai retornar cert.pem: OK.