Files
sam dcc12582ce
deploy / plan (push) Successful in 35s
deploy / archied-image (push) Canceled after 0s
deploy / agent-image (push) Canceled after 0s
deploy / dist-zip (push) Canceled after 0s
deploy / gate (push) Canceled after 25s
ci/woodpecker/push/deploy Pipeline was canceled
feat(audit): set per-kind event retention from the instance (#1856)
The retention sweep applied one window to a code-fixed allowlist, and the
largest event kind (agent transcripts) was outside it, so the events table
grew whatever the instance set. The audit-retention document now takes
per-kind overrides, the dashboard offers each prunable kind its own window
from the server's list, and a kind without an override follows the default.
A security kind is refused where the document is written, and the sweep cuts
each kind at its own cutoff in one bounded, locked transaction.
2026-11-11 02:31:46 +11:00

745 lines
24 KiB
Go

package webui
import (
"context"
"encoding/csv"
"encoding/json"
"errors"
"fmt"
"io"
"log/slog"
"maps"
"mime"
"net/http"
"net/url"
"strconv"
"strings"
"sync"
"time"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
"github.com/samcharles93/archie-core/internal/domain/access"
"github.com/samcharles93/archie-core/internal/domain/audit"
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/ratelimit"
)
// auditExportPageSize is the largest page the feed serves. An export walks
// pages this size.
const auditExportPageSize = audit.MaxLimit
// The export budget: six exports an hour per identity, one at a time. The
// caller's explicit range bounds the work, the deadline bounds the request,
// and the page cap bounds the stream even if the range is dense.
const (
auditExportPerHour = 6
auditExportWindow = time.Hour
auditExportMaxRange = 366 * 24 * time.Hour
auditExportDeadline = 5 * time.Minute
auditExportMaxPages = 2000
// auditExportMaxRows bounds one download. The preflight refuses a larger
// match before any byte is written, so a client never gets a truncated
// file it cannot tell from a complete one.
auditExportMaxRows = 100_000
)
var (
errAuditExportTooLarge = errors.New("audit export exceeded its page cap")
errAuditExportCursor = errors.New("audit export cursor unreadable")
)
type auditActorView struct {
ID string `json:"id"`
Name string `json:"name"`
Kind string `json:"kind"`
PrincipalID string `json:"principal_id"`
}
type auditTargetView struct {
Kind string `json:"kind"`
ID string `json:"id"`
Label string `json:"label"`
Href string `json:"href,omitempty"`
}
type auditFieldView struct {
Field string `json:"field"`
Old json.RawMessage `json:"old"`
New json.RawMessage `json:"new"`
}
type auditDetailView struct {
Fields []auditFieldView `json:"fields"`
Data json.RawMessage `json:"data"`
Version int64 `json:"version"`
RequestID string `json:"request_id"`
Source string `json:"source"`
Table string `json:"table"`
}
type auditRecordView struct {
ID string `json:"id"`
At time.Time `json:"at"`
Category string `json:"category"`
Action string `json:"action"`
Kind string `json:"kind"`
Severity string `json:"severity"`
Outcome string `json:"outcome"`
Actor auditActorView `json:"actor"`
Target auditTargetView `json:"target"`
Summary string `json:"summary"`
Detail auditDetailView `json:"detail"`
}
// auditSettingsKind is one control-plane resource kind and the title the
// catalog gives it, so the dashboard labels a settings row without carrying
// its own copy of the vocabulary.
type auditSettingsKind struct {
Kind string `json:"kind"`
Title string `json:"title"`
}
type auditFacetsView struct {
Categories []string `json:"categories"`
Severities []string `json:"severities"`
Outcomes []string `json:"outcomes"`
TargetKinds []string `json:"target_kinds"`
SettingsKinds []auditSettingsKind `json:"settings_kinds"`
// RetentionKinds is the runtime event kinds the instance's audit
// retention setting can give a window to; the dashboard offers exactly
// these in its retention editor.
RetentionKinds []string `json:"retention_kinds"`
}
type auditResponse struct {
Records []auditRecordView `json:"records"`
NextCursor string `json:"next_cursor"`
HasMore bool `json:"has_more"`
// Facets is supplied on the first page only: it is the closed vocabulary
// the UI needs once, not a field to repeat on every page.
Facets *auditFacetsView `json:"facets,omitempty"`
}
// auditAPI owns the /api/audit routes. exporting admits one export per
// identity and exportRate bounds how many each identity starts an hour; an
// export is also bounded by its explicit range, a five-minute deadline and a
// page cap.
type auditAPI struct {
audit audit.Store
controlPlane controlpb.ControlPlaneServiceClient
log *slog.Logger
actorNames func(context.Context) func(string) string
workflowDefinitions func(context.Context) ([]task.Definition, error)
exportRate *ratelimit.Limiter
exportMu sync.Mutex
exporting map[string]bool
}
func newAuditAPI(s *Server) *auditAPI {
return &auditAPI{
audit: s.Audit,
controlPlane: s.ControlPlane,
log: s.Log,
actorNames: s.actorNames,
workflowDefinitions: newWorkflowsAPI(s).workflowDefinitions,
exportRate: ratelimit.New(auditExportWindow, auditExportPerHour),
exporting: map[string]bool{},
}
}
func (a *auditAPI) logf(msg string, args ...any) { warnf(a.log, msg, args...) }
func (a *auditAPI) register(mux *http.ServeMux) {
mux.HandleFunc("GET /api/audit", a.handleAudit)
mux.HandleFunc("GET /api/audit/export", a.handleAuditExport)
}
// handleAudit is GET /api/audit: one page of the org-scoped feed. The org and
// the reader's authority come from the authenticated principal in the request
// context; the query string never names an org.
func (a *auditAPI) handleAudit(w http.ResponseWriter, r *http.Request) {
if a.audit == nil {
http.Error(w, "audit feed unavailable", http.StatusServiceUnavailable)
return
}
filter, cursor, limit, err := auditRequest(r)
if err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
if err := filter.Normalize(); err != nil {
http.Error(w, firstLine(err.Error()), http.StatusBadRequest)
return
}
page, err := a.audit.ListAudit(r.Context(), filter, cursor, limit)
if err != nil {
writeAuditError(w, err)
return
}
labels, settings := a.auditLabels(r.Context())
records := make([]auditRecordView, 0, len(page.Entries))
for _, entry := range page.Entries {
records = append(records, auditRecord(entry, labels))
}
response := auditResponse{Records: records, NextCursor: page.NextCursor, HasMore: page.HasMore}
if cursor.IsZero() {
response.Facets = &auditFacetsView{
Categories: audit.Categories(),
Severities: audit.Severities(),
Outcomes: audit.Outcomes(),
TargetKinds: audit.TargetKinds(),
SettingsKinds: settings,
RetentionKinds: audit.PrunableEventKinds(),
}
}
writeJSON(w, response)
}
// handleAuditExport is GET /api/audit/export?format=csv|json with the feed's
// filters. It requires an explicit range of at most a year and streams rows
// page by page.
func (a *auditAPI) handleAuditExport(w http.ResponseWriter, r *http.Request) {
if a.audit == nil {
http.Error(w, "audit feed unavailable", http.StatusServiceUnavailable)
return
}
format, ok := auditExportFormat(r)
if !ok {
http.Error(w, "format must be csv or json", http.StatusBadRequest)
return
}
filter, _, _, err := auditRequest(r)
if err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
if err := filter.Normalize(); err != nil {
http.Error(w, firstLine(err.Error()), http.StatusBadRequest)
return
}
if err := auditExportRange(filter); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
identity := auditExportIdentity(r.Context())
// Take the guard before charging the budget: a request rejected because
// the same identity is already exporting must cost no allowance.
if !a.beginAuditExport(identity) {
http.Error(w, "an audit export is already running for this identity", http.StatusTooManyRequests)
return
}
defer a.endAuditExport(identity)
if !a.exportRate.Allow("audit-export", identity) {
http.Error(w, "too many audit exports; try again later", http.StatusTooManyRequests)
return
}
ctx, cancel := context.WithTimeout(r.Context(), auditExportDeadline)
defer cancel()
// Count before any header is written: a match over the cap is the
// caller's problem to narrow, not a download that ends early.
if !a.auditExportWithinBudget(ctx, w, filter) {
return
}
// Fetch the first page before setting download headers: a failure here is
// still a normal error response, not a truncated file.
first, err := a.audit.ListAudit(ctx, filter, audit.Cursor{}, auditExportPageSize)
if err != nil {
writeAuditError(w, err)
return
}
writeAuditExportHeaders(w, format)
labels, _ := a.auditLabels(ctx)
flush := func() {}
if flusher, ok := w.(http.Flusher); ok {
flush = flusher.Flush
}
var rows int64
if format == "csv" {
rows, err = a.exportAuditCSV(ctx, filter, first, labels, w, flush)
} else {
rows, err = a.exportAuditJSON(ctx, filter, first, labels, w, flush)
}
if err != nil {
// Headers and status are already on the wire, so no error status is
// left to send. Abort the connection so the client sees a failed
// download rather than a silently short file.
a.logf("audit export failed", "format", format, "err", err)
panic(http.ErrAbortHandler)
}
// The file is complete; the trail row is bookkeeping, so a failed write
// is logged rather than turning a delivered export into a failed one.
if err := a.audit.RecordAuditExport(r.Context(), format, filter.Hash(), rows); err != nil {
a.logf("record audit export", "format", format, "err", err)
}
}
// auditExportWithinBudget refuses an export whose filter matches more than the
// cap, answering before any header is written so the client never receives a
// truncated file it cannot tell from a complete one. A feed error is written
// with the same status mapping as a page read.
func (a *auditAPI) auditExportWithinBudget(ctx context.Context, w http.ResponseWriter, filter audit.Filter) bool {
count, err := a.audit.CountAudit(ctx, filter)
if err != nil {
writeAuditError(w, err)
return false
}
if count > auditExportMaxRows {
http.Error(w, fmt.Sprintf(
"%d rows match; narrow the time range to at most %d",
count, auditExportMaxRows,
), http.StatusBadRequest)
return false
}
return true
}
// auditExportFormat resolves the download format. An absent format means JSON.
func auditExportFormat(r *http.Request) (string, bool) {
format := strings.ToLower(strings.TrimSpace(r.URL.Query().Get("format")))
switch format {
case "":
return "json", true
case "csv", "json":
return format, true
}
return "", false
}
// auditExportAllTime is the "any time" sentinel the dashboard sends for
// from. An export from the epoch is bounded by the page cap and deadline
// instead of the usual year.
var auditExportAllTime = time.Unix(0, 0).UTC()
// auditExportRange requires an explicit window of at most a year: an unbounded
// export would stream the instance's whole history.
func auditExportRange(filter audit.Filter) error {
if filter.From.IsZero() || filter.To.IsZero() {
return errors.New("choose an export time range of 366 days or less")
}
if filter.From.Equal(auditExportAllTime) {
return nil
}
if filter.To.Sub(filter.From) > auditExportMaxRange {
return errors.New("choose an export time range of 366 days or less")
}
return nil
}
func writeAuditExportHeaders(w http.ResponseWriter, format string) {
filename := "audit-" + time.Now().UTC().Format("20060102-150405") + "." + format
contentType := "application/json"
if format == "csv" {
contentType = "text/csv; charset=utf-8"
}
w.Header().Set("Content-Type", contentType)
w.Header().Set("Content-Disposition", mime.FormatMediaType("attachment", map[string]string{"filename": filename}))
w.Header().Set("Cache-Control", "no-store")
w.Header().Set("X-Content-Type-Options", "nosniff")
}
func (a *auditAPI) exportAuditCSV(ctx context.Context, filter audit.Filter, first audit.Page, labels *auditLabels, w io.Writer, flush func()) (int64, error) {
writer := csv.NewWriter(w)
if err := writer.Write(auditCSVHeader); err != nil {
return 0, err
}
rows, err := a.walkAudit(ctx, filter, first, func(entry audit.Entry) error {
return writer.Write(auditCSVRow(auditRecord(entry, labels)))
}, func() {
writer.Flush()
flush()
})
writer.Flush()
if flushErr := writer.Error(); err == nil {
err = flushErr
}
return rows, err
}
func (a *auditAPI) exportAuditJSON(ctx context.Context, filter audit.Filter, first audit.Page, labels *auditLabels, w io.Writer, flush func()) (int64, error) {
if _, err := io.WriteString(w, "["); err != nil {
return 0, err
}
encoder := json.NewEncoder(w)
firstRecord := true
rows, err := a.walkAudit(ctx, filter, first, func(entry audit.Entry) error {
if !firstRecord {
if _, err := io.WriteString(w, ","); err != nil {
return err
}
}
firstRecord = false
return encoder.Encode(auditRecord(entry, labels))
}, flush)
if err != nil {
// Leave the array open: the handler aborts the connection, and a
// closed array would masquerade as a complete download.
return rows, err
}
_, err = io.WriteString(w, "]\n")
return rows, err
}
// walkAudit streams every entry of the window in feed order and returns how
// many it emitted. It starts from the already-fetched first page so the caller
// could answer an error before any byte of the download was written.
func (a *auditAPI) walkAudit(ctx context.Context, filter audit.Filter, first audit.Page, emit func(audit.Entry) error, afterPage func()) (int64, error) {
page := first
pages := 1
var rows int64
for {
for _, entry := range page.Entries {
if err := emit(entry); err != nil {
return rows, err
}
rows++
}
if afterPage != nil {
afterPage()
}
if !page.HasMore || page.NextCursor == "" {
return rows, nil
}
if pages >= auditExportMaxPages {
return rows, errAuditExportTooLarge
}
pages++
cursor, ok := audit.ParseCursor(page.NextCursor)
if !ok {
return rows, errAuditExportCursor
}
next, err := a.audit.ListAudit(ctx, filter, cursor, auditExportPageSize)
if err != nil {
return rows, err
}
page = next
}
}
// auditRequest parses the shared filter query. Multi-valued parameters accept
// both repeated keys and comma-separated values, so the dashboard can send
// either encoding.
func auditRequest(r *http.Request) (audit.Filter, audit.Cursor, int, error) {
query := r.URL.Query()
filter := audit.Filter{
Categories: auditList(query, "categories"),
Actions: auditList(query, "actions"),
Kinds: auditList(query, "kind"),
Actor: query.Get("actor"),
TargetKinds: auditList(query, "target_kind"),
TargetIDs: auditList(query, "target_id"),
Severities: auditList(query, "severity"),
Outcomes: auditList(query, "outcome"),
Query: query.Get("q"),
}
from, err := auditTime(query.Get("from"))
if err != nil {
return audit.Filter{}, audit.Cursor{}, 0, fmt.Errorf("invalid from: %w", err)
}
to, err := auditTime(query.Get("to"))
if err != nil {
return audit.Filter{}, audit.Cursor{}, 0, fmt.Errorf("invalid to: %w", err)
}
filter.From, filter.To = from, to
cursor := audit.Cursor{}
if raw := strings.TrimSpace(query.Get("cursor")); raw != "" {
// A malformed cursor means newest, matching the feed's own rule.
if parsed, ok := audit.ParseCursor(raw); ok {
cursor = parsed
}
}
limit := 0
if raw := strings.TrimSpace(query.Get("limit")); raw != "" {
parsed, err := strconv.Atoi(raw)
if err != nil || parsed < 0 {
return audit.Filter{}, audit.Cursor{}, 0, fmt.Errorf("invalid limit")
}
limit = parsed
}
return filter, cursor, limit, nil
}
func auditList(query url.Values, key string) []string {
var out []string
for _, value := range query[key] {
for part := range strings.SplitSeq(value, ",") {
if part = strings.TrimSpace(part); part != "" {
out = append(out, part)
}
}
}
return out
}
// auditTime accepts the RFC3339 the dashboard sends and the local-style value
// a datetime control produces, treated as UTC rather than guessing a zone.
func auditTime(value string) (time.Time, error) {
value = strings.TrimSpace(value)
if value == "" {
return time.Time{}, nil
}
for _, layout := range []string{time.RFC3339Nano, "2006-01-02T15:04:05", "2006-01-02T15:04", "2006-01-02"} {
if parsed, err := time.Parse(layout, value); err == nil {
return parsed.UTC(), nil
}
}
return time.Time{}, fmt.Errorf("want an RFC3339 time")
}
// auditLabels resolves the display names one response needs. Actor names and
// catalog titles are fetched once; workflow names are loaded only when a row
// actually targets a workflow.
type auditLabels struct {
actorName func(string) string
titles map[string]string
workflowFn func() map[string]string
workflows map[string]string
}
func (l *auditLabels) workflow(id string) string {
if l.workflows == nil {
l.workflows = map[string]string{}
if l.workflowFn != nil {
maps.Copy(l.workflows, l.workflowFn())
}
}
return l.workflows[id]
}
// auditLabels builds the label resolver and the settings-kind facet in one
// catalog read. A failed catalog read degrades labels to their ids; it never
// fails the feed.
func (a *auditAPI) auditLabels(ctx context.Context) (*auditLabels, []auditSettingsKind) {
labels := &auditLabels{actorName: a.actorNames(ctx), titles: map[string]string{}}
settings := []auditSettingsKind{}
for _, resource := range a.auditCatalogResources(ctx) {
if resource.GetTitle() != "" {
labels.titles[resource.GetKind()] = resource.GetTitle()
}
// Domain-managed kinds are read through their own service, so they
// never appear as a stored settings document.
if resource.GetQueryService() == "" {
settings = append(settings, auditSettingsKind{Kind: resource.GetKind(), Title: resource.GetTitle()})
}
}
labels.workflowFn = func() map[string]string {
definitions, err := a.workflowDefinitions(ctx)
if err != nil {
return nil
}
names := make(map[string]string, len(definitions))
for _, definition := range definitions {
names[definition.ID] = definition.Name
}
return names
}
return labels, settings
}
// auditCatalogResources reads the control-plane catalogue once. A missing
// control plane or a failed read leaves labels at their ids rather than
// failing the feed.
func (a *auditAPI) auditCatalogResources(ctx context.Context) []*controlpb.ResourceDescriptor {
if a.controlPlane == nil {
return nil
}
catalog, err := a.controlPlane.Catalog(ctx, &controlpb.CatalogRequest{})
if err != nil {
return nil
}
return catalog.GetResources()
}
func auditRecord(entry audit.Entry, labels *auditLabels) auditRecordView {
fields := make([]auditFieldView, 0, len(entry.Fields))
for _, field := range entry.Fields {
fields = append(fields, auditFieldView{Field: field.Name, Old: jsonOrNull(field.Old), New: jsonOrNull(field.New)})
}
return auditRecordView{
ID: entry.ID(),
At: entry.At,
Category: string(entry.Category),
Action: entry.Action,
Kind: entry.Kind,
Severity: string(entry.Severity),
Outcome: string(entry.Outcome),
Actor: auditActorView{
ID: entry.Actor, Name: labels.actorName(entry.Actor),
Kind: entry.ActorKind, PrincipalID: entry.PrincipalID,
},
Target: auditTarget(entry, labels),
Summary: entry.Summary(),
Detail: auditDetailView{
Fields: fields, Data: jsonOrNull(entry.Data), Version: entry.RecordVersion,
RequestID: entry.RequestID, Source: entry.Source, Table: auditEntryTable(entry),
},
}
}
func auditTarget(entry audit.Entry, labels *auditLabels) auditTargetView {
view := auditTargetView{Kind: entry.TargetKind, ID: entry.TargetID}
switch entry.TargetKind {
case "resource":
// A settings row's id is the control-plane kind the catalog names.
view.Label = labels.titles[entry.TargetID]
case "task":
if entry.TargetID != "" {
view.Label = "#" + entry.TargetID
view.Href = "/tasks/" + url.PathEscape(entry.TargetID)
}
case "identity":
view.Label = labels.actorName(entry.TargetID)
view.Href = "/org/agents"
case "workflow":
view.Label = labels.workflow(entry.TargetID)
view.Href = "/workflows"
}
if view.Label == "" {
view.Label = auditTargetLabel(entry.TargetKind, entry.TargetID)
}
return view
}
// auditTargetLabel is the fallback for a row the dashboard has no route or
// title for: the kind and id it names.
func auditTargetLabel(kind, id string) string {
switch {
case kind == "" && id == "":
return ""
case kind == "":
return id
case id == "":
return kind
default:
return kind + "/" + id
}
}
// auditEntryTable is the audited table a row came from, for the detail view.
// The read model does not carry it, so it is derived from the branch that
// produced the row; coverage rows already carry their table name as the
// target kind.
func auditEntryTable(entry audit.Entry) string {
switch {
case entry.Category == audit.CategoryIdentity:
return "identity_events"
case entry.Category == audit.CategoryRuntime, entry.Category == audit.CategoryAutomation:
return "events"
case entry.Kind == "access_denial":
return "access_denials"
case entry.TargetKind == "policy":
return "access_policies"
case entry.TargetKind == "" || entry.TargetKind == "resource":
return "resources"
default:
return entry.TargetKind
}
}
// writeAuditError maps the feed's transport errors to the dashboard's status
// vocabulary. An unreadable feed is unavailable, never an empty page.
func writeAuditError(w http.ResponseWriter, err error) {
code := http.StatusInternalServerError
switch status.Code(err) {
case codes.InvalidArgument:
code = http.StatusBadRequest
case codes.PermissionDenied:
code = http.StatusForbidden
case codes.Unavailable, codes.DeadlineExceeded:
code = http.StatusServiceUnavailable
}
message := firstLine(status.Convert(err).Message())
if message == "" {
message = http.StatusText(code)
}
http.Error(w, message, code)
}
func firstLine(message string) string {
line, _, _ := strings.Cut(message, "\n")
return strings.TrimSpace(line)
}
// auditExportIdentity is the rate-limit key: the signed-in person. A service
// call acting for no person falls back to its org so it still has a budget.
func auditExportIdentity(ctx context.Context) string {
principal, ok := access.PrincipalFromContext(ctx)
if !ok {
return "unknown"
}
if principal.IdentityID != "" {
return string(principal.IdentityID)
}
if principal.Org != "" {
return "org:" + string(principal.Org)
}
return "unknown"
}
// beginAuditExport admits one export per identity. The guard is per identity,
// not process-wide: one person's long export must not stop another person in
// another org from taking their own.
func (a *auditAPI) beginAuditExport(identity string) bool {
a.exportMu.Lock()
defer a.exportMu.Unlock()
if a.exporting[identity] {
return false
}
a.exporting[identity] = true
return true
}
func (a *auditAPI) endAuditExport(identity string) {
a.exportMu.Lock()
delete(a.exporting, identity)
a.exportMu.Unlock()
}
var auditCSVHeader = []string{
"id", "at", "category", "action", "kind", "severity", "outcome",
"actor_id", "actor_name", "actor_kind", "principal_id",
"target_kind", "target_id", "target_label", "summary",
"fields", "data", "version", "request_id", "source", "table",
}
func auditCSVRow(view auditRecordView) []string {
fields, _ := json.Marshal(view.Detail.Fields)
return []string{
csvCell(view.ID), csvCell(view.At.UTC().Format(time.RFC3339Nano)),
csvCell(view.Category), csvCell(view.Action), csvCell(view.Kind),
csvCell(view.Severity), csvCell(view.Outcome),
csvCell(view.Actor.ID), csvCell(view.Actor.Name), csvCell(view.Actor.Kind), csvCell(view.Actor.PrincipalID),
csvCell(view.Target.Kind), csvCell(view.Target.ID), csvCell(view.Target.Label),
csvCell(view.Summary), csvCell(string(fields)), csvCell(string(view.Detail.Data)),
csvCell(strconv.FormatInt(view.Detail.Version, 10)),
csvCell(view.Detail.RequestID), csvCell(view.Detail.Source), csvCell(view.Detail.Table),
}
}
// csvCell neutralises a spreadsheet formula. A cell a spreadsheet would
// evaluate is prefixed with an apostrophe, which every common spreadsheet
// reads as text. Quoting and newlines are encoding/csv's job.
func csvCell(value string) string {
if value == "" {
return value
}
switch value[0] {
case '=', '+', '-', '@', '\t', '\r':
return "'" + value
}
return value
}
func jsonOrNull(value []byte) json.RawMessage {
if len(value) == 0 {
return json.RawMessage("null")
}
return value
}