Create custom notes and occurrences

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.

Go to project selector

Enable the Container Analysis API.

Enable the 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.

Go to project selector

Enable the Container Analysis API.

Enable the 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 example note.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.

import com.google.cloud.devtools.containeranalysis.v1.ContainerAnalysisClient;
import io.grafeas.v1.GrafeasClient;
import io.grafeas.v1.Note;
import io.grafeas.v1.ProjectName;
import io.grafeas.v1.Version;
import io.grafeas.v1.VulnerabilityNote;
import java.io.IOException;
import java.lang.InterruptedException;


public class CreateNote {

  // Creates and returns a new Note
  public static Note createNote(String noteId, String projectId)
      throws IOException, InterruptedException {
    // String noteId = "my-note";
    // String projectId = "my-project-id";
    final String projectName = ProjectName.format(projectId);


    Note newNote = Note.newBuilder()
        // Associate the Note with the metadata type
        // https://cloud.google.com/container-registry/docs/container-analysis#supported_metadata_types
        // Here, we use the type "vulnerability"
        .setVulnerability(VulnerabilityNote.newBuilder()
            .addDetails(VulnerabilityNote.Detail.newBuilder()
                .setAffectedCpeUri("your-uri-here")
                .setAffectedPackage("your-package-here")
                .setAffectedVersionStart(Version.newBuilder()
                    .setKind(Version.VersionKind.MINIMUM))
                .setAffectedVersionEnd(Version.newBuilder()
                    .setKind(Version.VersionKind.MAXIMUM))))
        .build();

    // Initialize client that will be used to send requests. After completing all of your requests, 
    // call the "close" method on the client to safely clean up any remaining background resources.
    GrafeasClient client = ContainerAnalysisClient.create().getGrafeasClient();
    Note result = client.createNote(projectName, noteId, newNote);
    return result;
  }
}

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.


import (
	"context"
	"fmt"

	containeranalysis "cloud.google.com/go/containeranalysis/apiv1"
	grafeaspb "google.golang.org/genproto/googleapis/grafeas/v1"
)

// createNote creates and returns a new vulnerability Note.
func createNote(noteID, projectID string) (*grafeaspb.Note, error) {
	ctx := context.Background()
	client, err := containeranalysis.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	projectName := fmt.Sprintf("projects/%s", projectID)

	req := &grafeaspb.CreateNoteRequest{
		Parent: projectName,
		NoteId: noteID,
		Note: &grafeaspb.Note{
			Type: &grafeaspb.Note_Vulnerability{
				// The 'Vulnerability' field can be modified to contain information about your vulnerability.
				Vulnerability: &grafeaspb.VulnerabilityNote{
					Details: []*grafeaspb.VulnerabilityNote_Detail{
						{
							AffectedCpeUri:  "your-uri-here",
							AffectedPackage: "your-package-here",
							AffectedVersionStart: &grafeaspb.Version{
								Kind: grafeaspb.Version_MINIMUM,
							},
							AffectedVersionEnd: &grafeaspb.Version{
								Kind: grafeaspb.Version_MAXIMUM,
							},
						},
					},
				},
			},
		},
	}

	return client.GetGrafeasClient().CreateNote(ctx, req)
}

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.

/**
 * TODO(developer): Uncomment these variables before running the sample
 */
// const projectId = 'your-project-id', // Your GCP Project ID
// const noteId = 'my-note-id' // Id of the note

// Import the library and create a client
const {ContainerAnalysisClient} = require('@google-cloud/containeranalysis');
const client = new ContainerAnalysisClient();

// Construct request
// Associate the Note with a metadata type
// https://cloud.google.com/container-registry/docs/container-analysis#supported_metadata_types
// Here, we use the type "vulnerabiltity"
const formattedParent = client.getGrafeasClient().projectPath(projectId);

// Creates and returns a new Note
const [note] = await client.getGrafeasClient().createNote({
  parent: formattedParent,
  noteId: noteId,
  note: {
    vulnerability: {
      details: [
        {
          affectedCpeUri: 'foo.uri',
          affectedPackage: 'foo',
          affectedVersionStart: {
            kind: 'MINIMUM',
          },
          affectedVersionEnd: {
            kind: 'MAXIMUM',
          },
        },
      ],
    },
  },
});

console.log(`Note ${note.name} created.`);

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.

# note_id    = "A user-specified identifier for the note"
# project_id = "Your Google Cloud project ID"

require "google/cloud/container_analysis"

# Initialize the client
client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client

parent = client.project_path project: project_id
note = {
  vulnerability: {
    details: [
      {
        affected_cpe_uri:       "your-uri-here",
        affected_package:       "your-package-here",
        affected_version_start: { kind: :MINIMUM },
        fixed_version:          { kind: :MAXIMUM }
      }
    ]
  }
}
response = client.create_note parent: parent, note_id: note_id, note: note
puts response.name

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.

from google.cloud.devtools import containeranalysis_v1
from grafeas.grafeas_v1 import types, Version


def create_note(note_id: str, project_id: str) -> types.grafeas.Note:
    """Creates and returns a new vulnerability note."""
    # note_id = 'my-note'
    # project_id = 'my-gcp-project'

    client = containeranalysis_v1.ContainerAnalysisClient()
    grafeas_client = client.get_grafeas_client()
    project_name = f"projects/{project_id}"
    note = {
        "vulnerability": {
            "details": [
                {
                    "affected_cpe_uri": "your-uri-here",
                    "affected_package": "your-package-here",
                    "affected_version_start": {"kind": Version.VersionKind.MINIMUM},
                    "fixed_version": {"kind": Version.VersionKind.MAXIMUM},
                }
            ]
        }
    }
    response = grafeas_client.create_note(
        parent=project_name, note_id=note_id, note=note
    )
    return response

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.

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.

import com.google.cloud.devtools.containeranalysis.v1.ContainerAnalysisClient;
import io.grafeas.v1.GrafeasClient;
import io.grafeas.v1.NoteName;
import io.grafeas.v1.Occurrence;
import io.grafeas.v1.ProjectName;
import io.grafeas.v1.Version;
import io.grafeas.v1.VulnerabilityOccurrence;
import io.grafeas.v1.VulnerabilityOccurrence.PackageIssue;
import java.io.IOException;
import java.lang.InterruptedException;

public class CreateOccurrence {
  // Creates and returns a new vulnerability Occurrence associated with an existing Note
  public static Occurrence createOccurrence(String resourceUrl, String noteId, 
      String occProjectId, String noteProjectId) throws IOException, InterruptedException {
    // String resourceUrl = "https://gcr.io/project/image@sha256:123";
    // String noteId = "my-note";
    // String occProjectId = "my-project-id";
    // String noteProjectId = "my-project-id";
    final NoteName noteName = NoteName.of(noteProjectId, noteId);
    final String occProjectName = ProjectName.format(occProjectId);

    Occurrence newOcc = Occurrence.newBuilder()
        .setNoteName(noteName.toString())
        .setResourceUri(resourceUrl)
        .setVulnerability(VulnerabilityOccurrence.newBuilder()
            .addPackageIssue(PackageIssue.newBuilder()
                .setAffectedCpeUri("your-uri-here")
                .setAffectedPackage("your-package-here")
                .setAffectedVersion(Version.newBuilder()
                    .setKind(Version.VersionKind.MINIMUM))
                .setFixedVersion(Version.newBuilder()
                    .setKind(Version.VersionKind.MAXIMUM))))
        .build();

    // Initialize client that will be used to send requests. After completing all of your requests, 
    // call the "close" method on the client to safely clean up any remaining background resources.
    GrafeasClient client = ContainerAnalysisClient.create().getGrafeasClient();
    Occurrence result = client.createOccurrence(occProjectName, newOcc);
    return result;
  }
}

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.


import (
	"context"
	"fmt"

	containeranalysis "cloud.google.com/go/containeranalysis/apiv1"
	grafeaspb "google.golang.org/genproto/googleapis/grafeas/v1"
)

// createsOccurrence creates and returns a new Occurrence of a previously created vulnerability Note.
func createOccurrence(resourceURL, noteID, occProjectID, noteProjectID string) (*grafeaspb.Occurrence, error) {
	// Use this style of URL when you use Google Container Registry.
	// resourceURL := "https://gcr.io/my-project/my-repo/my-image"
	// Use this style of URL when you use Google Artifact Registry.
	// resourceURL := "https://LOCATION-docker.pkg.dev/my-project/my-repo/my-image"
	// noteID := "my-note"
	ctx := context.Background()
	client, err := containeranalysis.NewClient(ctx)
	if err != nil {
		return nil, fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	req := &grafeaspb.CreateOccurrenceRequest{
		Parent: fmt.Sprintf("projects/%s", occProjectID),
		Occurrence: &grafeaspb.Occurrence{
			NoteName: fmt.Sprintf("projects/%s/notes/%s", noteProjectID, noteID),
			// Attach the occurrence to the associated resource uri.
			ResourceUri: resourceURL,
			// Details about the vulnerability instance can be added here.
			Details: &grafeaspb.Occurrence_Vulnerability{
				Vulnerability: &grafeaspb.VulnerabilityOccurrence{
					PackageIssue: []*grafeaspb.VulnerabilityOccurrence_PackageIssue{
						{
							AffectedCpeUri:  "your-uri-here",
							AffectedPackage: "your-package-here",
							AffectedVersion: &grafeaspb.Version{
								Kind: grafeaspb.Version_MINIMUM,
							},
							FixedVersion: &grafeaspb.Version{
								Kind: grafeaspb.Version_MAXIMUM,
							},
						},
					},
				},
			},
		},
	}
	return client.GetGrafeasClient().CreateOccurrence(ctx, req)
}

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.

/**
 * TODO(developer): Uncomment these variables before running the sample
 */
// const noteProjectId = 'your-project-id', // Your GCP Project Id
// const noteId = 'my-note-id', // Id of the note
// const occurrenceProjectId = 'your-project-id', // GCP Project Id of Occurrence
// If you are using Google Container Registry
// const imageUrl = 'https://gcr.io/my-project/my-repo/my-image:123' // Image to attach metadata to
// If you are using Google Artifact Registry
// const imageUrl = 'https://LOCATION-docker.pkg.dev/my-project/my-repo/my-image:123' // Image to attach metadata to

// Import the library and create a client
const {ContainerAnalysisClient} = require('@google-cloud/containeranalysis');
const client = new ContainerAnalysisClient();

// Construct request
const formattedParent = client
  .getGrafeasClient()
  .projectPath(occurrenceProjectId);
const formattedNote = client
  .getGrafeasClient()
  .notePath(noteProjectId, noteId);

// Creates and returns a new Occurrence associated with an existing Note
const [occurrence] = await client.getGrafeasClient().createOccurrence({
  parent: formattedParent,
  occurrence: {
    noteName: formattedNote,
    resourceUri: imageUrl,
    vulnerability: {
      packageIssue: [
        {
          affectedCpeUri: 'foo.uri',
          affectedPackage: 'foo',
          affectedVersion: {
            kind: 'MINIMUM',
          },
          fixedVersion: {
            kind: 'MAXIMUM',
          },
        },
      ],
    },
  },
});
console.log(`Occurrence created ${occurrence.name}.`);
return occurrence;

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.

# resource_url       = "The URL of the resource associated with the occurrence."
#                      # If you are using Google Container Registry
#                      # e.g. https://gcr.io/project/repo/image@sha256:123
#                      # If you are using Google Artifact Registry
#                      # e.g. https://LOCATION-docker.pkg.dev/project/repo/image@sha256:123
# note_id            = "The identifier of the note associated with the occurrence"
# occurrence_project = "The Google Cloud project ID for the new occurrence"
# note_project       = "The Google Cloud project ID of the associated note"

require "google/cloud/container_analysis"

# Initialize the client
client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client
note_path = client.note_path project: note_project, note: note_id
project_path = client.project_path project: occurrence_project

occurrence = {
  note_name:     note_path,
  resource_uri:  resource_url,
  vulnerability: {
    package_issue: [
      {
        affected_cpe_uri: "your-uri-here:",
        affected_package: "your-package-here",
        affected_version: { kind: :MINIMUM },
        fixed_version:    { kind: :MAXIMUM }
      }
    ]
  }
}

response = client.create_occurrence parent: project_path, occurrence: occurrence
puts response.name

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.

from google.cloud.devtools import containeranalysis_v1
from grafeas.grafeas_v1 import types, Version


def create_occurrence(
    resource_url: str, note_id: str, occurrence_project: str, note_project: str
) -> types.grafeas.Occurrence:
    """Creates and returns a new occurrence of a previously
    created vulnerability note."""
    # resource_url = 'https://gcr.io/my-project/my-image@sha256:123'
    # note_id = 'my-note'
    # occurrence_project = 'my-gcp-project'
    # note_project = 'my-gcp-project'

    client = containeranalysis_v1.ContainerAnalysisClient()
    grafeas_client = client.get_grafeas_client()
    formatted_note = f"projects/{note_project}/notes/{note_id}"
    formatted_project = f"projects/{occurrence_project}"

    occurrence = {
        "note_name": formatted_note,
        "resource_uri": resource_url,
        "vulnerability": {
            "package_issue": [
                {
                    "affected_cpe_uri": "your-uri-here",
                    "affected_package": "your-package-here",
                    "affected_version": {"kind": Version.VersionKind.MINIMUM},
                    "fixed_version": {"kind": Version.VersionKind.MAXIMUM},
                }
            ]
        },
    }

    return grafeas_client.create_occurrence(
        parent=formatted_project, occurrence=occurrence
    )

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.

import static java.lang.Thread.sleep;

import com.google.cloud.devtools.containeranalysis.v1.ContainerAnalysisClient;
import io.grafeas.v1.GrafeasClient;
import io.grafeas.v1.ListNoteOccurrencesRequest;
import io.grafeas.v1.NoteName;
import io.grafeas.v1.Occurrence;
import java.io.IOException;
import java.lang.InterruptedException;

public class OccurrencesForNote {  
  // Retrieves all the Occurrences associated with a specified Note
  // Here, all Occurrences are printed and counted
  public static int getOccurrencesForNote(String noteId, String projectId) 
      throws IOException, InterruptedException {
    // String noteId = "my-note";
    // String projectId = "my-project-id";
    final NoteName noteName = NoteName.of(projectId, noteId);

    ListNoteOccurrencesRequest request = ListNoteOccurrencesRequest.newBuilder()
                                                                   .setName(noteName.toString())
                                                                   .build();

    // Initialize client that will be used to send requests. After completing all of your requests, 
    // call the "close" method on the client to safely clean up any remaining background resources.
    GrafeasClient client = ContainerAnalysisClient.create().getGrafeasClient();
    int i = 0;
    for (Occurrence o : client.listNoteOccurrences(request).iterateAll()) {
      // Write custom code to process each Occurrence here
      System.out.println(o.getName());
      i = i + 1;
    }
    return i;
  }
}

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.


import (
	"context"
	"fmt"
	"io"

	containeranalysis "cloud.google.com/go/containeranalysis/apiv1"
	"google.golang.org/api/iterator"
	grafeaspb "google.golang.org/genproto/googleapis/grafeas/v1"
)

// getOccurrencesForNote retrieves all the Occurrences associated with a specified Note.
// Here, all Occurrences are printed and counted.
func getOccurrencesForNote(w io.Writer, noteID, projectID string) (int, error) {
	// noteID := fmt.Sprintf("my-note")
	ctx := context.Background()
	client, err := containeranalysis.NewClient(ctx)
	if err != nil {
		return -1, fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	req := &grafeaspb.ListNoteOccurrencesRequest{
		Name: fmt.Sprintf("projects/%s/notes/%s", projectID, noteID),
	}
	it := client.GetGrafeasClient().ListNoteOccurrences(ctx, req)
	count := 0
	for {
		occ, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return -1, fmt.Errorf("occurrence iteration error: %w", err)
		}
		// Write custom code to process each Occurrence here.
		fmt.Fprintln(w, occ)
		count = count + 1
	}
	return count, nil
}

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.

/**
 * TODO(developer): Uncomment these variables before running the sample
 */
// const projectId = 'your-project-id', // Your GCP Project ID
// const noteId = 'my-note-id' // Id of the note

// Import the library and create a client
const {ContainerAnalysisClient} = require('@google-cloud/containeranalysis');
const client = new ContainerAnalysisClient();

// Get path to Note
const formattedNote = client.notePath(projectId, noteId);

// Retrieves all the Occurrences associated with a specified Note
const [occurrences] = await client.getGrafeasClient().listNoteOccurrences({
  name: formattedNote,
});

if (occurrences.length) {
  console.log('Occurrences:');
  occurrences.forEach(occurrence => {
    console.log(`${occurrence.name}:`);
  });
} else {
  console.log('No occurrences found.');
}

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.

  # note_id    = "The identifier for the note to query"
  # project_id = "The Google Cloud project ID of the occurrences to retrieve"

  require "google/cloud/container_analysis"

  # Initialize the client
  client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client

  name = client.note_path project: project_id, note: note_id
  count = 0
  client.list_note_occurrences(name: name).each do |occurrence|
    # Process occurrence here
    puts occurrence
    count += 1
  end
  puts "Found #{count} occurrences"
  count
end

def get_discovery_info resource_url:, project_id:
  # resource_url = "The URL of the resource associated with the occurrence."
  #                # e.g. https://gcr.io/project/image@sha256:123
  # project_id   = "The Google Cloud project ID of the occurrences to retrieve"

  require "google/cloud/container_analysis"

  # Initialize the client
  client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client

  parent = client.project_path project: project_id
  filter = "kind = \"DISCOVERY\" AND resourceUrl = \"#{resource_url}\""
  client.list_occurrences(parent: parent, filter: filter).each do |occurrence|
    # Process discovery occurrence here
    puts occurrence
  end
end

def occurrence_pubsub subscription_id:, timeout_seconds:, project_id:
  # subscription_id = "A user-specified identifier for the new subscription"
  # timeout_seconds = "The number of seconds to listen for new Pub/Sub messages"
  # project_id      = "Your Google Cloud project ID"

  require "google/cloud/pubsub"

  pubsub = Google::Cloud::Pubsub.new project: project_id
  topic = pubsub.topic "container-analysis-occurrences-v1"
  subscription = topic.subscribe subscription_id

  count = 0
  subscriber = subscription.listen do |received_message|
    count += 1
    # Process incoming occurrence here
    puts "Message #{count}: #{received_message.data}"
    received_message.acknowledge!
  end
  subscriber.start
  # Wait for incomming occurrences
  sleep timeout_seconds
  subscriber.stop.wait!
  subscription.delete
  # Print and return the total number of Pub/Sub messages received
  puts "Total Messages Received: #{count}"
  count
end

# rubocop:disable Metrics/MethodLength

def poll_discovery_finished resource_url:, timeout_seconds:, project_id:
  # resource_url    = "The URL of the resource associated with the occurrence."
  #                   # e.g. https://gcr.io/project/image@sha256:123
  # timeout_seconds = "The number of seconds to wait for the discovery occurrence"
  # project_id      = "Your Google Cloud project ID"

  require "google/cloud/container_analysis"

  deadline = Time.now + timeout_seconds

  # Initialize the client
  client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client
  parent = client.project_path project: project_id

  # Find the discovery occurrence using a filter string
  discovery_occurrence = nil
  while discovery_occurrence.nil?
    begin
      filter = "resourceUrl=\"#{resource_url}\" " \
               'AND noteProjectId="goog-analysis" ' \
               'AND noteId="PACKAGE_VULNERABILITY"'
      # The above filter isn't testable, since it looks for occurrences in a
      # locked down project. Fall back to a more permissive filter for testing
      filter = "kind = \"DISCOVERY\" AND resourceUrl = \"#{resource_url}\""
      # Only the discovery occurrence should be returned for the given filter
      discovery_occurrence = client.list_occurrences(parent: parent, filter: filter).first
    rescue StandardError # If there is an error, keep trying until the deadline
      puts "discovery occurrence not yet found"
    ensure
      # check for timeout
      sleep 1
      raise "Timeout while retrieving discovery occurrence." if Time.now > deadline
    end
  end

  # Wait for the discovery occurrence to enter a terminal state
  status = Grafeas::V1::DiscoveryOccurrence::AnalysisStatus::PENDING
  until [:FINISHED_SUCCESS, :FINISHED_FAILED, :FINISHED_UNSUPPORTED].include? status
    # Update occurrence
    begin
      updated = client.get_occurrence name: discovery_occurrence.name
      status = updated.discovery.analysis_status
    rescue StandardError # If there is an error, keep trying until the deadline
      puts "discovery occurrence not yet in terminal state"
    ensure
      # check for timeout
      sleep 1
      raise "Timeout while retrieving discovery occurrence." if Time.now > deadline
    end
  end
  puts "Found discovery occurrence #{updated.name}."
  puts "Status: #{updated.discovery.analysis_status}"
  updated
end

# rubocop:enable Metrics/MethodLength

def find_vulnerabilities_for_image resource_url:, project_id:
  # resource_url = "The URL of the resource associated with the occurrence
  #                e.g. https://gcr.io/project/image@sha256:123"
  # project_id   = "The Google Cloud project ID of the vulnerabilities to find"

  require "google/cloud/container_analysis"

  # Initialize the client
  client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client

  parent = client.project_path project: project_id
  filter = "resourceUrl = \"#{resource_url}\" AND kind = \"VULNERABILITY\""
  client.list_occurrences parent: parent, filter: filter
end

def find_high_severity_vulnerabilities_for_image resource_url:, project_id:
  # resource_url       = "The URL of the resource associated with the occurrence."
  #                      # If you are using Google Container Registry
  #                      # e.g. https://gcr.io/project/repo/image@sha256:123
  #                      # If you are using Google Artifact Registry
  #                      # e.g. https://LOCATION-docker.pkg.dev/project/repo/image@sha256:123
  # project_id   = "The Google Cloud project ID of the vulnerabilities to find"

  require "google/cloud/container_analysis"

  # Initialize the client
  client = Google::Cloud::ContainerAnalysis.container_analysis.grafeas_client

  parent = client.project_path project: project_id
  filter = "resourceUrl = \"#{resource_url}\" AND kind = \"VULNERABILITY\""
  vulnerability_list = client.list_occurrences parent: parent, filter: filter
  # Filter the list to include only "high" and "critical" vulnerabilities
  vulnerability_list.select do |item|
    [:HIGH, :CRITICAL].include? item.vulnerability.effective_severity
  end
end

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.

from google.cloud.devtools import containeranalysis_v1


def get_occurrences_for_note(note_id: str, project_id: str) -> int:
    """Retrieves all the occurrences associated with a specified Note.
    Here, all occurrences are printed and counted."""
    # note_id = 'my-note'
    # project_id = 'my-gcp-project'

    client = containeranalysis_v1.ContainerAnalysisClient()
    grafeas_client = client.get_grafeas_client()
    note_name = f"projects/{project_id}/notes/{note_id}"

    response = grafeas_client.list_note_occurrences(name=note_name)
    count = 0
    for o in response:
        # do something with the retrieved occurrence
        # in this sample, we will simply count each one
        count += 1
    return count

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.