Files
archie/internal/domain/audit/audit.go
T

224 lines
7.0 KiB
Go

// Package audit owns the instance audit feed: the closed vocabularies its
// filters and rows use, the keyset cursor, and the read-only store contract.
// Every durable trail the State Store owns is projected into one timeline by
// the SQL read model; this package never imports infrastructure or app code.
package audit
import (
"context"
"encoding/json"
"strconv"
"time"
)
// Category is a feed row's origin, as the filter and the dashboard group them.
type Category string
const (
CategorySettings Category = "settings"
CategoryAccess Category = "access"
CategoryIdentity Category = "identity"
CategoryRuntime Category = "runtime"
CategoryAutomation Category = "automation"
)
// Severity is how loudly a row asks for attention. It is a closed set: the
// feed's filters validate against it, so a new value is a wire change.
type Severity string
const (
SeverityInfo Severity = "info"
SeverityWarning Severity = "warning"
SeverityError Severity = "error"
)
// Outcome is whether the action the row records succeeded. A denied action is
// its own outcome: it is not a failure of the system.
type Outcome string
const (
OutcomeSuccess Outcome = "success"
OutcomeFailure Outcome = "failure"
OutcomeDenied Outcome = "denied"
)
// Actions recorded by the sys_audit branches. Other sources use their own
// action vocabulary (identity lifecycle events and runtime event kinds), so
// the filter does not close over actions globally.
const (
ActionCreate = "create"
ActionUpdate = "update"
ActionDelete = "delete"
ActionReset = "reset"
ActionDeny = "deny"
)
// Valid reports whether c is one of the feed's categories.
func (c Category) Valid() bool {
switch c {
case CategorySettings, CategoryAccess, CategoryIdentity, CategoryRuntime, CategoryAutomation:
return true
}
return false
}
// Valid reports whether s is one of the feed's severities.
func (s Severity) Valid() bool {
switch s {
case SeverityInfo, SeverityWarning, SeverityError:
return true
}
return false
}
// Valid reports whether o is one of the feed's outcomes.
func (o Outcome) Valid() bool {
switch o {
case OutcomeSuccess, OutcomeFailure, OutcomeDenied:
return true
}
return false
}
// Categories is the feed's category vocabulary. The dashboard renders one
// filter value per entry rather than inventing its own list.
func Categories() []string {
return []string{
string(CategorySettings), string(CategoryAccess), string(CategoryIdentity),
string(CategoryRuntime), string(CategoryAutomation),
}
}
// Severities is the feed's severity vocabulary.
func Severities() []string {
return []string{string(SeverityInfo), string(SeverityWarning), string(SeverityError)}
}
// Outcomes is the feed's outcome vocabulary.
func Outcomes() []string {
return []string{string(OutcomeSuccess), string(OutcomeFailure), string(OutcomeDenied)}
}
// TargetKinds is the target-kind vocabulary the dashboard offers as a filter.
// The read model derives target_kind from each source, so the values are the
// access resource kinds and audited table names it emits.
func TargetKinds() []string {
return []string{
"resource", "policy", "identity", "task", "workflow",
"org", "workspace", "source", "event_type", "mapping", "binding",
"capture", "secret", "member", "dashboard", "event",
"orgs", "workspaces", "memberships", "org_agents",
"mappings", "bindings", "event_types", "sources",
"installed_packages", "harness_secrets",
// audit_retention is the retention sweep's coverage table, audit is
// the resource kind a denied feed read names, and audit_export is the
// row a completed export writes; all reach the feed as target kinds.
"audit_retention", "audit", "audit_export",
}
}
// Field is one changed field of a change set. Old and New are JSON values;
// an absent side of the change is JSON null.
type Field struct {
Name string
Old json.RawMessage
New json.RawMessage
}
// Entry is one row of the audit feed: a grouped change set, a lifecycle
// event, an aggregated denial, or a runtime event.
type Entry struct {
// Rank and SourceID place the entry in the feed order. Together with At
// they form the resume cursor and, through ID, the stable record id.
Rank int
SourceID int64
Category Category
At time.Time
Actor string
ActorKind string
PrincipalID string
TargetKind string
TargetID string
Kind string
RecordVersion int64
RequestID string
Source string
Fields []Field
Action string
// Severity and Outcome are derived by the read model, where the filters
// must see them before pagination.
Severity Severity
Outcome Outcome
Detail string
WorkspaceID string
TaskID int64
// Data is the redacted event data, absent for rows with none.
Data json.RawMessage
}
// ID is the entry's stable identity across pages and live refreshes.
func (e Entry) ID() string {
return strconv.Itoa(e.Rank) + ":" + strconv.FormatInt(e.SourceID, 10)
}
// Summary is the entry's one-line description. It is built from metadata
// only and must be called on a redacted entry: Detail can carry recorded
// prose, which the adapter redacts before the entry leaves the State Store.
func (e Entry) Summary() string {
if e.Detail != "" {
return e.Detail
}
if e.Action != "" {
return e.Action + " " + e.Kind
}
return e.Kind
}
// Page is one keyset page of the feed. HasMore means at least one row older
// than the last entry exists; NextCursor resumes from it.
type Page struct {
Entries []Entry
NextCursor string
HasMore bool
}
// Store is the audit feed's surface. The org is derived from the request
// context, never from the call: a caller cannot name another org's trail.
type Store interface {
// ListAudit returns one page of the org's feed, newest first.
ListAudit(ctx context.Context, filter Filter, cursor Cursor, limit int) (Page, error)
// CountAudit returns how many entries the filter matches, without a
// cursor or a page bound.
CountAudit(ctx context.Context, filter Filter) (int64, error)
// AuditHead returns a cheap token that changes when any trail the caller
// can read grows. It carries no rows and no org data.
AuditHead(ctx context.Context) (string, error)
// RecordAuditExport appends one audit row recording a completed export,
// attributed to the caller.
RecordAuditExport(ctx context.Context, format, filterHash string, rows int64) error
}
// instanceAdminKey carries the authenticated principal's instance-wide
// authority. It is a server-side fact derived from the principal, never from
// the requested org: being confined to the system org does not by itself make
// a viewer an instance administrator.
type instanceAdminKey struct{}
// WithInstanceAdmin marks whether the request's principal administers the
// whole instance.
func WithInstanceAdmin(ctx context.Context, admin bool) context.Context {
return context.WithValue(ctx, instanceAdminKey{}, admin)
}
// InstanceAdmin reports whether the request's principal administers the
// instance. It is false for a service call acting for no principal.
func InstanceAdmin(ctx context.Context) bool {
admin, _ := ctx.Value(instanceAdminKey{}).(bool)
return admin
}