Metadata storage

Stay organized with collections Save and categorize content based on your preferences.

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 that Container Analysis supports. Third-party metadata providers can store and retrieve all of the following metadata types for their customers' images.

Metadata type Usage in Google Cloud services
Vulnerability provides vulnerability information for audited files. Container Analysis generates vulnerability occurrences based on external databases of publicly disclosed security issues.
Build provides information on build provenance. Cloud Build generates this metadata and Container Analysis stores the information if you use Cloud Build to build the image.
Image is the metadata about the container image, for example, information about the different layers of an image. Supported
Package contains information about the packages installed in your image. Supported
Deployment provides information on image deployment events. Supported
Discovery contains information about the initial scan of images. Container Analysis provides this information only for vulnerability scans.
Attestation contains image certification information. Yes. Binary Authorization reads this information and can use it to gate deployments.
Upgrade, which describes a package upgrade that is available. Supported
Compliance, which provides information on a compliance check. Supported
DSSE attestation, which describes an attestation that uses the Dead Simple Signing Envelope signature. Supported

What's next