Debian Codegraph @

pkg/apis/audit/v1/types.go

raw
1 /*
2 Copyright 2018 The Kubernetes Authors.
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 */
16
17 package v1
18
19 import (
20 authnv1 "k8s.io/api/authentication/v1"
21 metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
22 "k8s.io/apimachinery/pkg/runtime"
23 "k8s.io/apimachinery/pkg/types"
24 )
25
26 // Header keys used by the audit system.
27 const (
28 // Header to hold the audit ID as the request is propagated through the serving hierarchy. The
29 // Audit-ID header should be set by the first server to receive the request (e.g. the federation
30 // server or kube-aggregator).
31 HeaderAuditID = "Audit-ID"
32 )
33
34 // Level defines the amount of information logged during auditing
35 type Level string
36
37 // Valid audit levels
38 const (
39 // LevelNone disables auditing
40 LevelNone Level = "None"
41 // LevelMetadata provides the basic level of auditing.
42 LevelMetadata Level = "Metadata"
43 // LevelRequest provides Metadata level of auditing, and additionally
44 // logs the request object (does not apply for non-resource requests).
45 LevelRequest Level = "Request"
46 // LevelRequestResponse provides Request level of auditing, and additionally
47 // logs the response object (does not apply for non-resource requests).
48 LevelRequestResponse Level = "RequestResponse"
49 )
50
51 // Stage defines the stages in request handling that audit events may be generated.
52 type Stage string
53
54 // Valid audit stages.
55 const (
56 // The stage for events generated as soon as the audit handler receives the request, and before it
57 // is delegated down the handler chain.
58 StageRequestReceived Stage = "RequestReceived"
59 // The stage for events generated once the response headers are sent, but before the response body
60 // is sent. This stage is only generated for long-running requests (e.g. watch).
61 StageResponseStarted Stage = "ResponseStarted"
62 // The stage for events generated once the response body has been completed, and no more bytes
63 // will be sent.
64 StageResponseComplete Stage = "ResponseComplete"
65 // The stage for events generated when a panic occurred.
66 StagePanic Stage = "Panic"
67 )
68
69 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
70
71 // Event captures all the information that can be included in an API audit log.
72 type Event struct {
73 metav1.TypeMeta `json:",inline"`
74
75 // AuditLevel at which event was generated
76 Level Level `json:"level" protobuf:"bytes,1,opt,name=level,casttype=Level"`
77
78 // Unique audit ID, generated for each request.
79 AuditID types.UID `json:"auditID" protobuf:"bytes,2,opt,name=auditID,casttype=k8s.io/apimachinery/pkg/types.UID"`
80 // Stage of the request handling when this event instance was generated.
81 Stage Stage `json:"stage" protobuf:"bytes,3,opt,name=stage,casttype=Stage"`
82
83 // RequestURI is the request URI as sent by the client to a server.
84 RequestURI string `json:"requestURI" protobuf:"bytes,4,opt,name=requestURI"`
85 // Verb is the kubernetes verb associated with the request.
86 // For non-resource requests, this is the lower-cased HTTP method.
87 Verb string `json:"verb" protobuf:"bytes,5,opt,name=verb"`
88 // Authenticated user information.
89 User authnv1.UserInfo `json:"user" protobuf:"bytes,6,opt,name=user"`
90 // Impersonated user information.
91 // +optional
92 ImpersonatedUser *authnv1.UserInfo `json:"impersonatedUser,omitempty" protobuf:"bytes,7,opt,name=impersonatedUser"`
93 // Source IPs, from where the request originated and intermediate proxies.
94 // The source IPs are listed from (in order):
95 // 1. X-Forwarded-For request header IPs
96 // 2. X-Real-Ip header, if not present in the X-Forwarded-For list
97 // 3. The remote address for the connection, if it doesn't match the last
98 // IP in the list up to here (X-Forwarded-For or X-Real-Ip).
99 // Note: All but the last IP can be arbitrarily set by the client.
100 // +optional
101 // +listType=atomic
102 SourceIPs []string `json:"sourceIPs,omitempty" protobuf:"bytes,8,rep,name=sourceIPs"`
103 // UserAgent records the user agent string reported by the client.
104 // Note that the UserAgent is provided by the client, and must not be trusted.
105 // +optional
106 UserAgent string `json:"userAgent,omitempty" protobuf:"bytes,16,opt,name=userAgent"`
107 // Object reference this request is targeted at.
108 // Does not apply for List-type requests, or non-resource requests.
109 // +optional
110 ObjectRef *ObjectReference `json:"objectRef,omitempty" protobuf:"bytes,9,opt,name=objectRef"`
111 // The response status, populated even when the ResponseObject is not a Status type.
112 // For successful responses, this will only include the Code and StatusSuccess.
113 // For non-status type error responses, this will be auto-populated with the error Message.
114 // +optional
115 ResponseStatus *metav1.Status `json:"responseStatus,omitempty" protobuf:"bytes,10,opt,name=responseStatus"`
116
117 // API object from the request, in JSON format. The RequestObject is recorded as-is in the request
118 // (possibly re-encoded as JSON), prior to version conversion, defaulting, admission or
119 // merging. It is an external versioned object type, and may not be a valid object on its own.
120 // Omitted for non-resource requests. Only logged at Request Level and higher.
121 // +optional
122 RequestObject *runtime.Unknown `json:"requestObject,omitempty" protobuf:"bytes,11,opt,name=requestObject"`
123 // API object returned in the response, in JSON. The ResponseObject is recorded after conversion
124 // to the external type, and serialized as JSON. Omitted for non-resource requests. Only logged
125 // at Response Level.
126 // +optional
127 ResponseObject *runtime.Unknown `json:"responseObject,omitempty" protobuf:"bytes,12,opt,name=responseObject"`
128 // Time the request reached the apiserver.
129 // +optional
130 RequestReceivedTimestamp metav1.MicroTime `json:"requestReceivedTimestamp" protobuf:"bytes,13,opt,name=requestReceivedTimestamp"`
131 // Time the request reached current audit stage.
132 // +optional
133 StageTimestamp metav1.MicroTime `json:"stageTimestamp" protobuf:"bytes,14,opt,name=stageTimestamp"`
134
135 // Annotations is an unstructured key value map stored with an audit event that may be set by
136 // plugins invoked in the request serving chain, including authentication, authorization and
137 // admission plugins. Note that these annotations are for the audit event, and do not correspond
138 // to the metadata.annotations of the submitted object. Keys should uniquely identify the informing
139 // component to avoid name collisions (e.g. podsecuritypolicy.admission.k8s.io/policy). Values
140 // should be short. Annotations are included in the Metadata level.
141 // +optional
142 Annotations map[string]string `json:"annotations,omitempty" protobuf:"bytes,15,rep,name=annotations"`
143 }
144
145 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
146
147 // EventList is a list of audit Events.
148 type EventList struct {
149 metav1.TypeMeta `json:",inline"`
150 // +optional
151 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
152
153 Items []Event `json:"items" protobuf:"bytes,2,rep,name=items"`
154 }
155
156 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
157
158 // Policy defines the configuration of audit logging, and the rules for how different request
159 // categories are logged.
160 type Policy struct {
161 metav1.TypeMeta `json:",inline"`
162 // ObjectMeta is included for interoperability with API infrastructure.
163 // +optional
164 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
165
166 // Rules specify the audit Level a request should be recorded at.
167 // A request may match multiple rules, in which case the FIRST matching rule is used.
168 // The default audit level is None, but can be overridden by a catch-all rule at the end of the list.
169 // PolicyRules are strictly ordered.
170 // +listType=atomic
171 Rules []PolicyRule `json:"rules" protobuf:"bytes,2,rep,name=rules"`
172
173 // OmitStages is a list of stages for which no events are created. Note that this can also
174 // be specified per rule in which case the union of both are omitted.
175 // +optional
176 // +listType=atomic
177 OmitStages []Stage `json:"omitStages,omitempty" protobuf:"bytes,3,rep,name=omitStages"`
178
179 // OmitManagedFields indicates whether to omit the managed fields of the request
180 // and response bodies from being written to the API audit log.
181 // This is used as a global default - a value of 'true' will omit the managed fileds,
182 // otherwise the managed fields will be included in the API audit log.
183 // Note that this can also be specified per rule in which case the value specified
184 // in a rule will override the global default.
185 // +optional
186 OmitManagedFields bool `json:"omitManagedFields,omitempty" protobuf:"varint,4,opt,name=omitManagedFields"`
187 }
188
189 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
190
191 // PolicyList is a list of audit Policies.
192 type PolicyList struct {
193 metav1.TypeMeta `json:",inline"`
194 // +optional
195 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
196
197 Items []Policy `json:"items" protobuf:"bytes,2,rep,name=items"`
198 }
199
200 // PolicyRule maps requests based off metadata to an audit Level.
201 // Requests must match the rules of every field (an intersection of rules).
202 type PolicyRule struct {
203 // The Level that requests matching this rule are recorded at.
204 Level Level `json:"level" protobuf:"bytes,1,opt,name=level,casttype=Level"`
205
206 // The users (by authenticated user name) this rule applies to.
207 // An empty list implies every user.
208 // +optional
209 // +listType=atomic
210 Users []string `json:"users,omitempty" protobuf:"bytes,2,rep,name=users"`
211 // The user groups this rule applies to. A user is considered matching
212 // if it is a member of any of the UserGroups.
213 // An empty list implies every user group.
214 // +optional
215 // +listType=atomic
216 UserGroups []string `json:"userGroups,omitempty" protobuf:"bytes,3,rep,name=userGroups"`
217
218 // The verbs that match this rule.
219 // An empty list implies every verb.
220 // +optional
221 // +listType=atomic
222 Verbs []string `json:"verbs,omitempty" protobuf:"bytes,4,rep,name=verbs"`
223
224 // Rules can apply to API resources (such as "pods" or "secrets"),
225 // non-resource URL paths (such as "/api"), or neither, but not both.
226 // If neither is specified, the rule is treated as a default for all URLs.
227
228 // Resources that this rule matches. An empty list implies all kinds in all API groups.
229 // +optional
230 // +listType=atomic
231 Resources []GroupResources `json:"resources,omitempty" protobuf:"bytes,5,rep,name=resources"`
232 // Namespaces that this rule matches.
233 // The empty string "" matches non-namespaced resources.
234 // An empty list implies every namespace.
235 // +optional
236 // +listType=atomic
237 Namespaces []string `json:"namespaces,omitempty" protobuf:"bytes,6,rep,name=namespaces"`
238
239 // NonResourceURLs is a set of URL paths that should be audited.
240 // `*`s are allowed, but only as the full, final step in the path.
241 // Examples:
242 // - `/metrics` - Log requests for apiserver metrics
243 // - `/healthz*` - Log all health checks
244 // +optional
245 // +listType=atomic
246 NonResourceURLs []string `json:"nonResourceURLs,omitempty" protobuf:"bytes,7,rep,name=nonResourceURLs"`
247
248 // OmitStages is a list of stages for which no events are created. Note that this can also
249 // be specified policy wide in which case the union of both are omitted.
250 // An empty list means no restrictions will apply.
251 // +optional
252 // +listType=atomic
253 OmitStages []Stage `json:"omitStages,omitempty" protobuf:"bytes,8,rep,name=omitStages"`
254
255 // OmitManagedFields indicates whether to omit the managed fields of the request
256 // and response bodies from being written to the API audit log.
257 // - a value of 'true' will drop the managed fields from the API audit log
258 // - a value of 'false' indicates that the managed fileds should be included
259 // in the API audit log
260 // Note that the value, if specified, in this rule will override the global default
261 // If a value is not specified then the global default specified in
262 // Policy.OmitManagedFields will stand.
263 // +optional
264 OmitManagedFields *bool `json:"omitManagedFields,omitempty" protobuf:"varint,9,opt,name=omitManagedFields"`
265 }
266
267 // GroupResources represents resource kinds in an API group.
268 type GroupResources struct {
269 // Group is the name of the API group that contains the resources.
270 // The empty string represents the core API group.
271 // +optional
272 Group string `json:"group,omitempty" protobuf:"bytes,1,opt,name=group"`
273 // Resources is a list of resources this rule applies to.
274 //
275 // For example:
276 // - `pods` matches pods.
277 // - `pods/log` matches the log subresource of pods.
278 // - `*` matches all resources and their subresources.
279 // - `pods/*` matches all subresources of pods.
280 // - `*/scale` matches all scale subresources.
281 //
282 // If wildcard is present, the validation rule will ensure resources do not
283 // overlap with each other.
284 //
285 // An empty list implies all resources and subresources in this API groups apply.
286 // +optional
287 // +listType=atomic
288 Resources []string `json:"resources,omitempty" protobuf:"bytes,2,rep,name=resources"`
289 // ResourceNames is a list of resource instance names that the policy matches.
290 // Using this field requires Resources to be specified.
291 // An empty list implies that every instance of the resource is matched.
292 // +optional
293 // +listType=atomic
294 ResourceNames []string `json:"resourceNames,omitempty" protobuf:"bytes,3,rep,name=resourceNames"`
295 }
296
297 // ObjectReference contains enough information to let you inspect or modify the referred object.
298 type ObjectReference struct {
299 // +optional
300 Resource string `json:"resource,omitempty" protobuf:"bytes,1,opt,name=resource"`
301 // +optional
302 Namespace string `json:"namespace,omitempty" protobuf:"bytes,2,opt,name=namespace"`
303 // +optional
304 Name string `json:"name,omitempty" protobuf:"bytes,3,opt,name=name"`
305 // +optional
306 UID types.UID `json:"uid,omitempty" protobuf:"bytes,4,opt,name=uid,casttype=k8s.io/apimachinery/pkg/types.UID"`
307 // APIGroup is the name of the API group that contains the referred object.
308 // The empty string represents the core API group.
309 // +optional
310 APIGroup string `json:"apiGroup,omitempty" protobuf:"bytes,5,opt,name=apiGroup"`
311 // APIVersion is the version of the API group that contains the referred object.
312 // +optional
313 APIVersion string `json:"apiVersion,omitempty" protobuf:"bytes,6,opt,name=apiVersion"`
314 // +optional
315 ResourceVersion string `json:"resourceVersion,omitempty" protobuf:"bytes,7,opt,name=resourceVersion"`
316 // +optional
317 Subresource string `json:"subresource,omitempty" protobuf:"bytes,8,opt,name=subresource"`
318 }