audit

Documentation

Index

• Constants
• Variables
• func Empty[T Auditable]() T
• type Action
  • func (t Action) String() string
• type Auditable
• type Backend
• type Exporter
  • func NewExporter(filter Filter, backends ...Backend) *Exporter
  • func (e *Exporter) Export(ctx context.Context, alog database.AuditLog) error
• type Filter
• type FilterDecision
• type FilterFunc
  • func (f FilterFunc) Check(ctx context.Context, alog database.AuditLog) (FilterDecision, error)
• type Map
  • func Diff[T Auditable](left, right T) Map
• type Table

Constants

const (
	// ActionIgnore ignores diffing for the field.
	ActionIgnore = "ignore"
	// ActionTrack includes the value in the diff if the value changed.
	ActionTrack = "track"
	// ActionSecret includes a zero value of the same type if the value changed.
	// It lets you indicate that a value changed, but without leaking its
	// contents.
	ActionSecret = "secret"
)

Variables

var AuditableResources = auditMap(map[any]map[string]Action{
	&database.GitSSHKey{}: {
		"user_id":     ActionTrack,
		"created_at":  ActionIgnore,
		"updated_at":  ActionIgnore,
		"private_key": ActionSecret,
		"public_key":  ActionTrack,
	},
	&database.OrganizationMember{}: {
		"user_id":         ActionTrack,
		"organization_id": ActionTrack,
		"created_at":      ActionIgnore,
		"updated_at":      ActionIgnore,
		"roles":           ActionTrack,
	},
	&database.Organization{}: {
		"id":          ActionTrack,
		"name":        ActionTrack,
		"description": ActionTrack,
		"created_at":  ActionIgnore,
		"updated_at":  ActionIgnore,
	},
	&database.Template{}: {
		"id":                ActionTrack,
		"created_at":        ActionIgnore,
		"updated_at":        ActionIgnore,
		"organization_id":   ActionTrack,
		"deleted":           ActionIgnore,
		"name":              ActionTrack,
		"provisioner":       ActionTrack,
		"active_version_id": ActionTrack,
		"description":       ActionTrack,
	},
	&database.TemplateVersion{}: {
		"id":              ActionTrack,
		"template_id":     ActionTrack,
		"organization_id": ActionTrack,
		"created_at":      ActionIgnore,
		"updated_at":      ActionIgnore,
		"name":            ActionTrack,
		"description":     ActionTrack,
		"job_id":          ActionIgnore,
	},
	&database.User{}: {
		"id":              ActionTrack,
		"email":           ActionTrack,
		"username":        ActionTrack,
		"hashed_password": ActionSecret,
		"created_at":      ActionIgnore,
		"updated_at":      ActionIgnore,
		"status":          ActionTrack,
		"rbac_roles":      ActionTrack,
	},
	&database.Workspace{}: {
		"id":                 ActionTrack,
		"created_at":         ActionIgnore,
		"updated_at":         ActionIgnore,
		"owner_id":           ActionTrack,
		"organization_id":    ActionTrack,
		"template_id":        ActionTrack,
		"deleted":            ActionIgnore,
		"name":               ActionTrack,
		"autostart_schedule": ActionTrack,
		"autostop_schedule":  ActionTrack,
	},
})

AuditableResources contains a definitive list of all auditable resources and which fields are auditable.

Functions

func Empty

func Empty[T Auditable]() T

Types

type Action

type Action string

func (Action) String

func (t Action) String() string

type Auditable

type Auditable interface {
	database.GitSSHKey |
		database.OrganizationMember |
		database.Organization |
		database.Template |
		database.TemplateVersion |
		database.User |
		database.Workspace
}

Auditable is mostly a marker interface. It contains a definitive list of all auditable types. If you want to audit a new type, first define it in AuditableResources, then add it to this interface.

type Backend

type Backend interface {
	// Decision determines the FilterDecisions that the backend tolerates.
	Decision() FilterDecision
	// Export sends an audit log to the backend.
	Export(ctx context.Context, alog database.AuditLog) error
}

Backends can store or send audit logs to arbitrary locations.

type Exporter

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

Exporter exports audit logs to an arbitrary list of backends.

func NewExporter

func NewExporter(filter Filter, backends ...Backend) *Exporter

NewExporter creates an exporter from the given filter and backends.

func (*Exporter) Export

func (e *Exporter) Export(ctx context.Context, alog database.AuditLog) error

Export exports and audit log. Before exporting to a backend, it uses the filter to determine if the backend tolerates the audit log. If not, it is dropped.

type Filter

type Filter interface {
	Check(ctx context.Context, alog database.AuditLog) (FilterDecision, error)
}

Filters produce a FilterDecision for a given audit log.

var DefaultFilter Filter = FilterFunc(func(ctx context.Context, alog database.AuditLog) (FilterDecision, error) {

	return FilterDecisionStore | FilterDecisionExport, nil
})

DefaultFilter is the default filter used when exporting audit logs. It allows storage and exporting for all audit logs.

type FilterDecision

type FilterDecision uint8

FilterDecision is a bitwise flag describing the actions a given filter allows for a given audit log.

const (
	// FilterDecisionDrop indicates that the audit log should be dropped. It
	// should not be stored or exported anywhere.
	FilterDecisionDrop FilterDecision = 0
	// FilterDecisionStore indicates that the audit log should be allowed to be
	// stored in the Coder database.
	FilterDecisionStore FilterDecision = 1 << iota
	// FilterDecisionExport indicates that the audit log should be exported
	// externally of Coder.
	FilterDecisionExport
)

type FilterFunc

type FilterFunc func(ctx context.Context, alog database.AuditLog) (FilterDecision, error)

FilterFunc constructs a Filter from a simple function.

func (FilterFunc) Check

func (f FilterFunc) Check(ctx context.Context, alog database.AuditLog) (FilterDecision, error)

type Map

type Map map[string]interface{}

TODO: this might need to be in the database package.

func Diff

func Diff[T Auditable](left, right T) Map

Diff compares two auditable resources and produces a Map of the changed values.

type Table

type Table map[string]map[string]Action

Table is a map of struct names to a map of field names that indicate that field's AuditType.