1/* 2Copyright 2017 The Kubernetes Authors. 3 4Licensed under the Apache License, Version 2.0 (the "License"); 5you may not use this file except in compliance with the License. 6You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10Unless required by applicable law or agreed to in writing, software 11distributed under the License is distributed on an "AS IS" BASIS, 12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13See the License for the specific language governing permissions and 14limitations under the License. 15*/ 16 17package v1alpha1 18 19import ( 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. 27const ( 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 42type Level string 43 44// Valid audit levels 45const ( 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. 59type Stage string 60 61// Valid audit stages. 62const ( 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// +k8s:prerelease-lifecycle-gen:introduced=1.7 78// +k8s:prerelease-lifecycle-gen:deprecated=1.21 79// +k8s:prerelease-lifecycle-gen:replacement=audit.k8s.io,v1,Event 80 81// DEPRECATED - This group version of Event is deprecated by audit.k8s.io/v1/Event. See the release notes for 82// more information. 83// Event captures all the information that can be included in an API audit log. 84type Event struct { 85 metav1.TypeMeta `json:",inline"` 86 // ObjectMeta is included for interoperability with API infrastructure. 87 // +optional 88 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 89 90 // AuditLevel at which event was generated 91 Level Level `json:"level" protobuf:"bytes,2,opt,name=level,casttype=Level"` 92 93 // Time the request reached the apiserver. 94 Timestamp metav1.Time `json:"timestamp" protobuf:"bytes,3,opt,name=timestamp"` 95 // Unique audit ID, generated for each request. 96 AuditID types.UID `json:"auditID" protobuf:"bytes,4,opt,name=auditID,casttype=k8s.io/apimachinery/pkg/types.UID"` 97 // Stage of the request handling when this event instance was generated. 98 Stage Stage `json:"stage" protobuf:"bytes,5,opt,name=stage,casttype=Stage"` 99 100 // RequestURI is the request URI as sent by the client to a server. 101 RequestURI string `json:"requestURI" protobuf:"bytes,6,opt,name=requestURI"` 102 // Verb is the kubernetes verb associated with the request. 103 // For non-resource requests, this is the lower-cased HTTP method. 104 Verb string `json:"verb" protobuf:"bytes,7,opt,name=verb"` 105 // Authenticated user information. 106 User authnv1.UserInfo `json:"user" protobuf:"bytes,8,opt,name=user"` 107 // Impersonated user information. 108 // +optional 109 ImpersonatedUser *authnv1.UserInfo `json:"impersonatedUser,omitempty" protobuf:"bytes,9,opt,name=impersonatedUser"` 110 // Source IPs, from where the request originated and intermediate proxies. 111 // +optional 112 SourceIPs []string `json:"sourceIPs,omitempty" protobuf:"bytes,10,rep,name=sourceIPs"` 113 // UserAgent records the user agent string reported by the client. 114 // Note that the UserAgent is provided by the client, and must not be trusted. 115 // +optional 116 UserAgent string `json:"userAgent,omitempty" protobuf:"bytes,18,opt,name=userAgent"` 117 // Object reference this request is targeted at. 118 // Does not apply for List-type requests, or non-resource requests. 119 // +optional 120 ObjectRef *ObjectReference `json:"objectRef,omitempty" protobuf:"bytes,11,opt,name=objectRef"` 121 // The response status, populated even when the ResponseObject is not a Status type. 122 // For successful responses, this will only include the Code and StatusSuccess. 123 // For non-status type error responses, this will be auto-populated with the error Message. 124 // +optional 125 ResponseStatus *metav1.Status `json:"responseStatus,omitempty" protobuf:"bytes,12,opt,name=responseStatus"` 126 127 // API object from the request, in JSON format. The RequestObject is recorded as-is in the request 128 // (possibly re-encoded as JSON), prior to version conversion, defaulting, admission or 129 // merging. It is an external versioned object type, and may not be a valid object on its own. 130 // Omitted for non-resource requests. Only logged at Request Level and higher. 131 // +optional 132 RequestObject *runtime.Unknown `json:"requestObject,omitempty" protobuf:"bytes,13,opt,name=requestObject"` 133 // API object returned in the response, in JSON. The ResponseObject is recorded after conversion 134 // to the external type, and serialized as JSON. Omitted for non-resource requests. Only logged 135 // at Response Level. 136 // +optional 137 ResponseObject *runtime.Unknown `json:"responseObject,omitempty" protobuf:"bytes,14,opt,name=responseObject"` 138 // Time the request reached the apiserver. 139 // +optional 140 RequestReceivedTimestamp metav1.MicroTime `json:"requestReceivedTimestamp" protobuf:"bytes,15,opt,name=requestReceivedTimestamp"` 141 // Time the request reached current audit stage. 142 // +optional 143 StageTimestamp metav1.MicroTime `json:"stageTimestamp" protobuf:"bytes,16,opt,name=stageTimestamp"` 144 145 // Annotations is an unstructured key value map stored with an audit event that may be set by 146 // plugins invoked in the request serving chain, including authentication, authorization and 147 // admission plugins. Note that these annotations are for the audit event, and do not correspond 148 // to the metadata.annotations of the submitted object. Keys should uniquely identify the informing 149 // component to avoid name collisions (e.g. podsecuritypolicy.admission.k8s.io/policy). Values 150 // should be short. Annotations are included in the Metadata level. 151 // +optional 152 Annotations map[string]string `json:"annotations,omitempty" protobuf:"bytes,17,rep,name=annotations"` 153} 154 155// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 156// +k8s:prerelease-lifecycle-gen:introduced=1.7 157// +k8s:prerelease-lifecycle-gen:deprecated=1.21 158// +k8s:prerelease-lifecycle-gen:replacement=audit.k8s.io,v1,EventList 159 160// EventList is a list of audit Events. 161type EventList struct { 162 metav1.TypeMeta `json:",inline"` 163 // +optional 164 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 165 166 Items []Event `json:"items" protobuf:"bytes,2,rep,name=items"` 167} 168 169// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 170// +k8s:prerelease-lifecycle-gen:introduced=1.7 171// +k8s:prerelease-lifecycle-gen:deprecated=1.21 172// +k8s:prerelease-lifecycle-gen:replacement=audit.k8s.io,v1,Policy 173 174// DEPRECATED - This group version of Policy is deprecated by audit.k8s.io/v1/Policy. See the release notes for 175// more information. 176// Policy defines the configuration of audit logging, and the rules for how different request 177// categories are logged. 178type Policy struct { 179 metav1.TypeMeta `json:",inline"` 180 // ObjectMeta is included for interoperability with API infrastructure. 181 // +optional 182 metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 183 184 // Rules specify the audit Level a request should be recorded at. 185 // A request may match multiple rules, in which case the FIRST matching rule is used. 186 // The default audit level is None, but can be overridden by a catch-all rule at the end of the list. 187 // PolicyRules are strictly ordered. 188 Rules []PolicyRule `json:"rules" protobuf:"bytes,2,rep,name=rules"` 189 190 // OmitStages is a list of stages for which no events are created. Note that this can also 191 // be specified per rule in which case the union of both are omitted. 192 // +optional 193 OmitStages []Stage `json:"omitStages,omitempty" protobuf:"bytes,3,rep,name=omitStages"` 194} 195 196// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object 197// +k8s:prerelease-lifecycle-gen:introduced=1.7 198// +k8s:prerelease-lifecycle-gen:deprecated=1.21 199// +k8s:prerelease-lifecycle-gen:replacement=audit.k8s.io,v1,PolicyList 200 201// PolicyList is a list of audit Policies. 202type PolicyList struct { 203 metav1.TypeMeta `json:",inline"` 204 // +optional 205 metav1.ListMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"` 206 207 Items []Policy `json:"items" protobuf:"bytes,2,rep,name=items"` 208} 209 210// PolicyRule maps requests based off metadata to an audit Level. 211// Requests must match the rules of every field (an intersection of rules). 212type PolicyRule struct { 213 // The Level that requests matching this rule are recorded at. 214 Level Level `json:"level" protobuf:"bytes,1,opt,name=level,casttype=Level"` 215 216 // The users (by authenticated user name) this rule applies to. 217 // An empty list implies every user. 218 // +optional 219 Users []string `json:"users,omitempty" protobuf:"bytes,2,rep,name=users"` 220 // The user groups this rule applies to. A user is considered matching 221 // if it is a member of any of the UserGroups. 222 // An empty list implies every user group. 223 // +optional 224 UserGroups []string `json:"userGroups,omitempty" protobuf:"bytes,3,rep,name=userGroups"` 225 226 // The verbs that match this rule. 227 // An empty list implies every verb. 228 // +optional 229 Verbs []string `json:"verbs,omitempty" protobuf:"bytes,4,rep,name=verbs"` 230 231 // Rules can apply to API resources (such as "pods" or "secrets"), 232 // non-resource URL paths (such as "/api"), or neither, but not both. 233 // If neither is specified, the rule is treated as a default for all URLs. 234 235 // Resources that this rule matches. An empty list implies all kinds in all API groups. 236 // +optional 237 Resources []GroupResources `json:"resources,omitempty" protobuf:"bytes,5,rep,name=resources"` 238 // Namespaces that this rule matches. 239 // The empty string "" matches non-namespaced resources. 240 // An empty list implies every namespace. 241 // +optional 242 Namespaces []string `json:"namespaces,omitempty" protobuf:"bytes,6,rep,name=namespaces"` 243 244 // NonResourceURLs is a set of URL paths that should be audited. 245 // *s are allowed, but only as the full, final step in the path. 246 // Examples: 247 // "/metrics" - Log requests for apiserver metrics 248 // "/healthz*" - Log all health checks 249 // +optional 250 NonResourceURLs []string `json:"nonResourceURLs,omitempty" protobuf:"bytes,7,rep,name=nonResourceURLs"` 251 252 // OmitStages is a list of stages for which no events are created. Note that this can also 253 // be specified policy wide in which case the union of both are omitted. 254 // An empty list means no restrictions will apply. 255 // +optional 256 OmitStages []Stage `json:"omitStages,omitempty" protobuf:"bytes,8,rep,name=omitStages"` 257} 258 259// GroupResources represents resource kinds in an API group. 260type GroupResources struct { 261 // Group is the name of the API group that contains the resources. 262 // The empty string represents the core API group. 263 // +optional 264 Group string `json:"group,omitempty" protobuf:"bytes,1,opt,name=group"` 265 // Resources is a list of resources this rule applies to. 266 // 267 // For example: 268 // 'pods' matches pods. 269 // 'pods/log' matches the log subresource of pods. 270 // '*' matches all resources and their subresources. 271 // 'pods/*' matches all subresources of pods. 272 // '*/scale' matches all scale subresources. 273 // 274 // If wildcard is present, the validation rule will ensure resources do not 275 // overlap with each other. 276 // 277 // An empty list implies all resources and subresources in this API groups apply. 278 // +optional 279 Resources []string `json:"resources,omitempty" protobuf:"bytes,2,rep,name=resources"` 280 // ResourceNames is a list of resource instance names that the policy matches. 281 // Using this field requires Resources to be specified. 282 // An empty list implies that every instance of the resource is matched. 283 // +optional 284 ResourceNames []string `json:"resourceNames,omitempty" protobuf:"bytes,3,rep,name=resourceNames"` 285} 286 287// ObjectReference contains enough information to let you inspect or modify the referred object. 288type ObjectReference struct { 289 // +optional 290 Resource string `json:"resource,omitempty" protobuf:"bytes,1,opt,name=resource"` 291 // +optional 292 Namespace string `json:"namespace,omitempty" protobuf:"bytes,2,opt,name=namespace"` 293 // +optional 294 Name string `json:"name,omitempty" protobuf:"bytes,3,opt,name=name"` 295 // +optional 296 UID types.UID `json:"uid,omitempty" protobuf:"bytes,4,opt,name=uid,casttype=k8s.io/apimachinery/pkg/types.UID"` 297 // +optional 298 APIVersion string `json:"apiVersion,omitempty" protobuf:"bytes,5,opt,name=apiVersion"` 299 // +optional 300 ResourceVersion string `json:"resourceVersion,omitempty" protobuf:"bytes,6,opt,name=resourceVersion"` 301 // +optional 302 Subresource string `json:"subresource,omitempty" protobuf:"bytes,7,opt,name=subresource"` 303} 304