Metadata management overview

This page introduces key concepts for metadata management and its importance in a secure software delivery chain.

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 is retired. This can be achieved by generating and storing metadata that describes important events about an artifact or a software resource: a container image, a virtual machine, or a software package.

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

How Artifact Analysis stores metadata

Artifact 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 Artifact 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 and specific remediation steps. 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 Artifact 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. Artifact 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 Artifact 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.
Package contains information about the packages installed in your image.
Deployment provides information on image deployment events.
Discovery contains information about the initial scan of images. Artifact 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.
Compliance, which provides information on a compliance check.
DSSE attestation, which describes an attestation that uses the Dead Simple Signing Envelope signature.
Vulnerability assessment stores an uploaded VEX statement in the Grafeas VulnerabilityAssessment note format.
SBOM reference provides additional metadata to help you locate and verify SBOMs.

What's next