Metadata storage

One of the aspects of a secure supply chain is keeping track of the lifespan of a software artifact. For compliance purposes, this tracking information might need to be available even well after the artifact was retired. This can be achieved by metadata that describes important events about an artifact or a software resource: a container image, a virtual machine, or a software package.

The Container Analysis API allows you to store metadata information associated with a resource, this metadata can be later retrieved to audit your software supply chain.

Overview

Container Analysis is built on top of Grafeas, an open source component metadata API that can work as a centralized source of truth for tracking and enforcing policies. Build, auditing, and compliance tools can use Grafeas to store, query and retrieve comprehensive metadata about software components.

Because Grafeas is open source, you are not locked in to a particular vendor. Grafeas associates metadata using a unique software identifier. It decouples the artifact storage, so you can store metadata about components from many different repositories. The same principles apply to Container Analysis, you can use it as a centralized universal metadata store for software components in Artifact Registry or any other location.

The Grafeas model involves two entities:

  • A provider that creates metadata stored in notes.
  • A customer that identifies if the metadata stored in a note applies to their artifacts. If that's the case, the metadata is represented as an occurrence of a note.

Note

A note describes a high-level piece of metadata. For example, you can create a note about a particular vulnerability for a Linux package. You can also use a note to store information about the builder of a build process. Providers that perform the analysis typically own and create notes. Customers that want to use the metadata can then identify occurrences of notes within their projects.

We recommend that you store notes and occurrences in separate projects, allowing for more fine-grained access control.

Notes must be editable only by the note owner, and read-only for customers who have access to occurrences referencing them.

Occurrence

An occurrence represents when a note was found on a software artifact; it can be thought of as an instantiation of a note. For example, an occurrence of a note about a vulnerability would describe the package that the vulnerability was found in, specific remediation steps, and so on. Alternatively, an occurrence of a note about build details would describe the container images that resulted from a build.

Typically, occurrences are stored in separate projects than those where notes are created. Write access to occurrences should only be granted to users who have access to link a note to the occurrence. Any user can have read access to occurrences.

Supported metadata types

The following table lists the metadata types Container Analysis supports and provides for images in Artifact Registry and Container Registry as notes. Third-party metadata providers can store and retrieve all of the following metadata types for their customers' images.

Metadata type Provided by Container Analysis for Artifact Registry and Container Registry images
Vulnerability, which provides vulnerability information for container images. Yes. Container Analysis obtains the vulnerability information from external sources.
Build, which provides information on build provenance. Yes. Container Analysis provides this information only if you use Cloud Build to build the image.
Deployment, which provides information on image deployment events. No
Image, which is the metadata about the container image, for example, information about the different layers of an image. No
Package, which contains information about the packages installed in your image. No
Attestation, which is the logical role that can attest to the images. Yes. Binary Authorization provides this information.
Discovery, contains information about the initial scan of images. Yes. Container Analysis provides this information only for vulnerability scans.

What's next