audit

Documentation

Overview

Package audit provides audit logging functionality for ToolHive.

Package audit provides audit logging configuration for ToolHive.

Package audit provides audit logging functionality for ToolHive. This package includes audit event structures and utilities based on the auditevent library from metal-toolbox/auditevent to ensure NIST SP 800-53 compliance.

Package audit provides MCP-specific audit event types and constants.

Index

• Constants
• func GetMiddlewareFromFile(path string) (func(http.Handler) http.Handler, error)
• func NewAuditLogger(w io.Writer) *slog.Logger
• type AuditEvent
  • func NewAuditEvent(eventType string, source EventSource, outcome string, ...) *AuditEvent
  • func NewAuditEventWithID(auditID string, eventType string, source EventSource, outcome string, ...) *AuditEvent
  • func (e *AuditEvent) LogTo(ctx context.Context, logger *slog.Logger, level slog.Level)
  • func (e *AuditEvent) WithData(data *json.RawMessage) *AuditEvent
  • func (e *AuditEvent) WithDataFromString(data string) *AuditEvent
  • func (e *AuditEvent) WithTarget(target map[string]string) *AuditEvent
• type Auditor
  • func NewAuditor(config *Config) (*Auditor, error)
  • func (a *Auditor) Middleware(next http.Handler) http.Handler
• type Config
  • func DefaultConfig() *Config
  • func LoadFromFile(path string) (*Config, error)
  • func LoadFromReader(r io.Reader) (*Config, error)
  • func (c *Config) CreateMiddleware() (func(http.Handler) http.Handler, error)
  • func (c *Config) GetLogWriter() (io.Writer, error)
  • func (c *Config) ShouldAuditEvent(eventType string) bool
  • func (c *Config) Validate() error
• type EventMetadata
• type EventSource

Constants

const (
	// OutcomeSuccess indicates the event was successful
	OutcomeSuccess = "success"
	// OutcomeFailure indicates the event failed
	OutcomeFailure = "failure"
	// OutcomeError indicates the event resulted in an error
	OutcomeError = "error"
	// OutcomeDenied indicates the event was denied (e.g., by authorization)
	OutcomeDenied = "denied"
)

Common event outcomes

const (
	// SourceTypeNetwork indicates the event came from a network request
	SourceTypeNetwork = "network"
	// SourceTypeLocal indicates the event came from a local source
	SourceTypeLocal = "local"
)

Common source types

const (
	// EventTypeMCPInitialize represents an MCP initialization event
	EventTypeMCPInitialize = "mcp_initialize"
	// EventTypeMCPToolCall represents an MCP tool call event
	EventTypeMCPToolCall = "mcp_tool_call"
	// EventTypeMCPToolsList represents an MCP tools list event
	EventTypeMCPToolsList = "mcp_tools_list"
	// EventTypeMCPResourceRead represents an MCP resource read event
	EventTypeMCPResourceRead = "mcp_resource_read"
	// EventTypeMCPResourcesList represents an MCP resources list event
	EventTypeMCPResourcesList = "mcp_resources_list"
	// EventTypeMCPPromptGet represents an MCP prompt get event
	EventTypeMCPPromptGet = "mcp_prompt_get"
	// EventTypeMCPPromptsList represents an MCP prompts list event
	EventTypeMCPPromptsList = "mcp_prompts_list"
	// EventTypeMCPNotification represents an MCP notification event
	EventTypeMCPNotification = "mcp_notification"
	// EventTypeMCPPing represents an MCP ping event
	EventTypeMCPPing = "mcp_ping"
	// EventTypeMCPLogging represents an MCP logging event
	EventTypeMCPLogging = "mcp_logging"
	// EventTypeMCPCompletion represents an MCP completion event
	EventTypeMCPCompletion = "mcp_completion"
	// EventTypeMCPRootsListChanged represents an MCP roots list changed notification
	EventTypeMCPRootsListChanged = "mcp_roots_list_changed"

	// Fallback event types for unrecognized or generic requests
	// EventTypeMCPRequest represents a generic MCP request when specific type cannot be determined
	EventTypeMCPRequest = "mcp_request"
	// EventTypeHTTPRequest represents a generic HTTP request (non-MCP)
	EventTypeHTTPRequest = "http_request"
)

MCP-specific event types based on the Model Context Protocol specification

const (
	// TargetTypeTool represents a tool target
	TargetTypeTool = "tool"
	// TargetTypeResource represents a resource target
	TargetTypeResource = "resource"
	// TargetTypePrompt represents a prompt target
	TargetTypePrompt = "prompt"
	// TargetTypeServer represents a server target
	TargetTypeServer = "server"
)

MCP target types for audit events

const (
	// TargetKeyType is the key for the target type in the target map
	TargetKeyType = "type"
	// TargetKeyName is the key for the target name in the target map
	TargetKeyName = "name"
	// TargetKeyURI is the key for the target URI in the target map
	TargetKeyURI = "uri"
	// TargetKeyMethod is the key for the MCP method in the target map
	TargetKeyMethod = "method"
	// TargetKeyEndpoint is the key for the endpoint in the target map
	TargetKeyEndpoint = "endpoint"
)

MCP-specific target field keys

const (
	// SubjectKeyUser is the key for the user in the subjects map
	SubjectKeyUser = "user"
	// SubjectKeyUserID is the key for the user ID in the subjects map
	SubjectKeyUserID = "user_id"
	// SubjectKeyClientName is the key for the client name in the subjects map
	SubjectKeyClientName = "client_name"
	// SubjectKeyClientVersion is the key for the client version in the subjects map
	SubjectKeyClientVersion = "client_version"
)

MCP-specific subject field keys

const (
	// SourceExtraKeyUserAgent is the key for the user agent in the source extra map
	SourceExtraKeyUserAgent = "user_agent"
	// SourceExtraKeyRequestID is the key for the request ID in the source extra map
	SourceExtraKeyRequestID = "request_id"
	// SourceExtraKeySessionID is the key for the session ID in the source extra map
	SourceExtraKeySessionID = "session_id"
)

MCP-specific source field keys for EventSource.Extra

const (
	// MetadataExtraKeyMCPVersion is the key for the MCP version in the metadata extra map
	MetadataExtraKeyMCPVersion = "mcp_version"
	// MetadataExtraKeyTransport is the key for the transport type in the metadata extra map
	MetadataExtraKeyTransport = "transport"
	// MetadataExtraKeyDuration is the key for the request duration in the metadata extra map
	MetadataExtraKeyDuration = "duration_ms"
	// MetadataExtraKeyResponseSize is the key for the response size in the metadata extra map
	MetadataExtraKeyResponseSize = "response_size_bytes"
)

MCP-specific metadata field keys for EventMetadata.Extra

const (
	// ComponentToolHive is the component name for ToolHive API audit events.
	// Note that events directed for an MCP server will have the name of the
	// MCP server as the component instead.
	ComponentToolHive = "toolhive-api"
)

Component name for ToolHive

const LevelAudit = slog.Level(2)

LevelAudit is a custom audit log level - between Info and Warn

Functions

func GetMiddlewareFromFile

func GetMiddlewareFromFile(path string) (func(http.Handler) http.Handler, error)

GetMiddlewareFromFile loads the audit configuration from a file and creates an HTTP middleware.

func NewAuditLogger

func NewAuditLogger(w io.Writer) *slog.Logger

NewAuditLogger creates a new structured audit logger that writes to the specified writer.

Types

type AuditEvent

type AuditEvent struct {
	Metadata EventMetadata `json:"metadata"`
	// Type: Defines the type of event that occurred
	// This is a small identifier to quickly determine what happened.
	// e.g. UserLogin, UserLogout, UserCreate, UserDelete, etc.
	Type string `json:"type"`
	// LoggedAt: determines when the event occurred.
	// Note that this should have sufficient information to authoritatively
	// determine the exact time the event was logged at. The output must be in
	// Coordinated Universal Time (UTC) format, a modern continuation of
	// Greenwich Mean Time (GMT), or local time with an offset from UTC to satisfy
	// NIST SP 800-53 requirement AU-8.
	LoggedAt time.Time `json:"loggedAt"`
	// Source: determines the source of the event.
	// Normally, using the IP address of the client, or pod name is sufficient.
	// One must be careful of the data that's added here as we don't want to
	// leak Personally Identifiable Information.
	Source EventSource `json:"source"`
	// Outcome: determines whether the event was successful or not, e.g. successful login
	// It may also determine if the event was approved or denied.
	Outcome string `json:"outcome"`
	// Subject: is the identity of the subject of the event.
	// e.g. who triggered the event? Additional information
	// may be added, such as group membership and/or role
	Subjects map[string]string `json:"subjects"`
	// Component: allows to determine in which component the event occurred
	// (Answering the "Where" question of section c in the NIST SP 800-53
	// Revision 5.1 Control AU-3).
	Component string `json:"component"`
	// Target: Defines where the target of the operation. e.g. the path of
	// the REST resource
	// (Answering the "Where" question of section c in the NIST SP 800-53
	// Revision 5.1 Control AU-3 as well as indicating an entity
	// associated for section f).
	Target map[string]string `json:"target,omitempty"`
	// Data: enhances the audit event with extra information that may be
	// useful for forensic analysis.
	Data *json.RawMessage `json:"data,omitempty"`
}

AuditEvent represents an audit event. It provides the minimal information needed to audit an event, as well as a uniform format to persist the events in audit logs.

It is highly recommended to use the NewAuditEvent function to create audit events and set the required fields.

func NewAuditEvent

func NewAuditEvent(
	eventType string,
	source EventSource,
	outcome string,
	subjects map[string]string,
	component string,
) *AuditEvent

NewAuditEvent returns a new AuditEvent with an appropriately set AuditID and logging time.

func NewAuditEventWithID

func NewAuditEventWithID(
	auditID string,
	eventType string,
	source EventSource,
	outcome string,
	subjects map[string]string,
	component string,
) *AuditEvent

NewAuditEventWithID returns a new AuditEvent with the passed AuditID.

func (*AuditEvent) LogTo

func (e *AuditEvent) LogTo(ctx context.Context, logger *slog.Logger, level slog.Level)

LogTo logs the audit event to the provided slog.Logger using the custom audit level.

func (*AuditEvent) WithData

func (e *AuditEvent) WithData(data *json.RawMessage) *AuditEvent

WithData sets the data of the event.

func (*AuditEvent) WithDataFromString

func (e *AuditEvent) WithDataFromString(data string) *AuditEvent

WithDataFromString sets the data of the event from a string. Note that validating that this is properly JSON-formatted is the responsibility of the caller.

func (*AuditEvent) WithTarget

func (e *AuditEvent) WithTarget(target map[string]string) *AuditEvent

WithTarget sets the target of the event.

type Auditor

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

Auditor handles audit logging for HTTP requests.

func NewAuditor

func NewAuditor(config *Config) (*Auditor, error)

NewAuditor creates a new Auditor with the given configuration.

func (*Auditor) Middleware

func (a *Auditor) Middleware(next http.Handler) http.Handler

Middleware creates an HTTP middleware that logs audit events.

type Config

type Config struct {
	// Component is the component name to use in audit events
	Component string `json:"component,omitempty" yaml:"component,omitempty"`
	// EventTypes specifies which event types to audit. If empty, all events are audited.
	EventTypes []string `json:"event_types,omitempty" yaml:"event_types,omitempty"`
	// ExcludeEventTypes specifies which event types to exclude from auditing.
	// This takes precedence over EventTypes.
	ExcludeEventTypes []string `json:"exclude_event_types,omitempty" yaml:"exclude_event_types,omitempty"`
	// IncludeRequestData determines whether to include request data in audit logs
	IncludeRequestData bool `json:"include_request_data,omitempty" yaml:"include_request_data,omitempty"`
	// IncludeResponseData determines whether to include response data in audit logs
	IncludeResponseData bool `json:"include_response_data,omitempty" yaml:"include_response_data,omitempty"`
	// MaxDataSize limits the size of request/response data included in audit logs (in bytes)
	MaxDataSize int `json:"max_data_size,omitempty" yaml:"max_data_size,omitempty"`
	// LogFile specifies the file path for audit logs. If empty, logs to stdout.
	LogFile string `json:"log_file,omitempty" yaml:"log_file,omitempty"`
}

Config represents the audit logging configuration.

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns a default audit configuration.

func LoadFromFile

func LoadFromFile(path string) (*Config, error)

LoadFromFile loads audit configuration from a file.

func LoadFromReader

func LoadFromReader(r io.Reader) (*Config, error)

LoadFromReader loads audit configuration from an io.Reader.

func (*Config) CreateMiddleware

func (c *Config) CreateMiddleware() (func(http.Handler) http.Handler, error)

CreateMiddleware creates an HTTP middleware from the audit configuration.

func (*Config) GetLogWriter

func (c *Config) GetLogWriter() (io.Writer, error)

GetLogWriter creates and returns the appropriate io.Writer based on the configuration.

func (*Config) ShouldAuditEvent

func (c *Config) ShouldAuditEvent(eventType string) bool

ShouldAuditEvent determines whether an event should be audited based on the configuration.

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the audit configuration.

type EventMetadata

type EventMetadata struct {
	// AuditID: is a unique identifier for the audit event.
	AuditID string `json:"auditId"`
	// Extra allows for including additional information about the event
	// that aids in tracking, parsing or auditing
	Extra map[string]any `json:"extra,omitempty"`
}

EventMetadata contains metadata about the audit event.

type EventSource

type EventSource struct {
	// Type indicates the source type. e.g. Network, File, local, etc.
	// The intent is to determine where a request came from.
	Type string `json:"type"`
	// Value aims to indicate the source of the event. e.g. IP address,
	// hostname, etc.
	Value string `json:"value"`
	// Extra allows for including additional information about the event
	// source that aids in tracking, parsing or auditing
	Extra map[string]any `json:"extra,omitempty"`
}

EventSource represents the source of an audit event.