From 51d906cabee4876b12497054b15b05d4a50ad027 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 8 Jan 2020 15:08:23 -0800 Subject: [PATCH] Import of Grafeas from Github. Update BUILD.bazel accordingly. PiperOrigin-RevId: 288783426 --- grafeas/v1/BUILD.bazel | 4 ++ grafeas/v1/common.proto | 2 + grafeas/v1/discovery.proto | 7 ++ grafeas/v1/grafeas.proto | 125 +++++++++++++++++++++++++++------ grafeas/v1/upgrade.proto | 114 ++++++++++++++++++++++++++++++ grafeas/v1/vulnerability.proto | 14 +++- 6 files changed, 241 insertions(+), 25 deletions(-) create mode 100644 grafeas/v1/upgrade.proto diff --git a/grafeas/v1/BUILD.bazel b/grafeas/v1/BUILD.bazel index b9b5ae9e..af4186de 100644 --- a/grafeas/v1/BUILD.bazel +++ b/grafeas/v1/BUILD.bazel @@ -22,10 +22,14 @@ proto_library( "image.proto", "package.proto", "provenance.proto", + "upgrade.proto", "vulnerability.proto", ], deps = [ "//google/api:annotations_proto", + "//google/api:client_proto", + "//google/api:field_behavior_proto", + "//google/api:resource_proto", "//google/rpc:status_proto", "@com_google_protobuf//:empty_proto", "@com_google_protobuf//:field_mask_proto", diff --git a/grafeas/v1/common.proto b/grafeas/v1/common.proto index 846948a5..db780bb6 100644 --- a/grafeas/v1/common.proto +++ b/grafeas/v1/common.proto @@ -39,6 +39,8 @@ enum NoteKind { DISCOVERY = 6; // This represents a logical "role" that can attest to artifacts. ATTESTATION = 7; + // This represents an available package upgrade. + UPGRADE = 8; } // Metadata for any related URL information. diff --git a/grafeas/v1/discovery.proto b/grafeas/v1/discovery.proto index ba8034d3..e0799255 100644 --- a/grafeas/v1/discovery.proto +++ b/grafeas/v1/discovery.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package grafeas.v1; +import "google/protobuf/timestamp.proto"; import "google/rpc/status.proto"; import "grafeas/v1/common.proto"; @@ -73,4 +74,10 @@ message DiscoveryOccurrence { // details to show to the user. The LocalizedMessage is output only and // populated by the API. google.rpc.Status analysis_status_error = 3; + + // The CPE of the resource being scanned. + string cpe = 4; + + // The last time this resource was scanned. + google.protobuf.Timestamp last_scan_time = 5; } diff --git a/grafeas/v1/grafeas.proto b/grafeas/v1/grafeas.proto index 1364b2aa..fdb26bcb 100644 --- a/grafeas/v1/grafeas.proto +++ b/grafeas/v1/grafeas.proto @@ -17,6 +17,9 @@ syntax = "proto3"; package grafeas.v1; import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/field_mask.proto"; import "google/protobuf/timestamp.proto"; @@ -27,7 +30,7 @@ import "grafeas/v1/deployment.proto"; import "grafeas/v1/discovery.proto"; import "grafeas/v1/image.proto"; import "grafeas/v1/package.proto"; -import "grafeas/v1/provenance.proto"; +import "grafeas/v1/upgrade.proto"; import "grafeas/v1/vulnerability.proto"; option go_package = "google.golang.org/genproto/googleapis/grafeas/v1;grafeas"; @@ -55,6 +58,7 @@ service Grafeas { option (google.api.http) = { get: "/v1/{name=projects/*/occurrences/*}" }; + option (google.api.method_signature) = "name"; } // Lists occurrences for the specified project. @@ -63,6 +67,7 @@ service Grafeas { option (google.api.http) = { get: "/v1/{parent=projects/*}/occurrences" }; + option (google.api.method_signature) = "parent,filter"; } // Deletes the specified occurrence. For example, use this method to delete an @@ -73,6 +78,7 @@ service Grafeas { option (google.api.http) = { delete: "/v1/{name=projects/*/occurrences/*}" }; + option (google.api.method_signature) = "name"; } // Creates a new occurrence. @@ -81,6 +87,7 @@ service Grafeas { post: "/v1/{parent=projects/*}/occurrences" body: "occurrence" }; + option (google.api.method_signature) = "parent,occurrence"; } // Creates new occurrences in batch. @@ -90,6 +97,7 @@ service Grafeas { post: "/v1/{parent=projects/*}/occurrences:batchCreate" body: "*" }; + option (google.api.method_signature) = "parent,occurrences"; } // Updates the specified occurrence. @@ -98,6 +106,7 @@ service Grafeas { patch: "/v1/{name=projects/*/occurrences/*}" body: "occurrence" }; + option (google.api.method_signature) = "name,occurrence,update_mask"; } // Gets the note attached to the specified occurrence. Consumer projects can @@ -106,6 +115,7 @@ service Grafeas { option (google.api.http) = { get: "/v1/{name=projects/*/occurrences/*}/notes" }; + option (google.api.method_signature) = "name"; } // Gets the specified note. @@ -113,6 +123,7 @@ service Grafeas { option (google.api.http) = { get: "/v1/{name=projects/*/notes/*}" }; + option (google.api.method_signature) = "name"; } // Lists notes for the specified project. @@ -120,6 +131,7 @@ service Grafeas { option (google.api.http) = { get: "/v1/{parent=projects/*}/notes" }; + option (google.api.method_signature) = "parent,filter"; } // Deletes the specified note. @@ -127,6 +139,7 @@ service Grafeas { option (google.api.http) = { delete: "/v1/{name=projects/*/notes/*}" }; + option (google.api.method_signature) = "name"; } // Creates a new note. @@ -135,6 +148,7 @@ service Grafeas { post: "/v1/{parent=projects/*}/notes" body: "note" }; + option (google.api.method_signature) = "parent,note_id,note"; } // Creates new notes in batch. @@ -144,6 +158,7 @@ service Grafeas { post: "/v1/{parent=projects/*}/notes:batchCreate" body: "*" }; + option (google.api.method_signature) = "parent,notes"; } // Updates the specified note. @@ -152,6 +167,7 @@ service Grafeas { patch: "/v1/{name=projects/*/notes/*}" body: "note" }; + option (google.api.method_signature) = "name,note,update_mask"; } // Lists occurrences referencing the specified note. Provider projects can use @@ -162,11 +178,17 @@ service Grafeas { option (google.api.http) = { get: "/v1/{name=projects/*/notes/*}/occurrences" }; + option (google.api.method_signature) = "name,filter"; } } // An instance of an analysis type that has been found on a resource. message Occurrence { + option (google.api.resource) = { + type: "grafeas.io/Occurrence" + pattern: "projects/{project}/occurrences/{occurrence}" + }; + // Output only. The name of the occurrence in the form of // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`. string name = 1; @@ -212,11 +234,18 @@ message Occurrence { grafeas.v1.DiscoveryOccurrence discovery = 13; // Describes an attestation of an artifact. grafeas.v1.AttestationOccurrence attestation = 14; + // Describes an available package upgrade on the linked resource. + grafeas.v1.UpgradeOccurrence upgrade = 15; } } // A type of analysis that can be done for a resource. message Note { + option (google.api.resource) = { + type: "grafeas.io/Note" + pattern: "projects/{project}/notes/{note}" + }; + // Output only. The name of the note in the form of // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`. string name = 1; @@ -264,6 +293,8 @@ message Note { grafeas.v1.DiscoveryNote discovery = 15; // A note describing an attestation role. grafeas.v1.AttestationNote attestation = 16; + // A note describing available package upgrades. + grafeas.v1.UpgradeNote upgrade = 17; } } @@ -271,14 +302,21 @@ message Note { message GetOccurrenceRequest { // The name of the occurrence in the form of // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = "grafeas.io/Occurrence" + ]; } // 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; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = + "cloudresourcemanager.googleapis.com/Project" + ]; // The filter expression. string filter = 2; @@ -301,29 +339,39 @@ message ListOccurrencesResponse { string next_page_token = 2; } -// Request to delete a occurrence. +// Request to delete an occurrence. message DeleteOccurrenceRequest { // The name of the occurrence in the form of // `projects/[PROJECT_ID]/occurrences/[OCCURRENCE_ID]`. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = "grafeas.io/Occurrence" + ]; } // 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; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = + "cloudresourcemanager.googleapis.com/Project" + ]; // The occurrence to create. - Occurrence occurrence = 2; + Occurrence occurrence = 2 [(google.api.field_behavior) = REQUIRED]; } // 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; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = "grafeas.io/Occurrence" + ]; // The updated occurrence. - Occurrence occurrence = 2; + Occurrence occurrence = 2 [(google.api.field_behavior) = REQUIRED]; // The fields to update. google.protobuf.FieldMask update_mask = 3; } @@ -332,21 +380,31 @@ message UpdateOccurrenceRequest { message GetNoteRequest { // The name of the note in the form of // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = "grafeas.io/Note" + ]; } // 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; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = "grafeas.io/Occurrence" + ]; } // 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; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = + "cloudresourcemanager.googleapis.com/Project" + ]; // The filter expression. string filter = 2; @@ -373,27 +431,37 @@ message ListNotesResponse { message DeleteNoteRequest { // The name of the note in the form of // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = "grafeas.io/Note" + ]; } // 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; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = + "cloudresourcemanager.googleapis.com/Project" + ]; // The ID to use for this note. - string note_id = 2; + string note_id = 2 [(google.api.field_behavior) = REQUIRED]; // The note to create. - Note note = 3; + Note note = 3 [(google.api.field_behavior) = REQUIRED]; } // 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; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = "grafeas.io/Note" + ]; // The updated note. - Note note = 2; + Note note = 2 [(google.api.field_behavior) = REQUIRED]; // The fields to update. google.protobuf.FieldMask update_mask = 3; } @@ -402,7 +470,10 @@ message UpdateNoteRequest { message ListNoteOccurrencesRequest { // The name of the note to list occurrences for in the form of // `projects/[PROVIDER_ID]/notes/[NOTE_ID]`. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = "grafeas.io/Note" + ]; // The filter expression. string filter = 2; // Number of occurrences to return in the list. @@ -423,10 +494,14 @@ message ListNoteOccurrencesResponse { 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; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = + "cloudresourcemanager.googleapis.com/Project" + ]; // The notes to create. Max allowed length is 1000. - map notes = 2; + map notes = 2 [(google.api.field_behavior) = REQUIRED]; } // Response for creating notes in batch. @@ -439,10 +514,14 @@ message BatchCreateNotesResponse { 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; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference).type = + "cloudresourcemanager.googleapis.com/Project" + ]; // The occurrences to create. Max allowed length is 1000. - repeated Occurrence occurrences = 2; + repeated Occurrence occurrences = 2 [(google.api.field_behavior) = REQUIRED]; } // Response for creating occurrences in batch. diff --git a/grafeas/v1/upgrade.proto b/grafeas/v1/upgrade.proto new file mode 100644 index 00000000..89d38929 --- /dev/null +++ b/grafeas/v1/upgrade.proto @@ -0,0 +1,114 @@ +// Copyright 2019 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.v1; + +import "google/protobuf/timestamp.proto"; +import "grafeas/v1/package.proto"; + +option go_package = "google.golang.org/genproto/googleapis/grafeas/v1;grafeas"; +option java_multiple_files = true; +option java_package = "io.grafeas.v1"; +option objc_class_prefix = "GRA"; + +// An Upgrade Note represents a potential upgrade of a package to a given +// version. For each package version combination (i.e. bash 4.0, bash 4.1, +// bash 4.1.2), there will be an Upgrade Note. For Windows, windows_update field +// represents the information related to the update. +message UpgradeNote { + // Required for non-Windows OS. The package this Upgrade is for. + string package = 1; + // Required for non-Windows OS. The version of the package in machine + human + // readable form. + grafeas.v1.Version version = 2; + // Metadata about the upgrade for each specific operating system. + repeated UpgradeDistribution distributions = 3; + // Required for Windows OS. Represents the metadata about the Windows update. + WindowsUpdate windows_update = 4; +} + +// The Upgrade Distribution represents metadata about the Upgrade for each +// operating system (CPE). Some distributions have additional metadata around +// updates, classifying them into various categories and severities. +message UpgradeDistribution { + // Required - The specific operating system this metadata applies to. See + // https://cpe.mitre.org/specification/. + string cpe_uri = 1; + // The operating system classification of this Upgrade, as specified by the + // upstream operating system upgrade feed. For Windows the classification is + // one of the category_ids listed at + // https://docs.microsoft.com/en-us/previous-versions/windows/desktop/ff357803(v=vs.85) + string classification = 2; + // The severity as specified by the upstream operating system. + string severity = 3; + // The cve tied to this Upgrade. + repeated string cve = 4; +} + +// Windows Update represents the metadata about the update for the Windows +// operating system. The fields in this message come from the Windows Update API +// documented at +// https://docs.microsoft.com/en-us/windows/win32/api/wuapi/nn-wuapi-iupdate. +message WindowsUpdate { + // The unique identifier of the update. + message Identity { + // The revision independent identifier of the update. + string update_id = 1; + // The revision number of the update. + int32 revision = 2; + } + // Required - The unique identifier for the update. + Identity identity = 1; + // The localized title of the update. + string title = 2; + // The localized description of the update. + string description = 3; + // The category to which the update belongs. + message Category { + // The identifier of the category. + string category_id = 1; + // The localized name of the category. + string name = 2; + } + // The list of categories to which the update belongs. + repeated Category categories = 4; + // The Microsoft Knowledge Base article IDs that are associated with the + // update. + repeated string kb_article_ids = 5; + // The hyperlink to the support information for the update. + string support_url = 6; + // The last published timestamp of the update. + google.protobuf.Timestamp last_published_timestamp = 7; +} + +// An Upgrade Occurrence represents that a specific resource_url could install a +// specific upgrade. This presence is supplied via local sources (i.e. it is +// present in the mirror and the running system has noticed its availability). +// For Windows, both distribution and windows_update contain information for the +// Windows update. +message UpgradeOccurrence { + // Required for non-Windows OS. The package this Upgrade is for. + string package = 1; + // Required for non-Windows OS. The version of the package in a machine + + // human readable form. + grafeas.v1.Version parsed_version = 3; + // Metadata about the upgrade for available for the specific operating system + // for the resource_url. This allows efficient filtering, as well as + // making it easier to use the occurrence. + UpgradeDistribution distribution = 4; + // Required for Windows OS. Represents the metadata about the Windows update. + WindowsUpdate windows_update = 5; +} diff --git a/grafeas/v1/vulnerability.proto b/grafeas/v1/vulnerability.proto index 27a5d238..6c94cdf0 100644 --- a/grafeas/v1/vulnerability.proto +++ b/grafeas/v1/vulnerability.proto @@ -16,6 +16,7 @@ syntax = "proto3"; package grafeas.v1; +import "google/protobuf/timestamp.proto"; import "grafeas/v1/common.proto"; import "grafeas/v1/cvss.proto"; import "grafeas/v1/package.proto"; @@ -109,6 +110,11 @@ message VulnerabilityNote { // Whether this detail is obsolete. Occurrences are expected not to point to // obsolete details. bool is_obsolete = 11; + + // The time this information was last changed at the source. This is an + // upstream timestamp from the underlying information source - e.g. Ubuntu + // security tracker. + google.protobuf.Timestamp source_update_time = 12; } // The full description of the CVSSv3 for this vulnerability. @@ -145,6 +151,11 @@ message VulnerabilityNote { string url = 2; } } + + // The time this information was last changed at the source. This is an + // upstream timestamp from the underlying information source - e.g. Ubuntu + // security tracker. + google.protobuf.Timestamp source_update_time = 6; } // An occurrence of a severity vulnerability on a resource. @@ -206,8 +217,7 @@ message VulnerabilityOccurrence { repeated grafeas.v1.RelatedUrl related_urls = 7; // The distro assigned severity for this vulnerability when it is available, - // and note provider assigned severity when distro has not yet assigned a - // severity for this vulnerability. + // otherwise this is the note provider assigned severity. Severity effective_severity = 8; // Output only. Whether at least one of the affected packages has a fix