audit_hook

package
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package audit_hook provides the audit extension for Nexus. It bridges lifecycle events from the plugin.Registry to an audit recorder (typically Chronicle). This follows the dispatch/audit_hook pattern exactly.

Usage:

nexus.WithExtension(audit_hook.New(audit_hook.RecorderFunc(func(ctx context.Context, event *audit_hook.AuditEvent) error {
    log.Println("audit:", event.Action, event.Resource)
    return nil
})))

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Action

type Action string

Action is the type of audit event.

const (
	// Request actions
	ActionRequestReceived  Action = "request.received"
	ActionRequestCompleted Action = "request.completed"
	ActionRequestFailed    Action = "request.failed"
	ActionRequestCached    Action = "request.cached"

	// Provider actions
	ActionProviderFailed    Action = "provider.failed"
	ActionCircuitOpened     Action = "circuit.opened"
	ActionFallbackTriggered Action = "fallback.triggered"

	// Guardrail actions
	ActionGuardrailBlocked  Action = "guardrail.blocked"
	ActionGuardrailRedacted Action = "guardrail.redacted"

	// Tenant/Key actions
	ActionTenantCreated  Action = "tenant.created"
	ActionTenantDisabled Action = "tenant.disabled"
	ActionKeyCreated     Action = "key.created"
	ActionKeyRevoked     Action = "key.revoked"

	// Budget actions
	ActionBudgetWarning  Action = "budget.warning"
	ActionBudgetExceeded Action = "budget.exceeded"

	// Stream actions
	ActionStreamStarted   Action = "stream.started"
	ActionStreamCompleted Action = "stream.completed"
	ActionStreamFailed    Action = "stream.failed"
)

type AuditEvent

type AuditEvent struct {
	Timestamp  time.Time      `json:"timestamp"`
	Action     Action         `json:"action"`
	Resource   Resource       `json:"resource"`
	Category   Category       `json:"category"`
	ActorID    string         `json:"actor_id,omitempty"` // tenant or key ID
	TenantID   string         `json:"tenant_id,omitempty"`
	ResourceID string         `json:"resource_id,omitempty"`
	Details    map[string]any `json:"details,omitempty"`
}

AuditEvent is an audit log entry.

type Category

type Category string

Category groups audit events for filtering.

const (
	CategoryRequest  Category = "request"
	CategoryProvider Category = "provider"
	CategorySecurity Category = "security"
	CategoryTenant   Category = "tenant"
	CategoryBudget   Category = "budget"
)

type Extension

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

Extension implements all plugin lifecycle hooks and records audit events.

func New

func New(recorder Recorder, opts ...Option) *Extension

New creates a new audit hook extension.

func (*Extension) Name

func (e *Extension) Name() string

func (*Extension) OnBudgetExceeded

func (e *Extension) OnBudgetExceeded(ctx context.Context, tenantID id.TenantID) error

func (*Extension) OnBudgetWarning

func (e *Extension) OnBudgetWarning(ctx context.Context, tenantID id.TenantID, usedPct float64) error

func (*Extension) OnCircuitOpened

func (e *Extension) OnCircuitOpened(ctx context.Context, providerName string) error

func (*Extension) OnFallbackTriggered

func (e *Extension) OnFallbackTriggered(ctx context.Context, from, to string) error

func (*Extension) OnGuardrailBlocked

func (e *Extension) OnGuardrailBlocked(ctx context.Context, guardName string, requestID id.RequestID) error

func (*Extension) OnGuardrailRedacted

func (e *Extension) OnGuardrailRedacted(ctx context.Context, guardName, field string) error

func (*Extension) OnKeyCreated

func (e *Extension) OnKeyCreated(ctx context.Context, keyID id.KeyID, tenantID id.TenantID) error

func (*Extension) OnKeyRevoked

func (e *Extension) OnKeyRevoked(ctx context.Context, keyID id.KeyID) error

func (*Extension) OnProviderFailed

func (e *Extension) OnProviderFailed(ctx context.Context, providerName, model string, err error) error

func (*Extension) OnRequestCached

func (e *Extension) OnRequestCached(ctx context.Context, requestID id.RequestID, model string) error

func (*Extension) OnRequestCompleted

func (e *Extension) OnRequestCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, elapsed time.Duration, inputTokens, outputTokens int) error

func (*Extension) OnRequestFailed

func (e *Extension) OnRequestFailed(ctx context.Context, requestID id.RequestID, model string, err error) error

func (*Extension) OnRequestReceived

func (e *Extension) OnRequestReceived(ctx context.Context, requestID id.RequestID, model, tenantID string) error

func (*Extension) OnStreamCompleted

func (e *Extension) OnStreamCompleted(ctx context.Context, requestID id.RequestID, model, providerName string, elapsed time.Duration, final *provider.CompletionResponse) error

func (*Extension) OnStreamFailed

func (e *Extension) OnStreamFailed(ctx context.Context, requestID id.RequestID, model string, err error) error

func (*Extension) OnStreamStarted

func (e *Extension) OnStreamStarted(ctx context.Context, requestID id.RequestID, model, providerName string) error

func (*Extension) OnTenantCreated

func (e *Extension) OnTenantCreated(ctx context.Context, tenantID id.TenantID) error

func (*Extension) OnTenantDisabled

func (e *Extension) OnTenantDisabled(ctx context.Context, tenantID id.TenantID) error

type Option

type Option func(*Extension)

Option configures the audit extension.

func WithActions

func WithActions(actions ...Action) Option

WithActions filters to only record specific actions.

func WithLogger

func WithLogger(l log.Logger) Option

WithLogger sets a custom logger for the extension.

type Recorder

type Recorder interface {
	Record(ctx context.Context, event *AuditEvent) error
}

Recorder persists audit events. It takes the event by pointer, like chronicle's emitter and dispatch's audit_hook. Each call gets a fresh event that the recorder may keep or modify.

type RecorderFunc

type RecorderFunc func(ctx context.Context, event *AuditEvent) error

RecorderFunc is a function adapter for Recorder.

func (RecorderFunc) Record

func (f RecorderFunc) Record(ctx context.Context, event *AuditEvent) error

type Resource

type Resource string

Resource is the type of resource being audited.

const (
	ResourceRequest   Resource = "request"
	ResourceProvider  Resource = "provider"
	ResourceGuardrail Resource = "guardrail"
	ResourceTenant    Resource = "tenant"
	ResourceKey       Resource = "key"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL