224 lines
7.0 KiB
Go
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
|
|
}
|