wtf is grafeas?

Grafeas is an API specification for storing and retrieving metadata about the software components you build and deploy, things like container images, VM images, JAR files, and scripts. Think of it as a structured filing system that keeps track of what's inside your software: known vulnerabilities, build details, what base image was used, deployment history, and more. The core idea revolves around two concepts: notes and occurrences. A note is a general description of something, say, a specific security vulnerability (like a known CVE) or a build tool. An occurrence is a specific instance where that note shows up in one of your actual resources, for example, "this vulnerability was found in this specific container image, and here's how to fix it." This split lets a security vendor maintain a library of notes (the vulnerabilities they know about) and then record occurrences in each customer's project when they find those issues during a scan. This design is useful for teams who need to answer questions like: "Which of our images contain this vulnerability?" or "What went into building this artifact?" A vulnerability scanning provider, for instance, could maintain notes for every CVE they track, then generate occurrences in your project when they scan your containers. You could also track build provenance (what builder produced an image and when), deployment history, or package manager details, all in a normalized, queryable format. Grafeas supports several metadata "kinds" out of the box: package vulnerabilities, build details, image base layers, package manager info, deployment history, and attestations. Each kind has a strict schema so data from different providers stays consistent and comparable. The API also has built-in access control concepts, note owners can keep their notes read-only for others, while occurrence access is limited to those authorized to create links. One practical detail: resource URLs need to be unique and immutable, so metadata always points to exactly one component. The spec recommends content-addressable URLs (like Docker image digests) and provides example URL formats for Debian packages, Maven artifacts, NPM modules, Python pip packages, RPMs, and generic files.