sigma

package
v0.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 17, 2022 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	SIGMA_SPECIAL_WILDCARD      = byte('*')
	SIGMA_SPECIAL_SINGLE        = byte('?')
	SIGMA_SPECIAL_ESCAPE        = byte('\\')
	GLOB_SPECIAL_SQRBRKT_LEFT   = byte('[')
	GLOB_SPECIAL_SQRBRKT_RIGHT  = byte(']')
	GLOB_SPECIAL_CURLBRKT_LEFT  = byte('{')
	GLOB_SPECIAL_CURLBRKT_RIGHT = byte('}')
)

Variables

View Source 
var ErrUnableToReflect = errors.New("unable to reflect on pattern kind")

ErrUnableToReflect indicates that kind reflection could not be done, as typeOf returned a nil value likely a missing pattern

Functions

func GetField 

func GetField(key string, data map[string]interface{}) (interface{}, bool)

GetField is a helper for retreiving nested JSON keys with dot notation

func NewRuleFileList 

func NewRuleFileList(dirs []string) ([]string, error)

NewRuleFileList finds all yaml files from defined root directories Subtree is scanned recursively No file validation, other than suffix matching

Types

type Branch 

type Branch interface {
	Matcher
}

Branch implements Matcher with additional methods for walking and debugging the tree

func NewSelectionBranch 

func NewSelectionBranch(expr interface{}, noCollapseWS bool) (Branch, error)

type Config 

type Config struct {
	// root directory for recursive rule search
	// rules must be readable files with "yml" suffix
	Directory []string
	// by default, a rule parse fail will simply increment Ruleset.Failed counter when failing to
	// parse yaml or rule AST
	// this parameter will cause an early error return instead
	FailOnRuleParse, FailOnYamlParse bool
	// by default, we will collapse whitespace for both rules and data of non-regex rules and non-regex compared data
	//setthig this to true turns that behavior off
	NoCollapseWS bool
}

Config is used as argument to creating a new ruleset

type ContentPattern 

type ContentPattern struct {
	Token        string
	Lowercase    bool
	NoCollapseWS bool
}

ContentPattern is a token for literal content matching

func (ContentPattern) StringMatch 

func (c ContentPattern) StringMatch(msg string) bool

StringMatch implements StringMatcher

type Detection 

type Detection map[string]interface{}

Detection represents the detection field in sigma rule contains condition expression and identifier fields for building AST

func (Detection) Extract 

func (d Detection) Extract() map[string]interface{}

type DynamicMap 

type DynamicMap map[string]interface{}

DynamicMap is a reference type for implementing sigma Matcher

func (DynamicMap) Keywords 

func (s DynamicMap) Keywords() ([]string, bool)

Keywords implements Keyworder

func (DynamicMap) Select 

func (s DynamicMap) Select(key string) (interface{}, bool)

Select implements Selector

type ErrBulkParseYaml 

type ErrBulkParseYaml struct {
	Errs []ErrParseYaml
}

ErrGotBrokenYamlFiles is a bulk error handler for dealing with broken sigma rules Some rules are bound to fail, no reason to exit entire application Individual errors can be collected and returned at the end Called decides if they should be only reported or it warrants full exit

func (ErrBulkParseYaml) Error 

func (e ErrBulkParseYaml) Error() string

type ErrEmptyDetection 

type ErrEmptyDetection struct{}

ErrEmptyDetection indicates detection field present but empty

func (ErrEmptyDetection) Error 

func (e ErrEmptyDetection) Error() string

type ErrIncompleteDetection 

type ErrIncompleteDetection struct {
	Condition string
	Keys      []string
	Msg       string
}

ErrIncompleteDetection indicates a rule has defined identifiers that are missing in detection map

func (ErrIncompleteDetection) Error 

func (e ErrIncompleteDetection) Error() string

type ErrIncompleteTokenSeq 

type ErrIncompleteTokenSeq struct {
	Expression string
	Items      []Item
	Last       Item
}

ErrIncompleteTokenSeq is invoked when lex channel drain does not end with EOF thus indicating incomplete lexing sequence

func (ErrIncompleteTokenSeq) Error 

func (e ErrIncompleteTokenSeq) Error() string

type ErrInvalidKeywordConstruct 

type ErrInvalidKeywordConstruct struct {
	Msg  string
	Expr interface{}
}

ErrInvalidKeywordConstruct indicates that parser found a keyword expression that did not match any known keyword rule structure could be unmarshal issue

func (ErrInvalidKeywordConstruct) Error 

func (e ErrInvalidKeywordConstruct) Error() string

type ErrInvalidKind 

type ErrInvalidKind struct {
	reflect.Kind
	Msg      string
	T        identType
	Critical bool
}

ErrInvalidKind indicates that type switching function received an unsupported or unhandled data type Contains the type in question, arbitrary error text and keyword/selection indicator Critical is used to indicate if this error should cause an exit or can simply be handled as a warning for future improvements

func (ErrInvalidKind) Error 

func (e ErrInvalidKind) Error() string

type ErrInvalidRegex 

type ErrInvalidRegex struct {
	Pattern string
	Err     error
}

ErrInvalidRegex contextualizes broken regular expressions presented by the user

func (ErrInvalidRegex) Error 

func (e ErrInvalidRegex) Error() string

Error implements error

type ErrInvalidSelectionConstruct 

type ErrInvalidSelectionConstruct struct {
	Msg  string
	Expr interface{}
}

ErrInvalidSelectionConstruct indicates that parser found a selection expression that did not match any known selection rule structure could be unmarshal issue

func (ErrInvalidSelectionConstruct) Error 

func (e ErrInvalidSelectionConstruct) Error() string

type ErrInvalidTokenSeq 

type ErrInvalidTokenSeq struct {
	Prev, Next Item
	Collected  []Item
}

ErrInvalidTokenSeq indicates expression syntax error from rule writer For example, two indents should be separated by a logical AND / OR operator

func (ErrInvalidTokenSeq) Error 

func (e ErrInvalidTokenSeq) Error() string

type ErrMissingCondition 

type ErrMissingCondition struct{}

ErrMissingCondition indicates missing condition field

func (ErrMissingCondition) Error 

func (e ErrMissingCondition) Error() string

type ErrMissingConditionItem 

type ErrMissingConditionItem struct {
	Key string
}

ErrMissingConditionItem indicates that identifier in condition is missing in detection map

func (ErrMissingConditionItem) Error 

func (e ErrMissingConditionItem) Error() string

type ErrMissingDetection 

type ErrMissingDetection struct{}

ErrMissingDetection indicates missing detection field

func (ErrMissingDetection) Error 

func (e ErrMissingDetection) Error() string

type ErrParseYaml 

type ErrParseYaml struct {
	Path  string
	Err   error
	Count int
}

ErrParseYaml indicates YAML parsing error

func (ErrParseYaml) Error 

func (e ErrParseYaml) Error() string

type ErrUnsupportedExpression 

type ErrUnsupportedExpression struct {
	Msg      string
	T        identType
	Expr     interface{}
	Critical bool
}

ErrUnsupportedExpression indicates that rule expression is not yet supported by parser mostly a type issue

func (ErrUnsupportedExpression) Error 

func (e ErrUnsupportedExpression) Error() string

type ErrUnsupportedToken 

type ErrUnsupportedToken struct{ Msg string }

ErrUnsupportedToken is a parser error indicating lexical token that is not yet supported Meant to be used as informational warning, rather than application breaking error

func (ErrUnsupportedToken) Error 

func (e ErrUnsupportedToken) Error() string

type ErrWip 

type ErrWip struct{}

ErrWip indicates a rule expression that is currently Work In Progress Functions like ErrUnsupportedToken but indicates that feature is under active development Non-critical escape hatch while debugging

func (ErrWip) Error 

func (e ErrWip) Error() string

type Event 

type Event interface {
	Keyworder
	Selector
}

Event implements sigma rule types by embedding Keyworder and Selector Used by rules to extract relevant fields

type GlobPattern 

type GlobPattern struct {
	Glob         *glob.Glob
	NoCollapseWS bool
}

GlobPattern is similar to ContentPattern but allows for asterisk wildcards

func (GlobPattern) StringMatch 

func (g GlobPattern) StringMatch(msg string) bool

StringMatch implements StringMatcher

type Item 

type Item struct {
	T   Token
	Val string
	// contains filtered or unexported fields
}

Item is lexical token along with respective plaintext value Item is communicated between lexer and parser

func (*Item) Glob added in v0.2.4 

func (i *Item) Glob() *glob.Glob

Item.Glob() - Wraps getting the compiled glob of Item.Val to ensure it is compiled properly. Do NOT access globVal directly as it won't be compiled until the first call to Item.Glob()

func (Item) String 

func (i Item) String() string

type Keyword 

type Keyword struct {
	S StringMatcher
	Stats
}

Keyword is a container for patterns joined by logical disjunction

func NewKeyword 

func NewKeyword(expr interface{}, noCollapseWS bool) (*Keyword, error)

func (Keyword) Match 

func (k Keyword) Match(msg Event) (bool, bool)

Match implements Matcher

type Keyworder 

type Keyworder interface {
	// Keywords implements Keyworder
	Keywords() ([]string, bool)
}

Keyworder implements keywords sigma rule type on arbitrary event Should return list of fields that are relevant for rule matching

type Logsource 

type Logsource struct {
	Product    string `yaml:"product" json:"product"`
	Category   string `yaml:"category" json:"category"`
	Service    string `yaml:"service" json:"service"`
	Definition string `yaml:"definition" json:"definition"`
}

Logsource represents the logsource field in sigma rule It defines relevant event streams and is used for pre-filtering

type Matcher 

type Matcher interface {
	// Match implements Matcher
	Match(Event) (bool, bool)
}

Matcher is used for implementing Abstract Syntax Tree for Sigma engine

type NodeAnd 

type NodeAnd struct {
	L, R Branch
}

NodeAnd is a two element node of a binary tree with Left and Right branches connected via logical conjunction

func (NodeAnd) Match 

func (n NodeAnd) Match(e Event) (bool, bool)

Match implements Matcher

type NodeNot 

type NodeNot struct {
	B Branch
}

NodeNot negates a branch

func (NodeNot) Match 

func (n NodeNot) Match(e Event) (bool, bool)

Match implements Matcher

type NodeOr 

type NodeOr struct {
	L, R Branch
}

NodeOr is a two element node of a binary tree with Left and Right branches connected via logical disjunction

func (NodeOr) Match 

func (n NodeOr) Match(e Event) (bool, bool)

Match implements Matcher

type NodeSimpleAnd 

type NodeSimpleAnd []Branch

NodeSimpleAnd is a list of matchers connected with logical conjunction

func (NodeSimpleAnd) Match 

func (n NodeSimpleAnd) Match(e Event) (bool, bool)

Match implements Matcher

func (NodeSimpleAnd) Reduce 

func (n NodeSimpleAnd) Reduce() Branch

Reduce cleans up unneeded slices Static structures can be used if node only holds one or two elements Avoids pointless runtime loops

type NodeSimpleOr 

type NodeSimpleOr []Branch

NodeSimpleOr is a list of matchers connected with logical disjunction

func (NodeSimpleOr) Match 

func (n NodeSimpleOr) Match(e Event) (bool, bool)

Match implements Matcher

func (NodeSimpleOr) Reduce 

func (n NodeSimpleOr) Reduce() Branch

Reduce cleans up unneeded slices Static structures can be used if node only holds one or two elements Avoids pointless runtime loops

type NumMatcher 

type NumMatcher interface {
	// NumMatch implements NumMatcher
	NumMatch(int) bool
}

NumMatcher is an atomic pattern for numeric item or list of items

func NewNumMatcher 

func NewNumMatcher(patterns ...int) (NumMatcher, error)

type NumMatchers 

type NumMatchers []NumMatcher

NumMatchers holds multiple numeric matchers

func (NumMatchers) NumMatch 

func (n NumMatchers) NumMatch(val int) bool

NumMatch implements NumMatcher

type NumPattern 

type NumPattern struct {
	Val int
}

NumPattern matches on numeric value

func (NumPattern) NumMatch 

func (n NumPattern) NumMatch(val int) bool

NumMatch implements NumMatcher

type PrefixPattern 

type PrefixPattern struct {
	Token        string
	Lowercase    bool
	NoCollapseWS bool
}

PrefixPattern is a token for literal content matching

func (PrefixPattern) StringMatch 

func (c PrefixPattern) StringMatch(msg string) bool

StringMatch implements StringMatcher

type RegexPattern 

type RegexPattern struct {
	Re *regexp.Regexp
}

RegexPattern is for matching messages with regular expresions

func (RegexPattern) StringMatch 

func (r RegexPattern) StringMatch(msg string) bool

StringMatch implements StringMatcher

type Result 

type Result struct {
	Tags

	ID, Title string
}

Result is an object returned on positive sigma match

type Results 

type Results []Result

Results should be returned when single event matches multiple rules

type Rule 

type Rule struct {
	Author         string   `yaml:"author" json:"author"`
	Description    string   `yaml:"description" json:"description"`
	Falsepositives []string `yaml:"falsepositives" json:"falsepositives"`
	Fields         []string `yaml:"fields" json:"fields"`
	ID             string   `yaml:"id" json:"id"`
	Level          string   `yaml:"level" json:"level"`
	Title          string   `yaml:"title" json:"title"`
	Status         string   `yaml:"status" json:"status"`
	References     []string `yaml:"references" json:"references"`

	Logsource `yaml:"logsource" json:"logsource"`
	Detection `yaml:"detection" json:"detection"`
	Tags      `yaml:"tags" json:"tags"`
}

Rule defines raw rule conforming to sigma rule specification https://github.com/Neo23x0/sigma/wiki/Specification only meant to be used for parsing yaml that matches Sigma rule definition

type RuleHandle 

type RuleHandle struct {
	Rule

	Path         string `json:"path"`
	Multipart    bool   `json:"multipart"`
	NoCollapseWS bool   `json:"noCollapseWS"`
}

RuleHandle is a meta object containing all fields from raw yaml, but is enhanced to also hold debugging info from the tool, such as source file path, etc

func NewRuleList 

func NewRuleList(files []string, skip, noCollapseWS bool) ([]RuleHandle, error)

NewRuleList reads a list of sigma rule paths and parses them to rule objects

type Ruleset 

type Ruleset struct {
	Rules []*Tree

	Total, Ok, Failed, Unsupported int
	// contains filtered or unexported fields
}

Ruleset is a collection of rules

func NewRuleset 

func NewRuleset(c Config) (*Ruleset, error)

NewRuleset instanciates a Ruleset object

func (Ruleset) EvalAll 

func (r Ruleset) EvalAll(e Event) (Results, bool)

type Selection 

type Selection struct {
	N []SelectionNumItem
	S []SelectionStringItem
	Stats
}

func (Selection) Match 

func (s Selection) Match(msg Event) (bool, bool)

Match implements Matcher TODO - numeric and boolean pattern match

type SelectionNumItem 

type SelectionNumItem struct {
	Key     string
	Pattern NumMatcher
}

type SelectionStringItem 

type SelectionStringItem struct {
	Key     string
	Pattern StringMatcher
}

type Selector 

type Selector interface {
	// Select implements Selector
	Select(string) (interface{}, bool)
}

Selector implements selection sigma rule type

type SimplePattern 

type SimplePattern struct {
	Token        string
	NoCollapseWS bool
}

SimplePattern is a reference type to illustrate StringMatcher

func (SimplePattern) StringMatch 

func (s SimplePattern) StringMatch(msg string) bool

StringMatch implements StringMatcher

type Stats 

type Stats struct {
	TypeMismatchCount uint64
}

Stats holds various rule statistics

type StringMatcher 

type StringMatcher interface {
	// StringMatch implements StringMatcher
	StringMatch(string) bool
}

StringMatcher is an atomic pattern that could implement glob, literal or regex matchers

func NewStringMatcher 

func NewStringMatcher(
	mod TextPatternModifier,
	lower, all, noCollapseWS bool,
	patterns ...string,
) (StringMatcher, error)

type StringMatchers 

type StringMatchers []StringMatcher

StringMatchers holds multiple atomic matchers Patterns are meant to be list of possibilities thus, objects are joined with logical disjunctions

func (StringMatchers) Optimize 

func (s StringMatchers) Optimize() StringMatchers

Optimize creates a new StringMatchers slice ordered by matcher type First match wins, thus we can optimize by making sure fast string patterns are executed first, then globs, and finally slow regular expressions

func (StringMatchers) StringMatch 

func (s StringMatchers) StringMatch(msg string) bool

StringMatch implements StringMatcher

type StringMatchersConj 

type StringMatchersConj []StringMatcher

StringMatchersConj is similar to StringMatcher but elements are joined with conjunction, i.e. all patterns must match used to implement "all" specifier for selection types

func (StringMatchersConj) Optimize 

func (s StringMatchersConj) Optimize() StringMatchersConj

Optimize creates a new StringMatchers slice ordered by matcher type First match wins, thus we can optimize by making sure fast string patterns are executed first, then globs, and finally slow regular expressions

func (StringMatchersConj) StringMatch 

func (s StringMatchersConj) StringMatch(msg string) bool

StringMatch implements StringMatcher

type SuffixPattern 

type SuffixPattern struct {
	Token        string
	Lowercase    bool
	NoCollapseWS bool
}

SuffixPattern is a token for literal content matching

func (SuffixPattern) StringMatch 

func (c SuffixPattern) StringMatch(msg string) bool

StringMatch implements StringMatcher

type Tags 

type Tags []string

Tags contains a metadata list for tying positive matches together with other threat intel sources For example, for attaching MITRE ATT&CK tactics or techniques to the event

type TextPatternModifier 

type TextPatternModifier int
const (
	TextPatternNone TextPatternModifier = iota
	TextPatternContains
	TextPatternPrefix
	TextPatternSuffix
	TextPatternAll
	TextPatternRegex
	TextPatternKeyword
)

type Token 

type Token int

Token is a lexical token extracted from condition field 

const (
	TokBegin Token = iota

	// Helpers for internal stuff
	TokErr
	TokUnsupp
	TokNil

	// user-defined word
	TokIdentifier
	TokIdentifierWithWildcard
	TokIdentifierAll

	// Literals
	TokLitEof

	// Separators
	TokSepLpar
	TokSepRpar
	TokSepPipe

	// Operators
	TokOpEq
	TokOpGt
	TokOpGte
	TokOpLt
	TokOpLte

	// Keywords
	TokKeywordAnd
	TokKeywordOr
	TokKeywordNot
	TokKeywordAgg

	// TODO
	TokKeywordNear
	TokKeywordBy

	// Statements
	TokStOne
	TokStAll
)

func (Token) Literal 

func (t Token) Literal() string

Literal documents plaintext values of a token Uses special symbols and expressions, as used in a rule

func (Token) Rune 

func (t Token) Rune() rune

Rune returns UTF-8 numeric value of symbol

func (Token) String 

func (t Token) String() string

String documents human readable textual value of token For visual debugging, so symbols will be written out and everything is uppercased

type Tree 

type Tree struct {
	Root Branch
	Rule *RuleHandle
}

Tree represents the full AST for a sigma rule

func NewTree 

func NewTree(r RuleHandle) (*Tree, error)

NewTree parses rule handle into an abstract syntax tree

func (Tree) Eval 

func (t Tree) Eval(e Event) (*Result, bool)

func (Tree) Match 

func (t Tree) Match(e Event) (bool, bool)

Match implements Matcher

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.