1// Copyright 2021 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.ids.v1;
18
19import "google/api/annotations.proto";
20import "google/api/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/resource.proto";
23import "google/longrunning/operations.proto";
24import "google/protobuf/timestamp.proto";
25
26option go_package = "cloud.google.com/go/ids/apiv1/idspb;idspb";
27option java_multiple_files = true;
28option java_outer_classname = "IdsProto";
29option java_package = "com.google.cloud.ids.v1";
30option ruby_package = "Google::Cloud::IDS::V1";
31
32// The IDS Service
33service IDS {
34  option (google.api.default_host) = "ids.googleapis.com";
35  option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
36
37  // Lists Endpoints in a given project and location.
38  rpc ListEndpoints(ListEndpointsRequest) returns (ListEndpointsResponse) {
39    option (google.api.http) = {
40      get: "/v1/{parent=projects/*/locations/*}/endpoints"
41    };
42    option (google.api.method_signature) = "parent";
43  }
44
45  // Gets details of a single Endpoint.
46  rpc GetEndpoint(GetEndpointRequest) returns (Endpoint) {
47    option (google.api.http) = {
48      get: "/v1/{name=projects/*/locations/*/endpoints/*}"
49    };
50    option (google.api.method_signature) = "name";
51  }
52
53  // Creates a new Endpoint in a given project and location.
54  rpc CreateEndpoint(CreateEndpointRequest) returns (google.longrunning.Operation) {
55    option (google.api.http) = {
56      post: "/v1/{parent=projects/*/locations/*}/endpoints"
57      body: "endpoint"
58    };
59    option (google.api.method_signature) = "parent,endpoint,endpoint_id";
60    option (google.longrunning.operation_info) = {
61      response_type: "Endpoint"
62      metadata_type: "OperationMetadata"
63    };
64  }
65
66  // Deletes a single Endpoint.
67  rpc DeleteEndpoint(DeleteEndpointRequest) returns (google.longrunning.Operation) {
68    option (google.api.http) = {
69      delete: "/v1/{name=projects/*/locations/*/endpoints/*}"
70    };
71    option (google.api.method_signature) = "name";
72    option (google.longrunning.operation_info) = {
73      response_type: "google.protobuf.Empty"
74      metadata_type: "OperationMetadata"
75    };
76  }
77}
78
79// Endpoint describes a single IDS endpoint. It defines a forwarding rule to
80// which packets can be sent for IDS inspection.
81message Endpoint {
82  option (google.api.resource) = {
83    type: "ids.googleapis.com/Endpoint"
84    pattern: "projects/{project}/locations/{location}/endpoints/{endpoint}"
85  };
86
87  // Threat severity levels.
88  enum Severity {
89    // Not set.
90    SEVERITY_UNSPECIFIED = 0;
91
92    // Informational alerts.
93    INFORMATIONAL = 1;
94
95    // Low severity alerts.
96    LOW = 2;
97
98    // Medium severity alerts.
99    MEDIUM = 3;
100
101    // High severity alerts.
102    HIGH = 4;
103
104    // Critical severity alerts.
105    CRITICAL = 5;
106  }
107
108  // Endpoint state
109  enum State {
110    // Not set.
111    STATE_UNSPECIFIED = 0;
112
113    // Being created.
114    CREATING = 1;
115
116    // Active and ready for traffic.
117    READY = 2;
118
119    // Being deleted.
120    DELETING = 3;
121  }
122
123  // Output only. The name of the endpoint.
124  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
125
126  // Output only. The create time timestamp.
127  google.protobuf.Timestamp create_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
128
129  // Output only. The update time timestamp.
130  google.protobuf.Timestamp update_time = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
131
132  // The labels of the endpoint.
133  map<string, string> labels = 4;
134
135  // Required. The fully qualified URL of the network to which the IDS Endpoint is
136  // attached.
137  string network = 5 [(google.api.field_behavior) = REQUIRED];
138
139  // Output only. The fully qualified URL of the endpoint's ILB Forwarding Rule.
140  string endpoint_forwarding_rule = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
141
142  // Output only. The IP address of the IDS Endpoint's ILB.
143  string endpoint_ip = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
144
145  // User-provided description of the endpoint
146  string description = 8;
147
148  // Required. Lowest threat severity that this endpoint will alert on.
149  Severity severity = 9 [(google.api.field_behavior) = REQUIRED];
150
151  // Output only. Current state of the endpoint.
152  State state = 12 [(google.api.field_behavior) = OUTPUT_ONLY];
153
154  // Whether the endpoint should report traffic logs in addition to threat logs.
155  bool traffic_logs = 13;
156}
157
158message ListEndpointsRequest {
159  // Required. The parent, which owns this collection of endpoints.
160  string parent = 1 [
161    (google.api.field_behavior) = REQUIRED,
162    (google.api.resource_reference) = {
163      child_type: "ids.googleapis.com/Endpoint"
164    }
165  ];
166
167  // Optional. The maximum number of endpoints to return. The service may return fewer
168  // than this value.
169  int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
170
171  // Optional. A page token, received from a previous `ListEndpoints` call.
172  // Provide this to retrieve the subsequent page.
173  //
174  // When paginating, all other parameters provided to `ListEndpoints` must
175  // match the call that provided the page token.
176  string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
177
178  // Optional. The filter expression, following the syntax outlined in
179  // https://google.aip.dev/160.
180  string filter = 4 [(google.api.field_behavior) = OPTIONAL];
181
182  // Optional. One or more fields to compare and use to sort the output.
183  // See https://google.aip.dev/132#ordering.
184  string order_by = 5 [(google.api.field_behavior) = OPTIONAL];
185}
186
187message ListEndpointsResponse {
188  // The list of endpoints response.
189  repeated Endpoint endpoints = 1;
190
191  // A token, which can be sent as `page_token` to retrieve the next page.
192  // If this field is omitted, there are no subsequent pages.
193  string next_page_token = 2;
194
195  // Locations that could not be reached.
196  repeated string unreachable = 3;
197}
198
199message GetEndpointRequest {
200  // Required. The name of the endpoint to retrieve.
201  // Format: `projects/{project}/locations/{location}/endpoints/{endpoint}`
202  string name = 1 [
203    (google.api.field_behavior) = REQUIRED,
204    (google.api.resource_reference) = {
205      type: "ids.googleapis.com/Endpoint"
206    }
207  ];
208}
209
210message CreateEndpointRequest {
211  // Required. The endpoint's parent.
212  string parent = 1 [
213    (google.api.field_behavior) = REQUIRED,
214    (google.api.resource_reference) = {
215      child_type: "ids.googleapis.com/Endpoint"
216    }
217  ];
218
219  // Required. The endpoint identifier. This will be part of the endpoint's
220  // resource name.
221  // This value must start with a lowercase letter followed by up to 62
222  // lowercase letters, numbers, or hyphens, and cannot end with a hyphen.
223  // Values that do not match this pattern will trigger an INVALID_ARGUMENT
224  // error.
225  string endpoint_id = 2 [(google.api.field_behavior) = REQUIRED];
226
227  // Required. The endpoint to create.
228  Endpoint endpoint = 3 [(google.api.field_behavior) = REQUIRED];
229
230  // An optional request ID to identify requests. Specify a unique request ID
231  // so that if you must retry your request, the server will know to ignore
232  // the request if it has already been completed. The server will guarantee
233  // that for at least 60 minutes since the first request.
234  //
235  // For example, consider a situation where you make an initial request and t
236  // he request times out. If you make the request again with the same request
237  // ID, the server can check if original operation with the same request ID
238  // was received, and if so, will ignore the second request. This prevents
239  // clients from accidentally creating duplicate commitments.
240  //
241  // The request ID must be a valid UUID with the exception that zero UUID is
242  // not supported (00000000-0000-0000-0000-000000000000).
243  string request_id = 4;
244}
245
246message DeleteEndpointRequest {
247  // Required. The name of the endpoint to delete.
248  string name = 1 [
249    (google.api.field_behavior) = REQUIRED,
250    (google.api.resource_reference) = {
251      type: "ids.googleapis.com/Endpoint"
252    }
253  ];
254
255  // An optional request ID to identify requests. Specify a unique request ID
256  // so that if you must retry your request, the server will know to ignore
257  // the request if it has already been completed. The server will guarantee
258  // that for at least 60 minutes after the first request.
259  //
260  // For example, consider a situation where you make an initial request and t
261  // he request times out. If you make the request again with the same request
262  // ID, the server can check if original operation with the same request ID
263  // was received, and if so, will ignore the second request. This prevents
264  // clients from accidentally creating duplicate commitments.
265  //
266  // The request ID must be a valid UUID with the exception that zero UUID is
267  // not supported (00000000-0000-0000-0000-000000000000).
268  string request_id = 2;
269}
270
271// Represents the metadata of the long-running operation.
272message OperationMetadata {
273  // Output only. The time the operation was created.
274  google.protobuf.Timestamp create_time = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
275
276  // Output only. The time the operation finished running.
277  google.protobuf.Timestamp end_time = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
278
279  // Output only. Server-defined resource path for the target of the operation.
280  string target = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
281
282  // Output only. Name of the verb executed by the operation.
283  string verb = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
284
285  // Output only. Human-readable status of the operation, if any.
286  string status_message = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
287
288  // Output only. Identifies whether the user has requested cancellation
289  // of the operation. Operations that have successfully been cancelled
290  // have [Operation.error][] value with a [google.rpc.Status.code][google.rpc.Status.code] of 1,
291  // corresponding to `Code.CANCELLED`.
292  bool requested_cancellation = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
293
294  // Output only. API version used to start the operation.
295  string api_version = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
296}
297