audit

Documentation

Index

• func BackgroundAudit[T Auditable](ctx context.Context, p *BackgroundAuditParams[T])
• func BackgroundTaskFields(subsystem BackgroundSubsystem) map[string]string
• func BackgroundTaskFieldsBytes(ctx context.Context, logger slog.Logger, subsystem BackgroundSubsystem) []byte
• func BaggageToContext(ctx context.Context, d Baggage) (context.Context, error)
• func Empty[T Auditable]() T
• func ResourceID[T Auditable](tgt T) uuid.UUID
• func ResourceRequiresOrgID[T Auditable]() bool
• func ResourceTarget[T Auditable](tgt T) string
• func ResourceType[T Auditable](tgt T) database.ResourceType
• type AdditionalFields
• type Auditable
• type Auditor
  • func NewNop() Auditor
• type BackgroundAuditParams
• type BackgroundSubsystem
• type Baggage
• type Differ
• type Map
  • func Diff[T Auditable](a Auditor, left, right T) Map
• type MockAuditor
  • func NewMock() *MockAuditor
  • func (a *MockAuditor) AuditLogs() []database.AuditLog
  • func (a *MockAuditor) Contains(t testing.TB, expected database.AuditLog) bool
  • func (a *MockAuditor) Export(_ context.Context, alog database.AuditLog) error
  • func (a *MockAuditor) ResetLogs()
• type OldNew
• type Request
  • func InitRequest[T Auditable](w http.ResponseWriter, p *RequestParams) (*Request[T], func())
  • func InitRequestWithCancel[T Auditable](w http.ResponseWriter, p *RequestParams) (*Request[T], func(commit bool))
  • func (r *Request[T]) UpdateOrganizationID(id uuid.UUID)
• type RequestParams
• type WorkspaceBuildBaggage
  • func BaggageFromContext(ctx context.Context) WorkspaceBuildBaggage
  • func WorkspaceBuildBaggageFromRequest(r *http.Request) WorkspaceBuildBaggage
  • func (b WorkspaceBuildBaggage) Props() ([]baggage.Property, error)

Functions

func BackgroundAudit

func BackgroundAudit[T Auditable](ctx context.Context, p *BackgroundAuditParams[T])

BackgroundAudit creates an audit log for a background event. The audit log is committed upon invocation.

func BackgroundTaskFields

func BackgroundTaskFields(subsystem BackgroundSubsystem) map[string]string

func BackgroundTaskFieldsBytes

func BackgroundTaskFieldsBytes(ctx context.Context, logger slog.Logger, subsystem BackgroundSubsystem) []byte

func BaggageToContext

func BaggageToContext(ctx context.Context, d Baggage) (context.Context, error)

func Empty

func Empty[T Auditable]() T

Empty returns a default value of type T.

func ResourceID

func ResourceID[T Auditable](tgt T) uuid.UUID

func ResourceRequiresOrgID

func ResourceRequiresOrgID[T Auditable]() bool

ResourceRequiresOrgID will ensure given resources are always audited with an organization ID.

func ResourceTarget

func ResourceTarget[T Auditable](tgt T) string

func ResourceType

func ResourceType[T Auditable](tgt T) database.ResourceType

Types

type AdditionalFields

type AdditionalFields struct {
	WorkspaceName  string               `json:"workspace_name"`
	BuildNumber    string               `json:"build_number"`
	BuildReason    database.BuildReason `json:"build_reason"`
	WorkspaceOwner string               `json:"workspace_owner"`
	WorkspaceID    uuid.UUID            `json:"workspace_id"`
}

type Auditable

type Auditable interface {
	database.APIKey |
		database.Template |
		database.TemplateVersion |
		database.User |
		database.WorkspaceTable |
		database.GitSSHKey |
		database.WorkspaceBuild |
		database.AuditableGroup |
		database.License |
		database.WorkspaceProxy |
		database.AuditOAuthConvertState |
		database.HealthSettings |
		database.NotificationsSettings |
		database.OAuth2ProviderApp |
		database.OAuth2ProviderAppSecret |
		database.CustomRole |
		database.AuditableOrganizationMember |
		database.Organization |
		database.NotificationTemplate
}

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 Auditor

type Auditor interface {
	Export(ctx context.Context, alog database.AuditLog) error
	// contains filtered or unexported methods
}

func NewNop

func NewNop() Auditor

type BackgroundAuditParams

type BackgroundAuditParams[T Auditable] struct {
	Audit Auditor
	Log   slog.Logger

	UserID         uuid.UUID
	RequestID      uuid.UUID
	Status         int
	Action         database.AuditAction
	OrganizationID uuid.UUID
	IP             string
	// todo: this should automatically marshal an interface{} instead of accepting a raw message.
	AdditionalFields json.RawMessage

	New T
	Old T
}

type BackgroundSubsystem

type BackgroundSubsystem string

const (
	BackgroundSubsystemDormancy BackgroundSubsystem = "dormancy"
)

type Baggage

type Baggage interface {
	Props() ([]baggage.Property, error)
}

type Differ

type Differ struct {
	DiffFn func(old, new any) Map
}

Differ is used so the enterprise version can implement the diff function in the Auditor feature interface. Only types in the same package as the interface can implement unexported methods.

type Map

type Map map[string]OldNew

Map is a map of changed fields in an audited resource. It maps field names to the old and new value for that field.

func Diff

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

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

type MockAuditor

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

func NewMock

func NewMock() *MockAuditor

func (*MockAuditor) AuditLogs

func (a *MockAuditor) AuditLogs() []database.AuditLog

func (*MockAuditor) Contains

func (a *MockAuditor) Contains(t testing.TB, expected database.AuditLog) bool

Contains returns true if, for each non-zero-valued field in expected, there exists a corresponding audit log in the mock auditor that matches the expected values. Returns false otherwise.

func (*MockAuditor) Export

func (a *MockAuditor) Export(_ context.Context, alog database.AuditLog) error

func (*MockAuditor) ResetLogs

func (a *MockAuditor) ResetLogs()

ResetLogs removes all audit logs from the mock auditor. This is helpful for testing to get a clean slate.

type OldNew

type OldNew struct {
	Old    any
	New    any
	Secret bool
}

OldNew is a pair of values representing the old value and the new value.

type Request

type Request[T Auditable] struct {
	Old T
	New T

	// UserID is an optional field can be passed in when the userID cannot be
	// determined from the API Key such as in the case of login, when the audit
	// log is created prior the API Key's existence.
	UserID uuid.UUID

	// Action is an optional field can be passed in if the AuditAction must be
	// overridden such as in the case of new user authentication when the Audit
	// Action is 'register', not 'login'.
	Action database.AuditAction
	// contains filtered or unexported fields
}

func InitRequest

func InitRequest[T Auditable](w http.ResponseWriter, p *RequestParams) (*Request[T], func())

InitRequest initializes an audit log for a request. It returns a function that should be deferred, causing the audit log to be committed when the handler returns.

func InitRequestWithCancel

func InitRequestWithCancel[T Auditable](w http.ResponseWriter, p *RequestParams) (*Request[T], func(commit bool))

InitRequestWithCancel returns a commit function with a boolean arg. If the arg is false, future calls to commit() will not create an audit log entry.

func (*Request[T]) UpdateOrganizationID

func (r *Request[T]) UpdateOrganizationID(id uuid.UUID)

UpdateOrganizationID can be used if the organization ID is not known at the initiation of an audit log request.

type RequestParams

type RequestParams struct {
	Audit Auditor
	Log   slog.Logger

	// OrganizationID is only provided when possible. If an audit resource extends
	// beyond the org scope, leave this as the nil uuid.
	OrganizationID   uuid.UUID
	Request          *http.Request
	Action           database.AuditAction
	AdditionalFields interface{}
}

type WorkspaceBuildBaggage

type WorkspaceBuildBaggage struct {
	IP string
}

func BaggageFromContext

func BaggageFromContext(ctx context.Context) WorkspaceBuildBaggage

func WorkspaceBuildBaggageFromRequest

func WorkspaceBuildBaggageFromRequest(r *http.Request) WorkspaceBuildBaggage

func (WorkspaceBuildBaggage) Props

func (b WorkspaceBuildBaggage) Props() ([]baggage.Property, error)