lua-resty-waf 实践总结

[jinhailang]

lua-resty-waf 实践总结

lua-resty-waf 是基于 OpenResty 开发的 WAF 项目，其核心的防护规则策略基本与 ModSecurity Core Rule 一致，但是具体实现有所不同。

下面主要分四块阐述其实现功能与原理：

• 配置模块
• 规则模块
• 日志模块
• 特别说明

配置模块

系统配置分为两块系统基本配置和规则配置。

规则配置

系统默认提供了基础的防护规则集，规则集文件都在 rules/ 文件夹下，默认有九个文件：

• 11000_whitelist.json
• 20000_http_violation.json 违反 HTTP 协议防御
• 21000_http_anomaly.json 异常 HTPP 请求防御
• 35000_user_agent.json user_agent 防御
• 40000_generic_attack.json 一般攻击防御
• 41000_sqli.json SQL 注入防御
• 42000_xss.json XSS 攻击防御
• 90000_custom.json 客户自定义防护规则
• 99000_scoring.json SCORE 阀值控制

默认规则集的执行顺序也是从上到下的，注意文件的命名规律，后续添加自己的规则集的时候最好遵循这种规范。

规则配置的加载方式有三种：

1）系统启动时默认加载

waf.init 函数默认会去 package.path 前缀路径下的目录 rules/ 下加载数组 global_rulesets 指定的 .json 规则集配置文件。 global_rulesets 默认就是包括了 rules/ 目录下的所有文件名，也是基本的系统参数之一，可以通过 waf:set_option("global_rulesets", {}) 来指定，具体后面会说。

2）使用 load_secrules 加载

可以调用函数 load_secrules 函数从磁盘加载 ModSecurity SecRules 配置文件，参数就是文件所在的绝对路径。需要注意的是还需要调用函数 add_ruleset 将规则集名（文件名称）注册到系统，否则系统是识别不到的。

系统内部会按行将 ModSecurity 规则集文件转换（在 translate 包内）成 waf 对应的规则格式（json）。目前支持四种规则指令：

• SecRule
• SecAction
• SecMarker
• SecDefaultAction

3）使用 add_ruleset_string 加载

add_ruleset_string 可以直接加载规则集字符串（json）。 用户可以使用这种方式动态的加载自定义规则集合。

在每个阶段执行对应的规则集之前，都会先合并（merge）规则集，主要就是根据规则集名，当规则集名称一样时，用户自己添加的规则集优先级更高。

系统配置

waf.new 函数会初始化一个系统基础参数表，这些参数都可以通过函数 waf.set_option(参数名称, value) 来设置。 一些比较重要的参数说明：

• _debug 开启 debug 模式，将会打印更详细的日志，默认 false
• _debug_log_level debug 模式的日志输出级别，默认 ngx.INFO
• _deny_status 请求被规则拒绝时返回的状态，默认 403
• _event_log_altered_only 是否只有当请求结束时（DENY 或 DROP）才对外输出日志数据，默认 true
• _event_log_level 设置日志输出级别，默认 ngx.info
• _event_log_request_* 可以指定对外日志输出 arguments、body、headers 字段，默认都是 false
• _event_log_target 设置日志对外输出的方式，有三种方式可选（详见日志模块说明），默认 error
• _mode 系统运行模式，有三种可选值，默认值 INACTIVE
  • SIMULATE 默认值，模拟模式，只会记录规则命中日志，不会执行规则 action
  • INACTIVE 不执行规则引擎，即 不执行 exec 函数
  • ACTIVE 即正常模式
• _score_threshold 风险最大阀值，当大于该值时，请求将会被 DENY

规则模块

规则模块是 WAF 项目的核心，包括解析和执行两个部分，为了支持类似 ModSecurity 的防护规则，规则配置比较复杂，解析和执行逻辑就更复杂了。

规则解析

规则配置是按规则集（规则数组）的形式被读取的，规则集再分为多个阶段 --- access,header_filter 等。所有的规则集在解析时，会按阶段的维度，添加到对应阶段的规则集数组。

需要注意的是，规则解析时会计算两个特殊的变量值：

• rule.offset_nomatch 数值，当当前规则匹配失败时，规则遍历迭代器接下来要跳转的规则数，即：当前规则序数 + offset_nomatch = 下条规则的序数
• rule.offset_match 数值，当当前规则匹配成功时，规则遍历迭代器接下来要跳转的规则数

这两个变量值一般都是 1，即直接进入相邻的下个规则，但是使用 skip 或 CHAIN 都会改变这些值。他们都被放入 table 对象 rule，供规则执行时使用。

规则配置项

• action 规则行为定义
  • nondisrupt map 数组，非破坏请求行为，定义命中当前规则后的数据行为，可与 disrupt 配合使用，在 disrupt 之前被执行
    • action 指定具体的行为，有九个可选值：
      • setvar 设置 K-V 值，默认将会存放到变量 storage（table 类型），可作为中间缓存，生存周期是当前请求（ngx.ctx）
      • initcol 持久化存储，将指定的值做存放到 redis、memcached 或 dict
      • sleep 调用 ngx.sleep
      • status 设置当前请求被 DENY 后，响应的 HTTP 状态
      • rule_remove_id 临时（内存）移出 data（规则 ID） 对应的规则， 与 ignore_rule 原理相同
      • mode_update 更新 _mode（系统运行模式） 值
    • data 上面 action 行为的参数值，动态数据类型，根据 action，可以是 map，字符串或者数值
      • col 设置存放到 storage 的 一维 key
      • inc 累加，当 value 为数字时，会将数值 value 累加到对应的中间缓存值
      • key 设置存储的二维 key
      • value 设置存储的值，数值或字符串
  • disrupt 字符串，定义具体防护方式，有六个可选值：
    • ACCEPT 结束当前阶段，继续执行下一阶段，目前因为规则都集中在 Acess 阶段，可以认为直接通过(PASS) Waf
    • DENY 拒绝当前请求，默认返回 403，返回状态可以在 nondisrupt.action.status 指定，但是不建议修改
    • DROP 断开当前请求连接，特殊的 444 状态，Nginx 将直接断开连接，而不响应任何字节给客户端
    • IGNORE 忽略该规则的本次命中，继续后面规则的校验
    • SCORE 调整（加减）风险数值（anomaly_score），只有当风险数值大于阀值（由配置 _score_threshold 指定）请求才会被拒绝，与 nondisrupt 配合使用
    • CHAIN 规则链，与其他防护方式的规则组合使用，相当于后续规则的前置条件，类似 and 操作
• id 数值，唯一的标识当前规则
• op_negated 否定规则匹配结果，即对匹配结果取反
• operator 操作符，可选值：
  • REGEX 正则匹配，如果待匹配项为 table，则会逐次匹配，一旦匹配成功就返回，下同
  • REFIND 查找（ngx.re.find）
  • EQUALS 相等
  • GREATER 大于
  • LESS 小于
  • EXISTS 在字符串数组 pattern 内存在指定的字符串
  • CONTAINS 在获取的字符串或字符串数组内包含指定的 pattern
  • STR_EXISTS 在指定的字符串内存在
    • STR_MATCH 字符串匹配
  • PM 字符串匹配，可同时与组内所有子串进行匹配（Aho–Corasick 算法）
  • CIDR_MATCH IP 地址匹配，当前 IP 是否在pattern IP 数组内
  • DETECT_SQLI SQL 攻击检查
  • DETECT_XSS XSS 攻击检查
  • VERIFY_CC 验证信用卡号是否合法
• pattern 匹配值，字符串或字符串数组，可以是具体的值或者正则表达式，与待匹配值(根据下面的 vars 计算所得)进行比较
• skip 数值，指跳过的规则个数（下个规则位置 = 当前规则位置 + skip + 1）
• skip_after 数值，根据规则 id，直接跳转到对应规则
• vars 对象数组，定义待匹配值的获取方式
  • type 定义数据源，可选值（部分）：
    • REQUEST_HEADERS 获取请求头，map 类型
    • METHOD 获取请求方法，字符串类型，例如：GET，POST 等 HTTP 标准方法
    • TX 获取中间缓存值（ctx.storage["TX"]），map 类型
    • URI_ARGS 获取请求参数（table），map 类型
    • QUERY_STRING 获取请求参数，字符串，示例：a=1&b=2
    • REQUEST_BODY 获取请求 body 部分，map 或字符串类型
    • URI 获取请求原始路径部分(ngx.var.uri)，字符串
    • REQUEST_URI 获取请求 URL，包括参数部分，字符串，示例：/a/b/c?a=1&b=2
    • COOKIES 请求 cookies（table），map 类型
    • REQUEST_ARGS 对象（map）类型。包括 URI_ARGS, REQUEST_BODY, COOKIES 三项值，但最终转化成一维 map
    • REMOTE_ADDR 获取请求端 IP 地址(remote_addr)，字符串
    • HTTP_VERSION 获取 HTTP 协议版本，数值，可选值：2.0, 1.0, 1.1
    • SCORE_THRESHOLD 获取当前风险阀值，数值类型
    • ARGS_COMBINED_SIZE 获取请求参数和请求 body 的字节大小，数值
    • TIME 字符串，格式：“时:分:秒”
    • TIME_EPOCH 获取当前时间戳，精确到秒，数值类型
  • storage 是否跳过缓存，根据 vars 的定义，重新计算待匹配值，存在(not nil)即为 true。因为请求处理过程数据源可能会修改数据源的某些值，导致缓存不一致的情况。需要注意的是这里的缓存，仅仅是存在当前请求内。
  • parse 字符串数组，长度固定为 2，定义从数据源取出待匹配数据集的规则
    • [1] 数组第一项值，字符串，表示从数据源取值的方法，有以下可选值：
      • specific 取出参数指定的值
      • regex 正则匹配，取出所有正则匹配参数的数据集
      • keys 取出数据源中所有的 key，作为数据集
      • values 取出数据源中所有的 value，作为数据集
      • all 将整个数据源作为数据集
    • [2] 数组第二项，字符串，取值方法（函数）的参数，注意，不能缺省，可设为 1，表示无意义
  • unconditional 指示当前规则将一定会被命中
• opts
  • transform 字符串或字符串数组，对上述数据源进行转换的方式，有如下可选值（部分）：
    • uri_decode uri 解码
    • lowercase 转成小写
    • md5 计算 md5
  • nolog 不记录该条规则的命中日志
• logdata 设置规则命中日志字段 logdata 的值，可以使用具体的值或者变量（%{value}），实例："logdata" : "%{TX.anomaly_score}"

规则执行

规则是在 waf.exec 函数内执行的，每个阶段只会执行当前阶段对应的规则集，及规则集里面的规则。需要注意的是 CHAIN 规则的执行逻辑，这种类型的规则会组成一个规则链，规则链内的规则是 and 关系，即规则匹配失败，就会跳过当前整个规则链。规则链是怎么组成的呢？当遇到非 CHAIN 规则时，就会计算成一个规则链。

下面使用 C 代表 CHAIN 规则，X 代表非 CHAIN 规则，有如下规则集：

C C C X X C X

将生成两条规则链：

• CCCX
• CX

日志模块

规则命中后，都会将命中（匹配成功）规则日志记录到日志输出缓存数组，除了 CHAIN 类型的规则，也就是说规则链命中后只会记录一条日志。 规则日志可以在阶段结束时输出，也可以在请求结束时，汇总一起输出。

日志是以 json 格式输出的，包括以下字段：

• timestamp 当前时间戳（秒）
• client 请求客户端地址（remote_addr）
• method 请求方法
• uri 请求路径
• alerts 数组，规则命中记录
  • id 命中的规则 id
  • msg 规则说明
  • match 规则操作符（operator）函数返回的第二个值，这个值非常灵活，可以是字符串，数字或者数组
  • logdata 规则 logdata 配置指定的输出项，比如当前阀值等
• id 唯一的标记当前请求 ID，首次调用函数 waf.new 时随机生成
• id 唯一的标记当前请求 ID，首次调用函数 waf.new 时随机生成
• uri_args map 类型，请求参数；可选，由参数 _event_log_request_arguments 控制
• request_headers map 类型，请求头；可选，由参数 _event_log_request_headers 控制
• request_body map 或字符串 类型，请求体；可选，由参数 _event_log_request_body 控制
• ngx 数组，可选，由参数 _event_log_ngx_vars 指定的变量（ngx.var）值

日志对外输出方式由 _event_log_target 设置，有三种输出方式：

• error 直接使用 ngx.log 输出
• file 输出到参数 _event_log_target_path 指定的文件内
• socket 使用库 resty.log 输出到指定的日志服务器，需要配置相关参数，初始化 log.socket 客户端

特别说明

虽然，系统支持通过函数 load_secrules 直接加载 ModSecurity 规则集文件，但是，最好别这么干，因为自动转换过程交繁琐，不小心就容易出错。

[V1og]

赞👍

[Veitor]

总结很到位。。这rule规则看得我头都晕了