Accede a los metadatos con Cloud Storage

Assured Open Source Software (Assured OSS) proporciona metadatos de seguridad para cada paquete y versión de paquete disponibles. Puedes acceder a estos metadatos en Cloud Storage para revisar los detalles de la compilación, el estado de vulnerabilidad, los resultados de las pruebas y la información de la licencia.

Este documento solo se aplica al nivel gratuito. Para obtener instrucciones sobre cómo acceder a los metadatos con la API de Artifact Analysis, consulta Accede a los metadatos con la API de Artifact Analysis.

Archivos de metadatos de seguridad

Los metadatos de seguridad de cada versión del paquete de Assured OSS se distribuyen en los siguientes cuatro archivos en un bucket de Cloud Storage:

  • buildinfo.zip: Este archivo contiene metadatos sobre la información de compilación de un paquete. Estos metadatos cambiarían en situaciones muy poco frecuentes, como la reconstrucción del paquete, la rotación de certificados y la adición de campos nuevos.
  • vexinfo.zip: Este archivo contiene la información de vulnerabilidad de un paquete en formato CycloneDX 1.4. Se espera que esto cambie cada vez que haya información sobre una vulnerabilidad para el paquete.
  • healthinfo.zip: Este archivo contiene detalles sobre las pruebas realizadas en un paquete. Esto puede cambiar si se modifica el estado de prueba de un paquete. Por ejemplo, si se realiza una nueva prueba de seguridad o si se cambia el resultado de la cobertura.
  • licenseinfo.zip: Este archivo contiene metadatos relacionados con la información de la licencia de un paquete. La información de la licencia de un paquete puede cambiar si el publicador del paquete modifica la información.

Cada archivo ZIP contiene los siguientes dos archivos:

  • Un archivo JSON que contiene datos.
  • Un archivo signature.zip que contiene la firma de esos datos.

Estructura del archivo JSON

La estructura de los archivos JSON se describe en la siguiente sección:

buildInfo.json

  • creationTime: Es la hora de creación de este documento en formato de cadena RFC 3339.
  • creator: Es el propietario del documento. Se proporcionan los siguientes detalles:
    • name: Es el nombre de la organización que creó este documento.
    • email: Es la dirección de correo electrónico de la organización en caso de que haya alguna consulta o queja.
  • buildDetails: Son los detalles relacionados con la compilación del objeto binario. Se proporcionan los siguientes detalles:
    • packageFileName: Es el nombre del archivo al que se aplican los detalles de la compilación.
    • buildProvenance: Es una cadena que representa la procedencia de compilación del paquete en formato SLSA v0.2. Cloud Build genera este ID.
    • envelope: Es una cadena que representa un sobre de DSSE que se puede usar para verificar la integridad del documento de procedencia. Cloud Build también genera este archivo.
    • slsaLevel: Indica el nivel de SLSA que cumple el sistema de compilación.
    • buildTool: Es el nombre de la herramienta que se usa para compilar el paquete, que es Cloud Build. Para obtener más información, consulta Cloud Build.
    • transitiveClosureState: Es un ENUM que indica si todas las dependencias de compilación del paquete (directas o indirectas) también están presentes en la cartera de Assured OSS o no. Puede tener dos valores:
      • OPEN: Si Assured OSS admite cero o solo dependencias transitivas parciales.
      • CLOSED: Si Assured OSS admite todas las dependencias transitivas.
  • sourceInfo: Es la información sobre el código fuente que se usó para compilar el paquete. Se proporcionan los siguientes detalles:
    • sourceUrl: Es la cadena de la URL de GitHub.
    • commitHash: Es la cadena de hash de confirmación adjunta a la versión.
    • tag: Es la etiqueta de la versión asociada con la versión del paquete.
    • host: Es el nombre del sistema que aloja el código fuente en GitHub.
    • commitTime: Es la hora de una confirmación en formato de cadena RFC 3339.
  • sbom: Es la cadena de SBOM en formato SPDX 2.3.

vexInfo.json

  • creationTime: Es la hora de creación de este documento en formato de cadena RFC 3339.
  • creator: Es el propietario del documento. Se proporcionan los siguientes detalles:
    • name: Es el nombre de la organización que creó este documento.
    • email: Es la dirección de correo electrónico de la organización en caso de que haya alguna consulta o queja.
  • vexData: Es la cadena de Vulnerability Exploitability eXchange (VEX) en formato CycloneDX 1.4.

healthInfo.json

  • creationTime: Es la hora de creación de este documento en formato de cadena RFC 3339.
  • creator: Es el propietario del documento. Se proporcionan los siguientes detalles:
    • name: Es el nombre de la organización que creó este documento.
    • email: Es la dirección de correo electrónico de la organización en caso de que haya alguna consulta o queja.
  • testingData: son los detalles sobre las pruebas de seguridad que se realizaron en un paquete. Se proporcionan los siguientes detalles:
    • testType: Es el tipo de prueba que se realizó. Por ejemplo, FUZZ
    • tool: Es el nombre de la herramienta que se usó para realizar la prueba.
    • testStatus: Es el estado de la prueba. El estado puede ser uno de los siguientes:
      • TESTED: Se ejecutaron las pruebas.
      • NOT_REQUIRED: No se requirieron pruebas para el paquete. Por ejemplo, no se requieren pruebas de fuzzing en un paquete que solo contiene interfaces.
      • UNTESTED: No se probó el paquete.

licenseInfo.json

  • package_name: Es el nombre del paquete en formato de cadena.
  • package_version: Es la versión del paquete.
  • license_info: Es la licencia asociada con el paquete.

Accede a los metadatos de seguridad desde Cloud Storage

Para acceder a los metadatos de seguridad desde Cloud Storage, sigue estos pasos:

Paso 1: Configura la autenticación

Para obtener información sobre cómo configurar la autenticación, consulta Configura la autenticación.

Paso 2: Construye la URL

Puedes usar los comandos gcloud storage o curl para descargar los metadatos. Crea la URL para ambas con la siguiente información:

  • Idioma: java o python. El valor debe estar en minúsculas.
  • Package_ID: Para Java, es groupId:artifactId y, para Python, es packageName. El valor debe estar en minúsculas.
  • Versión: Es la versión del paquete.
  • Metadata_Type: Elige entre buildinfo.zip, vexinfo.zip y healthinfo.zip.

La URL debe tener el siguiente formato:

gcloud

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

Ten en cuenta que la URL debe estar en minúsculas.

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

URL de Java de ejemplo: 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>

Ten en cuenta que la URL debe estar en minúsculas.

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

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

Paso 3: Descarga los metadatos

Usa los siguientes comandos para descargar los metadatos:

gcloud

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

Para descargar todos los tipos de metadatos, como la información de compilación, la información de estado y la información de VEX, para un paquete y una versión determinados, usa el siguiente comando:

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

Los metadatos se distribuyen en tres archivos ZIP (buildinfo.zip, healthinfo.zip y vexinfo.zip) y se descargan en la carpeta de salida.

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

Paso 4: Extrae los metadatos

Extrae el archivo ZIP. En macOS o Linux, usa el comando unzip: unzip input.zip -d outputFolder. Cada archivo ZIP contiene un archivo JSON y un archivo signature.zip. El archivo JSON contiene los metadatos de seguridad reales y el archivo signature.zip contiene archivos para verificar la firma de Google en el JSON.

Descarga la información de la licencia

La información de la licencia de todos los paquetes de Assured OSS está disponible en un solo archivo JSON. Para descargar este archivo, ejecuta el siguiente 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 descargar la firma del archivo de metadatos de la licencia, ejecuta el siguiente 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

¿Qué sigue?