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  }