audit

Documentation

Overview

TODO: Delete this file if we generate a clientset.

Index

• Variables
• func AddAuditAnnotation(ctx context.Context, key, value string)
• func AddAuditAnnotations(ctx context.Context, keysAndValues ...string)
• func AddAuditAnnotationsMap(ctx context.Context, annotations map[string]string)
• func AuditEventFrom(ctx context.Context) *auditinternal.Event
• func AuditIDFrom(ctx context.Context) (types.UID, bool)
• func EventString(ev *auditinternal.Event) string
• func GetAuditIDTruncated(ctx context.Context) string
• func HandlePluginError(plugin string, err error, impacted ...*auditinternal.Event)
• func LogImpersonatedUser(ae *auditinternal.Event, user user.Info)
• func LogRequestMetadata(ctx context.Context, req *http.Request, requestReceivedTimestamp time.Time, ...)
• func LogRequestObject(ctx context.Context, obj runtime.Object, objGV schema.GroupVersion, ...)
• func LogRequestPatch(ctx context.Context, patch []byte)
• func LogResponseObject(ctx context.Context, obj runtime.Object, gv schema.GroupVersion, ...)
• func ObserveEvent(ctx context.Context)
• func ObservePolicyLevel(ctx context.Context, level auditinternal.Level)
• func WithAuditContext(parent context.Context) context.Context
• func WithAuditID(ctx context.Context, auditID types.UID)
• type AuditContext
  • func AuditContextFrom(ctx context.Context) *AuditContext
  • func (ac *AuditContext) Enabled() bool
• type Backend
  • func Union(backends ...Backend) Backend
• type PolicyRuleEvaluator
• type RequestAuditConfig
• type Sink

Variables

var (
	ApiserverAuditDroppedCounter = metrics.NewCounter(
		&metrics.CounterOpts{
			Subsystem: subsystem,
			Name:      "requests_rejected_total",
			Help: "Counter of apiserver requests rejected due to an error " +
				"in audit logging backend.",
			StabilityLevel: metrics.ALPHA,
		},
	)
)

* By default, all the following metrics are defined as falling under * ALPHA stability level https://github.com/kubernetes/enhancements/blob/master/keps/sig-instrumentation/1209-metrics-stability/kubernetes-control-plane-metrics-stability.md#stability-classes) * * Promoting the stability level of the metric is a responsibility of the component owner, since it * involves explicitly acknowledging support for the metric across multiple releases, in accordance with * the metric stability policy.

var Codecs = serializer.NewCodecFactory(Scheme)

var Scheme = runtime.NewScheme()

Functions

func AddAuditAnnotation

func AddAuditAnnotation(ctx context.Context, key, value string)

AddAuditAnnotation sets the audit annotation for the given key, value pair. It is safe to call at most parts of request flow that come after WithAuditAnnotations. The notable exception being that this function must not be called via a defer statement (i.e. after ServeHTTP) in a handler that runs before WithAudit as at that point the audit event has already been sent to the audit sink. Handlers that are unaware of their position in the overall request flow should prefer AddAuditAnnotation over LogAnnotation to avoid dropping annotations.

func AddAuditAnnotations

func AddAuditAnnotations(ctx context.Context, keysAndValues ...string)

AddAuditAnnotations is a bulk version of AddAuditAnnotation. Refer to AddAuditAnnotation for restrictions on when this can be called. keysAndValues are the key-value pairs to add, and must have an even number of items.

func AddAuditAnnotationsMap

func AddAuditAnnotationsMap(ctx context.Context, annotations map[string]string)

AddAuditAnnotationsMap is a bulk version of AddAuditAnnotation. Refer to AddAuditAnnotation for restrictions on when this can be called.

func AuditEventFrom

func AuditEventFrom(ctx context.Context) *auditinternal.Event

AuditEventFrom returns the audit event struct on the ctx

func AuditIDFrom

func AuditIDFrom(ctx context.Context) (types.UID, bool)

AuditIDFrom returns the value of the audit ID from the request context, along with whether auditing is enabled.

func EventString

func EventString(ev *auditinternal.Event) string

EventString creates a 1-line text representation of an audit event, using a subset of the information in the event struct.

func GetAuditIDTruncated

func GetAuditIDTruncated(ctx context.Context) string

GetAuditIDTruncated returns the audit ID (truncated) from the request context. If the length of the Audit-ID value exceeds the limit, we truncate it to keep the first N (maxAuditIDLength) characters. This is intended to be used in logging only.

func HandlePluginError

func HandlePluginError(plugin string, err error, impacted ...*auditinternal.Event)

HandlePluginError handles an error that occurred in an audit plugin. This method should only be used if the error may have prevented the audit event from being properly recorded. The events are logged to the debug log.

func LogImpersonatedUser

func LogImpersonatedUser(ae *auditinternal.Event, user user.Info)

LogImpersonatedUser fills in the impersonated user attributes into an audit event.

func LogRequestMetadata

func LogRequestMetadata(ctx context.Context, req *http.Request, requestReceivedTimestamp time.Time, level auditinternal.Level, attribs authorizer.Attributes)

func LogRequestObject

func LogRequestObject(ctx context.Context, obj runtime.Object, objGV schema.GroupVersion, gvr schema.GroupVersionResource, subresource string, s runtime.NegotiatedSerializer)

LogRequestObject fills in the request object into an audit event. The passed runtime.Object will be converted to the given gv.

func LogRequestPatch

func LogRequestPatch(ctx context.Context, patch []byte)

LogRequestPatch fills in the given patch as the request object into an audit event.

func LogResponseObject

func LogResponseObject(ctx context.Context, obj runtime.Object, gv schema.GroupVersion, s runtime.NegotiatedSerializer)

LogResponseObject fills in the response object into an audit event. The passed runtime.Object will be converted to the given gv.

func ObserveEvent

func ObserveEvent(ctx context.Context)

ObserveEvent updates the relevant prometheus metrics for the generated audit event.

func ObservePolicyLevel

func ObservePolicyLevel(ctx context.Context, level auditinternal.Level)

ObservePolicyLevel updates the relevant prometheus metrics with the audit level for a request.

func WithAuditContext

func WithAuditContext(parent context.Context) context.Context

WithAuditContext returns a new context that stores the AuditContext.

func WithAuditID

func WithAuditID(ctx context.Context, auditID types.UID)

WithAuditID sets the AuditID on the AuditContext. The AuditContext must already be present in the request context. If the specified auditID is empty, no value is set.

Types

type AuditContext

type AuditContext struct {
	// RequestAuditConfig is the audit configuration that applies to the request
	RequestAuditConfig RequestAuditConfig

	// Event is the audit Event object that is being captured to be written in
	// the API audit log.
	Event auditinternal.Event
	// contains filtered or unexported fields
}

AuditContext holds the information for constructing the audit events for the current request.

func AuditContextFrom

func AuditContextFrom(ctx context.Context) *AuditContext

AuditContextFrom returns the pair of the audit configuration object that applies to the given request and the audit event that is going to be written to the API audit log.

func (*AuditContext) Enabled

func (ac *AuditContext) Enabled() bool

Enabled checks whether auditing is enabled for this audit context.

type Backend

type Backend interface {
	Sink

	// Run will initialize the backend. It must not block, but may run go routines in the background. If
	// stopCh is closed, it is supposed to stop them. Run will be called before the first call to ProcessEvents.
	Run(stopCh <-chan struct{}) error

	// Shutdown will synchronously shut down the backend while making sure that all pending
	// events are delivered. It can be assumed that this method is called after
	// the stopCh channel passed to the Run method has been closed.
	Shutdown()

	// Returns the backend PluginName.
	String() string
}

func Union

func Union(backends ...Backend) Backend

Union returns an audit Backend which logs events to a set of backends. The returned Sink implementation blocks in turn for each call to ProcessEvents.

type PolicyRuleEvaluator

type PolicyRuleEvaluator interface {
	// EvaluatePolicyRule evaluates the audit policy of the apiserver against
	// the given authorizer attributes and returns the audit configuration that
	// is applicable to the given equest.
	EvaluatePolicyRule(authorizer.Attributes) RequestAuditConfig
}

PolicyRuleEvaluator exposes methods for evaluating the policy rules.

type RequestAuditConfig

type RequestAuditConfig struct {
	// Level at which the request is being audited at
	Level audit.Level

	// OmitStages is the stages that need to be omitted from being audited.
	OmitStages []audit.Stage

	// OmitManagedFields indicates whether to omit the managed fields of the request
	// and response bodies from being written to the API audit log.
	OmitManagedFields bool
}

RequestAuditConfig is the evaluated audit configuration that is applicable to a given request. PolicyRuleEvaluator evaluates the audit policy against the authorizer attributes and returns a RequestAuditConfig that applies to the request.

type Sink

type Sink interface {
	// ProcessEvents handles events. Per audit ID it might be that ProcessEvents is called up to three times.
	// Errors might be logged by the sink itself. If an error should be fatal, leading to an internal
	// error, ProcessEvents is supposed to panic. The event must not be mutated and is reused by the caller
	// after the call returns, i.e. the sink has to make a deepcopy to keep a copy around if necessary.
	// Returns true on success, may return false on error.
	ProcessEvents(events ...*auditinternal.Event) bool
}