sigma

README

sigma-go

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

⚠️ This library is under development and an implementation of a draft specification. Test this well if you're using it for anything important.

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.

sigmac

To make managing rules easy, this repo includes a tool to "compile" directories of rules into Go packages.

./malware/rule_one.yaml
./malware/another_rule.yaml

Running the sigmac tool in this directory will generate a sigma.go file:

> go run github.com/bradleyjkemp/sigma-go/sigmac ./malware

The sigma.go file contains a map of parsed Sigma rules by their ID that you can iterate over when matching events.

for id, rule := range malware.Rules {
    if sigma.Evaluator(rule).Matches(event) {
        fmt.Println("event %v matched rule %s!", event, id)
    }
}

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)
• 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 Correlation
  • func ParseCorrelation(input []byte) (Correlation, error)
• type CorrelationCondition
  • func (c CorrelationCondition) Matches(i int) bool
  • func (c *CorrelationCondition) UnmarshalYAML(value *yaml.Node) error
• type CorrelationType
• type Count
• type Detection
• 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
• 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 RuleMetadata
• type Rules
  • func (i *Rules) UnmarshalYAML(value *yaml.Node) error
• type Search
  • func (s Search) MarshalYAML() (interface{}, error)
  • func (s *Search) UnmarshalYAML(node *yaml.Node) error
• type SearchExpr
• type SearchIdentifier
• type Sum
• type Timespan

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
	Aggregation AggregationExpr
}

func ParseCondition

func ParseCondition(input string) (Condition, error)

Parses the Sigma condition syntax

func (Condition) MarshalYAML

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

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 Correlation

type Correlation struct {
	RuleMetadata

	Type     CorrelationType // the type of correlation
	Rule     Rules           // a list of (possibly one) rule IDs that this correlates over
	GroupBy  []string        // a list of fields to group the correlation by
	Timespan Timespan        // the time window that correlated events must occur within

	Condition CorrelationCondition // for event_count or value_count rules, a numeric condition on the count necessary for this rule to fire
}

func ParseCorrelation

func ParseCorrelation(input []byte) (Correlation, error)

type CorrelationCondition

type CorrelationCondition struct {
	GreaterThan        *int
	GreaterThanEqual   *int
	LessThan           *int
	LessThanEqual      *int
	RangeMin, RangeMax *int
}

func (CorrelationCondition) Matches

func (c CorrelationCondition) Matches(i int) bool

func (*CorrelationCondition) UnmarshalYAML

func (c *CorrelationCondition) UnmarshalYAML(value *yaml.Node) error

type CorrelationType

type CorrelationType string

var (
	CorrelationEventCount CorrelationType = "event_count"
	CorrelationValueCount CorrelationType = "value_count"
	CorrelationTemporal   CorrelationType = "temporal"
)

type Count

type Count struct {
	Field     string
	GroupedBy string
}

type Detection

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

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
	Modifiers []string
	Values    []interface{}
}

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"`
	Product    string `yaml:",omitempty"`
	Service    string `yaml:",omitempty"`
	Definition string `yaml:",omitempty"`

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

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 {
	RuleMetadata
	Logsource Logsource
	Detection Detection
}

func ParseRule

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

type RuleMetadata

type RuleMetadata struct {
	ID          string   `yaml:",omitempty"` // a unique ID identifying this rule
	Title       string   `yaml:",omitempty"` // a human-readable summary
	Description string   `yaml:",omitempty"` // a longer description of the rule
	Related     []string `yaml:",omitempty"` // a list of related rules (referenced by ID) TODO: update this to reflect the new Sigma format for this field
	Status      string   `yaml:",omitempty"` // the stability of this rule
	Level       string   `yaml:",omitempty"` // the severity of this rule
	Author      string   `yaml:",omitempty"` // who wrote this rule
	References  []string `yaml:",omitempty"` // hyperlinks to any supporting research
	Tags        []string `yaml:",omitempty"` // a set of tags (e.g. MITRE ATT&CK techniques)

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

type Rules

type Rules []string

func (*Rules) UnmarshalYAML

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

type Search

type Search struct {
	Keywords      []string
	EventMatchers []EventMatcher
}

func (Search) MarshalYAML

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

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
}

type Timespan

type Timespan time.Time