audit

Documentation

Overview

Package audit provides engine-agnostic audit event emission using CloudEvents as the envelope format. It defines the Auditor contract and ships MVP backends (noop, stdout, kafka, multi) plus a Kratos middleware that intercepts RPC calls and emits structured audit events.

Architecture

The central abstraction is the Auditor interface (auditor.go):

type Auditor interface {
    Emit(ctx context.Context, event cloudevents.Event) error
}

Implementations live in sub-packages:

• obs/audit/noop — discards all events (testing / disabled mode)
• obs/audit/stdout — JSON-encodes events to stdout (local dev)
• obs/audit/kafka — delivers events to Kafka via CloudEvents binding (stub)
• obs/audit/multi — fans out to multiple auditors

Middleware

The Middleware function (audit_middleware.go) intercepts RPC calls, looks up CompiledRules by operation, builds CloudEvents events, supplements auth metadata, and emits through the configured Auditor. Emission errors are logged but never block business logic.

Recommended middleware chain order:

recovery → tracing → logging → ratelimit → validate → metrics → audit.Middleware → authn → authz → handler

CloudEvents Extensions

Servora audit events use the following CloudEvents extension attributes (defined in extensions.go): authid, authtype, traceparent, tracestate, severitytext, recordedtime, partitionkey, errormessage.

Index

• Constants
• func Middleware(auditor Auditor, opts ...MiddlewareOption) middleware.Middleware
• func NewEvent(ctx context.Context, opts ...EventOption) cloudevents.Event
• func SetProtoData(e *cloudevents.Event, msg proto.Message) error
• type Auditor
  • func Multi(auditors ...Auditor) Auditor
• type Closer
• type CompiledRule
• type EventOption
  • func WithSeverity(s string) EventOption
  • func WithSource(s string) EventOption
  • func WithSubject(s string) EventOption
  • func WithType(t string) EventOption
• type Flusher
• type MiddlewareOption
  • func WithAuthTypeFunc(fn func(context.Context) (string, bool)) MiddlewareOption
  • func WithRulesFuncs(fns ...func() map[string]*CompiledRule) MiddlewareOption
  • func WithSubjectFunc(fn func(context.Context) (string, bool)) MiddlewareOption

Constants

const (
	ExtAuthID       = "authid"
	ExtAuthType     = "authtype"
	ExtTraceParent  = "traceparent"
	ExtTraceState   = "tracestate"
	ExtSeverityText = "severitytext"
	ExtRecordedTime = "recordedtime"
	ExtPartitionKey = "partitionkey"
	ExtErrorMessage = "errormessage"
)

CloudEvents extension attribute names used by the Servora audit pipeline. These follow the CloudEvents naming convention (lowercase, no separators).

Functions

func Middleware

func Middleware(auditor Auditor, opts ...MiddlewareOption) middleware.Middleware

Middleware returns a Kratos middleware that intercepts RPC calls, builds audit events according to compiled rules, and emits them through the given Auditor. Audit emission errors are logged but never block business logic.

func NewEvent

func NewEvent(ctx context.Context, opts ...EventOption) cloudevents.Event

NewEvent constructs a CloudEvents event populated with Servora audit defaults. It extracts the operation from the transport context (if available) and sets it as the source. Options are applied after defaults, allowing full override.

func SetProtoData

func SetProtoData(e *cloudevents.Event, msg proto.Message) error

SetProtoData marshals a protobuf message and sets it as the CloudEvents data payload with content type "application/protobuf" and dataschema set to the fully qualified protobuf type URL.

Types

type Auditor

type Auditor interface {
	Emit(ctx context.Context, event cloudevents.Event) error
}

Auditor is the engine-agnostic interface for emitting structured audit events as CloudEvents. Unlike the legacy Emitter (which takes proto AuditEvent), Auditor works directly with the CloudEvents envelope — enabling decoupled, transport-neutral audit pipelines.

Implementations may batch, buffer, or fan-out events as needed.

func Multi

func Multi(auditors ...Auditor) Auditor

Multi creates a fan-out Auditor that emits events to all provided auditors independently. Errors from individual auditors are collected via errors.Join but do not block other auditors.

type Closer

type Closer interface {
	Close() error
}

Closer is an optional interface that Auditor implementations may satisfy to release resources on shutdown.

type CompiledRule

type CompiledRule struct {
	// Mode is the auditv1.AuditMode int32 value.
	// 0 = UNSPECIFIED (inherit), 1 = DISABLED, 2 = ENABLED.
	Mode int32

	// EventType is the CloudEvents type for the emitted event.
	EventType string

	// Severity is the severity text extension value.
	Severity string

	// BuildEvent constructs the full CloudEvents event for this operation.
	// ctx carries transport and auth metadata; req/resp are handler IO; err is handler error.
	BuildEvent func(ctx context.Context, req, resp any, err error) cloudevents.Event
}

CompiledRule describes how to audit a single RPC operation.

type EventOption

type EventOption func(*cloudevents.Event)

EventOption configures a CloudEvents event during construction.

func WithSeverity

func WithSeverity(s string) EventOption

WithSeverity sets the severity text extension attribute.

func WithSource

func WithSource(s string) EventOption

WithSource sets the CloudEvents source attribute.

func WithSubject

func WithSubject(s string) EventOption

WithSubject sets the CloudEvents subject attribute.

func WithType

func WithType(t string) EventOption

WithType sets the CloudEvents type attribute.

type Flusher

type Flusher interface {
	Flush(ctx context.Context) error
}

Flusher is an optional interface that Auditor implementations may satisfy to flush buffered events before graceful shutdown.

type MiddlewareOption

type MiddlewareOption func(*middlewareConfig)

MiddlewareOption configures the audit middleware.

func WithAuthTypeFunc

func WithAuthTypeFunc(fn func(context.Context) (string, bool)) MiddlewareOption

WithAuthTypeFunc sets a function that extracts the authentication type (e.g. "jwt", "apikey") from context.

func WithRulesFuncs

func WithRulesFuncs(fns ...func() map[string]*CompiledRule) MiddlewareOption

WithRulesFuncs registers one or more rule provider functions. Each returns a map[operation]*CompiledRule. Multiple providers are merged (later wins on conflict).

func WithSubjectFunc

func WithSubjectFunc(fn func(context.Context) (string, bool)) MiddlewareOption

WithSubjectFunc sets a function that extracts the authenticated subject ID from context.