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 Audited(eventType, resourceType, nameParam string, h http.HandlerFunc) http.HandlerFunc
- func AuditedEntry(eventType string, h http.HandlerFunc) http.HandlerFunc
- func AuditedServer(eventType string, h http.HandlerFunc) http.HandlerFunc
- func AuditedSkill(eventType string, h http.HandlerFunc) http.HandlerFunc
- func AuditedUpsert(onCreate, onUpdate, resourceType, nameParam string, h http.HandlerFunc) http.HandlerFunc
- func AuthFailureMiddleware(cfg *config.AuditConfig, logger *Logger) func(http.Handler) http.Handler
- func Middleware(cfg *config.AuditConfig, logger *Logger) func(http.Handler) http.Handler
- func OutcomeFromStatus(status int) string
- func SourceFromRequest(r *http.Request) audit.EventSource
- type Logger
- type RouteInfo
Constants ¶
const ( ResourceTypeSource = "source" ResourceTypeRegistry = "registry" ResourceTypeEntry = "entry" ResourceTypeUser = "user" ResourceTypeServer = "server" ResourceTypeSkill = "skill" )
Target field values for resource types.
const ( EventServerList = "server.list" EventServerVersionsList = "server.versions.list" EventServerVersionRead = "server.version.read" )
Event types for the MCP registry v0.1 discovery API.
const ( EventSkillList = "skill.list" EventSkillRead = "skill.read" EventSkillVersionsList = "skill.versions.list" EventSkillVersionRead = "skill.version.read" )
Event types for the skills extension API.
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 Audited ¶ added in v1.1.0
func Audited(eventType, resourceType, nameParam string, h http.HandlerFunc) http.HandlerFunc
Audited wraps a handler for routes with a single, unambiguous event type. resourceType is the ResourceType* constant (empty string for collection endpoints with no named resource). nameParam is the chi URL parameter name to use as "resource_name" (empty string when there is none).
func AuditedEntry ¶ added in v1.1.0
func AuditedEntry(eventType string, h http.HandlerFunc) http.HandlerFunc
AuditedEntry wraps handlers on /entries/{type}/{name}/... paths. Reads "type", "name", and optionally "version" chi URL params.
func AuditedServer ¶ added in v1.1.0
func AuditedServer(eventType string, h http.HandlerFunc) http.HandlerFunc
AuditedServer wraps handlers on /{registryName}/v0.1/servers/... paths. Reads "registryName" and optionally "serverName" and "version" chi URL params.
func AuditedSkill ¶ added in v1.1.0
func AuditedSkill(eventType string, h http.HandlerFunc) http.HandlerFunc
AuditedSkill wraps handlers on .../skills/... paths. Reads "registryName", "namespace", "name", and optionally "version" params.
func AuditedUpsert ¶ added in v1.1.0
func AuditedUpsert(onCreate, onUpdate, resourceType, nameParam string, h http.HandlerFunc) http.HandlerFunc
AuditedUpsert wraps a PUT handler whose event type depends on whether the operation created (201) or updated the resource.
func AuthFailureMiddleware ¶
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. This middleware should only be applied to routes that require authentication; public routes (health, readiness, etc.) should be excluded at the routing level.
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.
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.
type RouteInfo ¶ added in v1.1.0
type RouteInfo struct {
// EventType is the resolved event type for non-upsert routes.
EventType string
// OnCreate / OnUpdate are set for PUT upsert routes.
// The middleware resolves between them using the observed HTTP status:
// 201 → OnCreate, anything else → OnUpdate.
OnCreate string
OnUpdate string
// Target is the pre-populated target map, built at request time from
// chi URL params. It always contains "method" and "path"; optionally
// "resource_type", "resource_name", "entry_type", "version",
// "registry_name", and "namespace".
Target map[string]string
}
RouteInfo carries pre-resolved audit metadata for a single route.
func RouteInfoFromContext ¶ added in v1.1.0
RouteInfoFromContext returns the RouteInfo injected by one of the Audited* wrappers, or nil if none was injected.
Source Files