audit

Documentation

Overview

Package audit appends governance events as JSONL.

Package audit provides audit event persistence and verification.

Index

• Constants
• func APIVersion() string
• func Append(path string, event Event) error
• func AppendRecord(path string, record any, opts Options) error
• func AppendWithOptions(path string, event Event, opts Options) error
• func Configure(next Config)
• func DefaultPath() (string, error)
• func ParseTime(value string, now time.Time) (time.Time, error)
• func RotatedFileTimestamp(activePath, candidate string) (time.Time, bool)
• func RotatedFiles(path string) ([]string, error)
• type AuditPruneDetail
• type BackupPruneDetail
• type Config
• type Event
• type EventContext
• type EventError
• type EventRoleChange
• type EventRoleFetchDetail
• type EventTarget
  • func (t EventTarget) MarshalJSON() ([]byte, error)
  • func (t *EventTarget) UnmarshalJSON(data []byte) error
• type EventType
• type Filter
• type Options
• type RawRecord
• type RawResult
  • func QueryRaw(path string, filter Filter) (RawResult, error)
• type Result
  • func Query(path string, filter Filter) (Result, error)
• type VerifyFileResult
• type VerifyLockStatus
• type VerifyOptions
• type VerifyResult
  • func Verify(path string, opts VerifyOptions) (VerifyResult, error)

Constants

const (
	StatusPending       = "pending"
	StatusDenied        = "denied"
	StatusSuccess       = "success"
	StatusFailed        = "failed"
	StatusPartialFailed = "partial-failed"
)

Event status values written to Event.Status.

const DefaultMaxSizeBytes int64 = 100 * 1024 * 1024

DefaultMaxSizeBytes is the default active audit log size before rotation.

Functions

func APIVersion

func APIVersion() string

APIVersion returns the apiVersion stamp emitted by audit query JSON output.

func Append

func Append(path string, event Event) error

Append appends one JSONL event. The file is owner-only.

func AppendRecord

func AppendRecord(path string, record any, opts Options) error

AppendRecord appends one JSONL record using the record's own JSON shape.

func AppendWithOptions

func AppendWithOptions(path string, event Event, opts Options) error

AppendWithOptions appends one JSONL event and rotates the active log when it exceeds the configured max size.

func Configure

func Configure(next Config)

Configure sets package-level audit defaults for a consumer CLI.

func DefaultPath

func DefaultPath() (string, error)

DefaultPath returns the default audit log path.

func ParseTime

func ParseTime(value string, now time.Time) (time.Time, error)

ParseTime parses a --since/--until value. Accepts either a relative offset (24h / 7d / 30m / 90s / 2w) interpreted as "now minus duration", or an absolute RFC3339 timestamp.

func RotatedFileTimestamp

func RotatedFileTimestamp(activePath, candidate string) (time.Time, bool)

RotatedFileTimestamp returns the timestamp encoded in a rotated audit file.

func RotatedFiles

func RotatedFiles(path string) ([]string, error)

RotatedFiles returns rotated audit log paths sorted by filename timestamp.

Types

type AuditPruneDetail

type AuditPruneDetail struct {
	DeletedFiles []string `json:"deletedFiles"`
	Count        int      `json:"count"`
}

AuditPruneDetail records audit rotated files pruned by audit prune.

type BackupPruneDetail

type BackupPruneDetail struct {
	DeletedDirs []string `json:"deletedDirs"`
	Count       int      `json:"count"`
}

BackupPruneDetail records backup snapshots pruned after new backups.

type Config

type Config struct {
	APIVersion         string
	ConfigDirName      string
	PrivateKeyEnvVar   string
	TargetTypeJSONName string
	TimestampJSONName  string
	EventTypeJSONName  string
	OperatorJSONName   string
}

Config controls package-level defaults for audit logs.

type Event

type Event struct {
	Timestamp   time.Time             `json:"timestamp"`
	EventType   EventType             `json:"eventType"`
	Operator    string                `json:"operator,omitempty"`
	Context     EventContext          `json:"context"`
	Ticket      string                `json:"ticket,omitempty"`
	Reason      string                `json:"reason,omitempty"`
	Target      EventTarget           `json:"target"`
	Status      string                `json:"status"`
	Diff        string                `json:"diff,omitempty"`
	Error       *EventError           `json:"error,omitempty"`
	RoleChange  *EventRoleChange      `json:"roleChange,omitempty"`
	AuditPrune  *AuditPruneDetail     `json:"auditPrune,omitempty"`
	BackupPrune *BackupPruneDetail    `json:"backupPrune,omitempty"`
	RoleFetch   *EventRoleFetchDetail `json:"roleFetch,omitempty"`
}

Event is one JSONL audit record.

type EventContext

type EventContext struct {
	Name      string `json:"name,omitempty"`
	Env       string `json:"env,omitempty"`
	Protected bool   `json:"protected,omitempty"`
}

EventContext identifies the active context.

type EventError

type EventError struct {
	Code    string `json:"code,omitempty"`
	Message string `json:"message"`
}

EventError records a failed result.

type EventRoleChange

type EventRoleChange struct {
	ChangedOperator string `json:"changedOperator"`
	Role            string `json:"role,omitempty"`
}

EventRoleChange records RBAC role assignments and revocations.

type EventRoleFetchDetail

type EventRoleFetchDetail struct {
	URL        string `json:"url,omitempty"`
	CacheState string `json:"cacheState"`
}

EventRoleFetchDetail records remote RBAC role fetches.

type EventTarget

type EventTarget struct {
	App          string `json:"app,omitempty"`
	ResourceType string `json:"-"`
	Resource     string `json:"resource,omitempty"`
}

EventTarget identifies the changed resource set.

func (EventTarget) MarshalJSON

func (t EventTarget) MarshalJSON() ([]byte, error)

func (*EventTarget) UnmarshalJSON

func (t *EventTarget) UnmarshalJSON(data []byte) error

type EventType

type EventType string

EventType is an audit event category.

const (
	EventContextExport       EventType = "ctx.export"
	EventContextImport       EventType = "ctx.import"
	EventContextTest         EventType = "ctx.test"
	EventBackupPrune         EventType = "backup.prune"
	EventRoleAssign          EventType = "role.assign"
	EventRoleRevoke          EventType = "role.revoke"
	EventRoleFetch           EventType = "role.fetch"
	EventAuditPrune          EventType = "audit.prune"
	EventAuthorizationDenied EventType = "authorization.denied"
)

type Filter

type Filter struct {
	Since        *time.Time
	Until        *time.Time
	EventType    string
	Operator     string
	ContextName  string
	Env          string
	Protected    *bool
	Ticket       string
	App          string
	ResourceType string
	Resource     string
	Status       string
	Limit        int
	Reverse      bool
	PrivateKey   string
}

Filter is the set of optional predicates applied to audit log entries. All fields are AND-combined. Empty string fields mean "no filter".

type Options

type Options struct {
	MaxSizeBytes         int64
	EncryptPublicKeyPath string
}

Options controls audit append behavior.

type RawRecord

type RawRecord struct {
	Line      string
	Timestamp time.Time
	EventType string
	Operator  string
}

RawRecord is one matched audit row plus the fields parsed for filtering.

type RawResult

type RawResult struct {
	Records          []RawRecord
	MalformedEntries int
}

RawResult aggregates matched raw rows and a count of unparseable lines skipped.

func QueryRaw

func QueryRaw(path string, filter Filter) (RawResult, error)

QueryRaw streams audit logs and returns matching raw JSONL rows.

type Result

type Result struct {
	Events           []Event
	MalformedEntries int
}

Result aggregates matched events and a count of unparseable lines skipped.

func Query

func Query(path string, filter Filter) (Result, error)

Query streams an audit log file, returning entries that satisfy the filter. File-not-exist is not an error: callers get an empty Result. Lines that fail JSON decode are skipped and counted in Result.MalformedEntries.

type VerifyFileResult

type VerifyFileResult struct {
	Path        string `json:"path"`
	Total       int    `json:"total"`
	Valid       int    `json:"valid"`
	Malformed   int    `json:"malformed"`
	Quarantine  string `json:"quarantine,omitempty"`
	Repaired    bool   `json:"repaired,omitempty"`
	SchemaError int    `json:"schemaErrors,omitempty"`
}

VerifyFileResult summarizes one active or rotated audit file.

type VerifyLockStatus

type VerifyLockStatus struct {
	Path    string `json:"path,omitempty"`
	Present bool   `json:"present"`
	Content string `json:"content,omitempty"`
}

VerifyLockStatus reports the active audit lock file if present.

type VerifyOptions

type VerifyOptions struct {
	Decrypt    bool
	PrivateKey string
	Repair     bool
	Confirm    bool
}

VerifyOptions controls audit log verification.

type VerifyResult

type VerifyResult struct {
	Files                    []VerifyFileResult `json:"files"`
	Total                    int                `json:"total"`
	Valid                    int                `json:"valid"`
	Malformed                int                `json:"malformed"`
	SchemaErrors             int                `json:"schemaErrors"`
	TimestampOrderViolations int                `json:"timestampOrderViolations"`
	Lock                     VerifyLockStatus   `json:"lock"`
}

VerifyResult summarizes audit log verification.

func Verify

func Verify(path string, opts VerifyOptions) (VerifyResult, error)

Verify scans active and rotated audit files for malformed entries and basic schema/timestamp invariants.