Documentation
¶
Overview ¶
Package findings turns rule and query observations into finding episodes and records (PRD 7.7).
Index ¶
- Constants
- type Emit
- type Kind
- type Observation
- type Options
- type QueryProvenance
- type Tracker
- func (t *Tracker) AddQueryFinding(o Observation, emit Emit) (int, error)
- func (t *Tracker) Commit(seq uint64) error
- func (t *Tracker) DedupKey(o Observation) string
- func (t *Tracker) Flush(emit Emit) (int, error)
- func (t *Tracker) Observe(o Observation, emit Emit) (int, error)
- func (t *Tracker) OpenCount() int
- func (t *Tracker) Release()
- func (t *Tracker) Rollback() error
- func (t *Tracker) Stage()
- func (t *Tracker) Summary(fromSeq, watermark uint64) []protocol.SummaryEntry
Constants ¶
const ( StateFiring = "firing" StateStale = "stale" StateResolved = "resolved" )
Summary states.
const ( DefaultUpdateInterval = time.Minute DefaultLateThreshold = 15 * time.Minute DefaultMaxSamples = 10 DefaultMaxBytes = 16 << 10 DefaultMaxSampleBytes = 2 << 10 )
Defaults.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Observation ¶
type Observation struct {
Kind Kind
RuleID string
RuleVersion uint64
BundleVersion string
Query *QueryProvenance
// DedupKey overrides the derived key: rule id (or query hash) plus canonical sorted labels.
DedupKey string
// DedupLabels restricts the labels used for the derived key.
DedupLabels []string
Labels map[string]string
Category string
Severity protocol.Severity
EvalTime time.Time
// Count is the number of occurrences this observation represents (default 1).
Count uint64
Resources []string
Facts map[string]any
Evidence []protocol.Evidence
MaxSamples int
MaxBytes int
Flags uint64
Node string
Summary string
Coverage []string
Suggestions []protocol.Suggestion
}
Observation is one rule or query result; Stale and Fresh without key or labels apply rule-wide.
type Options ¶
type Options struct {
TargetID string
Store kv.Store
UpdateInterval time.Duration
LateThreshold time.Duration
MaxSamples int
MaxBytes int
MaxSampleBytes int
// VolatileLabels are excluded from derived dedup keys in addition to "value".
VolatileLabels []string
Redactor *redact.Redactor
Clock func() time.Time
}
Options configure a Tracker.
type QueryProvenance ¶
QueryProvenance identifies a query-generated finding (PRD I8).
type Tracker ¶
type Tracker struct {
// contains filtered or unexported fields
}
Tracker holds finding episodes; Emit runs under its lock, so take the spool lock first, never after.
func NewTracker ¶
NewTracker loads persisted episodes from o.Store.
func (*Tracker) AddQueryFinding ¶
func (t *Tracker) AddQueryFinding(o Observation, emit Emit) (int, error)
AddQueryFinding saves a query-generated observation as a finding with query provenance.
func (*Tracker) Commit ¶
Commit prunes resolved episodes and transition history at or below the committed seq.
func (*Tracker) DedupKey ¶
func (t *Tracker) DedupKey(o Observation) string
DedupKey returns o.DedupKey or the rule id (or query hash) plus canonical non-volatile labels.
func (*Tracker) Flush ¶
Flush emits pending updates for firing episodes whose update interval has elapsed.
func (*Tracker) Observe ¶
func (t *Tracker) Observe(o Observation, emit Emit) (int, error)
Observe applies an observation and emits the resulting transitions. It returns the number emitted.
func (*Tracker) Release ¶
func (t *Tracker) Release()
Release ends staging and keeps every change made since Stage.
func (*Tracker) Rollback ¶
Rollback restores every episode changed since Stage, in memory and in the store.
Source Files