events

package
v0.2.0-beta.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 9, 2016 License: Apache-2.0 Imports: 18 Imported by: 0

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

View Source
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'
)
View Source
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"
)
View Source
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
)

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditLog added in v1.0.0

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 these interfaces:

  • events.Log
  • recorder.Recorder

func NewAuditLog added in v1.0.0

func NewAuditLog(dataDir string) (*AuditLog, error)

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

func (*AuditLog) Close added in v1.0.0

func (l *AuditLog) Close() error

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

func (*AuditLog) EmitAuditEvent added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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

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

type EventFields added in v1.0.0

type EventFields map[string]interface{}

EventFields instance is attached to every logged event

func (EventFields) AsString added in v1.0.0

func (f EventFields) AsString() string

String returns a string representation of an event structure

func (EventFields) GetInt added in v1.0.0

func (f EventFields) GetInt(key string) int

GetString returns an int representation of a logged field

func (EventFields) GetString added in v1.0.0

func (f EventFields) GetString(key string) string

GetString returns a string representation of a logged field

func (EventFields) GetTime added in v1.0.0

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

GetString returns an int representation of a logged field

func (EventFields) GetType added in v1.0.0

func (f EventFields) GetType() string

GetType returns the type (string) of the event

type IAuditLog added in v1.0.0

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

type SessionLogger added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

func (sl *SessionLogger) LogEvent(fields EventFields)

LogEvent logs an event associated with this session

func (*SessionLogger) Write added in v1.0.0

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 added in v1.0.0

type TimeSourceFunc func() time.Time

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL