auditlog

Documentation

Overview

Copyright 2017 Canonical Ltd. Licensed under the AGPLv3, see LICENCE file for details.

Index

• type AuditLog
  • func NewLogFile(logDir string, maxSize, maxBackups int) AuditLog
• type Config
  • func (cfg Config) Validate() error
• type Conversation
• type ConversationArgs
• type Error
• type Record
• type Recorder
  • func NewRecorder(log AuditLog, clock clock.Clock, c ConversationArgs) (*Recorder, error)
  • func (r *Recorder) AddRequest(m RequestArgs) error
  • func (r *Recorder) AddResponse(m ResponseErrorsArgs) error
• type Request
• type RequestArgs
• type ResponseErrors
• type ResponseErrorsArgs

Types

type AuditLog

type AuditLog interface {
	AddConversation(c Conversation) error
	AddRequest(r Request) error
	AddResponse(r ResponseErrors) error
	Close() error
}

AuditLog represents something that can store calls, requests and responses somewhere.

func NewLogFile

func NewLogFile(logDir string, maxSize, maxBackups int) AuditLog

NewLogFile returns an audit entry sink which writes to an audit.log file in the specified directory. maxSize is the maximum size (in megabytes) of the log file before it gets rotated. maxBackups is the maximum number of old compressed log files to keep (or 0 to keep all of them).

type Config

type Config struct {
	// Enabled determines whether API requests should be audited at
	// all.
	Enabled bool

	// CaptureAPIArgs says whether to capture API method args (command
	// line args will always be captured).
	CaptureAPIArgs bool

	// MaxSizeMB defines the maximum log file size.
	MaxSizeMB int

	// MaxBackups determines how many files back to keep.
	MaxBackups int

	// ExcludeMethods is a set of facade.method names that we
	// shouldn't consider to be interesting: if a conversation only
	// consists of these method calls we won't log it.
	ExcludeMethods set.Strings

	// Target is the AuditLog entries should be written to.
	Target AuditLog
}

Config holds parameters to control audit logging.

func (Config) Validate

func (cfg Config) Validate() error

Validate checks the audit logging configuration.

type Conversation

type Conversation struct {
	Who            string `json:"who"`        // username@idm
	What           string `json:"what"`       // "juju deploy ./foo/bar"
	When           string `json:"when"`       // ISO 8601 to second precision
	ModelName      string `json:"model-name"` // full representation "user/name"
	ModelUUID      string `json:"model-uuid"`
	ConversationID string `json:"conversation-id"` // uint64 in hex
	ConnectionID   string `json:"connection-id"`   // uint64 in hex (using %X to match the value in log files)
}

Conversation represents a high-level juju command from the juju client (or other client). There'll be one Conversation per API connection from the client, with zero or more associated Request/ResponseErrors pairs.

type ConversationArgs

type ConversationArgs struct {
	Who          string
	What         string
	ModelName    string
	ModelUUID    string
	ConnectionID uint64
}

ConversationArgs is the information needed to create a method recorder.

type Error

type Error struct {
	Message string `json:"message"`
	Code    string `json:"code"`
}

Error holds the details of an error sent back from the API.

type Record

type Record struct {
	Conversation *Conversation   `json:"conversation,omitempty"`
	Request      *Request        `json:"request,omitempty"`
	Errors       *ResponseErrors `json:"errors,omitempty"`
}

Record is the top-level entry type in an audit log, which serves as a type discriminator. Only one of Conversation/Request/Errors should be set.

type Recorder

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

Recorder records method calls for a specific API connection.

func NewRecorder

func NewRecorder(log AuditLog, clock clock.Clock, c ConversationArgs) (*Recorder, error)

NewRecorder creates a Recorder for the connection described (and stores details of the initial call in the log).

func (*Recorder) AddRequest

func (r *Recorder) AddRequest(m RequestArgs) error

AddRequest records a method call to the API.

func (*Recorder) AddResponse

func (r *Recorder) AddResponse(m ResponseErrorsArgs) error

AddResponse records the result of a method call to the API.

type Request

type Request struct {
	ConversationID string `json:"conversation-id"`
	ConnectionID   string `json:"connection-id"`
	RequestID      uint64 `json:"request-id"`
	When           string `json:"when"`
	Facade         string `json:"facade"`
	Method         string `json:"method"`
	Version        int    `json:"version"`
	Args           string `json:"args,omitempty"`
}

Request represents a call to an API facade made as part of a specific conversation.

type RequestArgs

type RequestArgs struct {
	Facade    string
	Method    string
	Version   int
	Args      string
	RequestID uint64
}

RequestArgs is the information about an API call that we want to record.

type ResponseErrors

type ResponseErrors struct {
	ConversationID string   `json:"conversation-id"`
	ConnectionID   string   `json:"connection-id"`
	RequestID      uint64   `json:"request-id"`
	When           string   `json:"when"`
	Errors         []*Error `json:"errors"`
}

ResponseErrors captures any errors coming back from the API in response to a request.

type ResponseErrorsArgs

type ResponseErrorsArgs struct {
	RequestID uint64
	Errors    []*Error
}

ResponseErrorsArgs has errors from an API response to record in the audit log.