rules

Documentation

Index

• func CompileRules(config *Config) error
• func EvaluateRule(rule *Rule, record types.AuditRecord) (*types.Alert, error)
• func GetEmbeddedRuleSetInfo() (map[string]EmbeddedRuleSetInfo, error)
• func GetEmbeddedRuleSetNames() ([]string, error)
• func ValidateSeverity(severity string) bool
• type ActionStats
• type AlertWriter
• type Config
  • func LoadEmbeddedRules() (*Config, error)
  • func LoadRulesFromDirectory(dirPath string) (*Config, error)
  • func LoadRulesFromFile(path string) (*Config, error)
  • func LoadRulesWithEmbeddedDefaults(dirPath string) (*Config, error)
  • func MergeConfigs(base, override *Config) *Config
• type EmbeddedRuleSetInfo
• type Engine
  • func NewEngine(rulesPath string, alertWriter AlertWriter) (*Engine, error)
  • func NewEngineFromConfig(config *Config, alertWriter AlertWriter) (*Engine, error)
  • func (e *Engine) Close() error
  • func (e *Engine) Evaluate(record types.AuditRecord) (int, error)
  • func (e *Engine) GetActionStats() map[string]uint64
  • func (e *Engine) GetFirewallManager() *firewall.Manager
  • func (e *Engine) GetStats() map[string]any
  • func (e *Engine) SetDeduplicationWindow(d time.Duration)
  • func (e *Engine) SetFirewallManager(manager *firewall.Manager)
  • func (e *Engine) SetPerformanceTracker(tracker *performance.Tracker)
  • func (e *Engine) SetRateLimit(limit int)
  • func (e *Engine) UpdateConfig(config *Config) error
• type FileAlertWriter
  • func NewFileAlertWriter(outputDir string) (*FileAlertWriter, error)
  • func (w *FileAlertWriter) Close() error
  • func (w *FileAlertWriter) WriteAlert(alert *types.Alert) error
• type ResponseAction
  • func (a *ResponseAction) IsEnabled() bool
  • func (a *ResponseAction) Validate() error
• type Rule

Functions

func CompileRules

func CompileRules(config *Config) error

CompileRules compiles all rule expressions in the configuration.

func EvaluateRule

func EvaluateRule(rule *Rule, record types.AuditRecord) (*types.Alert, error)

EvaluateRule evaluates a rule against an audit record and returns an alert if it matches.

func GetEmbeddedRuleSetInfo

func GetEmbeddedRuleSetInfo() (map[string]EmbeddedRuleSetInfo, error)

GetEmbeddedRuleSetInfo returns information about all embedded rule sets including descriptions.

func GetEmbeddedRuleSetNames

func GetEmbeddedRuleSetNames() ([]string, error)

GetEmbeddedRuleSetNames returns a list of embedded rule set names (without .yml extension).

func ValidateSeverity

func ValidateSeverity(severity string) bool

ValidateSeverity checks if a severity string is valid.

Types

type ActionStats

type ActionStats struct {
	ActionsExecuted uint64
	ActionsSuccess  uint64
	ActionsFailed   uint64
	IPsBlocked      uint64
	// contains filtered or unexported fields
}

ActionStats tracks response action statistics.

type AlertWriter

type AlertWriter interface {
	WriteAlert(alert *types.Alert) error
	Close() error
}

AlertWriter is an interface for writing alerts.

type Config

type Config struct {
	Description string  `yaml:"description"`
	Rules       []*Rule `yaml:"rules"`
}

Config holds a collection of rules loaded from a YAML file.

func LoadEmbeddedRules

func LoadEmbeddedRules() (*Config, error)

LoadEmbeddedRules loads all embedded default detection rules. These are bundled into the binary at compile time.

func LoadRulesFromDirectory

func LoadRulesFromDirectory(dirPath string) (*Config, error)

LoadRulesFromDirectory loads all rule files from a directory and returns a merged configuration.

func LoadRulesFromFile

func LoadRulesFromFile(path string) (*Config, error)

LoadRulesFromFile loads rules from a YAML file.

func LoadRulesWithEmbeddedDefaults

func LoadRulesWithEmbeddedDefaults(dirPath string) (*Config, error)

LoadRulesWithEmbeddedDefaults loads rules from a directory path, but first loads embedded defaults. File rules override embedded rules with the same name.

func MergeConfigs

func MergeConfigs(base, override *Config) *Config

MergeConfigs merges two configs, with override rules taking precedence. Rules with matching names in override replace rules in base.

type EmbeddedRuleSetInfo

type EmbeddedRuleSetInfo struct {
	Name        string
	Description string
	RuleCount   int
}

EmbeddedRuleSetInfo contains information about an embedded rule set.

type Engine

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

Engine manages rules and evaluates them against audit records.

func NewEngine

func NewEngine(rulesPath string, alertWriter AlertWriter) (*Engine, error)

NewEngine creates a new rules engine with the given configuration and alert writer. rulesPath can be a path to a single YAML file or a directory containing multiple YAML files.

func NewEngineFromConfig

func NewEngineFromConfig(config *Config, alertWriter AlertWriter) (*Engine, error)

NewEngineFromConfig creates a new rules engine from an existing configuration. This allows creating an engine without reading from a file.

func (*Engine) Close

func (e *Engine) Close() error

Close closes the alert writer.

func (*Engine) Evaluate

func (e *Engine) Evaluate(record types.AuditRecord) (int, error)

Evaluate evaluates all applicable rules against an audit record. It returns the number of alerts generated.

func (*Engine) GetActionStats

func (e *Engine) GetActionStats() map[string]uint64

GetActionStats returns response action statistics.

func (*Engine) GetFirewallManager

func (e *Engine) GetFirewallManager() *firewall.Manager

GetFirewallManager returns the current firewall manager.

func (*Engine) GetStats

func (e *Engine) GetStats() map[string]any

GetStats returns statistics about the engine.

func (*Engine) SetDeduplicationWindow

func (e *Engine) SetDeduplicationWindow(d time.Duration)

SetDeduplicationWindow configures the time window for alert deduplication.

func (*Engine) SetFirewallManager

func (e *Engine) SetFirewallManager(manager *firewall.Manager)

SetFirewallManager sets the firewall manager for response actions. If not set, iptables-based response actions will be skipped.

func (*Engine) SetPerformanceTracker

func (e *Engine) SetPerformanceTracker(tracker *performance.Tracker)

SetPerformanceTracker sets the performance tracker for collecting metrics.

func (*Engine) SetRateLimit

func (e *Engine) SetRateLimit(limit int)

SetRateLimit configures the maximum number of alerts per minute per rule.

func (*Engine) UpdateConfig

func (e *Engine) UpdateConfig(config *Config) error

UpdateConfig updates the rules configuration in memory. This allows for runtime updates of rules without recreating the engine.

type FileAlertWriter

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

FileAlertWriter writes alerts to a netcap audit record file.

func NewFileAlertWriter

func NewFileAlertWriter(outputDir string) (*FileAlertWriter, error)

NewFileAlertWriter creates a new file-based alert writer. Alerts are written to Alert.ncap.gz in the specified output directory. If the file exists, it reads existing alerts and will rewrite them along with new ones on Close.

func (*FileAlertWriter) Close

func (w *FileAlertWriter) Close() error

Close writes all alerts (existing + new) to the alert file.

func (*FileAlertWriter) WriteAlert

func (w *FileAlertWriter) WriteAlert(alert *types.Alert) error

WriteAlert collects an alert to be written on Close.

type ResponseAction

type ResponseAction struct {
	// Type is the action type (iptables_block, iptables_reject, iptables_rate_limit, iptables_log)
	Type string `yaml:"type"`

	// Config contains action-specific configuration
	Config map[string]any `yaml:"config,omitempty"`

	// Enabled allows disabling specific actions (default: true if omitted)
	Enabled *bool `yaml:"enabled,omitempty"`
}

ResponseAction defines an automated response to a rule match.

func (*ResponseAction) IsEnabled

func (a *ResponseAction) IsEnabled() bool

IsEnabled returns true if the action is enabled (default is true).

func (*ResponseAction) Validate

func (a *ResponseAction) Validate() error

Validate checks if the response action has a valid type.

type Rule

type Rule struct {
	// Name is a unique identifier for the rule
	Name string `yaml:"name"`

	// Description provides human-readable information about the rule
	Description string `yaml:"description"`

	// Type specifies which audit record type this rule applies to (e.g., "TCP", "HTTP")
	Type string `yaml:"type"`

	// Expression is the expr-lang expression to evaluate
	Expression string `yaml:"expression"`

	// Severity indicates the importance of alerts generated by this rule
	// Valid values: low, medium, high, critical
	Severity string `yaml:"severity"`

	// MITRE contains MITRE ATT&CK technique IDs associated with this rule
	MITRE []string `yaml:"mitre"`

	// Tags are custom labels for categorizing rules
	Tags []string `yaml:"tags"`

	// Enabled determines whether this rule is active
	Enabled bool `yaml:"enabled"`

	// Threshold is the number of times this rule must match before triggering an alert
	// If 0 or 1, alert is triggered immediately on first match (default behavior)
	Threshold int `yaml:"threshold,omitempty"`

	// ThresholdWindow is the time window (in seconds) within which the threshold must be reached
	// Only applicable when Threshold > 1. Default is 60 seconds (1 minute)
	ThresholdWindow int `yaml:"threshold_window,omitempty"`

	// Actions are response actions to execute when this rule matches and generates an alert.
	// These are automated responses like blocking IPs via iptables.
	Actions []*ResponseAction `yaml:"actions,omitempty"`
	// contains filtered or unexported fields
}

Rule represents a detection rule that can be evaluated against audit records.