audit

package
v0.43.4 Latest Latest
Warning

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

Go to latest
Published: Aug 14, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package audit provides a unified audit trail for all agent activity.

Index

Constants

View Source
const (
	CategoryToolCall   = "tool_call"
	CategorySkill      = "skill"
	CategoryChannel    = "channel"
	CategoryApproval   = "approval"
	CategorySchedule   = "schedule"
	CategoryLLM        = "llm"
	CategoryConfig     = "config"
	CategorySession    = "session"
	CategoryMCP        = "mcp"
	CategorySafety     = "safety"
	CategorySupervisor = "supervisor"
	// CategoryEval covers eval and dry-run lifecycle events (a preview was
	// run, a run started/finished). The per-round events those turns produce
	// keep their ordinary categories (llm, tool_call) and are told apart by
	// their source, not by this category.
	CategoryEval = "eval"
)

Event categories.

View Source
const (
	StatusOK      = "ok"
	StatusError   = "error"
	StatusPending = "pending"
	StatusDenied  = "denied"
)

Event statuses.

Variables

This section is empty.

Functions

func ParseFilterList added in v0.43.0

func ParseFilterList(values ...string) []string

ParseFilterList normalizes multi-valued filter input into the union form ListOpts.Categories / ListOpts.Statuses expect. Each input may itself be comma-separated, so both `?category=llm,tool_call` and the repeated `?category=llm&category=tool_call` spelling arrive here as the same set. Blanks are dropped and duplicates collapsed, so a lone "" (the dashboard's "All" chip) yields nil — i.e. no filter.

Types

type BufferedEmitter

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

BufferedEmitter accepts events via a channel and writes them in batches.

func NewBufferedEmitter

func NewBufferedEmitter(store Store, bufSize int, logger *slog.Logger) *BufferedEmitter

NewBufferedEmitter creates a buffered emitter with the given buffer capacity.

func (*BufferedEmitter) Close

func (e *BufferedEmitter) Close()

Close stops the flush loop and drains remaining events.

func (*BufferedEmitter) Emit

func (e *BufferedEmitter) Emit(_ context.Context, event Event)

Emit queues an event for persistence. Non-blocking; drops events if buffer is full.

func (*BufferedEmitter) Flush added in v0.28.0

func (e *BufferedEmitter) Flush()

Flush synchronously drains all buffered events and writes them to the store. The emitter remains usable after Flush returns. Safe for concurrent use. Guarantees: all events emitted before Flush is called will be persisted when Flush returns. Events emitted concurrently during Flush may or may not be included.

func (*BufferedEmitter) Start

func (e *BufferedEmitter) Start(ctx context.Context)

Start begins the background flush loop. Call Close to stop.

type Emitter

type Emitter interface {
	Emit(ctx context.Context, event Event)
}

Emitter is the interface for emitting audit events. Implementations must be safe for concurrent use.

type Event

type Event struct {
	ID             int64     `json:"id"`
	Timestamp      time.Time `json:"timestamp"`
	Category       string    `json:"category"`
	Action         string    `json:"action"`
	Agent          string    `json:"agent"`
	Summary        string    `json:"summary"`
	Detail         string    `json:"detail"`
	Status         string    `json:"status"`
	DurationMs     int64     `json:"duration_ms"`
	Source         string    `json:"source"`
	ConversationID string    `json:"conversation_id"`
}

Event represents a single audit log entry.

type ListOpts

type ListOpts struct {
	Categories []string
	Agent      string
	Statuses   []string
	Source     string
	// ExcludeSources drops events carrying any of these sources. It is the
	// negative counterpart of Source: filtering *to* a source was always
	// possible, filtering one *out* was not — which matters because dry-run and
	// eval turns emit under the ordinary llm/tool_call categories and would
	// otherwise flood an unfiltered stream.
	ExcludeSources []string
	Search         string
	Since          *time.Time
	Until          *time.Time
	Limit          int
	Offset         int
}

ListOpts controls filtering and pagination for audit event queries.

Categories and Statuses are unions: an event matches when it carries any one of the listed values. Empty (or nil) means "no filter on this field".

type ListResult

type ListResult struct {
	Events []Event `json:"events"`
	Total  int     `json:"total"`
	Limit  int     `json:"limit"`
	Offset int     `json:"offset"`
}

ListResult wraps a paginated list response.

type NopEmitter

type NopEmitter struct{}

NopEmitter discards all events.

func (NopEmitter) Emit

Emit is a no-op.

type SQLiteStore

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

SQLiteStore implements Store using SQLite.

func NewInMemoryStore

func NewInMemoryStore() (*SQLiteStore, error)

NewInMemoryStore creates an in-memory audit store (for testing).

func NewSQLiteStore

func NewSQLiteStore(dbPath string) (*SQLiteStore, error)

NewSQLiteStore opens (or creates) the audit database at dbPath.

func (*SQLiteStore) Close

func (s *SQLiteStore) Close() error

Close closes the database connection.

func (*SQLiteStore) Insert

func (s *SQLiteStore) Insert(ctx context.Context, event Event) error

Insert persists a single audit event.

func (*SQLiteStore) InsertBatch

func (s *SQLiteStore) InsertBatch(ctx context.Context, events []Event) error

InsertBatch persists multiple audit events in a single transaction.

func (*SQLiteStore) List

func (s *SQLiteStore) List(ctx context.Context, opts ListOpts) ([]Event, int, error)

List queries audit events with filtering and pagination.

func (*SQLiteStore) PruneBefore

func (s *SQLiteStore) PruneBefore(ctx context.Context, before time.Time) (int, error)

PruneBefore deletes audit events older than the given time. Returns the number of deleted rows.

func (*SQLiteStore) Stats

func (s *SQLiteStore) Stats(ctx context.Context, opts StatsOpts) (*Stats, error)

Stats returns aggregate counts for the audit dashboard.

type Stats

type Stats struct {
	Total          int            `json:"total"`
	ByCategory     map[string]int `json:"by_category"`
	ByStatus       map[string]int `json:"by_status"`
	EventsLastHour int            `json:"events_last_hour"`
}

Stats holds aggregate counts for the audit log dashboard.

type StatsOpts added in v0.43.0

type StatsOpts struct {
	Since          *time.Time
	ExcludeSources []string
}

StatsOpts controls filtering for aggregate audit queries. Stats needs the same source exclusion as List: eval and dry-run events land under existing categories, so without it one preview visibly inflates the dashboard's headline counts.

type Store

type Store interface {
	Insert(ctx context.Context, event Event) error
	InsertBatch(ctx context.Context, events []Event) error
	List(ctx context.Context, opts ListOpts) ([]Event, int, error)
	Stats(ctx context.Context, opts StatsOpts) (*Stats, error)
	PruneBefore(ctx context.Context, before time.Time) (int, error)
	Close() error
}

Store persists and queries audit events.

Jump to

Keyboard shortcuts

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