You can choose to provide your own metadata to Artifact Analysis to satisfy a specific business need. For example, an organization that provides security management for their customers' Docker containers can use Artifact Analysis to store and retrieve security-related metadata for those images.
Follow the steps below to provide custom vulnerability metadata for your images using the Artifact Analysis API. You can use the same instructions to store and retrieve any kind of metadata that Artifact Analysis supports.
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Enable the Container Analysis API.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Enable the Container Analysis API.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
- Learn how to set up access control for metadata in your project. Skip this step if you only consume metadata from vulnerability occurrences created by Artifact Analysis container scanning.
Create notes and occurrences for projects
This section explains how you can create notes and occurrences. For this example, you will be using the VULNERABILITY
kind.
As a provider, you will create a note in your project for each vulnerability, and you will create an occurrence in your customer's project for an occurrence of that vulnerability.
Create notes
Use the following steps to create a note and give it a note ID.
API
Create a file named
note.json
with vulnerability description and details. The following code shows an examplenote.json
file:{ "shortDescription": "A brief Description of the note", "longDescription": "A longer description of the note", "kind": "VULNERABILITY", "vulnerability": { "details": [ { "affectedPackage": "libexempi3", "affectedCpeUri": "cpe:/o:debian:debian_linux:7", "affectedVersionStart": { "name": "2.5.7", "revision": "1", "kind": "MINIMUM"}, "affectedVersionEnd": { "name": "2.5.9", "revision": "1", "kind": "MINIMUM"}, }, { "affectedCpeUri": "cpe:/o:debian:abc:10", "affectedPackage": "anotherPackage", } ] } }
See the notes API documentation for more information about the notes JSON representation.
Run the following curl command to create a note:
curl -v -H "Content-Type: application/json" -H \ "Authorization: Bearer $(gcloud auth print-access-token)" \ https://containeranalysis.googleapis.com/v1/projects/PROVIDER_PROJECT_ID/notes?note_id=NOTE_ID -d @note.json
Where:
- PROVIDER_PROJECT_ID is your project ID.
- NOTE_ID specifies an identifier for your note. Use a string with a maximum length of 100 characters.
Java
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Java API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Go API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Node.js API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Ruby API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Python API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Create occurrences for the notes
To create occurrences for a note:
API
Create a file named
occurrence.json
with the following contents:{ "resourceUri": "<resource_url>", "noteName": "projects/<provider-project-id>/notes/<note_id>", "kind": "VULNERABILITY", "vulnerability": { "packageIssue": [{ "affectedCpeUri": "cpe:/o:debian_linux:7", "affectedPackage": "packageName", "affectedVersion": { "kind": "NORMAL", "name": "8.1", "revision": "3" }, "fixedCpeUri": "cpe:/o:debian_linux:7", "fixedPackage": "packageName", "fixedVersion": { "kind": "MAXIMUM" } }] "severity": "LOW" } }
Where:
- resource_url is the URL of the resource associated with the
occurrence, for example
https://us-central1-docker.pkg.dev/my-project/my-repository/my-image@sha256:123
. - note_id specifies an identifier for your note. Use a string with a maximum length of 100 characters.
See the occurrences API documentation for more information about the occurrences JSON representation.
- resource_url is the URL of the resource associated with the
occurrence, for example
Run the following curl command where CUSTOMER_PROJECT_ID is your customer's project ID:
curl -v -H "Content-Type: application/json" -H \ "Authorization: Bearer $(gcloud auth print-access-token)" \ https://containeranalysis.googleapis.com/v1/projects/CUSTOMER_PROJECT_ID/occurrences -d @occurrence.json
Java
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Java API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Go API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Node.js API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Ruby API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Python API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Get all occurrences for a specific note
You can view all occurrences of a specific vulnerability across your customer's
projects using notes.occurrences.list()
.
API
To list all the occurrences for a note, send a GET request as follows:
GET https://containeranalysis.googleapis.com/v1/projects/PROJECT_ID/notes/NOTE_ID/occurrences
Refer to the projects.notes.occurrences.list
API endpoint
for complete details.
Java
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Java API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Go API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Node.js API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Ruby API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Artifact Analysis, see Artifact Analysis client libraries. For more information, see the Artifact Analysis Python API reference documentation.
To authenticate to Artifact Analysis, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
What's next
For instructions on how to view and filter notes and occurrences for container images, see Viewing vulnerability occurrences.
For instructions on how to set up notifications, see Pub/Sub notifications.