Aqua Blog

Grafeas and Image Vulnerability Scanning

Grafeas and Image Vulnerability Scanning

A couple of months ago Aqua Security were part of a group of companies supporting the launch of Grafeas, an open source API initially introduced by Google that allows users to manage and query metadata about software artifacts.

At KubeCon I did a joint presentation with Puppet’s Gareth Rushgrove entitled “Kubernetes, metadata and you” which included a demo using Aqua vulnerability scan reports and the Grafeas API to enable powerful queries. If you have ever needed to find out which of your container images include a specific vulnerability, you’ll recognize just how useful this kind of querying can be.

Limitations of Container Metadata Today

As we discussed in our presentation, there are metadata capabilities within Kubernetes itself: labels and annotations, and of course you can apply metadata to container images through the use of labels in Dockerfiles. (As we know, naming things is one of software’s most difficult challenges; “labels” in Kubernetes are not the same thing as “labels” in Docker!).

Dockerfile labels allow you to attach metadata at build time; Kubernetes lets you add metadata to deployed software; but what about all the stages in between build and deployment? There are tools and APIs emerging – like manifesto and Grafeas – that allow you to manage metadata that can change after build, and that relate to container images that might not necessarily be currently deployed.

Vulnerability Reports in Grafeas

An example of this kind of metadata is a vulnerability scan report. Vulnerability scan reports are associated with a particular build of an image, but they can change over time. When a new exploit is discovered, it might be included in one (or more) of your existing container images, so a new scan over the same image can generate a different scan report.

Grafeas supports various types of metadata, associated with various different types of software artifact, but one combination that’s of great interest to us in container security is the ability to associate vulnerability information with container images.

Data in Grafeas is stored in “notes” and “occurrences”.

  • A “note” in Grafeas describes a “thing” – for vulnerability data there is a note for each different vulnerability (as identified by its CVE).
  • An “occurrence” relates to a note, and describes an instance of that “thing” – there would be a separate occurrence for each vulnerability detected in a particular container image.

By storing this information in Grafeas, it opens up the potential for complex queries about the vulnerabilities across a whole project.

Aqua Security Scanning in Grafeas Format

The demo in our talk shows how manifesto and Grafeas can be used together to manage the vulnerability data reported by Aqua’s scanning process.

  • Aqua’s Container Security Platform scans an image, generating a vulnerability report.
  • When the scan completes, the Aqua server triggers a webhook in a “converter” which transforms the Aqua-format vulnerability report into a set of notes and occurrences in Grafeas format.
  • We use the manifesto command-line tool to store these notes and occurrences in a Grafeas server,
  • And then we can query using the Grafeas REST API.

Grafeas and Image Vulnerability Scanning

Here’s a video of the demo in action.

In the demo I used the example Grafeas server that you can build and run locally. There is plenty of functionality not currently implemented in this example, but you can make make queries such as these:

curl localhost:8080/v1alpha1/projects/<project ID>/notes/<CVE ID>/occurrences

This will get a list of all the occurrences of the specified CVE in the project. Each occurrence relates to an image, so this gives us the answer to the question “which images have this particular CVE?”.

Garfeas and image vulnerability scanning

It’s still early days for Grafeas implementations (Google’s own Container Analysis API is in Alpha as I write, and subject to change before it’s rolled out more widely). However, it is a promising standard that has a level of momentum, and that offers the potential for complex metadata queries.

In the meantime, you can already answer the question of which of your containers include a particular CVE using Aqua’s product, as shown in this screenshot.

Containers with a particular CVE


Liz Rice
Liz Rice was the VP of Open Source Engineering at Aqua Security.