Documentation
¶
Overview ¶
Package audit provides structured audit logging for device spec transitions.
The audit logger records all mutations to device spec files (current.json, desired.json, rollback.json) in JSON lines format at /var/log/flightctl/audit.log. Events capture version transitions with action-based types (bootstrap, sync, upgrade, rollback) to provide a comprehensive audit trail for troubleshooting and compliance.
Log rotation is handled automatically using lumberjack with hardcoded defaults (2MB per file, 3 backups, 8MB total capacity).
Package audit is a generated GoMock package.
Index ¶
Constants ¶
const ( // DefaultLogPath is the hardcoded path for audit logs - not configurable by users DefaultLogPath = "/var/log/flightctl/audit.log" // DefaultEnabled is the default enabled state for audit logging DefaultEnabled = true // Hardcoded rotation defaults - non-configurable by users // 300 KB per file, 3 backups = 1.2 MB total (≈4,200 records) DefaultMaxSizeKB = 300 // 300KB per file (approximately 1,050 records) DefaultMaxBackups = 3 // Keep 3 backup files (1 active + 3 backups = 1.2 MB total) DefaultMaxAge = 0 // No time-based pruning )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AuditConfig ¶
type AuditConfig struct {
// Enabled enables or disables audit logging.
// Using *bool to distinguish between unset (nil) and explicitly set (true/false).
// This allows config overrides to explicitly disable audit logging with "enabled: false".
Enabled *bool `json:"enabled,omitempty"`
}
AuditConfig holds audit logging configuration. Flat enable/disable configuration only - rotation settings are hardcoded.
func NewDefaultAuditConfig ¶
func NewDefaultAuditConfig() *AuditConfig
NewDefaultAuditConfig creates a new audit config with default values. Following the pattern from config.NewDefault().
func (*AuditConfig) Complete ¶
func (c *AuditConfig) Complete() error
Complete fills in defaults for fields not set by the config. Following the pattern from agent config.Complete().
func (*AuditConfig) Validate ¶
func (c *AuditConfig) Validate(readWriter fileio.ReadWriter) error
Validate checks that the configuration is valid. Following the pattern from agent config.Validate().
type Event ¶
type Event struct {
Ts string `json:"ts"` // RFC3339 UTC format - when the attempt started
Device string `json:"device"` // device name
OldVersion string `json:"old_version"` // current effective version before the attempt
NewVersion string `json:"new_version"` // target version
Result Result `json:"result"` // success | failure
Reason Reason `json:"reason"` // why the write happened (bootstrap/sync/upgrade/rollback/recovery/initialization)
Type Type `json:"type"` // current/desired/rollback (WHAT file operation)
FleetTemplateVersion string `json:"fleet_template_version"` // from metadata.annotations["fleet-controller/templateVersion"]
AgentVersion string `json:"agent_version"` // e.g., 0.10.0
}
Event represents a single audit log entry.
type EventInfo ¶
type EventInfo struct {
Device string
OldVersion string
NewVersion string
Result Result
Reason Reason // WHY: bootstrap/sync/upgrade/rollback/recovery/initialization
Type Type // WHAT: current/desired/rollback
FleetTemplateVersion string
StartTime time.Time // When the operation started
}
EventInfo contains all the information needed to log an audit event. Note: AgentVersion is not included here as it's provided by the FileLogger at construction time.
type FileLogger ¶
type FileLogger struct {
// contains filtered or unexported fields
}
FileLogger implements the Logger interface using file-based logging with rotation. Following the pattern from config.Controller struct.
func NewFileLogger ¶
func NewFileLogger( config *AuditConfig, readWriter fileio.ReadWriter, deviceID string, agentVersion string, log *log.PrefixLogger, ) (*FileLogger, error)
NewFileLogger creates a new file-based audit logger. Following the dependency injection pattern from status.NewManager and config.NewController.
func (*FileLogger) Close ¶
func (f *FileLogger) Close() error
Close closes the audit logger and flushes any pending writes.
type Logger ¶
type Logger interface {
// LogEvent logs a complete audit event with all required fields.
LogEvent(ctx context.Context, info *EventInfo) error
// Close closes the audit logger and flushes any pending writes.
Close() error
}
Logger defines the interface for audit logging operations. Following the pattern from status.Manager interface.
type MockLogger ¶
type MockLogger struct {
// contains filtered or unexported fields
}
MockLogger is a mock of Logger interface.
func NewMockLogger ¶
func NewMockLogger(ctrl *gomock.Controller) *MockLogger
NewMockLogger creates a new mock instance.
func (*MockLogger) EXPECT ¶
func (m *MockLogger) EXPECT() *MockLoggerMockRecorder
EXPECT returns an object that allows the caller to indicate expected use.
type MockLoggerMockRecorder ¶
type MockLoggerMockRecorder struct {
// contains filtered or unexported fields
}
MockLoggerMockRecorder is the mock recorder for MockLogger.
func (*MockLoggerMockRecorder) Close ¶
func (mr *MockLoggerMockRecorder) Close() *gomock.Call
Close indicates an expected call of Close.
type Reason ¶
type Reason string
Reason represents why a spec file was written to disk. All disk writes are audited - the reason field documents the purpose of each write.
const ( // ReasonBootstrap represents initial device enrollment and first file creation ReasonBootstrap Reason = "bootstrap" // ReasonSync represents receiving a new spec from the management API ReasonSync Reason = "sync" // ReasonUpgrade represents applying a new desired spec ReasonUpgrade Reason = "upgrade" // ReasonRollback represents reverting to a previous working spec ReasonRollback Reason = "rollback" // ReasonRecovery represents recovery operations (recreating corrupted/deleted files) ReasonRecovery Reason = "recovery" // ReasonInitialization represents internal initialization operations (creating rollback snapshots) ReasonInitialization Reason = "initialization" )
Source Files