Audit Trail

Bridge evaluation lifecycle events to an audit backend for compliance and debugging.

The audit_hook package bridges Sentinel lifecycle events to an audit trail backend. It records structured audit events for evaluation operations.

Setup

import "github.com/xraph/sentinel/audit_hook"

// With a Recorder implementation
auditExt := audithook.New(myRecorder)

// Or with a simple function
auditExt := audithook.New(audithook.RecorderFunc(func(ctx context.Context, event *audithook.AuditEvent) error {
    log.Printf("AUDIT: %s %s %s", event.Action, event.Resource, event.ResourceID)
    return nil
}))

// Register with engine
eng, _ := engine.New(
    engine.WithExtension(auditExt),
)

Recorder interface

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

The RecorderFunc adapter lets you use a plain function:

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

AuditEvent

type AuditEvent struct {
    Action     string
    Resource   string
    Category   string
    ResourceID string
    Metadata   map[string]any
    Outcome    string
    Severity   string
    Reason     string
}

Actions

Audit actions for Sentinel lifecycle events:

Action	Description
`sentinel.eval.run.started`	Evaluation run initiated
`sentinel.eval.run.completed`	Run completed successfully
`sentinel.eval.run.failed`	Run failed
`sentinel.case.started`	Case evaluation started
`sentinel.case.completed`	Case evaluation completed
`sentinel.case.failed`	Case evaluation failed
`sentinel.baseline.saved`	Baseline saved
`sentinel.regression.detected`	Regression detected
`sentinel.redteam.started`	Red team evaluation started
`sentinel.redteam.completed`	Red team evaluation completed
`sentinel.prompt_version.created`	Prompt version created
`sentinel.comparison.completed`	Multi-model comparison completed

Severity levels

Level	Usage
`info`	Normal operations (run started, case completed)
`warning`	Regressions detected
`critical`	Failures (run failed, case failed)

Filtering

Use WithActions to limit which events are recorded:

auditExt := audithook.New(myRecorder,
    audithook.WithActions(
        audithook.ActionEvalRunStarted,
        audithook.ActionEvalRunFailed,
        audithook.ActionRegressionDetected,
    ),
)

Only the specified actions will be recorded; all others are silently dropped.