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