diff --git a/google/cloud/webrisk/v1/BUILD.bazel b/google/cloud/webrisk/v1/BUILD.bazel index 8d6cfdb2e..5df70ec29 100644 --- a/google/cloud/webrisk/v1/BUILD.bazel +++ b/google/cloud/webrisk/v1/BUILD.bazel @@ -28,6 +28,7 @@ proto_library( "//google/api:client_proto", "//google/api:field_behavior_proto", "//google/api:resource_proto", + "//google/longrunning:operations_proto", "@com_google_protobuf//:timestamp_proto", ], ) @@ -120,6 +121,7 @@ go_proto_library( protos = [":webrisk_proto"], deps = [ "//google/api:annotations_go_proto", + "//google/longrunning:longrunning_go_proto", ], ) @@ -135,6 +137,9 @@ go_gapic_library( transport = "grpc+rest", deps = [ ":webrisk_go_proto", + "//google/longrunning:longrunning_go_proto", + "@com_google_cloud_go_longrunning//:go_default_library", + "@com_google_cloud_go_longrunning//autogen:go_default_library", ], ) @@ -222,6 +227,7 @@ php_gapic_library( name = "webrisk_php_gapic", srcs = [":webrisk_proto_with_info"], grpc_service_config = "webrisk_grpc_service_config.json", + migration_mode = "PRE_MIGRATION_SURFACE_ONLY", rest_numeric_enums = True, service_yaml = "webrisk_v1.yaml", transport = "grpc+rest", diff --git a/google/cloud/webrisk/v1/webrisk.proto b/google/cloud/webrisk/v1/webrisk.proto index 47281fe7f..5c5f63929 100644 --- a/google/cloud/webrisk/v1/webrisk.proto +++ b/google/cloud/webrisk/v1/webrisk.proto @@ -20,6 +20,7 @@ import "google/api/annotations.proto"; import "google/api/client.proto"; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; +import "google/longrunning/operations.proto"; import "google/protobuf/timestamp.proto"; option csharp_namespace = "Google.Cloud.WebRisk.V1"; @@ -35,7 +36,8 @@ option ruby_package = "Google::Cloud::WebRisk::V1"; // website and in client applications. service WebRiskService { option (google.api.default_host) = "webrisk.googleapis.com"; - option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-platform"; // Gets the most recent threat list diffs. These diffs should be applied to // a local database of hashes to keep it up-to-date. If the local database is @@ -43,11 +45,13 @@ service WebRiskService { // be returned. This Method only updates a single ThreatList at a time. To // update multiple ThreatList databases, this method needs to be called once // for each list. - rpc ComputeThreatListDiff(ComputeThreatListDiffRequest) returns (ComputeThreatListDiffResponse) { + rpc ComputeThreatListDiff(ComputeThreatListDiffRequest) + returns (ComputeThreatListDiffResponse) { option (google.api.http) = { get: "/v1/threatLists:computeDiff" }; - option (google.api.method_signature) = "threat_type,version_token,constraints"; + option (google.api.method_signature) = + "threat_type,version_token,constraints"; } // This method is used to check whether a URI is on a given threatList. @@ -88,6 +92,27 @@ service WebRiskService { }; option (google.api.method_signature) = "parent,submission"; } + + // Submits a URI suspected of containing malicious content to be reviewed. + // Returns a google.longrunning.Operation which, once the review is complete, + // is updated with its result. You can use the [Pub/Sub API] + // (https://cloud.google.com/pubsub) to receive notifications for the returned + // Operation. If the result verifies the existence of malicious content, the + // site will be added to the [Google's Social Engineering lists] + // (https://support.google.com/webmasters/answer/6350487/) in order to + // protect users that could get exposed to this threat in the future. Only + // allowlisted projects can use this method during Early Access. Please reach + // out to Sales or your customer engineer to obtain access. + rpc SubmitUri(SubmitUriRequest) returns (google.longrunning.Operation) { + option (google.api.http) = { + post: "/v1/{parent=projects/*}/uris:submit" + body: "*" + }; + option (google.longrunning.operation_info) = { + response_type: "Submission" + metadata_type: "SubmitUriMetadata" + }; + } } // Describes an API diff request. @@ -108,9 +133,9 @@ message ComputeThreatListDiffRequest { repeated CompressionType supported_compressions = 3; } - // Required. The threat list to update. Only a single ThreatType should be specified - // per request. If you want to handle multiple ThreatTypes, you must make one - // request per ThreatType. + // Required. The threat list to update. Only a single ThreatType should be + // specified per request. If you want to handle multiple ThreatTypes, you must + // make one request per ThreatType. ThreatType threat_type = 1 [(google.api.field_behavior) = REQUIRED]; // The current version token of the client for the requested list (the @@ -180,7 +205,8 @@ message SearchUrisRequest { // Required. The URI to be checked for matches. string uri = 1 [(google.api.field_behavior) = REQUIRED]; - // Required. The ThreatLists to search in. Multiple ThreatLists may be specified. + // Required. The ThreatLists to search in. Multiple ThreatLists may be + // specified. repeated ThreatType threat_types = 2 [(google.api.field_behavior) = REQUIRED]; } @@ -207,7 +233,8 @@ message SearchHashesRequest { // the web safe base64 variant (RFC 4648). bytes hash_prefix = 1; - // Required. The ThreatLists to search in. Multiple ThreatLists may be specified. + // Required. The ThreatLists to search in. Multiple ThreatLists may be + // specified. repeated ThreatType threat_types = 2 [(google.api.field_behavior) = REQUIRED]; } @@ -342,14 +369,130 @@ message RiceDeltaEncoding { // Wraps a URI that might be displaying malicious content. message Submission { - // Required. The URI that is being reported for malicious content to be analyzed. + // Required. The URI that is being reported for malicious content to be + // analyzed. string uri = 1 [(google.api.field_behavior) = REQUIRED]; + + // Output only. ThreatTypes found to be associated with the submitted URI + // after reviewing it. This might be empty if the URI was not added to any + // list. + repeated ThreatType threat_types = 2 + [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// Context about the submission including the type of abuse found on the URI and +// supporting details. +// option (google.api.message_visibility).restriction = "TRUSTED_TESTER"; +message ThreatInfo { + // The abuse type found on the URI. + enum AbuseType { + // Default. + ABUSE_TYPE_UNSPECIFIED = 0; + + // The URI contains malware. + MALWARE = 1; + + // The URI contains social engineering. + SOCIAL_ENGINEERING = 2; + + // The URI contains unwanted software. + UNWANTED_SOFTWARE = 3; + } + + // Confidence that a URI is unsafe. + message Confidence { + // Enum representation of confidence. + enum ConfidenceLevel { + // Default. + CONFIDENCE_LEVEL_UNSPECIFIED = 0; + + // Less than 60% confidence that the URI is unsafe. + LOW = 1; + + // Between 60% and 80% confidence that the URI is unsafe. + MEDIUM = 2; + + // Greater than 80% confidence that the URI is unsafe. + HIGH = 3; + } + + oneof value { + // A decimal representation of confidence in the range of 0 + // to 1 where 0 indicates no confidence and 1 indicates + // complete confidence. + float score = 1; + + // Enum representation of confidence. + ConfidenceLevel level = 2; + } + } + + // Context about why the URI is unsafe. + message ThreatJustification { + // Labels that explain how the URI was classified. + enum JustificationLabel { + // Default. + JUSTIFICATION_LABEL_UNSPECIFIED = 0; + + // The submitter manually verified that the submission is unsafe. + MANUAL_VERIFICATION = 1; + + // The submitter received the submission from an end user. + USER_REPORT = 2; + + // The submitter received the submission from an automated system. + AUTOMATED_REPORT = 3; + } + + // Labels associated with this URI that explain how it was classified. + repeated JustificationLabel labels = 1; + + // Free-form context on why this URI is unsafe. + repeated string comments = 2; + } + + // The type of abuse. + AbuseType abuse_type = 1; + + // Confidence that the URI is unsafe. + Confidence threat_confidence = 2; + + // Context about why the URI is unsafe. + ThreatJustification threat_justification = 3; +} + +// Details about how the threat was discovered. +message ThreatDiscovery { + // Platform types. + enum Platform { + // Default. + PLATFORM_UNSPECIFIED = 0; + + // General Android platform. + ANDROID = 1; + + // General iOS platform. + IOS = 2; + + // General macOS platform. + MACOS = 3; + + // General Windows platform. + WINDOWS = 4; + } + + // Platform on which the threat was discovered. + Platform platform = 1; + + // CLDR region code of the countries/regions the URI poses a threat ordered + // from most impact to least impact. Example: "US" for United States. + repeated string region_codes = 2; } // Request to send a potentially phishy URI to WebRisk. message CreateSubmissionRequest { - // Required. The name of the project that is making the submission. This string is in - // the format "projects/{project_number}". + // Required. The name of the project that is making the submission. This + // string is in the format "projects/{project_number}". string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -360,3 +503,58 @@ message CreateSubmissionRequest { // Required. The submission that contains the content of the phishing report. Submission submission = 2 [(google.api.field_behavior) = REQUIRED]; } + +// Request to send a potentially malicious URI to WebRisk. +message SubmitUriRequest { + // Required. The name of the project that is making the submission. This + // string is in the format "projects/{project_number}". + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "cloudresourcemanager.googleapis.com/Project" + } + ]; + + // Required. The submission that contains the URI to be scanned. + Submission submission = 2 [(google.api.field_behavior) = REQUIRED]; + + // Provides additional information about the submission. + ThreatInfo threat_info = 3; + + // Provides additional information about how the submission was discovered. + ThreatDiscovery threat_discovery = 4; +} + +// Metadata for the Submit URI long-running operation. +// option (google.api.message_visibility).restriction = "TRUSTED_TESTER"; +message SubmitUriMetadata { + // Enum that represents the state of the long-running operation. + enum State { + // Default unspecified state. + STATE_UNSPECIFIED = 0; + + // The operation is currently running. + RUNNING = 1; + + // The operation finished with a success status. + SUCCEEDED = 2; + + // The operation was cancelled. + CANCELLED = 3; + + // The operation finished with a failure status. + FAILED = 4; + + // The operation was closed with no action taken. + CLOSED = 5; + } + + // The state of the operation. + State state = 1; + + // Creation time of the operation. + google.protobuf.Timestamp create_time = 2; + + // Latest update time of the operation. + google.protobuf.Timestamp update_time = 3; +} diff --git a/google/cloud/webrisk/v1/webrisk_v1.yaml b/google/cloud/webrisk/v1/webrisk_v1.yaml index cfb85a603..87691fd27 100644 --- a/google/cloud/webrisk/v1/webrisk_v1.yaml +++ b/google/cloud/webrisk/v1/webrisk_v1.yaml @@ -5,6 +5,23 @@ title: Web Risk API apis: - name: google.cloud.webrisk.v1.WebRiskService +- name: google.longrunning.Operations + +types: +- name: google.cloud.webrisk.v1.Submission +- name: google.cloud.webrisk.v1.SubmitUriMetadata + +http: + rules: + - selector: google.longrunning.Operations.CancelOperation + post: '/v1/{name=projects/*/operations/*}:cancel' + body: '*' + - selector: google.longrunning.Operations.DeleteOperation + delete: '/v1/{name=projects/*/operations/*}' + - selector: google.longrunning.Operations.GetOperation + get: '/v1/{name=projects/*/operations/*}' + - selector: google.longrunning.Operations.ListOperations + get: '/v1/{name=projects/*}/operations' authentication: rules: @@ -12,3 +29,7 @@ authentication: oauth: canonical_scopes: |- https://www.googleapis.com/auth/cloud-platform + - selector: google.longrunning.Operations.GetOperation + oauth: + canonical_scopes: |- + https://www.googleapis.com/auth/cloud-platform