Skip to content

Commit

Permalink
feat: adds the v1 API surface (#134)
Browse files Browse the repository at this point in the history
  • Loading branch information
bcoe authored Mar 24, 2020
1 parent a49c157 commit eea7bd2
Show file tree
Hide file tree
Showing 21 changed files with 10,026 additions and 1,174 deletions.
2 changes: 1 addition & 1 deletion packages/google-cloud-webrisk/.jsdoc.js
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2019 Google LLC
// Copyright 2020 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,352 @@
// Copyright 2020 Google LLC
//
// 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 google.cloud.webrisk.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/timestamp.proto";

option csharp_namespace = "Google.Cloud.WebRisk.V1";
option go_package = "google.golang.org/genproto/googleapis/cloud/webrisk/v1;webrisk";
option java_multiple_files = true;
option java_outer_classname = "WebRiskProto";
option java_package = "com.google.webrisk.v1";
option objc_class_prefix = "GCWR";
option php_namespace = "Google\\Cloud\\WebRisk\\V1";

// Web Risk API defines an interface to detect malicious URLs on your
// 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";

// 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
// empty or excessively out-of-date, a complete snapshot of the database will
// 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) {
option (google.api.http) = {
get: "/v1/threatLists:computeDiff"
};
option (google.api.method_signature) = "threat_type,version_token,constraints";
}

// This method is used to check whether a URI is on a given threatList.
// Multiple threatLists may be searched in a single query.
// The response will list all requested threatLists the URI was found to
// match. If the URI is not found on any of the requested ThreatList an
// empty response will be returned.
rpc SearchUris(SearchUrisRequest) returns (SearchUrisResponse) {
option (google.api.http) = {
get: "/v1/uris:search"
};
option (google.api.method_signature) = "uri,threat_types";
}

// Gets the full hashes that match the requested hash prefix.
// This is used after a hash prefix is looked up in a threatList
// and there is a match. The client side threatList only holds partial hashes
// so the client must query this method to determine if there is a full
// hash match of a threat.
rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse) {
option (google.api.http) = {
get: "/v1/hashes:search"
};
option (google.api.method_signature) = "hash_prefix,threat_types";
}

// Creates a Submission of a URI suspected of containing phishing content to
// be reviewed. If the result verifies the existence of malicious phishing
// 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
// projects with CREATE_SUBMISSION_USERS visibility can use this method.
rpc CreateSubmission(CreateSubmissionRequest) returns (Submission) {
option (google.api.http) = {
post: "/v1/{parent=projects/*}/submissions"
body: "submission"
};
option (google.api.method_signature) = "parent,submission";
}
}

// Describes an API diff request.
message ComputeThreatListDiffRequest {
// The constraints for this diff.
message Constraints {
// The maximum size in number of entries. The diff will not contain more
// entries than this value. This should be a power of 2 between 2**10 and
// 2**20. If zero, no diff size limit is set.
int32 max_diff_entries = 1;

// Sets the maximum number of entries that the client is willing to have
// in the local database. This should be a power of 2 between 2**10 and
// 2**20. If zero, no database size limit is set.
int32 max_database_entries = 2;

// The compression types supported by the client.
repeated CompressionType supported_compressions = 3;
}

// Required. The threat list to update. Only a single ThreatType should be specified.
ThreatType threat_type = 1 [(google.api.field_behavior) = REQUIRED];

// The current version token of the client for the requested list (the
// client version that was received from the last successful diff).
// If the client does not have a version token (this is the first time calling
// ComputeThreatListDiff), this may be left empty and a full database
// snapshot will be returned.
bytes version_token = 2;

// Required. The constraints associated with this request.
Constraints constraints = 3 [(google.api.field_behavior) = REQUIRED];
}

message ComputeThreatListDiffResponse {
// The expected state of a client's local database.
message Checksum {
// The SHA256 hash of the client state; that is, of the sorted list of all
// hashes present in the database.
bytes sha256 = 1;
}

// The type of response sent to the client.
enum ResponseType {
// Unknown.
RESPONSE_TYPE_UNSPECIFIED = 0;

// Partial updates are applied to the client's existing local database.
DIFF = 1;

// Full updates resets the client's entire local database. This means
// that either the client had no state, was seriously out-of-date,
// or the client is believed to be corrupt.
RESET = 2;
}

// The type of response. This may indicate that an action must be taken by the
// client when the response is received.
ResponseType response_type = 4;

// A set of entries to add to a local threat type's list.
ThreatEntryAdditions additions = 5;

// A set of entries to remove from a local threat type's list.
// This field may be empty.
ThreatEntryRemovals removals = 6;

// The new opaque client version token. This should be retained by the client
// and passed into the next call of ComputeThreatListDiff as 'version_token'.
// A separate version token should be stored and used for each threatList.
bytes new_version_token = 7;

// The expected SHA256 hash of the client state; that is, of the sorted list
// of all hashes present in the database after applying the provided diff.
// If the client state doesn't match the expected state, the client must
// discard this diff and retry later.
Checksum checksum = 8;

// The soonest the client should wait before issuing any diff
// request. Querying sooner is unlikely to produce a meaningful diff.
// Waiting longer is acceptable considering the use case.
// If this field is not set clients may update as soon as they want.
google.protobuf.Timestamp recommended_next_diff = 2;
}

// Request to check URI entries against threatLists.
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.
repeated ThreatType threat_types = 2 [(google.api.field_behavior) = REQUIRED];
}

message SearchUrisResponse {
// Contains threat information on a matching uri.
message ThreatUri {
// The ThreatList this threat belongs to.
repeated ThreatType threat_types = 1;

// The cache lifetime for the returned match. Clients must not cache this
// response past this timestamp to avoid false positives.
google.protobuf.Timestamp expire_time = 2;
}

// The threat list matches. This may be empty if the URI is on no list.
ThreatUri threat = 1;
}

// Request to return full hashes matched by the provided hash prefixes.
message SearchHashesRequest {
// A hash prefix, consisting of the most significant 4-32 bytes of a SHA256
// hash. For JSON requests, this field is base64-encoded.
bytes hash_prefix = 1;

// Required. The ThreatLists to search in. Multiple ThreatLists may be specified.
repeated ThreatType threat_types = 2 [(google.api.field_behavior) = REQUIRED];
}

message SearchHashesResponse {
// Contains threat information on a matching hash.
message ThreatHash {
// The ThreatList this threat belongs to.
// This must contain at least one entry.
repeated ThreatType threat_types = 1;

// A 32 byte SHA256 hash. This field is in binary format. For JSON
// requests, hashes are base64-encoded.
bytes hash = 2;

// The cache lifetime for the returned match. Clients must not cache this
// response past this timestamp to avoid false positives.
google.protobuf.Timestamp expire_time = 3;
}

// The full hashes that matched the requested prefixes.
// The hash will be populated in the key.
repeated ThreatHash threats = 1;

// For requested entities that did not match the threat list, how long to
// cache the response until.
google.protobuf.Timestamp negative_expire_time = 2;
}

// Contains the set of entries to add to a local database.
// May contain a combination of compressed and raw data in a single response.
message ThreatEntryAdditions {
// The raw SHA256-formatted entries.
// Repeated to allow returning sets of hashes with different prefix sizes.
repeated RawHashes raw_hashes = 1;

// The encoded 4-byte prefixes of SHA256-formatted entries, using a
// Golomb-Rice encoding. The hashes are converted to uint32, sorted in
// ascending order, then delta encoded and stored as encoded_data.
RiceDeltaEncoding rice_hashes = 2;
}

// Contains the set of entries to remove from a local database.
message ThreatEntryRemovals {
// The raw removal indices for a local list.
RawIndices raw_indices = 1;

// The encoded local, lexicographically-sorted list indices, using a
// Golomb-Rice encoding. Used for sending compressed removal indices. The
// removal indices (uint32) are sorted in ascending order, then delta encoded
// and stored as encoded_data.
RiceDeltaEncoding rice_indices = 2;
}

// The type of threat. This maps dirrectly to the threat list a threat may
// belong to.
enum ThreatType {
// Unknown.
THREAT_TYPE_UNSPECIFIED = 0;

// Malware targeting any platform.
MALWARE = 1;

// Social engineering targeting any platform.
SOCIAL_ENGINEERING = 2;

// Unwanted software targeting any platform.
UNWANTED_SOFTWARE = 3;
}

// The ways in which threat entry sets can be compressed.
enum CompressionType {
// Unknown.
COMPRESSION_TYPE_UNSPECIFIED = 0;

// Raw, uncompressed data.
RAW = 1;

// Rice-Golomb encoded data.
RICE = 2;
}

// A set of raw indices to remove from a local list.
message RawIndices {
// The indices to remove from a lexicographically-sorted local list.
repeated int32 indices = 1;
}

// The uncompressed threat entries in hash format.
// Hashes can be anywhere from 4 to 32 bytes in size. A large majority are 4
// bytes, but some hashes are lengthened if they collide with the hash of a
// popular URI.
//
// Used for sending ThreatEntryAdditons to clients that do not support
// compression, or when sending non-4-byte hashes to clients that do support
// compression.
message RawHashes {
// The number of bytes for each prefix encoded below. This field can be
// anywhere from 4 (shortest prefix) to 32 (full SHA256 hash).
// In practice this is almost always 4, except in exceptional circumstances.
int32 prefix_size = 1;

// The hashes, in binary format, concatenated into one long string. Hashes are
// sorted in lexicographic order. For JSON API users, hashes are
// base64-encoded.
bytes raw_hashes = 2;
}

// The Rice-Golomb encoded data. Used for sending compressed 4-byte hashes or
// compressed removal indices.
message RiceDeltaEncoding {
// The offset of the first entry in the encoded data, or, if only a single
// integer was encoded, that single integer's value. If the field is empty or
// missing, assume zero.
int64 first_value = 1;

// The Golomb-Rice parameter, which is a number between 2 and 28. This field
// is missing (that is, zero) if `num_entries` is zero.
int32 rice_parameter = 2;

// The number of entries that are delta encoded in the encoded data. If only a
// single integer was encoded, this will be zero and the single value will be
// stored in `first_value`.
int32 entry_count = 3;

// The encoded deltas that are encoded using the Golomb-Rice coder.
bytes encoded_data = 4;
}

// Wraps a URI that might be displaying phishing content.
message Submission {
// Required. The URI that is being reported for phishing content to be analyzed.
string uri = 1 [(google.api.field_behavior) = REQUIRED];
}

// 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}".
string parent = 1 [
(google.api.field_behavior) = REQUIRED,
(google.api.resource_reference) = {
type: "cloudresourcemanager.googleapis.com/Project"
}
];

// Required. The submission that contains the content of the phishing report.
Submission submission = 2 [(google.api.field_behavior) = REQUIRED];
}
Loading

0 comments on commit eea7bd2

Please sign in to comment.