Documentation
¶
Overview ¶
Package audit provides audit logging for the ToolHive Registry Server. It uses the shared audit library from toolhive-core to emit structured audit events for API operations.
Index ¶
- Constants
- func AuthFailureMiddleware(cfg *config.AuditConfig, logger *Logger, publicPaths []string) func(http.Handler) http.Handler
- func EventTypeFromRequest(method, path string, status int) string
- func Middleware(cfg *config.AuditConfig, logger *Logger) func(http.Handler) http.Handler
- func OutcomeFromStatus(status int) string
- func SourceFromRequest(r *http.Request) audit.EventSource
- func TargetFromRequest(method, path string) map[string]string
- type Logger
Constants ¶
const ( ResourceTypeSource = "source" ResourceTypeRegistry = "registry" ResourceTypeEntry = "entry" )
Target field values for resource types.
const ( EventSourceCreate = "source.create" EventSourceUpdate = "source.update" EventSourceDelete = "source.delete" EventRegistryCreate = "registry.create" EventRegistryUpdate = "registry.update" EventRegistryDelete = "registry.delete" EventEntryPublish = "entry.publish" EventEntryDelete = "entry.delete" EventEntryClaims = "entry.claims.update" )
Event types for audit logging — write operations.
const ( EventSourceList = "source.list" EventSourceRead = "source.read" EventSourceEntriesList = "source.entries.list" EventRegistryList = "registry.list" EventRegistryRead = "registry.read" EventRegistryEntriesList = "registry.entries.list" EventUserInfo = "user.info" )
Event types for audit logging — read operations.
const ComponentRegistryAPI = "toolhive-registry-api"
ComponentRegistryAPI is the component name for the registry server (distinct from toolhive's "toolhive-api").
const ( // EventAuthUnauthenticated is emitted when a request fails authentication // (HTTP 401). Captured by the pre-auth middleware so that auth failures // are visible to SIEM systems even though the post-auth audit middleware // never fires for rejected requests. EventAuthUnauthenticated = "auth.unauthenticated" )
Event types for audit logging — security events.
Variables ¶
This section is empty.
Functions ¶
func AuthFailureMiddleware ¶
func AuthFailureMiddleware(cfg *config.AuditConfig, logger *Logger, publicPaths []string) func(http.Handler) http.Handler
AuthFailureMiddleware returns HTTP middleware that emits audit events for authentication failures (HTTP 401). It must be installed BEFORE the auth middleware so it can observe auth rejections.
When cfg is nil or disabled, the middleware is a no-op pass-through.
func EventTypeFromRequest ¶
EventTypeFromRequest determines the audit event type from the HTTP method, request path, and response status code. The status code is used to distinguish creates (201) from updates (200) for PUT upsert endpoints. It returns an empty string if the request does not map to a known auditable operation.
func Middleware ¶
Middleware returns HTTP middleware that emits audit events for operations on /v1/ endpoints. It must be installed after auth and role resolution middleware so that JWT claims are available in the context.
When cfg is nil or disabled, the middleware is a no-op pass-through.
func OutcomeFromStatus ¶
OutcomeFromStatus maps an HTTP status code to an audit outcome string.
func SourceFromRequest ¶
func SourceFromRequest(r *http.Request) audit.EventSource
SourceFromRequest extracts the client IP and User-Agent for audit events.
For the IP address, it uses r.RemoteAddr as the primary source because Chi's middleware.RealIP runs earlier in the middleware chain and already resolves X-Forwarded-For / X-Real-IP into RemoteAddr. The raw X-Forwarded-For header is preserved in Extra for forensic context.
func TargetFromRequest ¶
TargetFromRequest extracts a rich target map from the request path, including explicit resource_type and resource_name fields alongside the raw method and path. This gives SIEM systems structured fields to query without needing to regex-parse the URL.
Types ¶
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger wraps a dedicated *slog.Logger for audit events and manages the underlying writer so it can be closed on shutdown.
func NewLogger ¶
NewLogger creates a dedicated audit logger. If logFile is non-empty, events are written to that file (created/appended); otherwise they go to stdout. The returned Logger must be closed via Close() on shutdown.
Source Files