detection

type Class ¶

type Class string

Class is a category of host activity the engine observes. Each class is backed by its own eBPF program with its own bounded map and can be loaded, disabled and fail INDEPENDENTLY — a missing kernel feature takes out one class with a coverage report, never the whole engine (#422 requirement 6).

The set mirrors the telemetry classes the emulation catalogue (#421) expects a detection for, so the purple ledger (#426) can reconcile "what we executed" against "what we detected" by detection id.

const (
	ClassProcess   Class = "process"   // process execution (exec/fork)
	ClassNetwork   Class = "network"   // outbound/inbound connect
	ClassFile      Class = "file"      // file access to sensitive paths
	ClassPrivilege Class = "privilege" // privilege / capability change
)

func Classes() []Class

func (c Class) Valid() bool

type ClassCoverage ¶

type ClassCoverage struct {
	Class   Class
	HostID  shared.ID
	AgentID shared.ID
	State   ClassState
	Reason  string // required when the state is not active/disabled: WHY the class is not observing
	Since   time.Time
}

ClassCoverage is the observation status of one event class on one host, over a window. It is the input to the coverage report the purple ledger (#426) and the detections-as-evidence issue (#423) consume.

func (c ClassCoverage) IsObservationGap() bool

func (c ClassCoverage) Observing() bool

func (c ClassCoverage) Validate() error

type ClassState ¶

type ClassState string

ClassState is whether a host is actually observing a given event class right now.

The whole point of this type is honesty about the negative case. A host that reports NO detections for a class is ambiguous: either nothing happened, or the sensor was not watching. StateActive is the only state under which "no detections" means "nothing detected". Every other state is an OBSERVATION GAP — the host is not clean for that class, it is unobserved, and a coverage number must say so (#422 requirements 4, 5 and 6).

const (
	StateActive   ClassState = "active"   // program loaded, map bound, events flowing
	StateDegraded ClassState = "degraded" // a required kernel feature is missing; this class is disabled
	StateFailed   ClassState = "failed"   // the program failed to load or attach on a supported kernel
	StateDisabled ClassState = "disabled" // switched off by configuration (SYNAPSE_DETECT_CLASSES)
)

type Detection ¶

type Detection struct {
	RuleID      string
	RuleVersion int
	Class       Class
	Severity    shared.Severity
	HostID      shared.ID
	AgentID     shared.ID
	Evidence    []Event // bounded (MaxEvidence); the triggering event plus surrounding context
	// Truncated records that the evidence window was capped: the shipped Evidence is not the complete
	// sequence. It is a field, not just a constructor return, so the incompleteness travels with the
	// stored/hash-chained record (#423) and a reconstructed detection cannot present a bounded window as
	// the whole story. Observed count is the number of events seen before truncation (>= len(Evidence)).
	Truncated     bool
	ObservedCount int
	Observed      time.Time
}

Detection is what a matched rule emits. It carries full attribution — the host, the agent identity, the rule id and version, the matched evidence and the time — because the next issue (#423) turns these into hash-chained, attributable evidence, and evidence with a hole in its provenance is not evidence.

func NewBurstDetection(r Rule, host, agent shared.ID, evidence []Event, observed int, at time.Time) (Detection, error)

func NewDetection(r Rule, host, agent shared.ID, evidence []Event, at time.Time) (Detection, error)

func (d Detection) Validate() error

type Evaluator ¶ added in v0.2.0

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

Evaluator applies a rule set to a stream of events, keeping the per-group state windowed rules need. Plain rules pass straight through Rule.Match. It is not safe for concurrent use; the caller serialises events, which a sensor stream already does.

func NewEvaluator(rules []Rule) (*Evaluator, error)

func (ev *Evaluator) Evaluate(e Event) []Fired

type Event ¶

type Event struct {
	Class Class
	At    time.Time
	Host  shared.ID

	Process   *ProcessEvent
	Network   *NetworkEvent
	File      *FileEvent
	Privilege *PrivilegeEvent
}

Event is one observed host activity, typed by Class. Exactly one of the per-class payloads is set — the one matching Class. The payloads are deliberately small and bounded: milestone one ships a detection plus a bounded window of these, never the raw stream.

Fields are TYPED, not a free-form map, so a rule matches over a closed, known set (see Field). That is what keeps a rule from being an arbitrary expression over untrusted keys.

func (e Event) Validate() error

type Field ¶

type Field string

Field is a closed enumeration of the event fields a rule may match over. It is deliberately NOT a free-form string key: a rule matches over this known set only, which is what stops a rule from being an arbitrary expression over untrusted input. Each field belongs to exactly one Class.

const (
	// process
	FieldProcComm Field = "proc.comm"
	FieldProcPath Field = "proc.path"
	FieldProcArg  Field = "proc.arg" // repeated: matches if ANY argv element satisfies the predicate
	FieldProcUID  Field = "proc.uid" // numeric

	// network
	FieldNetProto      Field = "net.proto"
	FieldNetRemoteAddr Field = "net.remote_addr"
	FieldNetRemotePort Field = "net.remote_port" // numeric
	FieldNetDirection  Field = "net.direction"

	// file
	FieldFilePath Field = "file.path"
	FieldFileOp   Field = "file.op"
	FieldFileComm Field = "file.comm"

	// privilege
	FieldPrivComm  Field = "priv.comm"
	FieldPrivCap   Field = "priv.cap"
	FieldPrivKind  Field = "priv.kind"
	FieldPrivToUID Field = "priv.to_uid" // numeric
)

func (f Field) Numeric() bool

func (f Field) Valid() bool

type FileEvent ¶

type FileEvent struct {
	Path string
	Op   string // read | write | open | unlink
	PID  int
	Comm string
}

FileEvent is a sensitive-path access observation.

type Fired ¶ added in v0.2.0

type Fired struct {
	Rule     Rule
	Evidence []Event
	// Observed is the number of matching events in the burst that fired (>= len(Evidence)); zero for a
	// plain rule. Pass it to NewBurstDetection so a burst longer than the kept evidence is marked truncated.
	Observed int
}

Fired is one rule that produced a detection for the evaluated event. For a windowed rule Evidence is the burst that crossed the threshold, oldest first; for a plain rule it is nil and the caller supplies whatever context it keeps.

type HostCoverage ¶

type HostCoverage struct {
	HostID  shared.ID
	Classes []ClassCoverage // exactly one per Class(), in Classes() order
}

HostCoverage is the per-host roll-up across every event class. Building it from ClassCoverage records makes the honest default structural: a class with no record at all is reported as an unknown gap, not silently omitted — you cannot accidentally drop a class and make a host look more covered than it is.

func NewHostCoverage(host shared.ID, reported []ClassCoverage) (HostCoverage, error)

func (h HostCoverage) FullyObserved() bool

func (h HostCoverage) Gaps() []ClassCoverage

type Incident ¶

type Incident struct {
	Key          string // stable dedup key: rule + asset
	RuleID       string
	AssetID      shared.ID
	Severity     shared.Severity // the most severe among the folded detections
	Count        int
	First        time.Time
	Last         time.Time
	DetectionIDs []shared.ID // the underlying records, preserved
}

Incident is an incident-level rollup of repeated detections of the same rule on the same asset. It is a VIEW: it never replaces the underlying records, which remain the ledger. DetectionIDs lists every record folded in, so an auditor can always descend from the incident to the individual, attributable, hash-chained detections beneath it.

func Rollup(records []Record) []Incident

type Matcher ¶

type Matcher struct {
	Class Class
	All   []Predicate
}

Matcher is the AND of its predicates over one event class. A rule needing OR is expressed as two rules — milestone one keeps the matcher language small and total on purpose. An empty predicate list is refused: a matcher that matches every event of a class is not a detection rule, it is a firehose.

func (m Matcher) Match(e Event) bool

type NetworkEvent ¶

type NetworkEvent struct {
	Proto      string // tcp | udp
	RemoteAddr string
	RemotePort int
	Direction  string // egress | ingress
	PID        int
	Comm       string
}

NetworkEvent is a connect observation.

type Op ¶

type Op string

Op is a comparison operator. The set is small and total: every op has a defined meaning for the field type it is used with, checked by Matcher.validate.

const (
	OpEquals   Op = "eq"       // string or numeric equality
	OpPrefix   Op = "prefix"   // string has prefix
	OpContains Op = "contains" // string contains
	OpIn       Op = "in"       // string is one of Values
	OpGTE      Op = "gte"      // numeric >=
)

type Predicate ¶

type Predicate struct {
	Field  Field
	Op     Op
	Value  string
	Values []string
}

Predicate is one field comparison. Value is used by every op except OpIn, which uses Values.

type PrivilegeEvent ¶

type PrivilegeEvent struct {
	PID     int
	Comm    string
	FromUID int
	ToUID   int
	Cap     string // capability gained, if any
	Kind    string // setuid | setgid | capset
}

PrivilegeEvent is a privilege/capability change observation.

type ProcessEvent ¶

type ProcessEvent struct {
	Kind                 string // exec | fork | exit; empty means legacy exec
	PID                  int
	PPID                 int
	StartTimeNanos       uint64
	ParentStartTimeNanos uint64
	Comm                 string   // short command name (kernel comm)
	Path                 string   // resolved executable path
	Args                 []string // bounded argv
	UID                  int
}

ProcessEvent is an exec/fork observation.

type Record ¶

type Record struct {
	ID           shared.ID
	TenantID     shared.ID
	EngagementID shared.ID
	AssetID      shared.ID // the asset the detection was observed on, so it joins the asset risk story
	AgentID      shared.ID
	Detection    Detection
	EvidenceID   shared.ID // the evidence-chain link that sealed this detection
	BatchSeq     uint64    // the agent batch sequence it arrived in
	RecordedAt   time.Time
	ExpiresAt    time.Time // zero = never expires; a set value is enforced by audited retention
}

Record is a detection as it lives in the control-plane ledger (#423): the detection itself, bound to the evidence-chain link that sealed it, the asset it was observed on, the agent that produced it, and the agent batch sequence it arrived in. The evidence-chain link is the tamper-evident ledger; this Record is the queryable projection over it (and the one subject to retention — the chain link is permanent, this row is not).

func (r Record) Expired(now time.Time) bool

func (r Record) Validate() error

type Rule ¶

type Rule struct {
	ID       string // stable, catalogued; matches an emulation ExpectedObservable.DetectionID
	Version  int
	Class    Class
	Title    string
	Severity shared.Severity
	Matcher  Matcher
	// Window, when set, makes the rule fire on a rate of matching events rather than on each one. Nil is
	// the plain per-event rule.
	Window *Window
	// Sequence, when set, makes the rule fire on an ordered series of matching events rather than on one.
	// It is mutually exclusive with Window, and it replaces the top-level Matcher (each step carries its
	// own), so a sequence rule leaves Matcher empty.
	Sequence *Sequence
}

Rule is a typed, versioned, clean-room detection definition. It matches over one event class and, on a match, the engine emits a Detection carrying the matched evidence. Rules are catalogued exactly like the SAST catalogue, with a drift test that fails the build if the shipped catalogue does not validate.

ID is stable and public-facing: it is the detection id the emulation catalogue (#421) names as the expected observable, so the purple ledger (#426) can reconcile executed techniques against detections by this id. Changing an ID breaks that linkage, so IDs are append-only in practice.

func Catalogue() ([]Rule, error)

func CatalogueByClass(c Class) ([]Rule, error)

func Lookup(id string) (Rule, bool)

func (r Rule) Match(e Event) bool

func (r Rule) Sequenced() bool

func (r Rule) Validate() error

func (r Rule) Windowed() bool

type Sequence ¶ added in v0.2.0

type Sequence struct {
	// Steps are the ordered matchers. An event advances the sequence only when it matches the next
	// unsatisfied step. At least two steps: a one-step sequence is a plain rule.
	Steps []Matcher
	// Within is the span from the FIRST matched step's event to the last, exclusive. A partial match that
	// lapses is reset, so a slow, unrelated recurrence is never stitched into a sequence.
	Within time.Duration
	// GroupBy partitions progress by these fields so two hosts' (or two entities') unrelated events do
	// not interleave into one sequence. Empty groups by host only. Fields must belong to the rule's class.
	GroupBy []Field
}

Sequence turns a rule from "one matching event is a detection" into "these matchers, satisfied by events of the rule's class IN THIS ORDER, for the same group, all within this span, is a detection". It expresses an ordered behaviour that no single event and no rate shows: stage a tool, then use it; probe identity, then attempt escalation. The steps match over the rule's own class; a cross-class sequence is out of scope for the per-class engine, which sees one class at a time.

type Window ¶ added in v0.2.0

type Window struct {
	// Count is the number of matching events that must fall inside the span (>= 2; a count of one is a
	// plain rule).
	Count int
	// Within is the sliding span measured on event timestamps, exclusive: events exactly Within apart
	// are not in one burst.
	Within time.Duration
	// GroupBy partitions the count by the values of these fields, so ten queries to ten resolvers do not
	// add up to a burst against one. Empty groups by host only. Fields must belong to the rule's class.
	GroupBy []Field
}

Window turns a rule from "every matching event is a detection" into "this many matching events within this span, for the same group, is a detection". It is what separates one DNS packet from a burst of them to one destination. The predicates still decide which events count; the window decides when the count is a finding.