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 
15 syntax = "proto3";
16 
17 package google.cloud.ids.v1;
18 
19 import "google/api/annotations.proto";
20 import "google/api/client.proto";
21 import "google/api/field_behavior.proto";
22 import "google/api/resource.proto";
23 import "google/longrunning/operations.proto";
24 import "google/protobuf/timestamp.proto";
25 
26 option go_package = "cloud.google.com/go/ids/apiv1/idspb;idspb";
27 option java_multiple_files = true;
28 option java_outer_classname = "IdsProto";
29 option java_package = "com.google.cloud.ids.v1";
30 option ruby_package = "Google::Cloud::IDS::V1";
31 
32 // The IDS Service
33 service 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.
81 message 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 
158 message 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 
187 message 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 
199 message 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 
210 message 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 
246 message 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.
272 message 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