Documentation
¶
Overview ¶
Package audit provides structured logging for Superbrain autonomous actions. All autonomous actions (stdin injection, restarts, fallbacks, etc.) are logged to a dedicated audit log for security review and transparency.
Index ¶
- func InitGlobal(cfg Config) error
- type AuditLogEntry
- type Config
- type Logger
- func (l *Logger) Close() error
- func (l *Logger) LogAction(entry AuditLogEntry)
- func (l *Logger) LogContextOptimization(requestID, provider, model string, originalTokens, optimizedTokens int, ...)
- func (l *Logger) LogDiagnosis(requestID, provider, model, failureType, remediation string, ...)
- func (l *Logger) LogFallback(requestID, originalProvider, fallbackProvider, model, reason, outcome string)
- func (l *Logger) LogRestart(requestID, provider, model string, flags []string, outcome string)
- func (l *Logger) LogSilenceDetection(requestID, provider, model string, silenceDurationMs int64)
- func (l *Logger) LogStdinInjection(requestID, provider, model, pattern, response, outcome string)
- func (l *Logger) Rotate() error
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InitGlobal ¶
InitGlobal initializes the global audit logger with the specified configuration. This should be called once during application startup.
Types ¶
type AuditLogEntry ¶
type AuditLogEntry struct {
// Timestamp is when the action was initiated.
Timestamp time.Time `json:"timestamp"`
// RequestID uniquely identifies the request that triggered this action.
RequestID string `json:"request_id"`
// ActionType categorizes the autonomous action (e.g., "stdin_injection", "restart_with_flags").
ActionType string `json:"action_type"`
// Provider is the provider being executed (e.g., "claudecli", "geminicli").
Provider string `json:"provider"`
// Model is the model being used.
Model string `json:"model"`
// ActionDetails contains action-specific metadata (e.g., flags applied, pattern matched).
ActionDetails map[string]interface{} `json:"action_details,omitempty"`
// Outcome describes the result of the action ("success", "failed", "skipped").
Outcome string `json:"outcome"`
// UserIdentifier optionally identifies the user who initiated the request.
UserIdentifier string `json:"user_identifier,omitempty"`
}
AuditLogEntry records a single autonomous action for security review. Each entry is written as a JSON line to the audit log file.
type Config ¶
type Config struct {
// Enabled toggles audit logging.
Enabled bool
// LogPath is the file path for the audit log.
LogPath string
// MaxSizeMB is the maximum size in megabytes before rotation.
// Default: 100 MB.
MaxSizeMB int
// MaxBackups is the maximum number of old log files to retain.
// Default: 10.
MaxBackups int
// MaxAgeDays is the maximum number of days to retain old log files.
// Default: 30 days.
MaxAgeDays int
// Compress determines whether rotated log files should be compressed.
// Default: true.
Compress bool
}
Config holds configuration for the audit logger.
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger provides structured audit logging for Superbrain actions. It writes JSON-formatted log entries to a rotating log file.
Example ¶
ExampleLogger demonstrates basic usage of the audit logger.
package main
import (
"fmt"
"log"
"github.com/traylinx/switchAILocal/internal/superbrain/audit"
)
func main() {
// Create a new audit logger
logger, err := audit.NewLogger(audit.Config{
Enabled: true,
LogPath: "./logs/superbrain_audit.log",
MaxSizeMB: 100,
MaxBackups: 10,
MaxAgeDays: 30,
Compress: true,
})
if err != nil {
log.Fatalf("Failed to create audit logger: %v", err)
}
defer logger.Close()
// Log a stdin injection action
logger.LogStdinInjection(
"req-12345",
"claudecli",
"claude-sonnet-4",
"permission_prompt",
"y\n",
"success",
)
// Log a restart action
logger.LogRestart(
"req-12345",
"claudecli",
"claude-sonnet-4",
[]string{"--dangerously-skip-permissions"},
"success",
)
// Log a fallback routing action
logger.LogFallback(
"req-12345",
"claudecli",
"geminicli",
"claude-opus-4",
"max_retries_exceeded",
"success",
)
fmt.Println("Audit log entries written successfully")
}
Output: Audit log entries written successfully
Example (Disabled) ¶
ExampleLogger_disabled demonstrates that a disabled logger is a no-op.
package main
import (
"fmt"
"log"
"github.com/traylinx/switchAILocal/internal/superbrain/audit"
)
func main() {
// Create a disabled logger
logger, err := audit.NewLogger(audit.Config{
Enabled: false,
})
if err != nil {
log.Fatalf("Failed to create audit logger: %v", err)
}
defer logger.Close()
// These calls are safe but do nothing
logger.LogStdinInjection("req-1", "test", "test-model", "pattern", "response", "success")
logger.LogRestart("req-2", "test", "test-model", []string{"--flag"}, "success")
fmt.Println("Disabled logger is safe to use")
}
Output: Disabled logger is safe to use
func Global ¶
func Global() *Logger
Global returns the global audit logger instance. It must be initialized with InitGlobal before use.
Example ¶
ExampleGlobal demonstrates usage of the global audit logger.
package main
import (
"fmt"
"log"
"github.com/traylinx/switchAILocal/internal/superbrain/audit"
)
func main() {
// Initialize the global audit logger
err := audit.InitGlobal(audit.Config{
Enabled: true,
LogPath: "./logs/superbrain_audit.log",
MaxSizeMB: 100,
MaxBackups: 10,
MaxAgeDays: 30,
Compress: true,
})
if err != nil {
log.Fatalf("Failed to initialize global audit logger: %v", err)
}
// Use the global logger from anywhere in the application
audit.Global().LogDiagnosis(
"req-67890",
"claudecli",
"claude-sonnet-4",
"permission_prompt",
"stdin_inject",
0.95,
)
fmt.Println("Global audit logger initialized and used")
}
Output: Global audit logger initialized and used
func NewLogger ¶
NewLogger creates a new audit logger with the specified configuration. If audit logging is disabled, the logger will be a no-op.
func (*Logger) LogAction ¶
func (l *Logger) LogAction(entry AuditLogEntry)
LogAction writes an audit log entry for an autonomous action. This method is thread-safe and can be called concurrently.
func (*Logger) LogContextOptimization ¶
func (l *Logger) LogContextOptimization(requestID, provider, model string, originalTokens, optimizedTokens int, outcome string)
LogContextOptimization logs a context sculpting action.
func (*Logger) LogDiagnosis ¶
func (l *Logger) LogDiagnosis(requestID, provider, model, failureType, remediation string, confidence float64)
LogDiagnosis logs a failure diagnosis action.
func (*Logger) LogFallback ¶
func (l *Logger) LogFallback(requestID, originalProvider, fallbackProvider, model, reason, outcome string)
LogFallback logs a fallback routing action.
func (*Logger) LogRestart ¶
LogRestart logs a process restart action.
func (*Logger) LogSilenceDetection ¶
LogSilenceDetection logs when a silence threshold is exceeded.
func (*Logger) LogStdinInjection ¶
LogStdinInjection logs a stdin injection action.
Source Files