Accede a los metadatos con la API de Artifact Analysis

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.

Metadatos de seguridad

Artifact Analysis proporciona almacenamiento de metadatos según el modelo de Grafeas de código abierto. Para cada versión del paquete, se proporciona la siguiente información:

Un objeto PackageNote para cada versión del paquete que lanzó Assured OSS. La nota del paquete contiene lo siguiente:
- distribution donde cada distribution corresponde a un artefacto proporcionado por Assured OSS. Incluye la ubicación y el resumen url (desde donde se pueden descargar la firma y el hash) para las fuentes binarias y reproducibles.
- relatedURL que contiene vínculos a metadatos, como la procedencia de la compilación, la certificación de la prueba y las vulnerabilidades.
Es un objeto BuildOccurrence. El vínculo a esta ocurrencia de compilación se proporciona en la sección relatedURL de la nota del paquete junto a la etiqueta BUILD_OCCURRENCE. El intotoStatement en el evento de compilación contiene la procedencia de SLSA v0.2.
Un segundo BuildOccurrenance El vínculo a esta ocurrencia de compilación se proporciona en la sección relatedURL de la nota del paquete junto a la etiqueta ORIGINAL_SOURCE_PROVENANCE. Este archivo contiene los detalles de la fuente original (GitHub) en forma de Source.
Es un AttestationOccurrence. El vínculo a este caso de certificación se proporciona en la sección relatedURL de la nota del paquete junto a la etiqueta TEST_OCCURRENCE. La carga útil serializada en la certificación contiene JSON que representa todas las pruebas de seguridad realizadas en la versión del paquete.
Es un segundo AttestationOccurrence. El vínculo a este caso de certificación se proporciona en la sección relatedURL de la nota del paquete junto a la etiqueta PACKAGE_ATTESTATION_OCCURRENCE. La carga útil serializada en formato JSON en la certificación es la carga útil de la nota del paquete y su firma. Esta certificación se usa para verificar la integridad del contenido de la nota del paquete.
Un objeto VulnerabilityNote y un objeto VulnerabilityOccurrence para cada vulnerabilidad asociada con el paquete. La nota y la ocurrencia combinadas proporcionan información sobre las vulnerabilidades, como el resumen o la descripción de la vulnerabilidad, la gravedad, la puntuación de CVSSV3, la información de la versión afectada y corregida, y la corrección.

Accede a los metadatos de seguridad desde Artifact Analysis

Puedes acceder a los metadatos de seguridad de Artifact Analysis con los clientes de la API de Artifact Analysis, que están disponibles en diferentes lenguajes. Para comenzar a usar las bibliotecas cliente de Cloud para la API de Artifact Analysis, consulta Cómo instalar las bibliotecas cliente de Artifact Analysis requeridas.

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

Paso 1: Configura la autenticación

Configura la autenticación con las credenciales predeterminadas de la aplicación (ADC).

Paso 2: Recupera los metadatos de seguridad

Para recuperar metadatos de seguridad, crea un paquete note_name con la siguiente información:

Project_ID: Es el identificador alfanumérico de tu proyecto de Google Cloud .
Package Language: Java o Python. Debe estar en mayúsculas.
Package_ID: Para Java, es groupId_artifactId y, para Python, es packageName. Este valor distingue mayúsculas de minúsculas. Puedes encontrar el uso de mayúsculas y minúsculas válido para el nombre de la versión del paquete en Cómo enumerar todos los paquetes en Assured OSS.
Version: Es la versión del paquete.

El note_name debe tener la siguiente estructura: projects/<project_id>/notes/<language>-<package_id>-<version>.

Por ejemplo: projects/cloud-aoss/notes/JAVA-org.apache.commons_commons-compress-1.21.

Opción 1:

Si usas las bibliotecas cliente de Container Analysis, usa getNotes con note_name para consultar PackageNote. El PackageNote tiene vínculos a otras notas y ocurrencias.

Opción 2:

Si usas el comando curl, usa el siguiente comando:

curl  -H "Content-Type: application/json" -H   "Authorization: Bearer $(gcloud auth print-access-token)" $URL

En Java, usa la URL https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2.
En Python, usa la URL https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/notes/PYTHON-Flask-Cors-3.0.10.

Metadatos de muestra

{
  "name": "projects/cloud-aoss/notes/JAVA-org.jsoup_jsoup-1.15.2",
  "kind": "PACKAGE",
  "relatedUrl": [
    {
      "url": "projects/cloud-aoss/occurrences/621d7e7b-8e6c-4313-b24b-eae3a1d1b884",
      "label": "ORIGINAL_SOURCE_PROVENANCE"
    },
    {
      "url": "https://containeranalysis.googleapis.com/v1/projects/cloud-aoss/occurrences/a0967d97-634c-4066-b6da-0a723273a165",
      "label": "BUILD_OCCURRENCE"
    },
    {
      "url": "projects/cloud-aoss/occurrences/6005db73-7310-44f9-9a36-6ca0174732a1",
      "label": "TEST_OCCURRENCE"
    },
    {
      "url": "projects/cloud-aoss/notes/GHSA-gp7f-rwcx-9369",
      "label": "VULNERABILITY_GHSA-gp7f-rwcx-9369"
    }
  ],
  "createTime": "2022-10-12T06:48:19.162016Z",
  "updateTime": "2022-10-18T05:31:15.081736Z",
  "package": {
    "distribution": [
      {
        "cpeUri": "cpe:2.3:a:JAVA::org.jsoup:jsoup:1.15.2:*:*:*:*:*:*:*",
        "url": "https://us-maven.pkg.dev/…/org/jsoup/jsoup/1.15.2/jsoup-1.15.2.jar",
        "description": "..."
      },
      {
        "cpeUri": "cpe:2.3:a:JAVA::org.jsoup:jsoup:1.15.2:*:*:*:*:*:*:*",
        "url": "https://us-maven.pkg.dev/…/org/jsoup/jsoup/1.15.2/jsoup-1.15.2-sources.jar",
        "description": "..."
      }
]}}

Usa los nombres de las notas y las ocurrencias proporcionados en el mapa relatedURL para recuperar datos adicionales relacionados con la fuente, la compilación, la prueba y la vulnerabilidad. Para ello, usa las APIs de GetNote y GetOccurrence, o los comandos de curl. En el caso de BUILD_OCCURRENCE, quita el prefijo inicial de https://containeranalysis.googleapis.com/v1/ cuando uses la API. Para otras entidades, usa las URLs directamente como note_name o occurrence_name en el parámetro de la API.

Secuencia de comandos de Python de muestra

En la siguiente ubicación de Cloud Storage, se encuentra disponible un ejemplo de secuencia de comandos de Python que imprime todos los metadatos descargados, junto con su archivo README:

gs://cloud-aoss/utils/python-download-metadata/v1.1

Sigue estos pasos para descargar la secuencia de comandos con Google Cloud CLI:

Configura la autenticación con las credenciales predeterminadas de la aplicación (ADC).
Instala la biblioteca cliente de Container Analysis. Específicamente, este comando debería instalar lo siguiente:
```
pip install google-cloud-containeranalysis
```

Instala los paquetes cloud-kms y cryptography con los siguientes comandos:

pip install --upgrade google-cloud-kms
pip install --upgrade cryptography

Descarga download_metadata.py en tu sistema con el siguiente comando:
```
gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/download_metadata.py
PATH_TO_LOCAL_STORE --recursive
```
Reemplaza PATH_TO_LOCAL_STORE por la ruta de acceso local en la que deseas guardar el archivo.
Descarga el README.md que contiene las instrucciones para usar la secuencia de comandos con el siguiente comando:
```
gcloud storage cp gs://cloud-aoss/utils/python-download-metadata/v1.1/README.md PATH_TO_LOCAL_STORE --recursive
```
Reemplaza PATH_TO_LOCAL_STORE por la ruta de acceso local en la que deseas guardar el archivo.

Comando de muestra

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1'

Para verificar las firmas en los metadatos de Container Analysis, agrega el siguiente comando a la secuencia de comandos:

python ./download_metadata.py -l 'JAVA' -p 'org.apache.logging.log4j:log4j-core' -v '2.17.1' -s`