Audit Logging

The audit logging feature records all environment variable operations for security auditing, compliance checks, and troubleshooting.

Enabling Audit

Configuration

cfg := env.ProductionConfig()
cfg.AuditEnabled = true
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)

loader, _ := env.New(cfg)

Configuration Presets

Preset	Audit Status
DefaultConfig()	Disabled
DevelopmentConfig()	Disabled
TestingConfig()	Disabled
ProductionConfig()	Enabled

---

Audit Handlers

JSONAuditHandler

Outputs JSON formatted logs:

import (
    "os"
    "github.com/cybergodev/env"
)

cfg := env.ProductionConfig()
cfg.AuditEnabled = true
cfg.AuditHandler = env.NewJSONAuditHandler(os.Stdout)

Output Example:

{"timestamp":"2024-01-15T10:30:00Z","action":"load","file":".env","success":true,"duration_ns":1234567}
{"timestamp":"2024-01-15T10:30:01Z","action":"set","key":"[MASKED:7 chars]","success":true,"masked":true}
{"timestamp":"2024-01-15T10:30:02Z","action":"set","key":"CUSTOM_VAR","success":true}

Sensitive keys (such as API_KEY) have their key field automatically masked as [MASKED:N chars] in the audit log (N is the key length); non-sensitive keys (such as CUSTOM_VAR) are shown as-is.

---

LogAuditHandler

Outputs using the standard log package:

import (
    "log"
    "os"
    "github.com/cybergodev/env"
)

logger := log.New(os.Stderr, "[AUDIT] ", log.LstdFlags)
cfg.AuditHandler = env.NewLogAuditHandler(logger)

Output Example:

[AUDIT] 2024/01/15 10:30:00 action=load success=true reason="" file=.env duration=1.23ms
[AUDIT] 2024/01/15 10:30:01 action=set key=[MASKED:7 chars] success=true reason=""
[AUDIT] 2024/01/15 10:30:02 action=set key=CUSTOM_VAR success=true reason=""

---

ChannelAuditHandler

Sends to a channel for async processing:

ch := make(chan env.AuditEvent, 100)
cfg.AuditHandler = env.NewChannelAuditHandler(ch)

// Process audit events asynchronously
go func() {
    for event := range ch {
        processAuditEvent(event)
    }
}()

Use cases:

• Send to remote logging services
• Write to databases
• Real-time monitoring and alerting

---

NopAuditHandler

A no-op handler that discards all events:

cfg.AuditHandler = env.NewNopAuditHandler()

Use cases:

• Temporarily disable auditing
• Testing environments

---

Audit Events

AuditEvent Structure

type AuditEvent struct {
    Timestamp time.Time   // Timestamp
    Action    AuditAction // Action type
    Key       string      // Key name
    File      string      // File name
    Reason    string      // Reason
    Success   bool        // Whether successful
    Masked    bool        // Whether masked
    Details   string      // Details
    Duration  int64       // Duration (nanoseconds)
}

AuditAction Types

Constant	Value	Description
ActionLoad	load	File loading
ActionParse	parse	Parse operation
ActionGet	get	Variable read
ActionSet	set	Variable set
ActionDelete	delete	Variable delete
ActionValidate	validate	Validation operation
ActionExpand	expand	Variable expansion
ActionSecurity	security	Security event
ActionError	error	Error event
ActionFileAccess	file_access	File access

---

Custom Handlers

Implementing the FullAuditLogger Interface

FullAuditLogger is the complete audit logging interface, extending the minimal AuditLogger interface (which only contains the LogError method):

type FullAuditLogger interface {
    AuditLogger  // Embeds minimal interface (LogError)
    Log(action AuditAction, key, reason string, success bool) error
    LogWithFile(action AuditAction, key, file, reason string, success bool) error
    LogWithDuration(action AuditAction, key, reason string, success bool, duration time.Duration) error
    Close() error
}

Example: Database Audit Handler

package myhandler

import (
    "database/sql"
    "time"
    "github.com/cybergodev/env"
)

type DatabaseAuditHandler struct {
    db *sql.DB
}

func NewDatabaseAuditHandler(db *sql.DB) *DatabaseAuditHandler {
    return &DatabaseAuditHandler{db: db}
}

func (h *DatabaseAuditHandler) Log(action env.AuditAction, key, reason string, success bool) error {
    _, err := h.db.Exec(`
        INSERT INTO audit_log (timestamp, action, key, reason, success)
        VALUES (?, ?, ?, ?, ?)
    `, time.Now(), string(action), key, reason, success)
    return err
}

func (h *DatabaseAuditHandler) LogError(action env.AuditAction, key, errMsg string) error {
    return h.Log(action, key, errMsg, false)
}

func (h *DatabaseAuditHandler) LogWithFile(action env.AuditAction, key, file, reason string, success bool) error {
    _, err := h.db.Exec(`
        INSERT INTO audit_log (timestamp, action, key, file, reason, success)
        VALUES (?, ?, ?, ?, ?, ?)
    `, time.Now(), string(action), key, file, reason, success)
    return err
}

func (h *DatabaseAuditHandler) LogWithDuration(action env.AuditAction, key, reason string, success bool, duration time.Duration) error {
    _, err := h.db.Exec(`
        INSERT INTO audit_log (timestamp, action, key, reason, success, duration_ms)
        VALUES (?, ?, ?, ?, ?, ?)
    `, time.Now(), string(action), key, reason, success, duration.Milliseconds())
    return err
}

func (h *DatabaseAuditHandler) Close() error {
    return nil
}

---

Complete Examples

Production Configuration

package main

import (
    "log"
    "os"
    "github.com/cybergodev/env"
)

func main() {
    // Create audit log file
    auditFile, err := os.OpenFile("/var/log/app/env-audit.log",
        os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)
    if err != nil {
        log.Fatal(err)
    }
    defer auditFile.Close()

    // Configuration
    cfg := env.ProductionConfig()
    cfg.AuditEnabled = true
    cfg.AuditHandler = env.NewJSONAuditHandler(auditFile)
    cfg.RequiredKeys = []string{"DB_HOST", "API_KEY"}

    // Create loader
    loader, err := env.New(cfg)
    if err != nil {
        log.Fatal(err)
    }
    defer loader.Close()

    // Load configuration
    err = loader.LoadFiles(".env")
    if err != nil {
        log.Fatal(err)
    }

    // Validate
    err = loader.Validate()
    if err != nil {
        log.Fatal(err)
    }

    // Use configuration
    log.Println("Configuration loaded successfully")
}

Async Audit Processing

package main

import (
    "encoding/json"
    "log"
    "os"
    "github.com/cybergodev/env"
)

func main() {
    // Create audit event channel
    auditChan := make(chan env.AuditEvent, 1000)

    // Start async processor
    go processAuditEvents(auditChan)

    // Configuration
    cfg := env.ProductionConfig()
    cfg.AuditEnabled = true
    cfg.AuditHandler = env.NewChannelAuditHandler(auditChan)

    loader, _ := env.New(cfg)
    defer loader.Close()

    // Normal usage...
}

func processAuditEvents(ch chan env.AuditEvent) {
    file, _ := os.OpenFile("/var/log/app/audit.log",
        os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0600)
    defer file.Close()

    encoder := json.NewEncoder(file)

    for event := range ch {
        // Add filtering, aggregation, etc.
        if event.Action == env.ActionError {
            log.Printf("Audit error: %+v", event)
        }

        encoder.Encode(event)
    }
}

---

Security Considerations

Audit Records and Masking

The audit log automatically masks the key field of sensitive keys (shown as [MASKED:N chars], where N is the number of characters in the key name; non-sensitive keys are shown as-is). Only write operations produce audit events: Set / Delete / LoadFiles and similar trigger ActionSet / ActionDelete / ActionLoad events and record the masked key name in the event.

Read operations do not produce audit events: Get / GetString / GetInt / GetSecure and similar normal reads do not record audit logs. The ActionGet event is only triggered on the error path of a parse failure during type conversion in GetInt / GetBool / GetFloat64 and similar (success=false), for example:

// Write operation: produces an audit event (sensitive key recorded after masking)
_ = loader.Set("API_KEY", "sk-1234567890")
// Audit record: {"action":"set","key":"[MASKED:7 chars]","success":true,"masked":true}

// Read operations: normal reads do not produce audit events
secret := loader.GetSecure("API_KEY") // no audit log produced
_ = loader.GetInt("PORT")             // parse succeeds, no audit log produced
_ = loader.GetInt("API_KEY")          // produces an ActionGet event when parsing fails (success=false)

Audit Log Permissions

# Set audit log file permissions
chmod 600 /var/log/app/env-audit.log

# Ensure only the application user can read/write
chown app:app /var/log/app/env-audit.log

Log Rotation

Using logrotate to manage audit logs is recommended:

# /etc/logrotate.d/app-env-audit
/var/log/app/env-audit.log {
    daily
    rotate 30
    compress
    delaycompress
    missingok
    notifempty
    create 0600 app app
}

---

Related Documentation

• Security Overview - Security architecture and core features
• Production Checklist - Audit configuration checklist
• Interfaces - AuditLogger interface
• Component Factory - Audit handler factory