audit

Documentation

Index

• Constants
• Variables
• func NewAuditor(filter Filter, backends ...Backend) audit.Auditor
• type Action
  • func (t Action) String() string
• type Backend
• type Filter
• type FilterDecision
• type FilterFunc
  • func (f FilterFunc) Check(ctx context.Context, alog database.AuditLog) (FilterDecision, error)
• 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 AuditActionMap = map[string][]codersdk.AuditAction{
	"GitSSHKey":          {codersdk.AuditActionCreate},
	"OrganizationMember": {},
	"Organization":       {},
	"Template":           {codersdk.AuditActionWrite, codersdk.AuditActionDelete},
	"TemplateVersion":    {codersdk.AuditActionCreate, codersdk.AuditActionWrite},
	"User":               {codersdk.AuditActionCreate, codersdk.AuditActionWrite, codersdk.AuditActionDelete},
	"Workspace":          {codersdk.AuditActionCreate, codersdk.AuditActionWrite, codersdk.AuditActionDelete},
	"WorkspaceBuild":     {codersdk.AuditActionStart, codersdk.AuditActionStop},
	"Group":              {codersdk.AuditActionCreate, codersdk.AuditActionWrite, codersdk.AuditActionDelete},
	"APIKey":             {codersdk.AuditActionWrite},
}

This mapping creates a relationship between an Auditable Resource and the Audit Actions we track for that resource. It is important to maintain this mapping when adding a new Auditable Resource to the AuditableResources map (below) as our documentation - generated in scripts/auditdocgen/main.go - depends upon it.

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.Template{}: {
		"id":                               ActionTrack,
		"created_at":                       ActionIgnore,
		"updated_at":                       ActionIgnore,
		"organization_id":                  ActionIgnore,
		"deleted":                          ActionIgnore,
		"name":                             ActionTrack,
		"display_name":                     ActionTrack,
		"provisioner":                      ActionTrack,
		"active_version_id":                ActionTrack,
		"description":                      ActionTrack,
		"icon":                             ActionTrack,
		"default_ttl":                      ActionTrack,
		"min_autostart_interval":           ActionTrack,
		"created_by":                       ActionTrack,
		"is_private":                       ActionTrack,
		"group_acl":                        ActionTrack,
		"user_acl":                         ActionTrack,
		"allow_user_cancel_workspace_jobs": ActionTrack,
	},
	&database.TemplateVersion{}: {
		"id":              ActionTrack,
		"template_id":     ActionTrack,
		"organization_id": ActionIgnore,
		"created_at":      ActionIgnore,
		"updated_at":      ActionIgnore,
		"name":            ActionTrack,
		"readme":          ActionTrack,
		"job_id":          ActionIgnore,
		"created_by":      ActionTrack,
	},
	&database.User{}: {
		"id":              ActionTrack,
		"email":           ActionTrack,
		"username":        ActionTrack,
		"hashed_password": ActionSecret,
		"created_at":      ActionIgnore,
		"updated_at":      ActionIgnore,
		"status":          ActionTrack,
		"rbac_roles":      ActionTrack,
		"login_type":      ActionIgnore,
		"avatar_url":      ActionIgnore,
		"last_seen_at":    ActionIgnore,
		"deleted":         ActionTrack,
	},
	&database.Workspace{}: {
		"id":                 ActionTrack,
		"created_at":         ActionIgnore,
		"updated_at":         ActionIgnore,
		"owner_id":           ActionTrack,
		"organization_id":    ActionIgnore,
		"template_id":        ActionTrack,
		"deleted":            ActionIgnore,
		"name":               ActionTrack,
		"autostart_schedule": ActionTrack,
		"ttl":                ActionTrack,
		"last_used_at":       ActionIgnore,
	},
	&database.WorkspaceBuild{}: {
		"id":                  ActionIgnore,
		"created_at":          ActionIgnore,
		"updated_at":          ActionIgnore,
		"workspace_id":        ActionIgnore,
		"template_version_id": ActionTrack,
		"build_number":        ActionIgnore,
		"transition":          ActionIgnore,
		"initiator_id":        ActionIgnore,
		"provisioner_state":   ActionIgnore,
		"job_id":              ActionIgnore,
		"deadline":            ActionIgnore,
		"reason":              ActionIgnore,
		"daily_cost":          ActionIgnore,
	},
	&database.AuditableGroup{}: {
		"id":              ActionTrack,
		"name":            ActionTrack,
		"organization_id": ActionIgnore,
		"avatar_url":      ActionTrack,
		"quota_allowance": ActionTrack,
		"members":         ActionTrack,
	},

	&database.APIKey{}: {
		"id":               ActionIgnore,
		"hashed_secret":    ActionIgnore,
		"user_id":          ActionIgnore,
		"last_used":        ActionIgnore,
		"expires_at":       ActionIgnore,
		"created_at":       ActionIgnore,
		"updated_at":       ActionIgnore,
		"login_type":       ActionIgnore,
		"lifetime_seconds": ActionIgnore,
		"ip_address":       ActionIgnore,
		"scope":            ActionIgnore,
	},
})

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

Functions

func NewAuditor

func NewAuditor(filter Filter, backends ...Backend) audit.Auditor

Types

type Action

type Action string

func (Action) String

func (t Action) String() string

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 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 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.