Вы можете загрузить исходный код PCRE с [сайта PCRE](http://www.pcre.org/). Также смотрите этот [пост в блоге](https://www.cryptobells.com/building-openresty-with-pcre-jit/) с пошаговым руководством по сборке OpenResty с библиотекой PCRE с поддержкой JIT.

## Производительность

lua-resty-waf проектировался с учётом эффективности и масштабируемости. Он использует асинхронную модель обработки Nginx и эффективную архитектуру, чтобы обрабатывать каждую транзакцию как можно быстрее. Нагрузочное тестирование показало, что развёртывания, использующие все предоставляемые наборы правил, которые призваны имитировать логику ModSecurity CRS, обрабатывают транзакции примерно за 300–500 микросекунд на запрос; это соответствует производительности, заявленной для [WAF Cloudflare](https://www.cloudflare.com/waf). Тесты проводились на разумном аппаратном стеке (CPU E3-1230, 32 ГБ ОЗУ, 2 x 840 EVO в RAID 0), достигая примерно 15 000 запросов в секунду. Более подробную информацию см. в [этом посте в блоге](http://www.cryptobells.com/freewaf-a-high-performance-scalable-open-web-firewall).

## Установка

Предоставляется простой Makefile:```
# make && sudo make install

lua-resty-waf использует пакетный менеджер [OPM](https://github.com/openresty/opm), доступный в современных дистрибутивах OpenResty. Клиентские инструменты OPM требуют, чтобы инструмент командной строки `resty` был доступен в переменной окружения `PATH` вашей системы.

Обратите внимание, что по умолчанию 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

*По умолчанию*: none

Добавляет дополнительный набор правил для использования при обработке. Это позволяет пользователям создавать собственные наборы правил, не затирая входящий в комплект каталог правил. Наборы правил определяются инлайн в виде 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

*По умолчанию*: none

Определяет один или несколько заголовков 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

Удаляет флаги `oj` из всех вызовов `ngx.re.match`, `ngx.re.find` и `ngx.re.sub`. Это может быть полезно в некоторых случаях, когда используются старые библиотеки PCRE, но вызовет серьёзную деградацию производительности, поэтому использование этой опции настоятельно не рекомендуется; вместо этого пользователям рекомендуется собрать OpenResty с современной библиотекой PCRE, поддерживающей JIT.

*Пример*:```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

*Default*: пусто

Определяет, какие дополнительные переменные из `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

Установите SNI-хост для подключений `lua-resty-logger-socket`.

*Пример*:```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

*По умолчанию*: не задано

Определяет целевой сервер для журналов событий, которые направляются на удалённый сервер.

*Пример*:```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

*По умолчанию*: none

Инструктирует модуль игнорировать указанный идентификатор правила. Обратите внимание, что игнорирование правила в цепочке приведёт к игнорированию всей цепочки, и обработка продолжится со следующего правила после цепочки.

*Пример*:```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 МБ)

Определяет порог длины содержимого, при превышении которого тела ответов не будут обрабатываться. Этот размер тела ответа определяется заголовком ответа 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)
    }
}

Несколько MIME-типов можно добавить, передав таблицу типов в `set_option`.

### res_tid_header

*По умолчанию*: false

Устанавливает HTTP-заголовок `X-Lua-Resty-WAF-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

*Default*: 10000

Настройте (в миллисекундах) тайм-аут для cosocket keepalive-пула для удаленных хостов постоянного хранилища.

*Пример*:```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`, который будет использоваться для хранения данных постоянного хранилища. Эта зона должна быть определена в блоке `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")
    }
}