跳到主要内容

suricata

suricata 库提供 Suricata 规则的解析、匹配与流量生成能力,可加载 IDS 规则对数据包做匹配,或据规则生成"混沌流量"用于检测设备验证,常用于流量检测与 IDS/IPS 规则研究。

典型使用场景:

  • 规则解析与匹配:suricata.ParseSuricata(raw) 解析规则,suricata.NewSuricataMatcher / suricata.NewSuricataMatcherGroup 创建匹配器对数据包匹配。
  • 规则库:suricata.LoadSuricataToDatabase 入库,suricata.YieldRules / suricata.YieldRulesByKeyword 检索规则。
  • 流量生成:suricata.TrafficGenerator() 创建 ChaosMaker,据规则生成符合特征的流量(用于验证检测能力)。

与相邻库的关系:suricata 与 pcapx(抓包/造包)配合做流量层匹配与生成,是流量侧检测与红蓝对抗的工具。

共 18 个函数

函数索引​

函数参数返回值说明
suricata.DeleteSuricataRuleByIDid int64error根据规则 ID 从本地规则数据库中删除一条 Suricata 规则
suricata.LoadSuricataToDatabaseraw stringerror解析 Suricata 规则文本并将其保存到本地规则数据库
suricata.NewSuricataMatcherr *surirule.Rule*match.Matcher基于单条 Suricata 规则创建一个流量匹配器,用于判断数据包是否命中该规则
suricata.TrafficGenerator-*ChaosMakerNewChaosMaker 创建一个流量生成器(ChaosMaker),可根据 Suricata 规则生成对应的模拟攻击流量
suricata.YieldRules-chan *rule.Storage从本地规则库中读取全部规则,以 channel 形式逐条返回

可变参数函数索引​

函数参数返回值说明
suricata.LoadStatefulRulespath string, envs ...string*StatefulRuleSet, errorparses one .rules file or a directory, then compiles every
suricata.LoadSuricataRulespath string, envs ...string[]*surirule.Rule, errorreads one .rules file or every .rules file under a
suricata.NewStatefulEnginerules []*surirule.Rule, opts ...StatefulEngineOption*engine.StatefulEngine, errorcompiles rules for the stateful TCP inspection engine.
suricata.NewSuricataMatcherGroupopt ...match.GroupOption*match.Group创建一个 Suricata 规则匹配器组,可批量加载规则并对数据包进行匹配
suricata.ParseSuricataraw string, envs ...string[]*surirule.Rule, error解析 Suricata 规则文本,返回结构化的规则对象列表
suricata.YieldRulesByKeywordkeywords string, protos ...stringchan *rule.Storage按关键词(以及可选协议)从本地规则库中检索匹配的规则,以 channel 形式返回
suricata.YieldSuricataRulesByKeywordskeywords string, protos ...stringchan *rule.Storage按关键词检索类型为 suricata 的规则,以 channel 形式返回

函数详情​

DeleteSuricataRuleByID​

DeleteSuricataRuleByID(id int64) error

根据规则 ID 从本地规则数据库中删除一条 Suricata 规则

在 yak 中通过 suricata.DeleteSuricataRuleByID 调用

参数

参数名类型说明
idint64规则在数据库中的 ID

返回值

序号类型说明
r1error错误信息,删除失败时非 nil

示例

// 该示例为示意性用法:按 ID 删除规则
err = suricata.DeleteSuricataRuleByID(1)

LoadSuricataToDatabase​

LoadSuricataToDatabase(raw string) error

解析 Suricata 规则文本并将其保存到本地规则数据库

在 yak 中通过 suricata.LoadSuricataToDatabase 调用

参数

参数名类型说明
rawstringSuricata 规则文本,可包含多条规则

返回值

序号类型说明
r1error错误信息,解析失败时非 nil(单条保存失败仅记录告警)

示例

// 该示例为示意性用法:导入规则到本地库
err = suricata.LoadSuricataToDatabase(`alert tcp any any -> any any (msg:"x"; content:"a"; sid:1;)`)

NewSuricataMatcher​

NewSuricataMatcher(r *surirule.Rule) *match.Matcher

基于单条 Suricata 规则创建一个流量匹配器,用于判断数据包是否命中该规则

在 yak 中通过 suricata.NewSuricataMatcher 调用

兼容接口:新代码应使用 suricata.NewStatefulEngine,它包含完整的 matcher 能力并支持状态规则。

参数

参数名类型说明
r*surirule.Rule单条 Suricata 规则对象(通常来自 suricata.ParseSuricata)

返回值

序号类型说明
r1*match.Matcher流量匹配器对象

示例

// 该示例为示意性用法:用单条规则创建匹配器
rules = suricata.ParseSuricata(`alert tcp any any -> any any (msg:"x"; content:"a"; sid:1;)`)~
matcher = suricata.NewSuricataMatcher(rules[0])
println(matcher != nil)

TrafficGenerator​

TrafficGenerator() *ChaosMaker

NewChaosMaker 创建一个流量生成器(ChaosMaker),可根据 Suricata 规则生成对应的模拟攻击流量

在 yak 中通过 suricata.TrafficGenerator 调用

返回值

序号类型说明
r1*ChaosMaker流量生成器对象

示例

// 该示例为示意性用法:创建流量生成器
maker = suricata.TrafficGenerator()
println(maker != nil)

YieldRules​

YieldRules() chan *rule.Storage

从本地规则库中读取全部规则,以 channel 形式逐条返回

在 yak 中通过 suricata.YieldRules 调用,依赖本地规则数据库

返回值

序号类型说明
r1chan *rule.Storage一个只读 channel,逐条产出规则存储对象

示例

// 该示例为示意性用法:遍历本地规则库

for rule = range suricata.YieldRules() {
println(rule.Name)
}

可变参数函数详情​

LoadStatefulRules​

LoadStatefulRules(path string, envs ...string) (*StatefulRuleSet, error)

parses one .rules file or a directory, then compiles every rule independently. Unsupported rules and duplicate identities are reported in Rejected instead of aborting the whole ruleset, which is what real ET corpora require. Rules that are returned are known to compile in M1.

必填参数

参数名类型说明
pathstring

可选参数

参数名类型说明
envs...string

返回值

序号类型说明
r1*StatefulRuleSet
r2error

LoadSuricataRules​

LoadSuricataRules(path string, envs ...string) ([]*surirule.Rule, error)

reads one .rules file or every .rules file under a directory. Files are parsed in lexical order so rule order and flowbits writers stay deterministic. Tolerant parsing is available directly through ParseSuricata; this helper surfaces parse failures instead of silently dropping a file.

必填参数

参数名类型说明
pathstring

可选参数

参数名类型说明
envs...string

返回值

序号类型说明
r1[]*surirule.Rule
r2error

NewStatefulEngine​

NewStatefulEngine(rules []*surirule.Rule, opts ...StatefulEngineOption) (*engine.StatefulEngine, error)

compiles rules for the stateful TCP inspection engine. In Yak, call it as suricata.NewStatefulEngine(rules, opts...).

必填参数

参数名类型说明
rules[]*surirule.Rule

可选参数

可作为可变参数 opts ...StatefulEngineOption 传入选项;共 5 个可用选项,详见 StatefulEngineOption 选项列表。

返回值

序号类型说明
r1*engine.StatefulEngine
r2error

NewSuricataMatcherGroup​

NewSuricataMatcherGroup(opt ...match.GroupOption) *match.Group

创建一个 Suricata 规则匹配器组,可批量加载规则并对数据包进行匹配

在 yak 中通过 suricata.NewSuricataMatcherGroup 调用

兼容接口:新代码应使用 suricata.NewStatefulEngine,它包含完整的 matcher 能力并支持状态规则。

可选参数

可作为可变参数 opt ...match.GroupOption 传入选项;共 1 个可用选项,详见 GroupOption 选项列表。

返回值

序号类型说明
r1*match.Group规则匹配器组对象

示例

// 该示例为示意性用法:创建匹配器组并设置命中回调

group = suricata.NewSuricataMatcherGroup(suricata.groupCallback(func(packet, matchedRule) {
println("matched:", matchedRule.Message)
}))

println(group != nil)

ParseSuricata​

ParseSuricata(raw string, envs ...string) ([]*surirule.Rule, error)

解析 Suricata 规则文本,返回结构化的规则对象列表

在 yak 中通过 suricata.ParseSuricata 调用

必填参数

参数名类型说明
rawstringSuricata 规则文本,可包含一条或多条规则

可选参数

参数名类型说明
envs...string可选的环境变量定义,格式为 "NAME=value",用于替换规则中的 $NAME 占位符

返回值

序号类型说明
r1[]*surirule.Rule解析得到的规则对象列表
r2error错误信息,解析失败时非 nil

示例

rule = `alert tcp any any -> any any (msg:"test rule"; content:"hello"; sid:1000001;)`
rules, err = suricata.ParseSuricata(rule)
assert err == nil, "should parse suricata rule"
println(len(rules)) // OUT: 1
assert rules[0].Message == "test rule", "rule message should be parsed"

YieldRulesByKeyword​

YieldRulesByKeyword(keywords string, protos ...string) chan *rule.Storage

按关键词(以及可选协议)从本地规则库中检索匹配的规则,以 channel 形式返回

在 yak 中通过 suricata.YieldRulesByKeyword 调用,依赖本地规则数据库

必填参数

参数名类型说明
keywordsstring检索关键词,多个关键词可用逗号分隔

可选参数

参数名类型说明
protos...string可选的协议过滤,如 "tcp"、"http"

返回值

序号类型说明
r1chan *rule.Storage一个只读 channel,逐条产出匹配的规则存储对象

示例

// 该示例为示意性用法:按关键词检索规则

for rule = range suricata.YieldRulesByKeyword("redis", "tcp") {
println(rule.Name)
}

YieldSuricataRulesByKeywords​

YieldSuricataRulesByKeywords(keywords string, protos ...string) chan *rule.Storage

按关键词检索类型为 suricata 的规则,以 channel 形式返回

在 yak 中通过 suricata.YieldSuricataRulesByKeywords 调用,依赖本地规则数据库

必填参数

参数名类型说明
keywordsstring检索关键词,多个关键词可用逗号分隔

可选参数

参数名类型说明
protos...string可选的协议过滤,如 "tcp"、"http"

返回值

序号类型说明
r1chan *rule.Storage一个只读 channel,逐条产出匹配的 suricata 规则存储对象

示例

// 该示例为示意性用法:检索 suricata 规则

for rule = range suricata.YieldSuricataRulesByKeywords("trojan") {
println(rule.Name)
}

可变参数选项列表​

以下按选项类型汇总全部可变参数选项(原先重复在各主函数下的选项表已收拢到此处):

1. 类型:GroupOption​

涉及到的函数有:suricata.NewSuricataMatcherGroup

选项函数参数返回值说明
suricata.groupCallbackcb func(packet gopacket.Packet, match *surirule.Rule)match.GroupOption设置规则匹配器组在命中规则时触发的回调函数

2. 类型:StatefulEngineOption​

涉及到的函数有:suricata.NewStatefulEngine

选项函数参数返回值说明
suricata.engineEpochepoch intStatefulEngineOptionisolates flowbits, thresholds and xbits between ruleset
suricata.engineLimitsvalues map[string]int64StatefulEngineOptionbounds aggregate engine resources. Recognized keys:
suricata.engineOnAlertcallback func(StatefulAlert)StatefulEngineOptioninstalls the alert callback. The callback runs synchronously
suricata.engineOnDiagnosticcallback func(StatefulDiagnostic)StatefulEngineOptioninstalls the diagnostic callback.
suricata.engineStateLimitsvalues map[string]int64StatefulEngineOptionoverrides state-store limits. Recognized keys: