auditor

Documentation

Index

• Constants
• func GetActorIdentifier() string
• type ActorType
• type AuditEventPayload
• type AuditLogPublisher
  • func NewAuditLogPublisher(ctx context.Context, rc *natsconn.ReloadableConnection, logger log.Logger) (*AuditLogPublisher, error)
  • func NewPublishOnlyAuditLogPublisher(rc *natsconn.ReloadableConnection, logger log.Logger) (*AuditLogPublisher, error)
  • func (p *AuditLogPublisher) Publish(data *EventPayload) error
• type DescriptionVariables
• type Dispatcher
  • func NewDispatcher(publisher Publisher, logger log.Logger) *Dispatcher
  • func (d *Dispatcher) Dispatch(entry LogEntry, opts ...GeneratorOption)
  • func (d *Dispatcher) Enabled() bool
• type EventPayload
  • func GenerateAuditEvent(entry LogEntry, opts ...GeneratorOption) (*EventPayload, error)
  • func (e *EventPayload) ToJSON() ([]byte, error)
• type GeneratorOption
  • func WithActor(actorType ActorType, actorID uuid.UUID, email, name string) GeneratorOption
  • func WithOrgID(orgID uuid.UUID) GeneratorOption
• type GeneratorOptions
• type LogEntry
• type Publisher
• type TargetType

Constants

const ActorSystemIdentifier = "system@chainloop.dev"

GetActorIdentifier returns the actor identifier for audit log descriptions. It prioritizes ActorName, then ActorEmail, and finally falls back to system@chainloop.dev.

const AuditEventType = "AUDIT_EVENT"

Functions

func GetActorIdentifier

func GetActorIdentifier() string

Types

type ActorType

type ActorType string

ActorType is the type for the actor of a log entry, meaning the user or service that performed the action.

const (
	// ActorTypeUser is the type for a user actor.
	ActorTypeUser ActorType = "USER"
	// ActorTypeAPIToken is the type for am API Token actor.
	ActorTypeAPIToken ActorType = "API_TOKEN"
	// ActorTypeSystem is the type for a system actor.
	ActorTypeSystem = "SYSTEM"
)

type AuditEventPayload

type AuditEventPayload struct {
	ActionType  string
	TargetType  TargetType
	TargetID    *uuid.UUID
	ActorType   ActorType
	ActorID     *uuid.UUID
	ActorEmail  string
	ActorName   string
	OrgID       *uuid.UUID
	Description string
	Info        json.RawMessage
	Digest      *cr_v1.Hash
}

type AuditLogPublisher

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

func NewAuditLogPublisher

func NewAuditLogPublisher(ctx context.Context, rc *natsconn.ReloadableConnection, logger log.Logger) (*AuditLogPublisher, error)

NewAuditLogPublisher creates a publisher that owns the JetStream stream: it creates or updates it on boot and after every NATS reconnection.

func NewPublishOnlyAuditLogPublisher

func NewPublishOnlyAuditLogPublisher(rc *natsconn.ReloadableConnection, logger log.Logger) (*AuditLogPublisher, error)

NewPublishOnlyAuditLogPublisher creates a publisher that never creates or updates the JetStream stream. Meant for components (e.g. the Artifact CAS) that publish to the stream owned and configured by the control plane, so they can't accidentally override its configuration (e.g. downgrade the replica count).

func (*AuditLogPublisher) Publish

func (p *AuditLogPublisher) Publish(data *EventPayload) error

type DescriptionVariables

type DescriptionVariables struct {
	ActorType  ActorType
	ActorID    *uuid.UUID
	ActorEmail string
	ActorName  string
	OrgID      *uuid.UUID
}

type Dispatcher

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

Dispatcher centralizes the generate -> publish -> error-reporting flow shared by every component that emits audit events (e.g. the control plane's biz.AuditorUseCase and the Artifact CAS). Callers resolve the actor and organization themselves and pass them as GeneratorOptions, so each component keeps its own actor/org policy (request context vs JWT claims) while sharing the common dispatch machinery.

func NewDispatcher

func NewDispatcher(publisher Publisher, logger log.Logger) *Dispatcher

NewDispatcher builds a Dispatcher. A nil publisher (e.g. NATS not configured) turns Dispatch into a no-op and makes Enabled report false.

func (*Dispatcher) Dispatch

func (d *Dispatcher) Dispatch(entry LogEntry, opts ...GeneratorOption)

Dispatch generates the audit event from entry and the given options and publishes it. Best-effort: failures are logged and reported to Sentry, never returned, so they can't fail or slow down the caller. A disabled dispatcher is a no-op.

func (*Dispatcher) Enabled

func (d *Dispatcher) Enabled() bool

Enabled reports whether Dispatch would actually publish an event. Callers can use it to skip extra work when the dispatcher is a no-op.

type EventPayload

type EventPayload struct {
	EventType string // AUDIT_EVENT
	Timestamp time.Time
	Data      *AuditEventPayload
}

func GenerateAuditEvent

func GenerateAuditEvent(entry LogEntry, opts ...GeneratorOption) (*EventPayload, error)

func (*EventPayload) ToJSON

func (e *EventPayload) ToJSON() ([]byte, error)

type GeneratorOption

type GeneratorOption func(*GeneratorOptions) error

func WithActor

func WithActor(actorType ActorType, actorID uuid.UUID, email, name string) GeneratorOption

func WithOrgID

func WithOrgID(orgID uuid.UUID) GeneratorOption

type GeneratorOptions

type GeneratorOptions struct {
	ActorType  ActorType
	ActorID    *uuid.UUID
	ActorEmail string
	ActorName  string
	OrgID      *uuid.UUID
}

type LogEntry

type LogEntry interface {
	// ActionType returns the type of the action performed.
	ActionType() string
	// ActionInfo returns the information about the action performed.
	ActionInfo() (json.RawMessage, error)
	// TargetType returns the type of the target of the action.
	TargetType() TargetType
	// TargetID returns the ID of the target of the action.
	TargetID() *uuid.UUID
	// Description returns a templatable string, see the DescriptionVariables struct.
	Description() string
	RequiresActor() bool
}

LogEntry is the interface for all log entries. All events should implement this interface to be able to be logged.

type Publisher

type Publisher interface {
	Publish(data *EventPayload) error
}

Publisher publishes generated audit event payloads to the event bus. Implemented by *AuditLogPublisher; abstracted so it can be faked in tests and so a nil publisher can act as a no-op (NATS not configured).

type TargetType

type TargetType string

TargetType is the type for the target of a log entry, aka the resource acted upon.