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