evaluator

Documentation

Index

• func CaseSensitive(e *RuleEvaluator)
• func EventTimeFromContext(ctx context.Context) (time.Time, bool)
• func LazyEvaluation(e *RuleEvaluator)
• func WithEventTime(ctx context.Context, t time.Time) context.Context
• type CorrelationEvaluator
  • func ForCorrelation(rule sigma.Rule, referencedRules []sigma.Rule, options ...Option) (*CorrelationEvaluator, error)
  • func (c *CorrelationEvaluator) Matches(ctx context.Context, event Event) (CorrelationResult, error)
• type CorrelationResult
• type Event
• type GroupedByValues
  • func (a GroupedByValues) Key() string
• type Option
  • func AverageImplementation(...) Option
  • func CountDistinctImplementation(...) Option
  • func CountImplementation(count func(ctx context.Context, key GroupedByValues) (float64, error)) Option
  • func MaxImplementation(...) Option
  • func MinImplementation(...) Option
  • func SumImplementation(...) Option
  • func WithConfig(config ...sigma.Config) Option
  • func WithPlaceholderExpander(f func(ctx context.Context, placeholderName string) ([]string, error)) Option
• type Result
• type RuleEvaluator
  • func ForRule(rule sigma.Rule, options ...Option) *RuleEvaluator
  • func (rule *RuleEvaluator) GetFieldValuesFromEvent(field string, event Event) ([]interface{}, error)
  • func (rule RuleEvaluator) Indexes() []string
  • func (rule RuleEvaluator) Matches(ctx context.Context, event Event) (Result, error)
  • func (rule RuleEvaluator) RelevantToEvent(ctx context.Context, eventIndex string, event Event) (bool, error)
• type RuleEvaluatorBundle
  • func ForRules(rules []sigma.Rule, options ...Option) RuleEvaluatorBundle
  • func (bundle RuleEvaluatorBundle) Matches(ctx context.Context, event Event) ([]RuleResult, error)
• type RuleResult

Functions

func CaseSensitive

func CaseSensitive(e *RuleEvaluator)

CaseSensitive turns off the default Sigma behaviour that string operations are by default case-insensitive This can increase performance (especially for larger events) by skipping expensive calls to strings.ToLower

func EventTimeFromContext

func EventTimeFromContext(ctx context.Context) (time.Time, bool)

EventTimeFromContext returns the event timestamp set by WithEventTime, or (zero, false) if none was set (callers fall back to time.Now()).

func LazyEvaluation

func LazyEvaluation(e *RuleEvaluator)

LazyEvaluation allows the evaluator to skip evaluating searches if they won't affect the overall match result

func WithEventTime

func WithEventTime(ctx context.Context, t time.Time) context.Context

WithEventTime returns a context carrying the timestamp of the event being evaluated. The in-memory aggregator and correlation evaluator window by this time instead of wall-clock arrival time, so aggregation/correlation results are correct when replaying historical logs (where every event "arrives" at once).

Types

type CorrelationEvaluator

type CorrelationEvaluator struct {
	Rule sigma.Rule
	// contains filtered or unexported fields
}

CorrelationEvaluator evaluates a Sigma correlation rule: a meta-rule that aggregates the matches of one or more referenced rules over a sliding time window (event_count, value_count, temporal, temporal_ordered).

It is stateful: feed it the same stream of events you feed your normal rule evaluators and it raises a match when the correlation condition is met. State is kept in-memory and partitioned by the rule's group-by values.

func ForCorrelation

func ForCorrelation(rule sigma.Rule, referencedRules []sigma.Rule, options ...Option) (*CorrelationEvaluator, error)

ForCorrelation builds an evaluator for a correlation rule. referencedRules must contain every rule named in the correlation's `rules` list (looked up by Name or ID); options are passed through to each referenced rule's evaluator.

A correlation may reference other correlation rules ("chained correlations", per the Sigma spec): such references are built recursively into nested correlation evaluators, and a child's firing is fed to the parent as a matching event.

func (*CorrelationEvaluator) Matches

func (c *CorrelationEvaluator) Matches(ctx context.Context, event Event) (CorrelationResult, error)

type CorrelationResult

type CorrelationResult struct {
	// Match is true if this event caused the correlation condition to be met.
	Match bool
	// GroupValues are the group-by field values of the bucket that fired (nil if
	// no referenced rule matched this event).
	GroupValues map[string]interface{}
}

CorrelationResult is the outcome of evaluating a single event against a correlation rule.

type Event

type Event interface{}

Event should be some form a map[string]interface{} or map[string]string

type GroupedByValues

type GroupedByValues struct {
	ConditionID int // TODO: there's some forward/backward compatibility pitfalls here: what happens if you switch the order of conditions in your Sigma file?
	EventValues map[string]interface{}

	// RuleID identifies the rule this aggregation belongs to (the rule's ID, or
	// its name/title when no ID is set). Without it, two different rules with the
	// same condition shape and group-by values would share one aggregation bucket
	// when evaluated through the same aggregator (e.g. a bundle), cross-counting
	// each other's events.
	RuleID string

	// Timeframe is the sliding window (taken from the rule's `detection.timeframe`)
	// over which this aggregation should be calculated. It is zero if the rule
	// doesn't specify a timeframe, in which case the aggregation implementation
	// should fall back to its own default window.
	Timeframe time.Duration
}

GroupedByValues contains the fields that uniquely identify a distinct aggregation statistic. Think of it like a ratelimit key.

For example, if a Sigma rule has a condition like this (attempting to detect login brute forcing)

detection:

  login_attempt:
    # something here
  condition:
    login_attempt | count() by (username) > 100
	 timeframe: 1m

Conceptually there's a bunch of boxes somewhere (one for each username) containing their current count. Each different GroupedByValues points to a different box.

GroupedByValues

    ||
 ___↓↓___          ________
| User A |        | User B |
|__2041__|        |___01___|

It's up to your implementation to ensure that different GroupedByValues map to different boxes (although a default Key() method is provided which is good enough for most use cases)

func (GroupedByValues) Key

func (a GroupedByValues) Key() string

type Option

type Option func(*RuleEvaluator)

func AverageImplementation

func AverageImplementation(average func(ctx context.Context, key GroupedByValues, value float64) (float64, error)) Option

func CountDistinctImplementation

func CountDistinctImplementation(countDistinct func(ctx context.Context, key GroupedByValues, value interface{}) (float64, error)) Option

CountDistinctImplementation provides the implementation for the count-distinct aggregation (e.g. `count(TargetUserName) by IpAddress`). For each event it is passed the group key and the value of the counted field, and must return the number of distinct values seen for that group within the rule's timeframe.

func CountImplementation

func CountImplementation(count func(ctx context.Context, key GroupedByValues) (float64, error)) Option

func MaxImplementation

func MaxImplementation(max func(ctx context.Context, key GroupedByValues, value float64) (float64, error)) Option

MaxImplementation provides the implementation for the max aggregation (e.g. `max(FileSize) by Host`). For each event it is passed the group key and the value of the aggregated field, and must return the maximum value seen for that group within the rule's timeframe.

func MinImplementation

func MinImplementation(min func(ctx context.Context, key GroupedByValues, value float64) (float64, error)) Option

MinImplementation provides the implementation for the min aggregation (e.g. `min(FileSize) by Host`). For each event it is passed the group key and the value of the aggregated field, and must return the minimum value seen for that group within the rule's timeframe.

func SumImplementation

func SumImplementation(sum func(ctx context.Context, key GroupedByValues, value float64) (float64, error)) Option

func WithConfig

func WithConfig(config ...sigma.Config) Option

func WithPlaceholderExpander

func WithPlaceholderExpander(f func(ctx context.Context, placeholderName string) ([]string, error)) Option

type Result

type Result struct {
	Match            bool            // whether this event matches the Sigma rule
	SearchResults    map[string]bool // For each Search, whether it matched the event
	ConditionResults []bool          // For each Condition, whether it matched the event
}

type RuleEvaluator

type RuleEvaluator struct {
	sigma.Rule
	// contains filtered or unexported fields
}

func ForRule

func ForRule(rule sigma.Rule, options ...Option) *RuleEvaluator

func (*RuleEvaluator) GetFieldValuesFromEvent

func (rule *RuleEvaluator) GetFieldValuesFromEvent(field string, event Event) ([]interface{}, error)

func (RuleEvaluator) Indexes

func (rule RuleEvaluator) Indexes() []string

func (RuleEvaluator) Matches

func (rule RuleEvaluator) Matches(ctx context.Context, event Event) (Result, error)

func (RuleEvaluator) RelevantToEvent

func (rule RuleEvaluator) RelevantToEvent(ctx context.Context, eventIndex string, event Event) (bool, error)

RelevantToEvent calculates whether a rule is applicable to an event based on:

• Whether the rule has been configured with a config file that matches the eventIndex
• Whether the event matches the conditions from the config file

type RuleEvaluatorBundle

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

func ForRules

func ForRules(rules []sigma.Rule, options ...Option) RuleEvaluatorBundle

ForRules compiles a set of rule evaluators which are evaluated together allowing for use of more efficient string matching algorithms

func (RuleEvaluatorBundle) Matches

func (bundle RuleEvaluatorBundle) Matches(ctx context.Context, event Event) ([]RuleResult, error)

type RuleResult

type RuleResult struct {
	Result
	sigma.Rule
}