Giter Site home page Giter Site logo

netgenius18 / grafeas Goto Github PK

View Code? Open in Web Editor NEW

This project forked from grafeas/grafeas

0.0 3.0 0.0 2.2 MB

Cloud artifact metadata CRUD API and resource specifications

License: Apache License 2.0

Dockerfile 0.11% Makefile 1.24% Go 96.90% ANTLR 1.76%

grafeas's Introduction

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.

Notes

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.

Occurrences

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 Type Identifier Example
Debian deb://dist(optional):arch:name:version deb://lucid:i386:acl:2.2.49-2
Docker https://Namespace/name@sha256: https://gcr.io/scanning-customer/dockerimage@sha256:244fd47e07d1004f0aed9c156aa09083c82bf8944eceb67c946ff7430510a77b
Generic file file://sha256::name file://sha256:244fd47e07d1004f0aed9c156aa09083c82bf8944eceb67c946ff7430510a77b:foo.jar
Maven gav://group:artifact:version gav://ant:ant:1.6.5
NPM npm://package:version npm://mocha:2.4.5
NuGet nuget://module:version nuget://log4net:9.0.1
Python pip://package:version pip://raven:5.13.0
RPM rpm://dist(optional):arch:name:version rpm://el6:i386:ImageMagick:6.7.2.7-4

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.

Kind Note Summary Occurrence Summary
ATTESTATION A logical attestation role or authority, used as an anchor for specific attestations An attestation by an authority for a specific property and resource
BUILD Builder version and signature Details of this specific build, such as inputs and outputs
DEPLOYMENT A resource that can be deployed Details of each deployment of the resource
DISCOVERY Only used as an anchor for specific occurrences Information about the status of an image after the first scan, such as package vulnerability, base image, and package manager info
IMAGE Information about the base image of a container Information about layers included on top of the base image in a particular container
PACKAGE Package descriptions Filesystem locations detailing where the package is installed in a specific resource
VULNERABILITY CVE or vulnerability description and details including severity, versions Affected packages/versions in a specific resource

The API

The authoritative API for grafeas is the protobuf files. We're currently working from master, and have a versioned path as well.

There is a swagger/OpenAPI representation of the API as well, which provides a JSON bridge to the Protobuf API.

Next steps

You can run Grafeas locally following these instructions. Once you have a running server, you can use the client libraries to experiment with creating notes and occurrences in Grafeas. There are client libraries available in Java, Go, Ruby, and Python.

grafeas's People

Contributors

r2wend2 avatar vtsao avatar furuholm avatar shrajfr12 avatar tristonianjones avatar daniel-sanche avatar katee avatar vbatts avatar nenaddedic avatar jonpulsifer avatar pombredanne avatar suteebu avatar skelterjohn avatar arunbsar avatar antweiss avatar bendory avatar kelseyhightower avatar lizrice avatar patricklawsongoogle avatar tejal29 avatar vbehar avatar wteiken avatar

Watchers

James Cloos avatar Heng WU avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.