Repository Public
1package audit23import (4 "bufio"5 "bytes"6 "context"7 "crypto/ed25519"8 "crypto/sha256"9 "encoding/base64"10 "encoding/hex"11 "encoding/json"12 "errors"13 "fmt"14 "io"15 "strings"16 "time"1718 "github.com/google/uuid"19 "github.com/jackc/pgx/v5"20)2122// Signed export of a range of the audit log.23//24// Format: JSON Lines. One ExportEntry per line in ascending seq, then ONE25// final line {"manifest":{…},"signature":"<key id>:<base64>"}.26//27// The manifest states the range, the number of entries, the first and last28// seq, the chain hash before the first entry (prev_hash), the hash of the29// last entry (head_hash) and the SHA-256 of every byte that precedes the30// manifest line. The signature is Ed25519 over a domain prefix followed by31// the exact bytes of the manifest object. Because the body is streamed, its32// hash is only known at the end: that is why the signed manifest is the last33// line of the file rather than an HTTP header. (The response headers carry34// the head hash, known beforehand, and a detached signature of it.)35//36// VerifyExport needs nothing but the file and the public key. It checks the37// signature, the byte hash, the counts, that every entry's hash matches its38// content, and that the entries form an unbroken chain from prev_hash to39// head_hash. Any changed, removed, added or reordered byte fails one of them.4041const (42 exportDomain = "mcc-audit-export-v1\x00"43 headDomain = "mcc-audit-head-v1\x00"44)4546type ExportEntry struct {47 Seq int64 `json:"seq"`48 TS time.Time `json:"ts"`49 ActorKind string `json:"actor_kind"`50 ActorID *uuid.UUID `json:"actor_id,omitempty"`51 ActorLabel string `json:"actor_label"`52 DeviceID *uuid.UUID `json:"device_id,omitempty"`53 SessionID *uuid.UUID `json:"session_id,omitempty"`54 IP *string `json:"ip,omitempty"`55 Action string `json:"action"`56 TargetKind string `json:"target_kind,omitempty"`57 TargetID string `json:"target_id,omitempty"`58 Params json.RawMessage `json:"params"`59 Outcome string `json:"outcome"`60 Detail string `json:"detail"`61 CorrelationID uuid.UUID `json:"correlation_id"`62 PrevHash string `json:"prev_hash"`63 Hash string `json:"hash"`64}6566// contentHash recomputes the chain hash of an entry from its exported fields.67func (x ExportEntry) contentHash(prev []byte) []byte {68 e := Entry{ActorKind: x.ActorKind, ActorID: x.ActorID, ActorLabel: x.ActorLabel, DeviceID: x.DeviceID, SessionID: x.SessionID, Action: x.Action,69 TargetKind: x.TargetKind, TargetID: x.TargetID, Outcome: Outcome(x.Outcome), Detail: x.Detail, CorrelationID: x.CorrelationID}70 return entryHash(prev, x.TS.UTC(), e, x.Params, x.IP)71}7273type Manifest struct {74 V int `json:"v"`75 From time.Time `json:"from"`76 To time.Time `json:"to"`77 Count int64 `json:"count"`78 FirstSeq int64 `json:"first_seq"`79 LastSeq int64 `json:"last_seq"`80 PrevHash string `json:"prev_hash"` // chain hash before the first exported entry ("" when empty)81 HeadHash string `json:"head_hash"` // hash of the last exported entry ("" when empty)82 SHA256 string `json:"sha256"` // of all bytes before the manifest line83 KeyID string `json:"key_id"`84 ExportedAt time.Time `json:"exported_at"`85}8687type manifestLine struct {88 Manifest json.RawMessage `json:"manifest"`89 Signature string `json:"signature"`90}9192func sign(priv ed25519.PrivateKey, keyID, domain string, msg []byte) string {93 return keyID + ":" + base64.StdEncoding.EncodeToString(ed25519.Sign(priv, append([]byte(domain), msg...)))94}9596func checkSig(pub ed25519.PublicKey, domain string, msg []byte, sig string) (keyID string, err error) {97 keyID, b64, ok := strings.Cut(sig, ":")98 raw, derr := base64.StdEncoding.DecodeString(b64)99 if !ok || derr != nil || len(pub) != ed25519.PublicKeySize || !ed25519.Verify(pub, append([]byte(domain), msg...), raw) {100 return keyID, errors.New("signature does not verify")101 }102 return keyID, nil103}104105// SignHead signs the hex head hash (X-MCC-Audit-Signature header).106func SignHead(priv ed25519.PrivateKey, keyID, headHex string) string {107 return sign(priv, keyID, headDomain, []byte(headHex))108}109110// VerifyHead checks a detached head-hash signature.111func VerifyHead(pub ed25519.PublicKey, headHex, sig string) error {112 _, err := checkSig(pub, headDomain, []byte(headHex), sig)113 return err114}115116const exportColumns = `seq, ts, actor_kind, actor_id, actor_label, device_id, session_id, host(ip), action, coalesce(target_kind,''), coalesce(target_id,''),117 params, outcome::text, detail, correlation_id, prev_hash, hash`118119func scanExport(rows pgx.Rows) (ExportEntry, []byte, []byte, error) {120 var x ExportEntry121 var params, prev, hash []byte122 err := rows.Scan(&x.Seq, &x.TS, &x.ActorKind, &x.ActorID, &x.ActorLabel, &x.DeviceID, &x.SessionID, &x.IP, &x.Action, &x.TargetKind, &x.TargetID,123 ¶ms, &x.Outcome, &x.Detail, &x.CorrelationID, &prev, &hash)124 x.TS = x.TS.UTC()125 x.Params = params126 x.PrevHash, x.Hash = hex.EncodeToString(prev), hex.EncodeToString(hash)127 return x, prev, hash, err128}129130// Head returns the hex hash of the last entry of [from, to) ("" when empty).131func Head(ctx context.Context, q interface {132 QueryRow(ctx context.Context, sql string, args ...any) pgx.Row133}, from, to time.Time) (string, error) {134 var h []byte135 err := q.QueryRow(ctx, `select hash from audit_log where ts >= $1 and ts < $2 order by seq desc limit 1`, from, to).Scan(&h)136 if errors.Is(err, pgx.ErrNoRows) {137 return "", nil138 }139 return hex.EncodeToString(h), err140}141142// WriteExport streams the entries of [from, to) and the signed manifest line.143// q should be a transaction with a stable snapshot (repeatable read) when the144// head hash was announced beforehand.145func WriteExport(ctx context.Context, q querier, w io.Writer, from, to time.Time, priv ed25519.PrivateKey, keyID string, now time.Time) (Manifest, error) {146 m := Manifest{V: 1, From: from.UTC(), To: to.UTC(), KeyID: keyID, ExportedAt: now.UTC()}147 rows, err := q.Query(ctx, `select `+exportColumns+` from audit_log where ts >= $1 and ts < $2 order by seq`, from, to)148 if err != nil {149 return m, err150 }151 defer rows.Close()152 sum := sha256.New()153 out := io.MultiWriter(w, sum)154 enc := json.NewEncoder(out)155 enc.SetEscapeHTML(false)156 for rows.Next() {157 x, _, _, err := scanExport(rows)158 if err != nil {159 return m, err160 }161 if m.Count == 0 {162 m.FirstSeq, m.PrevHash = x.Seq, x.PrevHash163 }164 m.Count++165 m.LastSeq, m.HeadHash = x.Seq, x.Hash166 if err := enc.Encode(x); err != nil {167 return m, err168 }169 }170 if err := rows.Err(); err != nil {171 return m, err172 }173 m.SHA256 = hex.EncodeToString(sum.Sum(nil))174 raw, err := json.Marshal(m)175 if err != nil {176 return m, err177 }178 line, err := json.Marshal(manifestLine{Manifest: raw, Signature: sign(priv, keyID, exportDomain, raw)})179 if err != nil {180 return m, err181 }182 _, err = w.Write(append(line, '\n'))183 return m, err184}185186// VerifyExport checks an export file offline. It returns the manifest when187// (and only when) everything verifies.188func VerifyExport(r io.Reader, pub ed25519.PublicKey) (Manifest, error) {189 var m Manifest190 br := bufio.NewReaderSize(r, 1<<20)191 sum := sha256.New()192 var (193 pending []byte // the previous line: an entry unless it turns out to be the last line194 prev []byte195 count int64196 first int64197 last int64198 firstPrv string199 head string200 )201 entry := func(line []byte) error {202 var x ExportEntry203 dec := json.NewDecoder(bytes.NewReader(line))204 dec.DisallowUnknownFields()205 if err := dec.Decode(&x); err != nil {206 return fmt.Errorf("line %d: not an audit entry: %v", count+1, err)207 }208 ph, err1 := hex.DecodeString(x.PrevHash)209 hh, err2 := hex.DecodeString(x.Hash)210 if err1 != nil || err2 != nil || len(ph) != sha256.Size || len(hh) != sha256.Size {211 return fmt.Errorf("seq %d: malformed hash", x.Seq)212 }213 if count == 0 {214 first, firstPrv = x.Seq, x.PrevHash215 } else {216 if !bytes.Equal(ph, prev) {217 return fmt.Errorf("seq %d: prev_hash does not match the previous entry (entry removed, added or reordered)", x.Seq)218 }219 if x.Seq <= last {220 return fmt.Errorf("seq %d: sequence not increasing", x.Seq)221 }222 }223 if !bytes.Equal(x.contentHash(ph), hh) {224 return fmt.Errorf("seq %d: content does not match its hash (entry modified)", x.Seq)225 }226 prev, last, head = hh, x.Seq, x.Hash227 count++228 sum.Write(line)229 return nil230 }231 for {232 line, err := br.ReadBytes('\n')233 if len(line) > 0 {234 if pending != nil {235 if err := entry(pending); err != nil {236 return m, err237 }238 }239 pending = line240 }241 if err == io.EOF {242 break243 }244 if err != nil {245 return m, err246 }247 }248 if pending == nil {249 return m, errors.New("empty file: no manifest")250 }251 if !bytes.HasSuffix(pending, []byte("\n")) {252 return m, errors.New("truncated file: the last line is incomplete")253 }254 var ml manifestLine255 dec := json.NewDecoder(bytes.NewReader(pending))256 dec.DisallowUnknownFields()257 if err := dec.Decode(&ml); err != nil || len(ml.Manifest) == 0 {258 return m, errors.New("the last line is not a signed manifest (truncated export?)")259 }260 if want, _ := json.Marshal(manifestLine{Manifest: ml.Manifest, Signature: ml.Signature}); !bytes.Equal(append(want, '\n'), pending) {261 return m, errors.New("the manifest line is not in canonical form")262 }263 keyID, err := checkSig(pub, exportDomain, ml.Manifest, ml.Signature)264 if err != nil {265 return m, fmt.Errorf("manifest: %w (key %q)", err, keyID)266 }267 mdec := json.NewDecoder(bytes.NewReader(ml.Manifest))268 mdec.DisallowUnknownFields()269 if err := mdec.Decode(&m); err != nil {270 return m, fmt.Errorf("manifest: %v", err)271 }272 switch {273 case m.V != 1:274 return m, fmt.Errorf("manifest: unsupported version %d", m.V)275 case m.KeyID != keyID:276 return m, errors.New("manifest: key id differs from the signature")277 case m.SHA256 != hex.EncodeToString(sum.Sum(nil)):278 return m, errors.New("the content does not match the SHA-256 of the manifest (bytes changed)")279 case m.Count != count:280 return m, fmt.Errorf("the file holds %d entries, the manifest says %d", count, m.Count)281 case count > 0 && (m.FirstSeq != first || m.LastSeq != last || m.HeadHash != head || m.PrevHash != firstPrv):282 return m, errors.New("first/last entries do not match the manifest")283 case count == 0 && (m.HeadHash != "" || m.PrevHash != ""):284 return m, errors.New("empty export with a head hash")285 }286 return m, nil287}288289// VerifyFrom recomputes the chain from fromSeq (anchored on the hash of the290// entry just before it). fromSeq <= 1 verifies the whole log.291func VerifyFrom(ctx context.Context, q interface {292 querier293 QueryRow(ctx context.Context, sql string, args ...any) pgx.Row294}, fromSeq int64) (VerifyResult, error) {295 if fromSeq <= 1 {296 return Verify(ctx, q)297 }298 prev := genesis299 if err := q.QueryRow(ctx, `select hash from audit_log where seq < $1 order by seq desc limit 1`, fromSeq).Scan(&prev); err != nil && !errors.Is(err, pgx.ErrNoRows) {300 return VerifyResult{}, err301 }302 rows, err := q.Query(ctx, `select `+exportColumns+` from audit_log where seq >= $1 order by seq`, fromSeq)303 if err != nil {304 return VerifyResult{}, err305 }306 defer rows.Close()307 res := VerifyResult{OK: true, HeadHash: prev}308 for rows.Next() {309 x, ph, hh, err := scanExport(rows)310 if err != nil {311 return res, err312 }313 if res.Entries == 0 {314 res.FirstSeq = x.Seq315 }316 res.Entries++317 if !bytes.Equal(ph, prev) {318 res.OK, res.BrokenSeq, res.Reason = false, x.Seq, "prev_hash does not match the previous entry (entry removed or reordered)"319 return res, nil320 }321 if !bytes.Equal(x.contentHash(prev), hh) {322 res.OK, res.BrokenSeq, res.Reason = false, x.Seq, "entry content does not match its hash (entry modified)"323 return res, nil324 }325 prev, res.LastSeq, res.HeadHash = hh, x.Seq, hh326 }327 return res, rows.Err()328}329