audit

Documentation

Overview

Package audit provides functionality to validate and emit application audit logs.

Index

• Variables
• func LogReqFromCtx(ctx context.Context) (*api.AuditLogRequest, bool)
• type Client
  • func NewClient(options ...Option) (*Client, error)
  • func (c *Client) Log(ctx context.Context, logReq *api.AuditLogRequest) error
  • func (c *Client) Stop() error
• type Interceptor
  • func NewInterceptor(options ...InterceptorOption) (*Interceptor, error)
  • func (i *Interceptor) StreamInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, ...) error
  • func (i *Interceptor) UnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, ...) (interface{}, error)
• type InterceptorOption
  • func WithAuditClient(c *Client) InterceptorOption
  • func WithAuditRules(rs ...*api.AuditRule) InterceptorOption
  • func WithInterceptorLogMode(m api.AuditLogRequest_LogMode) InterceptorOption
  • func WithSecurityContext(sc security.GRPCContext) InterceptorOption
• type LabelProcessor
  • func (p *LabelProcessor) Process(ctx context.Context, logReq *api.AuditLogRequest) error
• type LogProcessor
• type Option
  • func WithBackend(p LogProcessor) Option
  • func WithLogMode(mode api.AuditLogRequest_LogMode) Option
  • func WithMutator(p LogProcessor) Option
  • func WithRuntimeInfo() Option
  • func WithValidator(p LogProcessor) Option
• type StoppableProcessor

Variables

var (
	// ErrInvalidRequest is the (base) error to return when a log processor
	// considers a log request is invalid.
	ErrInvalidRequest = fmt.Errorf("invalid audit log request")

	// ErrFailedPrecondition is the (base) error to return when a log processor
	// considers a log request should not continue to be processed by any remaining
	// log processors. The audit client will not return this type of errors.
	ErrFailedPrecondition = fmt.Errorf("failed precondition")
)

Functions

func LogReqFromCtx

func LogReqFromCtx(ctx context.Context) (*api.AuditLogRequest, bool)

LogReqFromCtx returns the AuditLogRequest stored in the context. If the AuditLogRequest doesn't exist, we return an empty one.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the Lumberjack audit logging Client.

func NewClient

func NewClient(options ...Option) (*Client, error)

NewClient initializes a logger with the given options.

func (*Client) Log

func (c *Client) Log(ctx context.Context, logReq *api.AuditLogRequest) error

Log runs the client processors sequentially on the given AuditLogRequest.

func (*Client) Stop

func (c *Client) Stop() error

Stop stops the client.

type Interceptor

type Interceptor struct {
	*Client
	// contains filtered or unexported fields
}

Interceptor contains the fields required for an interceptor to autofill and emit audit logs.

func NewInterceptor

func NewInterceptor(options ...InterceptorOption) (*Interceptor, error)

NewInterceptor creates a new interceptor with the given options.

func (*Interceptor) StreamInterceptor

func (i *Interceptor) StreamInterceptor(srv interface{}, ss grpc.ServerStream, info *grpc.StreamServerInfo, handler grpc.StreamHandler) error

StreamInterceptor intercepts gRPC stream calls to inject audit logging capability.

func (*Interceptor) UnaryInterceptor

func (i *Interceptor) UnaryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error)

UnaryInterceptor is a gRPC unary interceptor that automatically emits application audit logs. The interceptor is currently implemented in fail-close mode.

type InterceptorOption

type InterceptorOption func(i *Interceptor) error

InterceptorOption defines the option func to configure an interceptor.

func WithAuditClient

func WithAuditClient(c *Client) InterceptorOption

WithAuditClient configures the interceptor to use the given audit client to send audit logs.

func WithAuditRules

func WithAuditRules(rs ...*api.AuditRule) InterceptorOption

WithAuditRules configures the interceptor to use the given rules to match methods and instruct audit logging.

func WithInterceptorLogMode

func WithInterceptorLogMode(m api.AuditLogRequest_LogMode) InterceptorOption

WithInterceptorLogMode configures the interceptor to honor the given log mode.

func WithSecurityContext

func WithSecurityContext(sc security.GRPCContext) InterceptorOption

WithSecurityContext configures the interceptor to use the given security context to retrieve authentication info.

type LabelProcessor

type LabelProcessor struct {
	DefaultLabels map[string]string
}

LabelProcessor is a mutator that adds labels to each AuditLogRequest. These labels are specified through the configuration, and are intended to be defaults. They do not overwrite any labels that are already in the request, and can be overwritten by the server code.

func (*LabelProcessor) Process

func (p *LabelProcessor) Process(ctx context.Context, logReq *api.AuditLogRequest) error

Process adds the configured labels to each passed in request, without overwriting existing labels.

type LogProcessor

type LogProcessor interface {
	Process(context.Context, *api.AuditLogRequest) error
}

LogProcessor is the interface we use to process an AuditLogRequest. Examples include:

• validate that the AuditLogRequest is properly formed
• convert an AuditLogRequest to a Cloud LogEntry and write it to Cloud Logging

type Option

type Option func(o *Client) error

An Option is a configuration Option for NewClient.

func WithBackend

func WithBackend(p LogProcessor) Option

WithBackend adds the given log processor as a logging backend. Log backend processors are executed in the order provided with this option and after any other audit log processing. Examples of logging backends are:

• The Cloud Logging GCP service
• The custom Lumberjack gRPC service

func WithLogMode

func WithLogMode(mode api.AuditLogRequest_LogMode) Option

Sets FailClose value. This specifies whether errors should be surfaced or swalled. Can be overridden on a per-request basis.

func WithMutator

func WithMutator(p LogProcessor) Option

WithMutator adds the given log processor to mutate audit log requests. The mutators are executed in the order provided with this option. Mutators are executed after validators, but before backends.

func WithRuntimeInfo

func WithRuntimeInfo() Option

WithRuntimeInfo adds the runtime info to all the audit log requests.

func WithValidator

func WithValidator(p LogProcessor) Option

WithValidator adds the given log processor to validate audit log requests. The validators are executed in the order provided with this option and before any further audit log processing.

type StoppableProcessor

type StoppableProcessor interface {
	Stop() error
}

StoppableProcessor is the interface to log processors that are stoppable.