sigma

README

sigma-go

A Go implementation and parser of Sigma rules. Useful for building your own detection pipelines.

Who's using sigma-go in production?

• Monzo Bank
• Phish Report
• SysFlow

Usage

This library is designed for you to build your own alert systems. It exposes the ability to check whether a rule matches a given event but not much else. It's up to you to use this building block in your own detection pipeline.

A basic usage of this library might look like this:

// You can load/create rules dynamically or use sigmac to load Sigma rule files
var rule, _ = sigma.ParseRule(contents)

// Rules need to be wrapped in an evaluator.
// This is also where (if needed) you provide functions implementing the count, max, etc. aggregation functions
e := sigma.Evaluator(rule, options...)

// Get a stream of events from somewhere e.g. audit logs
for event := range events {
    if e.Matches(ctx, event) {
        // Raise your alert here
        newAlert(rule.ID, rule.Description, ...)
    }
}

Aggregation functions

If your Sigma rules make use of the count, max, min, or any other aggregation function in your conditions then you'll need some extra setup.

When creating an evaluator, you can pass in implementations of each of the aggregation functions:

sigma.Evaluator(rule, sigma.CountFunc(countImplementation), sigma.MaxFunc(maxImplementation))

This repo includes some toy implementations in the aggregators package but for production use cases you'll need to supply your own.

Documentation

Index

• func FuzzConditionParser(data []byte) int
• func FuzzConfigParser(data []byte) int
• func FuzzRuleParser(data []byte) int
• type AggregationExpr
• type AggregationFunc
• type AllOfIdentifier
• type AllOfPattern
• type AllOfThem
• type And
• type Average
• type Comparison
• type ComparisonOp
• type Condition
  • func ParseCondition(input string) (Condition, error)
  • func (c Condition) MarshalYAML() (interface{}, error)
  • func (c Condition) Position() (int, int)
• type Conditions
  • func (c Conditions) MarshalYAML() (interface{}, error)
  • func (c *Conditions) UnmarshalYAML(node *yaml.Node) error
• type Config
  • func ParseConfig(contents []byte) (Config, error)
• type Count
• type Detection
  • func (d *Detection) UnmarshalYAML(node *yaml.Node) error
• type EventMatcher
  • func (f EventMatcher) MarshalYAML() (interface{}, error)
  • func (f *EventMatcher) UnmarshalYAML(node *yaml.Node) error
• type FieldMapping
  • func (f *FieldMapping) UnmarshalYAML(value *yaml.Node) error
• type FieldMatcher
  • func (f FieldMatcher) Position() (int, int)
• type FileType
  • func InferFileType(contents []byte) FileType
  • func (f *FileType) UnmarshalYAML(node *yaml.Node) error
• type Logsource
• type LogsourceIndexes
  • func (i *LogsourceIndexes) UnmarshalYAML(value *yaml.Node) error
• type LogsourceMapping
• type Max
• type Min
• type Near
• type Not
• type OneOfIdentifier
• type OneOfPattern
• type OneOfThem
• type Or
• type RelatedRule
• type Rule
  • func ParseRule(input []byte) (Rule, error)
• type Search
  • func (s Search) MarshalYAML() (interface{}, error)
  • func (s Search) Position() (int, int)
  • func (s *Search) UnmarshalYAML(node *yaml.Node) error
• type SearchExpr
• type SearchIdentifier
• type Sum

Functions

func FuzzConditionParser

func FuzzConditionParser(data []byte) int

func FuzzConfigParser

func FuzzConfigParser(data []byte) int

func FuzzRuleParser

func FuzzRuleParser(data []byte) int

Types

type AggregationExpr

type AggregationExpr interface {
	// contains filtered or unexported methods
}

type AggregationFunc

type AggregationFunc interface {
	// contains filtered or unexported methods
}

type AllOfIdentifier

type AllOfIdentifier struct {
	Ident SearchIdentifier
}

type AllOfPattern

type AllOfPattern struct {
	Pattern string
}

type AllOfThem

type AllOfThem struct{}

type And

type And []SearchExpr

type Average

type Average struct {
	Field     string
	GroupedBy string
}

type Comparison

type Comparison struct {
	Func      AggregationFunc
	Op        ComparisonOp
	Threshold float64
}

type ComparisonOp

type ComparisonOp string

var (
	Equal            ComparisonOp = "="
	NotEqual         ComparisonOp = "!="
	LessThan         ComparisonOp = "<"
	LessThanEqual    ComparisonOp = "<="
	GreaterThan      ComparisonOp = ">"
	GreaterThanEqual ComparisonOp = ">="
)

type Condition

type Condition struct {
	Search      SearchExpr      `yaml:",omitempty" json:",omitempty"`
	Aggregation AggregationExpr `yaml:",omitempty" json:",omitempty"`
	// contains filtered or unexported fields
}

func ParseCondition

func ParseCondition(input string) (Condition, error)

Parses the Sigma condition syntax

func (Condition) MarshalYAML

func (c Condition) MarshalYAML() (interface{}, error)

func (Condition) Position

func (c Condition) Position() (int, int)

Position returns the line and column of this Condition in the original input

type Conditions

type Conditions []Condition

func (Conditions) MarshalYAML

func (c Conditions) MarshalYAML() (interface{}, error)

Marshal the conditions back to grammar expressions :sob:

func (*Conditions) UnmarshalYAML

func (c *Conditions) UnmarshalYAML(node *yaml.Node) error

type Config

type Config struct {
	Title         string   // A short description of what this configuration does
	Order         int      // Defines the order of expansion when multiple config files are applicable
	Backends      []string // Lists the Sigma implementations that this config file is compatible with
	FieldMappings map[string]FieldMapping
	Logsources    map[string]LogsourceMapping
	// TODO: LogsourceMerging option
	DefaultIndex string                   // Defines a default index if no logsources match
	Placeholders map[string][]interface{} // Defines values for placeholders that might appear in Sigma rules
}

func ParseConfig

func ParseConfig(contents []byte) (Config, error)

type Count

type Count struct {
	Field     string
	GroupedBy string
}

type Detection

type Detection struct {
	Searches   map[string]Search `yaml:",inline" json:",inline"`
	Conditions Conditions        `yaml:"condition" json:"condition"`
	Timeframe  time.Duration     `yaml:",omitempty" json:",omitempty"`
}

func (*Detection) UnmarshalYAML

func (d *Detection) UnmarshalYAML(node *yaml.Node) error

type EventMatcher

type EventMatcher []FieldMatcher

func (EventMatcher) MarshalYAML

func (f EventMatcher) MarshalYAML() (interface{}, error)

func (*EventMatcher) UnmarshalYAML

func (f *EventMatcher) UnmarshalYAML(node *yaml.Node) error

type FieldMapping

type FieldMapping struct {
	TargetNames []string // The name(s) that appear in the events being matched

}

func (*FieldMapping) UnmarshalYAML

func (f *FieldMapping) UnmarshalYAML(value *yaml.Node) error

type FieldMatcher

type FieldMatcher struct {
	Field     string        `yaml:",omitempty" json:",omitempty"`
	Modifiers []string      `yaml:",omitempty" json:",omitempty"`
	Values    []interface{} `yaml:",omitempty" json:",omitempty"`
	// contains filtered or unexported fields
}

func (FieldMatcher) Position

func (f FieldMatcher) Position() (int, int)

Position returns the line and column of this FieldMatcher in the original input

type FileType

type FileType string

const (
	UnknownFile FileType = ""
	InvalidFile FileType = "invalid"
	RuleFile    FileType = "rule"
	ConfigFile  FileType = "config"
)

func InferFileType

func InferFileType(contents []byte) FileType

func (*FileType) UnmarshalYAML

func (f *FileType) UnmarshalYAML(node *yaml.Node) error

type Logsource

type Logsource struct {
	Category   string `yaml:",omitempty" json:",omitempty"`
	Product    string `yaml:",omitempty" json:",omitempty"`
	Service    string `yaml:",omitempty" json:",omitempty"`
	Definition string `yaml:",omitempty" json:",omitempty"`

	// Any non-standard fields will end up in here
	AdditionalFields map[string]interface{} `yaml:",inline,omitempty" json:",inline,omitempty"`
}

type LogsourceIndexes

type LogsourceIndexes []string

func (*LogsourceIndexes) UnmarshalYAML

func (i *LogsourceIndexes) UnmarshalYAML(value *yaml.Node) error

type LogsourceMapping

type LogsourceMapping struct {
	Logsource  `yaml:",inline"` // Matches the logsource field in Sigma rules
	Index      LogsourceIndexes // The index(es) that should be used
	Conditions Search           // Conditions that are added to all rules targeting this logsource
	Rewrite    Logsource        // Rewrites this logsource (i.e. so that it can be matched by another lower precedence config)
}

type Max

type Max struct {
	Field     string
	GroupedBy string
}

type Min

type Min struct {
	Field     string
	GroupedBy string
}

type Near

type Near struct {
	Condition SearchExpr
}

type Not

type Not struct {
	Expr SearchExpr
}

type OneOfIdentifier

type OneOfIdentifier struct {
	Ident SearchIdentifier
}

type OneOfPattern

type OneOfPattern struct {
	Pattern string
}

type OneOfThem

type OneOfThem struct{}

type Or

type Or []SearchExpr

type RelatedRule

type RelatedRule struct {
	ID   string
	Type string
}

type Rule

type Rule struct {
	// Required fields
	Title     string
	Logsource Logsource
	Detection Detection

	ID          string        `yaml:",omitempty" json:",omitempty"`
	Related     []RelatedRule `yaml:",omitempty" json:",omitempty"`
	Status      string        `yaml:",omitempty" json:",omitempty"`
	Description string        `yaml:",omitempty" json:",omitempty"`
	Author      string        `yaml:",omitempty" json:",omitempty"`
	Level       string        `yaml:",omitempty" json:",omitempty"`
	References  []string      `yaml:",omitempty" json:",omitempty"`
	Tags        []string      `yaml:",omitempty" json:",omitempty"`

	// Any non-standard fields will end up in here
	AdditionalFields map[string]interface{} `yaml:",inline,omitempty" json:",inline,omitempty"`
}

func ParseRule

func ParseRule(input []byte) (Rule, error)

type Search

type Search struct {
	Keywords      []string       `yaml:",omitempty" json:",omitempty"`
	EventMatchers []EventMatcher `yaml:",omitempty" json:",omitempty"`
	// contains filtered or unexported fields
}

func (Search) MarshalYAML

func (s Search) MarshalYAML() (interface{}, error)

func (Search) Position

func (s Search) Position() (int, int)

Position returns the line and column of this Search in the original input

func (*Search) UnmarshalYAML

func (s *Search) UnmarshalYAML(node *yaml.Node) error

type SearchExpr

type SearchExpr interface {
	// contains filtered or unexported methods
}

type SearchIdentifier

type SearchIdentifier struct {
	Name string
}

type Sum

type Sum struct {
	Field     string
	GroupedBy string
}