Grafeas: A Component Metadata API

Grafeas defines an API spec for managing metadata about software resources, such as container images, Virtual Machine (VM) images, JAR files, and scripts. You can use Grafeas to define and aggregate information about your project’s components.

Grafeas divides the metadata information into notes and occurrences. Notes are high-level descriptions of particular types of metadata. Occurrences are instantiations of notes, which describe how and when a given note occurs on the resource associated with the occurrence. This division allows third-party metadata providers to create and manage metadata on behalf of many customers. It also allows for fine-grained access control of different types of metadata.


A note describes a high-level piece of metadata. For example, you could create a note about a particular vulnerability after analyzing a Linux package. You would also use a note to store information about the builder of a build process. Notes are often owned and created by the providers doing the analysis. Notes are generally found via analysis and occur multiple times across different projects.

Note names must follow the format /projects/<project_id>/notes/<note_id>. The note ID must be unique per project, and be as informative as possible. For example, the name of a vulnerability note could be CVE-2013-4869, referencing the CVE it describes.

It’s generally preferable to store notes and occurrences in separate projects, allowing for more fine-grained access control.

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


An occurrence is an instantiation of a note. Occurrences describe project-specific details of a given 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.

Occurrence names should follow the format /projects/<project_id>/occurrences/<occurrence_id>. The occurrence ID must be unique per project and is often random. 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.

Resource URLs

A resource URL is a unique URL for the resource to which a given occurrence applies. Common examples of resources are container images, Virtual Machine (VM) images, or JAR files. Resource URLs must be unique per resource and immutable. This ensures that each occurrence is always associated with exactly one component. If using resources that cannot be made immutable, you must append a timestamp. Where possible, use content-addressable resource URLs.

The following table provides examples of possible resource URLs for several component types:

Component TypeIdentifierExample
Dockerhttps://Namespace/[email protected]:https://gcr.io/scanning-customer/[email protected]:244fd47e07d1004f0aed9c156aa09083c82bf8944eceb67c946ff7430510a77b
Generic filefile://sha256::namefile://sha256:244fd47e07d1004f0aed9c156aa09083c82bf8944eceb67c946ff7430510a77b:foo.jar

Kind-Specific Schemas

Each kind of metadata information has a strict schema. This allows you to normalize data from multiple providers, making it easier to see meaningful insights about your components over time. Defining different kinds of data also makes it easy to expand Grafeas to support new metadata types.

The currently supported kinds are defined below, along with a brief summary of the type of information each kind of note and occurrence contains.

KindNote SummaryOccurrence Summary
ATTESTATIONA logical attestation role or authority, used as an anchor for specific attestationsAn attestation by an authority for a specific property and resource
BUILDBuilder version and signatureDetails of this specific build, such as inputs and outputs
DEPLOYMENTA resource that can be deployedDetails of each deployment of the resource
DISCOVERYOnly used as an anchor for specific occurrencesInformation about the status of an image after the first scan, such as package vulnerability, base image, and package manager info
IMAGEInformation about the base image of a containerInformation about layers included on top of the base image in a particular container
PACKAGEPackage descriptionsFilesystem locations detailing where the package is installed in a specific resource
VULNERABILITYCVE or vulnerability description and details including severity, versionsAffected packages/versions in a specific resource

Next steps

You can run Grafeas locally following these instructions. Once you have a running server, you can use the [client libraries] (https://github.com/grafeas) to experiment with creating notes and occurrences in Grafeas. There are client libraries available in Java, Go, Ruby, and Python.