securitylog

Documentation

Overview

Package securitylog provides an append-only, mutex-protected JSON Lines writer for structured security events. Events are written to both a dedicated log file and kept in a bounded in-memory ring buffer for the /api/security/events and /api/security/summary admin endpoints.

Reference: Tech Spec Section 11.2.

Index

• type Event
• type Logger
  • func New(logFile string, logger *slog.Logger) (*Logger, error)
  • func (l *Logger) Close() error
  • func (l *Logger) Emit(e Event)
  • func (l *Logger) Recent(n int) []Event
  • func (l *Logger) Summarize() Summary
  • func (l *Logger) SummarizeDetailed() (Summary, map[string]SourceMetrics)
• type SourceMetrics
• type Summary

Types

type Event

type Event struct {
	EventType string                 `json:"event_type"`
	Source    string                 `json:"source,omitempty"`
	Subject   string                 `json:"subject,omitempty"`
	IP        string                 `json:"ip,omitempty"`
	Endpoint  string                 `json:"endpoint,omitempty"`
	Timestamp time.Time              `json:"timestamp"`
	Details   map[string]interface{} `json:"details,omitempty"`
}

Event represents a single structured security event. Reference: Tech Spec Section 11.2.

type Logger

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

Logger is an append-only, mutex-protected security event logger. It writes JSON Lines to a file and retains the last maxRing events in memory for the admin API.

func New

func New(logFile string, logger *slog.Logger) (*Logger, error)

New creates a Logger that writes to logFile. The parent directory is created with mode 0700 if needed. The file is opened append-only with mode 0600. Returns an error if the file cannot be opened.

func (*Logger) Close

func (l *Logger) Close() error

Close flushes and closes the underlying file. Safe to call multiple times.

func (*Logger) Emit

func (l *Logger) Emit(e Event)

Emit writes a security event to the file and ring buffer. It is safe for concurrent use. Errors writing to the file are logged but do not propagate — the ring buffer always receives the event.

func (*Logger) Recent

func (l *Logger) Recent(n int) []Event

Recent returns the last n events from the ring buffer. If n <= 0 or exceeds the buffer size, all buffered events are returned. The returned slice is a copy and safe to use without holding the lock.

func (*Logger) Summarize

func (l *Logger) Summarize() Summary

Summarize returns aggregated counts across all buffered events.

func (*Logger) SummarizeDetailed

func (l *Logger) SummarizeDetailed() (Summary, map[string]SourceMetrics)

SummarizeDetailed returns aggregated counts with per-source per-event-type breakdown for the dashboard contract /api/security/summary shape.

type SourceMetrics

type SourceMetrics struct {
	AuthFailures  int `json:"auth_failures"`
	PolicyDenials int `json:"policy_denials"`
	RateLimitHits int `json:"rate_limit_hits"`
}

SourceMetrics holds per-source security metric breakdown.

type Summary

type Summary struct {
	AuthFailures              int            `json:"auth_failures"`
	PolicyDenials             int            `json:"policy_denials"`
	RateLimitHits             int            `json:"rate_limit_hits"`
	WALTamperDetected         int            `json:"wal_tamper_detected"`
	ConfigSignatureInvalid    int            `json:"config_signature_invalid"`
	AdminAccess               int            `json:"admin_access"`
	RetrievalFirewallFiltered int            `json:"retrieval_firewall_filtered"`
	RetrievalFirewallDenied   int            `json:"retrieval_firewall_denied"`
	BySource                  map[string]int `json:"by_source"`
}

Summary holds aggregated counts for /api/security/summary.