Documentation
¶
Overview ¶
Package detect is the agent-side detection engine (issue #422, phase 3). It runs ON THE AGENT: it consumes the per-class event stream from a DetectionSensor, evaluates the clean-room rule catalogue against each event, and emits a detection — with a bounded context window — for every match.
It is deterministic-first and observe-only: the engine matches typed rules and emits detections; it never executes anything (golden rule 1). It enforces a CPU ceiling by SHEDDING whole event classes in a defined order and reporting that it did, and it reports per-class coverage that folds in the sensor's gaps, its own shedding, and back-pressure drops — so a class the agent is not fully observing is never presented as clean.
Index ¶
Constants ¶
const DefaultContextWindow = 16
DefaultContextWindow is how many recent same-class events accompany a detection as bounded context.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Engine ¶
type Engine struct {
// contains filtered or unexported fields
}
Engine ties a sensor to the rule catalogue.
func NewEngine ¶
func NewEngine(sensor ports.DetectionSensor, sink ports.DetectionSink, host, agentID shared.ID, opts Options) (*Engine, error)
NewEngine validates dependencies and loads the rule catalogue for the enabled classes.
func (*Engine) Coverage ¶
func (e *Engine) Coverage() []detection.ClassCoverage
Coverage returns the honest per-class observation status: the sensor's coverage, with a class the engine has shed downgraded to a degraded gap, and a class the sensor is dropping under back-pressure likewise downgraded. A class the engine does not evaluate is never reported as cleanly observed.
type LoadSampler ¶
type LoadSampler interface {
CPUPercent() float64
}
LoadSampler reports the CPU cost currently attributable to detection, as a percentage of one core. The engine samples it to decide whether to shed load. A real implementation reads getrusage; tests inject a deterministic one.
type Options ¶
type Options struct {
Classes []detection.Class // classes to evaluate; defaults to all
CPUCeilingPct float64 // shed when the sampler exceeds this; 0 disables shedding
Sampler LoadSampler // load source; nil → never sheds
SampleInterval time.Duration // minimum spacing between load samples; 0 → sample every event
ContextWindow int // events of context kept per class; defaults to DefaultContextWindow
Clock ports.Clock
}
Options configures an engine.
Source Files