SPB Git

Repository Public

audit.go 7.0 KB 250 lines go

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, &params, &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
Files main
Menu

Theme