---
title: Audit Trail
description: 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

```go
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

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

The `RecorderFunc` adapter lets you use a plain function:

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

## AuditEvent

```go
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:

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

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