audit

package
v0.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package audit writes Snellius audit records as JSON lines and tags each request with an ID.

Index

Constants

View Source
const (
	LevelSecurity   = "security"
	LevelAgent      = "agent"
	LevelReads      = "reads"
	LevelSummaries  = "summaries"
	LevelDisclosure = "disclosure"
	LevelRequests   = "requests"
)

Audit levels.

View Source
const (
	// SummaryWindow is how often summary records are flushed.
	SummaryWindow = 5 * time.Minute
	// DenialWindow is how long repeated denials of one request collapse into one record.
	DenialWindow = time.Minute
	// MaxOpenKeys is the most open keys a window holds; past it the oldest is flushed early.
	MaxOpenKeys = 10000
)

Collapse windows and the open-key cap (design §9.2, §9.4).

View Source
const DefaultLevels = "security,agent,reads,summaries"

DefaultLevels is the level list used when none is configured.

View Source
const Schema = "1"

Schema is the record schema version.

Variables

This section is empty.

Functions

func ParseCIDRs

func ParseCIDRs(s string) ([]netip.Prefix, error)

ParseCIDRs parses a comma list of CIDRs; empty means none.

func RequestID

func RequestID(next http.Handler) http.Handler

RequestID gives every request a fresh ID, sets it as the X-Request-Id response header and stores it in the request context.

func RequestIDFrom

func RequestIDFrom(ctx context.Context) string

RequestIDFrom returns the request ID in ctx, or empty.

func RequestIDTrusting

func RequestIDTrusting(cidrs []netip.Prefix, next http.Handler) http.Handler

RequestIDTrusting is RequestID, except that a request from a peer in cidrs keeps a valid incoming X-Request-Id, and its X-Forwarded-For gives the audit source: the right-most address that is not itself in cidrs.

Types

type Identity

type Identity struct{ Issuer, Subject string }

Identity names a person by issuer and subject.

type Kube

type Kube struct {
	Username string
	Groups   []string
}

Kube is the identity Kubernetes sees.

type Levels

type Levels map[string]bool

Levels is the set of enabled audit levels.

func ParseLevels

func ParseLevels(s string) (Levels, error)

ParseLevels parses a comma list of level names; empty means DefaultLevels. An unknown name is an error.

type Logger

type Logger struct {
	// contains filtered or unexported fields
}

Logger writes enabled records as JSON lines. Emit never blocks: a full queue, or a writer that has stopped, drops the record and counts it. Summarize and Collapse hold records in windows that Run flushes.

func New

func New(w io.Writer, levels Levels, reg *obs.Registry, opts ...Option) *Logger

New returns a Logger that writes to w. Start it with Run. reg may be nil.

func (*Logger) Collapse

func (l *Logger) Collapse(ctx context.Context, key string, rec Record)

Collapse counts rec under key in the denial window, flushed every DenialWindow and when Run stops: repeats of one denial become one record with a count. Its time and request ID are the first denial's.

func (*Logger) Emit

func (l *Logger) Emit(ctx context.Context, rec Record)

Emit queues rec if its level is enabled, filling the time, ID and request ID.

func (*Logger) Enabled

func (l *Logger) Enabled(level string) bool

Enabled reports whether level is on.

func (*Logger) Run

func (l *Logger) Run(ctx context.Context)

Run writes queued records and closed windows until ctx is done, then writes what is left, the open windows included. Records emitted after that are dropped. Windows close on their ticks in a goroutine of their own, so a slow write never stretches a window.

func (*Logger) Summarize

func (l *Logger) Summarize(key string, rec Record)

Summarize counts rec under key in the summary window, flushed every SummaryWindow and when Run stops. A summary stands for many requests, so it carries no request ID; its time is the first request's.

type Option

type Option func(*Logger)

Option configures a Logger.

func WithBuffer

func WithBuffer(n int) Option

WithBuffer sets the queue size.

func WithClock

func WithClock(c clock.WithTicker) Option

WithClock sets the clock that times records and flushes; without it, the real clock.

func WithMaxOpenKeys

func WithMaxOpenKeys(n int) Option

WithMaxOpenKeys sets the open-key cap of each window; without it, MaxOpenKeys.

func WithServer

func WithServer(name string) Option

WithServer sets the server instance name written in every record.

type Record

type Record struct {
	Time       time.Time
	ID         string
	Level      string
	Action     string
	Outcome    string
	Reason     string
	User       Identity
	Kube       Kube
	Session    string
	Agent      string
	OnBehalfOf string
	Request    Request
	Install    string
	Server     string
	Refs       []string
	AuthzRev   string
	Source     string
	UserAgent  string
	// Count is the number of events a collapsed record stands for.
	Count int
	// Mode and Listen describe the process; the startup record uses them.
	Mode   string
	Listen string
	// contains filtered or unexported fields
}

Record is one audit record (schema 1). Empty fields are left out of the output.

func FromRequest

func FromRequest(r *http.Request) Record

FromRequest fills the request ID, method, route template, source IP and user agent, truncated and without control characters, from r. The source is the peer, or the forwarded client that RequestIDTrusting accepted. It copies no header, cookie, query or body.

type Request

type Request struct {
	ID      string
	Method  string
	Route   string
	Filters map[string]string
}

Request describes the HTTP request behind a record. Filters hold only allow-listed names and values, never a raw query string.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL