Repository Public
1// Package audit writes the append-only, hash-chained audit log.2//3// Each entry's hash covers the previous entry's hash and a canonical encoding4// of its own fields, so any after-the-fact edit, deletion or reordering5// (which the database triggers already refuse) is detectable by Verify.6package audit78import (9 "bytes"10 "context"11 "crypto/sha256"12 "encoding/binary"13 "encoding/json"14 "fmt"15 "net/netip"16 "regexp"17 "strings"18 "time"1920 "github.com/google/uuid"21 "github.com/jackc/pgx/v5"2223 "clustr.spboucher.ai/mcc/internal/events"24)2526type Outcome string2728const (29 Success Outcome = "success"30 Denied Outcome = "denied"31 Failure Outcome = "failure"32)3334// Entry is what callers provide. Params must contain non-sensitive values35// only; as a second line of defence, keys that look secret are masked.36type Entry struct {37 ActorKind string // user | agent | system | cli38 ActorID *uuid.UUID39 ActorLabel string40 DeviceID *uuid.UUID41 SessionID *uuid.UUID42 IP *netip.Addr43 Action string44 TargetKind string45 TargetID string46 Params map[string]any47 Outcome Outcome48 Detail string49 CorrelationID uuid.UUID50}5152// DB is satisfied by *pgxpool.Pool and pgx.Tx.53type DB interface {54 Begin(ctx context.Context) (pgx.Tx, error)55}5657const chainLock = 0x6d6363_025859var genesis = make([]byte, 32)6061var secretKey = regexp.MustCompile(`(?i)(token|secret|password|passwd|private|credential|authorization|cookie|api[_-]?key|challenge|signature)`)6263// Redact masks values whose key name suggests a secret, recursively.64func Redact(v map[string]any) map[string]any {65 if v == nil {66 return map[string]any{}67 }68 out := make(map[string]any, len(v))69 for k, val := range v {70 switch {71 case secretKey.MatchString(k):72 out[k] = "[redacted]"73 default:74 if m, ok := val.(map[string]any); ok {75 out[k] = Redact(m)76 } else {77 out[k] = val78 }79 }80 }81 return out82}8384// Append writes one entry. It runs in its own transaction when db is a pool,85// or inside the caller's transaction when db is a pgx.Tx (savepoint), so a86// state change and its audit record can commit atomically.87func Append(ctx context.Context, db DB, e Entry) (seq int64, err error) {88 if e.Action == "" || e.ActorKind == "" || e.Outcome == "" {89 return 0, fmt.Errorf("audit: incomplete entry")90 }91 if e.CorrelationID == uuid.Nil {92 e.CorrelationID = uuid.New()93 }94 params, err := json.Marshal(Redact(e.Params))95 if err != nil {96 return 0, fmt.Errorf("audit: params: %w", err)97 }98 tx, err := db.Begin(ctx)99 if err != nil {100 return 0, err101 }102 defer tx.Rollback(ctx)103 // Serialize writers: the chain is strictly ordered.104 if _, err := tx.Exec(ctx, `select pg_advisory_xact_lock($1)`, chainLock); err != nil {105 return 0, err106 }107 prev := genesis108 if err := tx.QueryRow(ctx, `select hash from audit_log order by seq desc limit 1`).Scan(&prev); err != nil && err != pgx.ErrNoRows {109 return 0, err110 }111 ts := time.Now().UTC().Truncate(time.Microsecond)112 var ip *string113 if e.IP != nil {114 s := e.IP.String()115 ip = &s116 }117 h := entryHash(prev, ts, e, params, ip)118 err = tx.QueryRow(ctx, `insert into audit_log119 (ts, actor_kind, actor_id, actor_label, device_id, session_id, ip, action, target_kind, target_id, params, outcome, detail, correlation_id, prev_hash, hash)120 values ($1,$2,$3,$4,$5,$6,$7::inet,$8,nullif($9,''),nullif($10,''),$11,$12,$13,$14,$15,$16) returning seq`,121 ts, e.ActorKind, e.ActorID, e.ActorLabel, e.DeviceID, e.SessionID, ip, e.Action, e.TargetKind, e.TargetID,122 params, string(e.Outcome), e.Detail, e.CorrelationID, prev, h).Scan(&seq)123 if err != nil {124 return 0, err125 }126 if err := events.Publish(ctx, tx, "audit.appended", map[string]int64{"seq": seq}); err != nil {127 return 0, err128 }129 return seq, tx.Commit(ctx)130}131132func entryHash(prev []byte, ts time.Time, e Entry, params []byte, ip *string) []byte {133 var b bytes.Buffer134 field := func(s string) {135 var n [4]byte136 binary.BigEndian.PutUint32(n[:], uint32(len(s)))137 b.Write(n[:])138 b.WriteString(s)139 }140 opt := func(u *uuid.UUID) string {141 if u == nil {142 return ""143 }144 return u.String()145 }146 b.Write(prev)147 field(ts.Format(time.RFC3339Nano))148 field(e.ActorKind)149 field(opt(e.ActorID))150 field(e.ActorLabel)151 field(opt(e.DeviceID))152 field(opt(e.SessionID))153 if ip != nil {154 field(*ip)155 } else {156 field("")157 }158 field(e.Action)159 field(e.TargetKind)160 field(e.TargetID)161 field(string(canonicalJSON(params)))162 field(string(e.Outcome))163 field(e.Detail)164 field(e.CorrelationID.String())165 sum := sha256.Sum256(b.Bytes())166 return sum[:]167}168169// canonicalJSON re-encodes JSON with sorted keys so the hash does not depend170// on how PostgreSQL's jsonb stores and returns the document.171func canonicalJSON(raw []byte) []byte {172 var v any173 dec := json.NewDecoder(bytes.NewReader(raw))174 dec.UseNumber()175 if err := dec.Decode(&v); err != nil {176 return raw177 }178 out, err := json.Marshal(v) // encoding/json sorts map keys179 if err != nil {180 return raw181 }182 return out183}184185// VerifyResult reports the state of the chain.186type VerifyResult struct {187 OK bool `json:"ok"`188 Entries int64 `json:"entries"`189 FirstSeq int64 `json:"first_seq"`190 LastSeq int64 `json:"last_seq"`191 HeadHash []byte `json:"head_hash"`192 BrokenSeq int64 `json:"broken_seq,omitempty"`193 Reason string `json:"reason,omitempty"`194}195196type querier interface {197 Query(ctx context.Context, sql string, args ...any) (pgx.Rows, error)198}199200// Verify recomputes the whole chain and reports the first inconsistency.201func Verify(ctx context.Context, q querier) (VerifyResult, error) {202 rows, err := q.Query(ctx, `select seq, ts, actor_kind, actor_id, actor_label, device_id, session_id, host(ip), action,203 coalesce(target_kind,''), coalesce(target_id,''), params, outcome::text, detail, correlation_id, prev_hash, hash204 from audit_log order by seq`)205 if err != nil {206 return VerifyResult{}, err207 }208 defer rows.Close()209 res := VerifyResult{OK: true}210 prev := genesis211 var lastSeq int64212 for rows.Next() {213 var (214 seq int64215 ts time.Time216 e Entry217 ip *string218 params, prevH, hashH []byte219 outcome string220 )221 if err := rows.Scan(&seq, &ts, &e.ActorKind, &e.ActorID, &e.ActorLabel, &e.DeviceID, &e.SessionID, &ip, &e.Action,222 &e.TargetKind, &e.TargetID, ¶ms, &outcome, &e.Detail, &e.CorrelationID, &prevH, &hashH); err != nil {223 return res, err224 }225 e.Outcome = Outcome(outcome)226 if res.Entries == 0 {227 res.FirstSeq = seq228 }229 res.Entries++230 fail := func(reason string) (VerifyResult, error) {231 res.OK, res.BrokenSeq, res.Reason = false, seq, reason232 return res, nil233 }234 if !bytes.Equal(prevH, prev) {235 return fail("prev_hash does not match the previous entry (entry removed or reordered)")236 }237 if !bytes.Equal(entryHash(prev, ts.UTC(), e, params, ip), hashH) {238 return fail("entry content does not match its hash (entry modified)")239 }240 prev, lastSeq = hashH, seq241 }242 res.LastSeq, res.HeadHash = lastSeq, prev243 return res, rows.Err()244}245246// ActionName validates the dotted lowercase naming of audit actions.247func ActionName(s string) bool {248 return s != "" && s == strings.ToLower(s) && !strings.ContainsAny(s, " \t\n")249}250