Acessar metadados de segurança e verificar pacotes

Nível de serviço Enterprise

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.

Observação: Para acessar o repositório de metadados de segurança depois de configurar o Assured OSS Premium usando o gcloud, envie um e-mail para [e-mail] com as contas de serviço que você ativou para o Assured OSS.

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. 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 usando a ferramenta aoss-verifier
• Verificar manualmente as assinaturas dos pacotes baixados

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 por ele usando 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.

   Observação: no macOS, é possível usar shasum -a 256 para calcular o resumo.

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 bem-sucedido, 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 bem-sucedido, 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
   

   Observação: no macOS, é possível usar shasum -a 256 para calcular o resumo.

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.