// Package auditquery scans the server's JSON-lines audit file. // // The server writes its own audit records to logs/audit.log (see // logger.AuditAt); records are already redacted at write time, so returning // raw fields to an authenticated viewer is safe as long as we never widen what // is written. // // Only the CURRENT audit file is searched. Rotated files (audit-*.log[.gz]) // are deliberately out of scope: they need gzip support and a separate index, // and both the web UI and the MCP tool exist for recent-window triage ("what // happened just now"). // // The package is shared by web/audit_query.go (admin audit page) and the MCP // get_audit_log tool, which is why it has no dependency on either. package auditquery import ( "bufio" "encoding/json" "os" "strings" "time" ) const ( // DefaultLimit is used when the caller asks for no limit (0 or negative). DefaultLimit = 100 // MaxLimit caps how many records one query may return. MaxLimit = 1000 // MaxOffset caps how far a query may page into the result set. MaxOffset = 10000 // scanBudget bounds how much of the audit file a single query reads. The // tail is read when the file is larger, so the newest records (what // operators actually triage) are always covered and a multi-GB log cannot // stall the query goroutine. scanBudget = 32 << 20 // 32 MB ) // Query is one audit-log search. All filters are optional and combined with // AND. Limit/Offset are clamped by Scan; callers that report the effective // values back should clamp first with ClampLimit/ClampOffset. type Query struct { From string `json:"from"` // RFC3339 ("2026-10-18T10:00:00Z"), optional To string `json:"to"` // RFC3339, optional Event string `json:"event"` // exact ("web.login.failure"), prefix ("web." / "web.*"), or "" Actor string `json:"actor"` // exact, case-insensitive IP string `json:"ip"` // exact DeviceID string `json:"device_id"` Keyword string `json:"keyword"` // case-insensitive substring of the raw record WarnOnly bool `json:"warn_only"` // only level=warn records // EventContains is a case-insensitive substring match on the event column. // The web UI uses Event's exact/prefix forms; the MCP get_audit_log tool // exposes a "type contains" filter, which maps here. EventContains string `json:"event_contains"` Limit int `json:"limit"` Offset int `json:"offset"` // skip the newest N matching records } // Result is the outcome of scanning the audit file. type Result struct { Events []map[string]any // newest-first Total int // matching records in the scanned window TotalAll int // audit records in the scanned window before filters FileExists bool FileSize int64 ScannedBytes int64 Truncated bool // the file was larger than the scan budget } // ClampLimit bounds n to [1, max]. A non-positive n means DefaultLimit; a // non-positive max means MaxLimit. Callers with a tighter UI cap (the web // audit page uses 500) pass it as max. func ClampLimit(n, max int) int { if max <= 0 { max = MaxLimit } if n <= 0 { return DefaultLimit } if n > max { return max } return n } // ClampOffset bounds n to [0, MaxOffset]. func ClampOffset(n int) int { if n < 0 { return 0 } if n > MaxOffset { return MaxOffset } return n } // Scan scans path for audit records matching q. The returned events are the // newest Limit records after skipping Offset, in newest-first order. A missing // file is not an error: no audit record has been written yet (the logger // creates the file lazily), so the result is empty with FileExists=false. func Scan(path string, q Query) (Result, error) { q.Limit = ClampLimit(q.Limit, MaxLimit) q.Offset = ClampOffset(q.Offset) res := Result{Events: []map[string]any{}} f, err := os.Open(path) if err != nil { if os.IsNotExist(err) { return res, nil } return res, err } defer f.Close() info, err := f.Stat() if err != nil { return res, err } res.FileExists = true res.FileSize = info.Size() // For very large files, scan only the tail; the newest matches live there. start := int64(0) if info.Size() > scanBudget { start = info.Size() - scanBudget if _, err := f.Seek(start, 0); err != nil { return res, err } res.Truncated = true } from, hasFrom := parseTime(q.From) to, hasTo := parseTime(q.To) keep := q.Offset + q.Limit ring := make([]map[string]any, keep) filled := 0 sc := bufio.NewScanner(f) // Sanitized values are capped at 4096 bytes each; a record with many // fields stays well under 1 MB. Allow headroom rather than aborting the // whole query on one long line. sc.Buffer(make([]byte, 64*1024), 4*1024*1024) first := true for sc.Scan() { line := sc.Text() if start > 0 && first { // Seeking into the middle of the file lands mid-line. Drop that // partial record. first = false continue } first = false res.ScannedBytes += int64(len(line)) + 1 line = strings.TrimSpace(line) if line == "" { continue } var rec map[string]any if err := json.Unmarshal([]byte(line), &rec); err != nil { continue // tolerate a torn line instead of failing the page } if _, ok := rec["event"].(string); !ok { continue } // Only audit records belong in the result. The dedicated file contains // nothing else, but a hand-edited or mixed file must not surface // ordinary operational lines here. if rec["audit"] != true { continue } res.TotalAll++ if !recordMatches(rec, line, q, from, hasFrom, to, hasTo) { continue } // Ring buffer of the last `keep` matches (file order is chronological). ring[res.Total%keep] = rec if filled < keep { filled++ } res.Total++ } if err := sc.Err(); err != nil { return res, err } // Newest first, skipping Offset. The match with 0-based index i lives at // ring[i%keep] as long as i >= Total-filled. for i := res.Total - 1 - q.Offset; i >= 0 && i >= res.Total-filled; i-- { res.Events = append(res.Events, ring[i%keep]) if len(res.Events) >= q.Limit { break } } return res, nil } // recordMatches applies the non-time and time filters to one record. line is // the raw JSON line, used for the keyword substring search. func recordMatches(rec map[string]any, line string, q Query, from time.Time, hasFrom bool, to time.Time, hasTo bool) bool { if q.Event != "" && !eventFilterMatches(q.Event, StringField(rec, "event")) { return false } if q.EventContains != "" && !strings.Contains(strings.ToLower(StringField(rec, "event")), strings.ToLower(q.EventContains)) { return false } if q.Actor != "" && !strings.EqualFold(StringField(rec, "actor"), q.Actor) { return false } if q.IP != "" && StringField(rec, "ip") != q.IP { return false } if q.DeviceID != "" && StringField(rec, "device_id") != q.DeviceID { return false } if q.WarnOnly && StringField(rec, "level") != "warn" { return false } if q.Keyword != "" && !strings.Contains(strings.ToLower(line), strings.ToLower(q.Keyword)) { return false } if hasFrom || hasTo { t, ok := parseTime(StringField(rec, "time")) if !ok { return false // cannot prove it is in range } if hasFrom && t.Before(from) { return false } if hasTo && t.After(to) { return false } } return true } // eventFilterMatches supports three forms so the UI stays simple: // // "web.login.failure" exact // "web.*" prefix (trailing "*") // "web." prefix (trailing ".") func eventFilterMatches(filter, event string) bool { switch { case strings.HasSuffix(filter, "*"): return strings.HasPrefix(event, strings.TrimSuffix(filter, "*")) case strings.HasSuffix(filter, "."): return strings.HasPrefix(event, filter) default: return event == filter } } // StringField returns rec[key] when it is a string, else "". func StringField(rec map[string]any, key string) string { s, _ := rec[key].(string) return s } // parseTime accepts the formats operators and browsers realistically send. // Layouts without an explicit zone are parsed as UTC; the frontend always sends // Date.toISOString(), so the RFC3339 path is what production uses. func parseTime(s string) (time.Time, bool) { s = strings.TrimSpace(s) if s == "" { return time.Time{}, false } layouts := []string{ time.RFC3339Nano, time.RFC3339, "2006-01-02T15:04:05", "2006-01-02T15:04", "2006-01-02 15:04:05", "2006-01-02", } for _, layout := range layouts { if t, err := time.Parse(layout, s); err == nil { return t, true } } return time.Time{}, false }