Accede a los metadatos con Cloud Storage

Assured OSS proporciona metadatos de seguridad para cada paquete disponible. Cada versión del paquete tiene sus propios metadatos. En esta página, se explica qué información se proporciona como parte de los metadatos y cómo puedes acceder a ellos.

Puedes acceder a los metadatos de seguridad con una de las siguientes opciones:

  • API de Artifact Analysis
  • Cloud Storage

Esta página solo se aplica al nivel gratuito.

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 de 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 recompilació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 del paquete.
  • healthinfo.zip: Este archivo contiene detalles sobre las pruebas realizadas en un paquete. Este valor puede cambiar si se modifica el estado de prueba de un paquete. Por ejemplo, si se realiza una nueva prueba de seguridad o si 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 editor del paquete la modifica.

Cada archivo ZIP contiene los siguientes dos archivos:

  • Es 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 fecha y 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: La dirección de correo electrónico de la organización en caso de consultas o reclamos
  • 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 la compilación del paquete en formato SLSA v0.2. Cloud Build genera este valor.
    • 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 al que se adhiere el sistema de compilación.
    • buildTool: 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. Puede tener dos valores:
      • OPEN: Si Assured OSS admite cero o solo dependencias transitivas parciales.
      • CLOSED: Indica 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 URL de GitHub.
    • commitHash: Es la cadena de hash de confirmación adjunta a la versión.
    • tag: Es la etiqueta de 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 fecha y 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 fecha y 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: La dirección de correo electrónico de la organización en caso de consultas o reclamos
  • vexData: Cadena de Vulnerability Exploitability eXchange (VEX) en formato CycloneDX 1.4.

healthInfo.json

  • creationTime: Es la fecha y 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: La dirección de correo electrónico de la organización en caso de consultas o reclamos
  • 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 requirió la prueba para el paquete. Por ejemplo, no se requiere realizar 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 al paquete.

Accede a los metadatos de seguridad de 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. Construye la URL para ambos 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 muestra de 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>

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 muestra de Java: 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, 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 archivo 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?