events

Documentation

Overview

Package events currently implements the audit log using a simple filesystem backend. "Implements" means it implements events.IAuditLog interface (see events/api.go)

The main log files are saved as:

/var/lib/teleport/log/<date>.log

Each session has its own session log stored as two files

/var/lib/teleport/log/<session-id>.session.log
/var/lib/teleport/log/<session-id>.session.bytes

Where:

• .session.log (same events as in the main log, but related to the session)
• .session.bytes (recorded session bytes: PTY IO)

The log file is rotated every 24 hours. The old files must be cleaned up or archived by an external tool.

Log file format: utc_date,action,json_fields

Common JSON fields - user : teleport user - login : server OS login, the user logged in as - addr.local : server address:port - addr.remote: connected client's address:port - sid : session ID (GUID format)

Examples: 2016-04-25 22:37:29 +0000 UTC,session.start,{"addr.local":"127.0.0.1:3022","addr.remote":"127.0.0.1:35732","login":"root","sid":"4a9d97de-0b36-11e6-a0b3-d8cb8ae5080e","user":"vincent"} 2016-04-25 22:54:31 +0000 UTC,exec,{"addr.local":"127.0.0.1:3022","addr.remote":"127.0.0.1:35949","command":"-bash -c ls /","login":"root","user":"vincent"}

Index

• Constants
• type AuditLog
  • func (l *AuditLog) Close() error
  • func (l *AuditLog) EmitAuditEvent(eventType string, fields EventFields) error
  • func (l *AuditLog) GetSessionChunk(sid session.ID, offsetBytes, maxBytes int) ([]byte, error)
  • func (l *AuditLog) GetSessionEvents(sid session.ID, afterN int) ([]EventFields, error)
  • func (l *AuditLog) LoggerFor(sid session.ID) (sl *SessionLogger, err error)
  • func (l *AuditLog) PostSessionChunk(sid session.ID, reader io.Reader) error
  • func (l *AuditLog) SearchEvents(fromUTC, toUTC time.Time, query string) ([]EventFields, error)
• type DiscardAuditLog
  • func (d *DiscardAuditLog) EmitAuditEvent(eventType string, fields EventFields) error
  • func (d *DiscardAuditLog) GetSessionChunk(sid session.ID, offsetBytes, maxBytes int) ([]byte, error)
  • func (d *DiscardAuditLog) GetSessionEvents(sid session.ID, after int) ([]EventFields, error)
  • func (d *DiscardAuditLog) PostSessionChunk(sid session.ID, reader io.Reader) error
  • func (d *DiscardAuditLog) SearchEvents(fromUTC, toUTC time.Time, query string) ([]EventFields, error)
• type EventFields
  • func (f EventFields) AsString() string
  • func (f EventFields) GetInt(key string) int
  • func (f EventFields) GetString(key string) string
  • func (f EventFields) GetTime(key string) time.Time
  • func (f EventFields) GetType() string
• type IAuditLog
  • func NewAuditLog(dataDir string) (IAuditLog, error)
• type SessionLogger
  • func (sl *SessionLogger) Close() error
  • func (sl *SessionLogger) Finalize() error
  • func (sl *SessionLogger) LogEvent(fields EventFields)
  • func (sl *SessionLogger) Write(bytes []byte) (written int, err error)
• type TimeSourceFunc

Constants

const (
	// Common event fields:
	EventType   = "event"       // event type/kind
	EventTime   = "time"        // event time
	EventLogin  = "login"       // OS login
	EventUser   = "user"        // teleport user
	LocalAddr   = "addr.local"  // address on the host
	RemoteAddr  = "addr.remote" // client (user's) address
	EventCursor = "id"          // event ID (used as cursor value for enumeration, not stored)

	// SessionPrintEvent event happens every time a write occurs to
	// temirnal I/O during a session
	SessionPrintEvent = "print"

	// SessionPrintEventBytes says how many bytes have been written into the session
	// during "print" event
	SessionPrintEventBytes = "bytes"

	// SessionEventTimestamp is an offset (in milliseconds) since the beginning of the
	// session when the terminal IO event happened
	SessionEventTimestamp = "ms"

	// SessionEvent indicates that session has been initiated
	// or updated by a joining party on the server
	SessionStartEvent = "session.start"

	// SessionEndEvent indicates taht a session has ended
	SessionEndEvent = "session.end"
	SessionEventID  = "sid"
	SessionServerID = "server_id"

	// SessionByteOffset is the number of bytes written to session stream since
	// the beginning
	SessionByteOffset = "offset"

	// Join & Leave events indicate when someone joins/leaves a session
	SessionJoinEvent  = "session.join"
	SessionLeaveEvent = "session.leave"

	// ExecEvent is an exec command executed by script or user on
	// the server side
	ExecEvent        = "exec"
	ExecEventCommand = "command"
	ExecEventCode    = "exitCode"
	ExecEventError   = "exitError"

	// Port forwarding event
	PortForwardEvent = "port"
	PortForwardAddr  = "addr"

	// AuthAttemptEvent is authentication attempt that either
	// succeeded or failed based on event status
	AuthAttemptEvent   = "auth"
	AuthAttemptSuccess = "success"
	AuthAttemptErr     = "error"

	// SCPEvent means data transfer that occured on the server
	SCPEvent  = "scp"
	SCPPath   = "path"
	SCPLengh  = "len"
	SCPAction = "action"

	// ResizeEvent means that some user resized PTY on the client
	ResizeEvent  = "resize"
	TerminalSize = "size" // expressed as 'W:H'
)

const (
	// SessionLogsDir is a subdirectory inside the eventlog data dir
	// where all session-specific logs and streams are stored, like
	// in /var/lib/teleport/logs/sessions
	SessionLogsDir = "sessions"

	// LogfileExt defines the ending of the daily event log file
	LogfileExt = ".log"

	// SessionLogPrefix defines the endof of session log files
	SessionLogPrefix = ".session.log"

	// SessionStreamPrefix defines the ending of session stream files,
	// that's where interactive PTY I/O is saved.
	SessionStreamPrefix = ".session.bytes"
)

const (
	// MaxChunkBytes defines the maximum size of a session stream chunk that
	// can be requested via AuditLog.GetSessionChunk(). Set to 5MB
	MaxChunkBytes = 1024 * 1024 * 5
)

Types

type AuditLog

type AuditLog struct {
	sync.Mutex

	// RotationPeriod defines how frequently to rotate the log file
	RotationPeriod time.Duration

	// same as time.Now(), but helps with testing
	TimeSource TimeSourceFunc
	// contains filtered or unexported fields
}

AuditLog is a new combined facility to record Teleport events and sessions. It implements IAuditLog

func (*AuditLog) Close

func (l *AuditLog) Close() error

Closes the audit log, which inluces closing all file handles and releasing all session loggers

func (*AuditLog) EmitAuditEvent

func (l *AuditLog) EmitAuditEvent(eventType string, fields EventFields) error

EmitAuditEvent adds a new event to the log. Part of auth.IAuditLog interface.

func (*AuditLog) GetSessionChunk

func (l *AuditLog) GetSessionChunk(sid session.ID, offsetBytes, maxBytes int) ([]byte, error)

GetSessionChunk returns a reader which console and web clients request to receive a live stream of a given session. The reader allows access to a session stream range from offsetBytes to offsetBytes+maxBytes

func (*AuditLog) GetSessionEvents

func (l *AuditLog) GetSessionEvents(sid session.ID, afterN int) ([]EventFields, error)

Returns all events that happen during a session sorted by time (oldest first).

Can be filtered by 'after' (cursor value to return events newer than)

This function is usually used in conjunction with GetSessionReader to replay recorded session streams.

func (*AuditLog) LoggerFor

func (l *AuditLog) LoggerFor(sid session.ID) (sl *SessionLogger, err error)

LoggerFor creates a logger for a specified session. Session loggers allow to group all events into special "session log files" for easier audit

func (*AuditLog) PostSessionChunk

func (l *AuditLog) PostSessionChunk(sid session.ID, reader io.Reader) error

PostSessionChunk writes a new chunk of session stream into the audit log

func (*AuditLog) SearchEvents

func (l *AuditLog) SearchEvents(fromUTC, toUTC time.Time, query string) ([]EventFields, error)

Search finds events. Results show up sorted by date (newest first)

type DiscardAuditLog

type DiscardAuditLog struct {
}

DiscardAuditLog is do-nothing, discard-everything implementation of IAuditLog interface used for cases when audit is turned off

func (*DiscardAuditLog) EmitAuditEvent

func (d *DiscardAuditLog) EmitAuditEvent(eventType string, fields EventFields) error

func (*DiscardAuditLog) GetSessionChunk

func (d *DiscardAuditLog) GetSessionChunk(sid session.ID, offsetBytes, maxBytes int) ([]byte, error)

func (*DiscardAuditLog) GetSessionEvents

func (d *DiscardAuditLog) GetSessionEvents(sid session.ID, after int) ([]EventFields, error)

func (*DiscardAuditLog) PostSessionChunk

func (d *DiscardAuditLog) PostSessionChunk(sid session.ID, reader io.Reader) error

func (*DiscardAuditLog) SearchEvents

func (d *DiscardAuditLog) SearchEvents(fromUTC, toUTC time.Time, query string) ([]EventFields, error)

type EventFields

type EventFields map[string]interface{}

EventFields instance is attached to every logged event

func (EventFields) AsString

func (f EventFields) AsString() string

String returns a string representation of an event structure

func (EventFields) GetInt

func (f EventFields) GetInt(key string) int

GetString returns an int representation of a logged field

func (EventFields) GetString

func (f EventFields) GetString(key string) string

GetString returns a string representation of a logged field

func (EventFields) GetTime

func (f EventFields) GetTime(key string) time.Time

GetString returns an int representation of a logged field

func (EventFields) GetType

func (f EventFields) GetType() string

GetType returns the type (string) of the event

type IAuditLog

type IAuditLog interface {
	EmitAuditEvent(eventType string, fields EventFields) error

	// PostSessionChunk returns a writer which SSH nodes use to submit
	// their live sessions into the session log
	PostSessionChunk(sid session.ID, reader io.Reader) error

	// GetSessionChunk returns a reader which can be used to read a byte stream
	// of a recorded session starting from 'offsetBytes' (pass 0 to start from the
	// beginning) up to maxBytes bytes.
	//
	// If maxBytes > MaxChunkBytes, it gets rounded down to MaxChunkBytes
	GetSessionChunk(sid session.ID, offsetBytes, maxBytes int) ([]byte, error)

	// Returns all events that happen during a session sorted by time
	// (oldest first).
	//
	// after tells to use only return events after a specified cursor Id
	//
	// This function is usually used in conjunction with GetSessionReader to
	// replay recorded session streams.
	GetSessionEvents(sid session.ID, after int) ([]EventFields, error)

	// SearchEvents is a flexible way to find events. The format of a query string
	// depends on the implementing backend. A recommended format is urlencoded
	// (good enough for Lucene/Solr)
	//
	// Pagination is also defined via backend-specific query format.
	//
	// The only mandatory requirement is a date range (UTC). Results must always
	// show up sorted by date (newest first)
	SearchEvents(fromUTC, toUTC time.Time, query string) ([]EventFields, error)
}

IAuditLog is the primary (and the only external-facing) interface for AUditLogger. If you wish to implement a different kind of logger (not filesystem-based), you have to implement this interface

func NewAuditLog

func NewAuditLog(dataDir string) (IAuditLog, error)

Creates and returns a new Audit Log oboject whish will store its logfiles in a given directory>

type SessionLogger

type SessionLogger struct {
	sync.Mutex
	// contains filtered or unexported fields
}

BaseSessionLogger implements the common features of a session logger. The imporant property of the base logger is that it never fails and can be used as a fallback implementation behind more sophisticated loggers

func (*SessionLogger) Close

func (sl *SessionLogger) Close() error

Close() is called when clients close on the requested "session writer". We ignore their requests because this writer (file) should be closed only when the session logger is closed

func (*SessionLogger) Finalize

func (sl *SessionLogger) Finalize() error

Finalize is called by the session when it's closing. This is where we're releasing audit resources associated with the session

func (*SessionLogger) LogEvent

func (sl *SessionLogger) LogEvent(fields EventFields)

LogEvent logs an event associated with this session

func (*SessionLogger) Write

func (sl *SessionLogger) Write(bytes []byte) (written int, err error)

Write takes a stream of bytes (usually the output from a session terminal) and writes it into a "stream file", for future replay of interactive sessions.

type TimeSourceFunc

type TimeSourceFunc func() time.Time