Documentation
¶
Overview ¶
Package audit writes Snellius audit records as JSON lines and tags each request with an ID.
Index ¶
- Constants
- func ParseCIDRs(s string) ([]netip.Prefix, error)
- func RequestID(next http.Handler) http.Handler
- func RequestIDFrom(ctx context.Context) string
- func RequestIDTrusting(cidrs []netip.Prefix, next http.Handler) http.Handler
- type Identity
- type Kube
- type Levels
- type Logger
- type Option
- type Record
- type Request
Constants ¶
const ( LevelSecurity = "security" LevelAgent = "agent" LevelReads = "reads" LevelSummaries = "summaries" LevelDisclosure = "disclosure" LevelRequests = "requests" )
Audit levels.
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).
const DefaultLevels = "security,agent,reads,summaries"
DefaultLevels is the level list used when none is configured.
const Schema = "1"
Schema is the record schema version.
Variables ¶
This section is empty.
Functions ¶
func ParseCIDRs ¶
ParseCIDRs parses a comma list of CIDRs; empty means none.
func RequestID ¶
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 ¶
RequestIDFrom returns the request ID in ctx, or empty.
func RequestIDTrusting ¶
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 Levels ¶
Levels is the set of enabled audit levels.
func ParseLevels ¶
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 (*Logger) Collapse ¶
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.
type Option ¶
type Option func(*Logger)
Option configures a Logger.
func WithClock ¶
func WithClock(c clock.WithTicker) Option
WithClock sets the clock that times records and flushes; without it, the real clock.
func WithMaxOpenKeys ¶
WithMaxOpenKeys sets the open-key cap of each window; without it, MaxOpenKeys.
func WithServer ¶
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 ¶
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.