您可以从 [PCRE 官网](http://www.pcre.org/) 下载 PCRE 源码。另请参阅这篇 [博客文章](https://www.cryptobells.com/building-openresty-with-pcre-jit/)，了解如何构建带有 JIT 支持的 PCRE 库的 OpenResty 的分步指南。

## 性能

lua-resty-waf 的设计以效率和可扩展性为核心。它利用 Nginx 的异步处理模型和高效设计，尽可能快速地处理每个事务。负载测试表明，部署了所有自带规则集（这些规则集旨在模拟 ModSecurity CRS 背后的逻辑）的部署，每个请求的处理时间大约为 300-500 微秒；这相当于 [Cloudflare 的 WAF](https://www.cloudflare.com/waf) 所宣传的性能。测试在合理的硬件配置（E3-1230 CPU、32 GB RAM、2 x 840 EVO 组 RAID 0）上运行，最高达到约每秒 15,000 个请求。更多信息请参阅 [这篇博客文章](http://www.cryptobells.com/freewaf-a-high-performance-scalable-open-web-firewall)。

lua-resty-waf 的工作负载几乎完全受 CPU 限制。Lua VM 中的内存占用（不包括由 `lua-shared-dict` 支持的持久化存储）约为 2MB。

## 安装

提供了一个简单的 Makefile：```
# make && sudo make install

lua-resty-waf 使用 [OPM](https://github.com/openresty/opm) 包管理器，该管理器可在现代 OpenResty 发行版中使用。OPM 客户端工具要求系统的 `PATH` 环境变量中存在 `resty` 命令行工具。

请注意，默认情况下 lua-resty-waf 以 SIMULATE 模式运行，以避免立即影响应用程序；希望启用规则操作的用户必须显式将运行模式设置为 ACTIVE。

## Synopsis```lua
http {
    init_by_lua_block {
        -- use resty.core for performance improvement, see the status note above
        require "resty.core"

        -- require the base module
        local lua_resty_waf = require "resty.waf"

        -- perform some preloading and optimization
        lua_resty_waf.init()
    }

    server {
        location / {
            access_by_lua_block {
                local lua_resty_waf = require "resty.waf"

                local waf = lua_resty_waf:new()

                -- define options that will be inherited across all scopes
                waf:set_option("debug", true)
                waf:set_option("mode", "ACTIVE")

                -- this may be desirable for low-traffic or testing sites
                -- by default, event logs are not written until the buffer is full
                -- for testing, flush the log buffer every 5 seconds
                --
                -- this is only necessary when configuring a remote TCP/UDP
                -- socket server for event logs. otherwise, this is ignored
                waf:set_option("event_log_periodic_flush", 5)

                -- run the firewall
                waf:exec()
            }

            header_filter_by_lua_block {
                local lua_resty_waf = require "resty.waf"

                -- note that options set in previous handlers (in the same scope)
                -- do not need to be set again
                local waf = lua_resty_waf:new()

                waf:exec()
            }

            body_filter_by_lua_block {
                local lua_resty_waf = require "resty.waf"

                local waf = lua_resty_waf:new()

                waf:exec()
            }

            log_by_lua_block {
                local lua_resty_waf = require "resty.waf"

                local waf = lua_resty_waf:new()

                waf:exec()
            }
        }
    }
}

    -- this translates and calculates a ruleset called 'ruleset_name'
    local ok, errs = pcall(function()
        lua_resty_waf.load_secrules("/path/to/secrules/ruleset_name")
    end)

    -- errs is an array-like table
    if errs then
        for i = 1, #errs do
            ngx.log(ngx.ERR, errs[i])
        end
    end
}

server {
    location / {
        access_by_lua_block {
            local lua_resty_waf = require "resty.waf"

            local waf = lua_resty_waf:new()

            -- in order to use the loaded ruleset, it must be added via
            -- the 'add_ruleset' option
            waf:set_option("add_ruleset", "ruleset_name")
        }
    }
}

此外，`load_secrules` 可以接受一个可选的第二个参数，作为传递给各种转换函数的选项表。识别以下选项：

* *path*: 定义用于搜索操作符（如 @pmFromFile）数据文件的文件系统路径。如果未定义此键，则使用当前工作目录（`.`）
* *force*: 在无法转换规则变量时不报错并中止
* *loose*: 在无法转换规则操作时不报错并中止
* *quiet*: 在无法转换规则操作时不报错或警告

该函数还可以接受第三个选项作为表，用于捕获转换错误以供后续处理。如果此选项不存在或不是表，则转换错误将改为记录到错误日志中。

### lua-resty-waf.init()

根据默认分发的规则集所提供的内容，对规则和规则集进行一些预计算。建议（但非必需）调用此函数（不调用将导致轻微的性能损失）。此函数不应在此范围之外调用。

*示例*：```lua
http {
    init_by_lua_block {
        local lua_resty_waf = require "resty.waf"

        lua_resty_waf.init()
    }
}

    local waf = lua_resty_waf:new()
}

### lua-resty-waf:set_option()

按作用域配置选项。

*示例*:```lua
location / {
    access_by_lua_block {
        local lua_resty_waf = require "resty.waf"

        local waf = lua_resty_waf:new()

        -- enable debug logging only for this scope
        waf:set_option("debug", true)
    }
}

    local waf = lua_resty_waf:new()

    waf:set_var("FOO", "bar")
}

请注意，与任何其他 ModSecurity 规则一样，变量的存在并不会对 WAF 处理产生功能上的改变；理解并使用 `TX` 变量是规则编写者的责任。

### lua-resty-waf:sieve_rule()

为给定规则定义集合排除。

*示例*:```lua
location / {
    access_by_lua_block {
        local lua_resty_waf = require "resty.waf"

        local waf = lua_resty_waf:new()

        local sieves = {
            {
                type   = "ARGS",
                elts   = "foo",
                action = "ignore",
            }
        }

        waf:sieve_rule("12345", sieves)
    }
}

    local waf = lua_resty_waf:new()

    -- execute according to access phase collections and rules
    waf:exec()
}

content_by_lua_block {
    local lua_resty_waf = require "waf"

    local waf = lua_resty_waf:new()

    -- execute header_filter rules, passing in a table of additional collections
    -- this assumes the 'request_headers' and 'status' Lua variables were
    -- declared and initialized elsewhere
    local opts = {
        phase = 'header_filter',
        collections = {
            REQUEST_HEADERS = request_headers,
            STATUS = status,
        }
    }

    waf:exec(opts)
}

### lua-resty-waf:write_log_events()

写入从事务中生成的任何审计日志条目。仅当 `exec` 在 `log_by_lua` 处理器中被调用时，此步骤才是可选的。

*示例*:```lua
location / {
    log_by_lua_block {
        local lua_resty_waf = require "resty.waf"

        local waf = lua_resty_waf:new()

        -- write out any event log entries to the
        -- configured target, if applicable
        waf:write_log_events()
    }
}

server {
    location / {
        access_by_lua_block {
            waf:set_option("add_ruleset", "50000_extra_rules")
        }
    }
}

可以通过向 `set_option` 传递一个值表来添加多个规则集。请注意，规则集名称在处理前会进行排序。规则集将按从低到高的排序顺序进行处理。

### add_ruleset_string

*默认*：无

添加一个在处理期间使用的额外规则集。这允许用户实现自定义规则集，而不会覆盖随附的规则目录。规则集以内联 Lua 字符串的形式定义，即转换后的规则集 JSON 结构。

*示例*：```lua
location / {
    access_by_lua_block {
        waf:set_option("add_ruleset_string", "70000_extra_rules", [=[{"access":[{"action":"DENY","id":73,"operator":"REGEX","opts":{},"pattern":"foo","vars":[{"parse":{"values":1},"type":"REQUEST_ARGS"}]}],"body_filter":[],"header_filter":[]}]=])
    }
}

### allowed_content_types

*默认值*: 无

定义了一个或多个允许的 Content-Type 头，除了默认的 Content-Type `application/x-www-form-urlencoded` 和 `multipart/form-data` 之外。当请求的内容类型与 `allowed_content_types` 之一匹配时，`REQUEST_BODY` 集合将被设置为一个字符串（而不是一个表）；当请求的内容类型与这些值或 `application/x-www-form-urlencoded`、`multipart/form-data` 均不匹配时，该请求将被拒绝。

*示例*:```lua
location / {
    access_by_lua_block {
        -- define a single allowed Content-Type value
        waf:set_option("allowed_content_types", "text/xml")

        -- defines multiple allowed Content-Type values
        waf:set_option("allowed_content_types", { "text/html", "text/json", "application/json" })
    }
}

### debug_log_level

*默认*: ngx.INFO

设置用于调试日志记录的 nginx 日志级别常量。

*示例*:```lua
location / {
    access_by_lua_block {
        waf:set_option("debug_log_level", ngx.DEBUG)
    }
}

### disable_pcre_optimization

*默认值*: false

从所有 `ngx.re.match`、`ngx.re.find` 和 `ngx.re.sub` 调用中移除 `oj` 标志。在某些使用较旧 PCRE 库的情况下这可能有用，但会导致严重的性能下降，因此强烈不建议使用；建议用户改用带有现代、支持 JIT 的 PCRE 库来构建 OpenResty。

*示例*:```lua
location / {
    access_by_lua_block {
        waf:set_option("disable_pcre_optimization", true)
    }
}

注意：`mode` 不会影响事务是否被视为已修改。也就是说，如果匹配了带有 `DENY` 操作的规则，但 lua-resty-waf 正在以 `SIMULATE` 模式运行，该事务仍将被视为已修改，并且规则匹配会被记录。

### event_log_buffer_size

*默认值*: 4096

定义用于保存事件日志的缓冲区的阈值大小（以字节为单位）。当达到此阈值时，缓冲区将被刷新。

*示例*:```lua
location / {
    access_by_lua_block {
        -- 8 KB event log message buffer
        waf:set_option("event_log_buffer_size", 8192)
    }
}

### event_log_ngx_vars

*默认值*：空

定义 `ngx.var` 中的哪些额外变量会被写入日志事件。这是一种通用的方式，用于为告警增加额外的上下文。变量名将作为日志条目中 `ngx` 键下条目的键。如果该变量不存在于 nginx 变量中，则不会向事件中添加任何条目。

*示例*：```lua
location / {
    access_by_lua_block {
        waf:set_option("event_log_ngx_vars", "host")
        waf:set_option("event_log_ngx_vars", "request_id")
    }
}

### event_log_periodic_flush

*默认值*: none

定义一个时间间隔（以秒为单位），事件日志缓冲区将按照该间隔定期刷新。如果未配置任何值，缓冲区将不会定期刷新，而只会在达到 `event_log_buffer_size` 阈值时刷新。对于流量极低、可能在很长时间内不会收到任何事件日志数据的站点，请配置此选项，以防止陈旧数据滞留在缓冲区中。

*示例*:```lua
location / {
    access_by_lua_block {
        -- flush the event log buffer every 30 seconds
        waf:set_option("event_log_periodic_flush", 30)
    }
}

### event_log_request_body

*默认*: false

当设置为 true 时，日志条目在 `request_body` 键下包含请求正文。

*示例*:```lua
location / {
    access_by_lua_block {
        waf:set_option("event_log_request_body", true)
    }
}

生成的事件包含这些额外项：```json
{
"request_headers": {
    "accept": "*/*",
    "user-agent": "curl/7.22.0 (x86_64-pc-linux-gnu) libcurl/7.22.0 OpenSSL/1.0.1 zlib/1.2.3.4 libidn/1.23 librtmp/2.3"
}
}

### event_log_ssl_sni_host

*默认*: none

为 `lua-resty-logger-socket` 连接设置 SNI 主机。

*示例*:```lua
location / {
    access_by_lua_block {
        waf:set_option("event_log_ssl_sni_host", "loghost.example.com")
    }
}

### event_log_socket_proto

*默认*: udp

定义通过远程套接字发送事件日志时使用的 IP 协议（TCP 或 UDP）。无论使用哪种协议，都将采用相同的缓冲和定期刷新逻辑。

*示例*:```lua
location / {
    access_by_lua_block {
        -- send logs via TCP
        waf:set_option("event_log_socket_proto", "tcp")
    }
}

    -- send event logs to a local file on disk
    waf:set_option("event_log_target", "file")

    -- send event logs to a remote server
    waf:set_option("event_log_target", "socket")
}

注意，由于所使用的日志库存在限制，只能定义一个目标套接字。也就是说，您只能配置一个具有特定主机/端口组合的 `socket` 目标；如果配置了第二个主机/端口组合，数据将无法正确记录。

### event_log_target_host

*默认值*: none

定义指向远程服务器的事件日志的目标服务器。

*示例*:```lua
location / {
    access_by_lua_block {
        waf:set_option("event_log_target_host", "10.10.10.10")
    }
}

该路径必须位于 nginx 用户可写的位置。请注意，从本质上讲，磁盘日志记录在高并发环境中可能导致显著的性能下降。

### event_log_target_port

*默认值*: 无

定义指向远程服务器的事件日志的目标端口。

*示例*:```lua
location / {
    access_by_lua_block {
        waf:set_option("event_log_target_port", 9001)
    }
}

location / {
    access_by_lua_block {
        local deny_override = function(waf, ctx)
            ngx.log(ngx.INFO, "Overriding DENY action")
            ngx.status = 404
        end

        -- override the DENY action with the function defined above
        waf:set_option("hook_action", "DENY", deny_override)
    }
}

### ignore_rule

*默认值*：无

指示模块忽略指定的规则 ID。请注意，忽略链中的某条规则将导致整条链被忽略，并且处理将继续到该链之后的下一条规则。

*示例*：```lua
location / {
    access_by_lua_block {
        waf:set_option("ignore_rule", 40294)
        waf:set_option("ignore_rule", {40002, 41036})
    }
}

### mode

*默认*: SIMULATE

设置模块的运行模式。可选值为 ACTIVE、INACTIVE 和 SIMULATE。在 ACTIVE 模式下，规则匹配会被记录并执行操作。在 SIMULATE 模式下，lua-resty-waf 会遍历每个已启用的规则并记录规则匹配情况，但不会执行给定运行中指定的操作。INACTIVE 模式会阻止模块运行。

默认情况下，如果没有显式设置模式，则选择 SIMULATE；这要求新用户通过将模式设置为 ACTIVE 来主动实施拦截。

*示例*:```lua
location / {
    access_by_lua_block {
        waf:set_option("mode", "ACTIVE")
    }
}

### process_multipart_body

*默认值* true

启用对 multipart/form-data 请求体（如果存在）的处理，使用 `lua-resty-upload` 模块。将来，lua-resty-waf 可能会使用此处理来对上传请求体执行更严格的检查；目前该模块仅对请求体执行最小限度的健全性检查，并且如果请求体无效，不会记录事件。如果您不需要此检查，或者上游模块中的错误导致 HTTP 上传出现问题，请禁用此选项。

*示例*：```lua
location / {
    access_by_lua_block {
        -- disable processing of multipart/form-data requests
        -- note that the request body will still be sent to the upstream
        waf:set_option("process_multipart_body", false)
    }
}

### res_body_max_size

*默认值*: 1048576 (1 MB)

定义内容长度阈值，超过该阈值的响应体将不会被处理。响应体的大小由 Content-Length 响应头确定。如果响应中不存在该响应头，则响应体将永远不会被处理。

*示例*:```lua
location / {
    access_by_lua_block {
        -- increase the max response size to 2 MB
        waf:set_option("res_body_max_size", 1024 * 1024 * 2)
    }
}

### res_tid_header

*默认值*: false

在下游响应中设置一个 HTTP 头 `X-Lua-Resty-WAF-ID`，其值为事务 ID。该 ID 将与调试日志（如果已设置）中的事务 ID 相关联。这对于请求跟踪或调试目的非常有用。

*示例*:```lua
location / {
    access_by_lua_block {
        waf:set_option("res_tid_header", true)
    }
}

### storage_backend

*默认*: dict

定义用于持久变量存储的引擎。当前可用的选项有 *dict*（ngx_lua 共享内存区）、*memcached* 和 *redis*。

*示例*:```lua
location / {
    acccess_by_lua_block {
        waf:set_option("storage_backend", "memcached")
    }
}

### storage_keepalive_timeout

*默认值*: 10000

配置远程持久化存储主机的 cosocket 保持连接池的超时时间（以毫秒为单位）。

*示例*:```lua
location / {
    acccess_by_lua_block {
        waf:set_option("storage_keepalive_timeout", 30000)
    }
}

### storage_memcached_host

*默认值*: 127.0.0.1

定义当使用 memcached 作为持久变量存储引擎时要使用的主机。

*示例*:```lua
location / {
    acccess_by_lua_block {
        waf:set_option("storage_memcached_host", "10.10.10.10")
    }
}

### storage_redis_host

*默认值*: 127.0.0.1

定义在使用 redis 作为持久化变量存储引擎时要使用的主机。

*示例*:```lua
location / {
    acccess_by_lua_block {
        waf:set_option("storage_redis_host", "10.10.10.10")
    }
}

### storage_zone

*默认值*: none

定义用于保存持久化存储数据的 `lua_shared_dict`。该 zone 必须在配置的 `http{}` 块中定义。

*示例*:_```lua
http {
    -- define a 64M shared memory zone to hold persistent storage data
    lua_shared_dict persistent_storage 64m;
}

location / {
    access_by_lua_block {
        waf:set_option("storage_zone", "persistent_storage")
    }
}