v1beta1/grafeas/grafeas.proto

// Copyright 2018 The Grafeas Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package grafeas.v1beta1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/devtools/containeranalysis/v1beta1/attestation/attestation.proto";
import "google/devtools/containeranalysis/v1beta1/build/build.proto";
import "google/devtools/containeranalysis/v1beta1/common/common.proto";
import "google/devtools/containeranalysis/v1beta1/deployment/deployment.proto";
import "google/devtools/containeranalysis/v1beta1/discovery/discovery.proto";
import "google/devtools/containeranalysis/v1beta1/image/image.proto";
import "google/devtools/containeranalysis/v1beta1/package/package.proto";
import "google/devtools/containeranalysis/v1beta1/provenance/provenance.proto";
import "google/devtools/containeranalysis/v1beta1/vulnerability/vulnerability.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option go_package = "google.golang.org/genproto/googleapis/devtools/containeranalysis/v1beta1/grafeas;grafeas";
option java_multiple_files = true;
option java_package = "io.grafeas.v1beta1";
option objc_class_prefix = "GRA";

// [Grafeas](grafeas.io) API.
//
// Retrieves analysis results of Cloud components such as Docker container
// images.
//
// Analysis results are stored as a series of occurrences. An `Occurrence`
// contains information about a specific analysis instance on a resource. An
// occurrence refers to a `Note`. A note contains details describing the
// analysis and is generally stored in a separate project, called a `Provider`.
// Multiple occurrences can refer to the same note.
//
// For example, an SSL vulnerability could affect multiple images. In this case,
// there would be one note for the vulnerability and an occurrence for each
// image with the vulnerability referring to that note.
service GrafeasV1Beta1 {
  option (google.api.default_host) = "containeranalysis.googleapis.com";
  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";

  // Gets the specified occurrence.
  rpc GetOccurrence(GetOccurrenceRequest) returns (Occurrence) {
    option (google.api.http) = {
      get: "/v1beta1/{name=projects/*/occurrences/*}"
    };
  }

  // Lists occurrences for the specified project.
  rpc ListOccurrences(ListOccurrencesRequest)
      returns (ListOccurrencesResponse) {
    option (google.api.http) = {
      get: "/v1beta1/{parent=projects/*}/occurrences"
    };
  }

  // Deletes the specified occurrence. For example, use this method to delete an
  // occurrence when the occurrence is no longer applicable for the given
  // resource.
  rpc DeleteOccurrence(DeleteOccurrenceRequest)
      returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1beta1/{name=projects/*/occurrences/*}"
    };
  }

  // Creates a new occurrence.
  rpc CreateOccurrence(CreateOccurrenceRequest) returns (Occurrence) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*}/occurrences"
      body: "occurrence"
    };
  }

  // Creates new occurrences in batch.
  rpc BatchCreateOccurrences(BatchCreateOccurrencesRequest)
      returns (BatchCreateOccurrencesResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*}/occurrences:batchCreate"
      body: "*"
    };
  }

  // Updates the specified occurrence.
  rpc UpdateOccurrence(UpdateOccurrenceRequest) returns (Occurrence) {
    option (google.api.http) = {
      patch: "/v1beta1/{name=projects/*/occurrences/*}"
      body: "occurrence"
    };
  }

  // Gets the note attached to the specified occurrence. Consumer projects can
  // use this method to get a note that belongs to a provider project.
  rpc GetOccurrenceNote(GetOccurrenceNoteRequest) returns (Note) {
    option (google.api.http) = {
      get: "/v1beta1/{name=projects/*/occurrences/*}/notes"
    };
  }

  // Gets the specified note.
  rpc GetNote(GetNoteRequest) returns (Note) {
    option (google.api.http) = {
      get: "/v1beta1/{name=projects/*/notes/*}"
    };
  }

  // Lists notes for the specified project.
  rpc ListNotes(ListNotesRequest) returns (ListNotesResponse) {
    option (google.api.http) = {
      get: "/v1beta1/{parent=projects/*}/notes"
    };
  }

  // Deletes the specified note.
  rpc DeleteNote(DeleteNoteRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v1beta1/{name=projects/*/notes/*}"
    };
  }

  // Creates a new note.
  rpc CreateNote(CreateNoteRequest) returns (Note) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*}/notes"
      body: "note"
    };
  }

  // Creates new notes in batch.
  rpc BatchCreateNotes(BatchCreateNotesRequest)
      returns (BatchCreateNotesResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*}/notes:batchCreate"
      body: "*"
    };
  }

  // Updates the specified note.
  rpc UpdateNote(UpdateNoteRequest) returns (Note) {
    option (google.api.http) = {
      patch: "/v1beta1/{name=projects/*/notes/*}"
      body: "note"
    };
  }

  // Lists occurrences referencing the specified note. Provider projects can use
  // this method to get all occurrences across consumer projects referencing the
  // specified note.
  rpc ListNoteOccurrences(ListNoteOccurrencesRequest)
      returns (ListNoteOccurrencesResponse) {
    option (google.api.http) = {
      get: "/v1beta1/{name=projects/*/notes/*}/occurrences"
    };
  }

  // Gets a summary of the number and severity of occurrences.
  rpc GetVulnerabilityOccurrencesSummary(
      GetVulnerabilityOccurrencesSummaryRequest)
      returns (VulnerabilityOccurrencesSummary) {
    option (google.api.http) = {
      get: "/v1beta1/{parent=projects/*}/occurrences:vulnerabilitySummary"
    };
  }
}

// An instance of an analysis type that has been found on a resource.
message Occurrence {
  // Output only. The name of the occurrence in the form of
  // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`.
  string name = 1;

  // Required. Immutable. The resource for which the occurrence applies.
  Resource resource = 2;

  // Required. Immutable. The analysis note associated with this occurrence, in
  // the form of `projects/[PROVIDER_ID]/notes/[NOTE_ID]`. This field can be
  // used as a filter in list requests.
  string note_name = 3;

  // Output only. This explicitly denotes which of the occurrence details are
  // specified. This field can be used as a filter in list requests.
  grafeas.v1beta1.NoteKind kind = 4;

  // A description of actions that can be taken to remedy the note.
  string remediation = 5;

  // Output only. The time this occurrence was created.
  google.protobuf.Timestamp create_time = 6;

  // Output only. The time this occurrence was last updated.
  google.protobuf.Timestamp update_time = 7;

  // Required. Immutable. Describes the details of the note kind found on this
  // resource.
  oneof details {
    // Describes a security vulnerability.
    grafeas.v1beta1.vulnerability.Details vulnerability = 8;
    // Describes a verifiable build.
    grafeas.v1beta1.build.Details build = 9;
    // Describes how this resource derives from the basis in the associated
    // note.
    grafeas.v1beta1.image.Details derived_image = 10;
    // Describes the installation of a package on the linked resource.
    grafeas.v1beta1.package.Details installation = 11;
    // Describes the deployment of an artifact on a runtime.
    grafeas.v1beta1.deployment.Details deployment = 12;
    // Describes when a resource was discovered.
    grafeas.v1beta1.discovery.Details discovered = 13;
    // Describes an attestation of an artifact.
    grafeas.v1beta1.attestation.Details attestation = 14;
  }

  // next_id = 15;
}

// An entity that can have metadata. For example, a Docker image.
message Resource {
  // The name of the resource. For example, the name of a Docker image -
  // "Debian".
  string name = 1;
  // Required. The unique URI of the resource. For example,
  // `https://gcr.io/project/image@sha256:foo` for a Docker image.
  string uri = 2;
  // The hash of the resource content. For example, the Docker digest.
  grafeas.v1beta1.provenance.Hash content_hash = 3;

  // next_id = 4;
}

// A type of analysis that can be done for a resource.
message Note {
  // Output only. The name of the note in the form of
  // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`.
  string name = 1;

  // A one sentence description of this note.
  string short_description = 2;

  // A detailed description of this note.
  string long_description = 3;

  // Output only. The type of analysis. This field can be used as a filter in
  // list requests.
  grafeas.v1beta1.NoteKind kind = 4;

  // URLs associated with this note.
  repeated grafeas.v1beta1.RelatedUrl related_url = 5;

  // Time of expiration for this note. Empty if note does not expire.
  google.protobuf.Timestamp expiration_time = 6;

  // Output only. The time this note was created. This field can be used as a
  // filter in list requests.
  google.protobuf.Timestamp create_time = 7;

  // Output only. The time this note was last updated. This field can be used as
  // a filter in list requests.
  google.protobuf.Timestamp update_time = 8;

  // Other notes related to this note.
  repeated string related_note_names = 9;

  // Required. Immutable. The type of analysis this note represents.
  oneof type {
    // A note describing a package vulnerability.
    grafeas.v1beta1.vulnerability.Vulnerability vulnerability = 10;
    // A note describing build provenance for a verifiable build.
    grafeas.v1beta1.build.Build build = 11;
    // A note describing a base image.
    grafeas.v1beta1.image.Basis base_image = 12;
    // A note describing a package hosted by various package managers.
    grafeas.v1beta1.package.Package package = 13;
    // A note describing something that can be deployed.
    grafeas.v1beta1.deployment.Deployable deployable = 14;
    // A note describing the initial analysis of a resource.
    grafeas.v1beta1.discovery.Discovery discovery = 15;
    // A note describing an attestation role.
    grafeas.v1beta1.attestation.Authority attestation_authority = 16;
  }

  // next_id = 17;
}

// Request to get an occurrence.
message GetOccurrenceRequest {
  // The name of the occurrence in the form of
  // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`.
  string name = 1;
}

// Request to list occurrences.
message ListOccurrencesRequest {
  // The name of the project to list occurrences for in the form of
  // `projects/[PROJECT_ID]`.
  string parent = 1;

  // The filter expression.
  string filter = 2;

  // Number of occurrences to return in the list.
  int32 page_size = 3;

  // Token to provide to skip to a particular spot in the list.
  string page_token = 4;

  // next_id = 7;
}

// Response for listing occurrences.
message ListOccurrencesResponse {
  // The occurrences requested.
  repeated Occurrence occurrences = 1;
  // The next pagination token in the list response. It should be used as
  // `page_token` for the following request. An empty value means no more
  // results.
  string next_page_token = 2;
}

// Request to delete a occurrence.
message DeleteOccurrenceRequest {
  // The name of the occurrence in the form of
  // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`.
  string name = 1;
}

// Request to create a new occurrence.
message CreateOccurrenceRequest {
  // The name of the project in the form of `projects/[PROJECT_ID]`, under which
  // the occurrence is to be created.
  string parent = 1;
  // The occurrence to create.
  Occurrence occurrence = 2;
}

// Request to update an occurrence.
message UpdateOccurrenceRequest {
  // The name of the occurrence in the form of
  // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`.
  string name = 1;
  // The updated occurrence.
  Occurrence occurrence = 2;
  // The fields to update.
  google.protobuf.FieldMask update_mask = 3;
}

// Request to get a note.
message GetNoteRequest {
  // The name of the note in the form of
  // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`.
  string name = 1;
}

// Request to get the note to which the specified occurrence is attached.
message GetOccurrenceNoteRequest {
  // The name of the occurrence in the form of
  // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`.
  string name = 1;
}

// Request to list notes.
message ListNotesRequest {
  // The name of the project to list notes for in the form of
  // `projects/[PROJECT_ID]`.
  string parent = 1;
  // The filter expression.
  string filter = 2;
  // Number of notes to return in the list.
  int32 page_size = 3;
  // Token to provide to skip to a particular spot in the list.
  string page_token = 4;
}

// Response for listing notes.
message ListNotesResponse {
  // The notes requested.
  repeated Note notes = 1;
  // The next pagination token in the list response. It should be used as
  // `page_token` for the following request. An empty value means no more
  // results.
  string next_page_token = 2;
}

// Request to delete a note.
message DeleteNoteRequest {
  // The name of the note in the form of
  // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`.
  string name = 1;
}

// Request to create a new note.
message CreateNoteRequest {
  // The name of the project in the form of `projects/[PROJECT_ID]`, under which
  // the note is to be created.
  string parent = 1;
  // The ID to use for this note.
  string note_id = 2;
  // The note to create.
  Note note = 3;
}

// Request to update a note.
message UpdateNoteRequest {
  // The name of the note in the form of
  // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`.
  string name = 1;
  // The updated note.
  Note note = 2;
  // The fields to update.
  google.protobuf.FieldMask update_mask = 3;
}

// Request to list occurrences for a note.
message ListNoteOccurrencesRequest {
  // The name of the note to list occurrences for in the form of
  // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`.
  string name = 1;
  // The filter expression.
  string filter = 2;
  // Number of occurrences to return in the list.
  int32 page_size = 3;
  // Token to provide to skip to a particular spot in the list.
  string page_token = 4;
}

// Response for listing occurrences for a note.
message ListNoteOccurrencesResponse {
  // The occurrences attached to the specified note.
  repeated Occurrence occurrences = 1;
  // Token to provide to skip to a particular spot in the list.
  string next_page_token = 2;
}

// Request to create notes in batch.
message BatchCreateNotesRequest {
  // The name of the project in the form of `projects/[PROJECT_ID]`, under which
  // the notes are to be created.
  string parent = 1;

  // The notes to create.
  map<string, Note> notes = 2;
}

// Response for creating notes in batch.
message BatchCreateNotesResponse {
  // The notes that were created.
  repeated Note notes = 1;
}

// Request to create occurrences in batch.
message BatchCreateOccurrencesRequest {
  // The name of the project in the form of `projects/[PROJECT_ID]`, under which
  // the occurrences are to be created.
  string parent = 1;
  // The occurrences to create.
  repeated Occurrence occurrences = 2;
}

// Response for creating occurrences in batch.
message BatchCreateOccurrencesResponse {
  // The occurrences that were created.
  repeated Occurrence occurrences = 1;
}

// Request to get a vulnerability summary for some set of occurrences.
message GetVulnerabilityOccurrencesSummaryRequest {
  // The name of the project to get a vulnerability summary for in the form of
  // `projects/[PROJECT_ID]`.
  string parent = 1;
  // The filter expression.
  string filter = 2;
}

// A summary of how many vulnerability occurrences there are per resource and
// severity type.
message VulnerabilityOccurrencesSummary {
  // A listing by resource of the number of fixable and total vulnerabilities.
  repeated FixableTotalByDigest counts = 1;

  // Per resource and severity counts of fixable and total vulnerabilities.
  message FixableTotalByDigest {
    // The affected resource.
    Resource resource = 1;
    // The severity for this count. SEVERITY_UNSPECIFIED indicates total across
    // all severities.
    grafeas.v1beta1.vulnerability.Severity severity = 2;
    // The number of fixable vulnerabilities associated with this resource.
    int64 fixable_count = 3;
    // The total number of vulnerabilities associated with this resource.
    int64 total_count = 4;
  }
}