Sie können die PCRE-Quelle von der [PCRE-Website](http://www.pcre.org/) herunterladen. Siehe auch diesen [Blogbeitrag](https://www.cryptobells.com/building-openresty-with-pcre-jit/) für eine Schritt-für-Schritt-Anleitung zum Erstellen von OpenResty mit einer JIT-fähigen PCRE-Bibliothek.

## Leistung

lua-resty-waf wurde mit Blick auf Effizienz und Skalierbarkeit entwickelt. Es nutzt das asynchrone Verarbeitungsmodell von Nginx und ein effizientes Design, um jede Transaktion so schnell wie möglich zu verarbeiten. Belastungstests haben gezeigt, dass Bereitstellungen, die alle bereitgestellten Regelsätze implementieren, die die Logik hinter dem ModSecurity CRS nachbilden sollen, Transaktionen in etwa 300-500 Mikrosekunden pro Anfrage verarbeiten; das entspricht der Leistung, die von [Cloudflare-WAF](https://www.cloudflare.com/waf) beworben wird. Die Tests wurden auf einem vernünftigen Hardware-Stack (E3-1230 CPU, 32 GB RAM, 2 x 840 EVO in RAID 0) durchgeführt und erreichten maximal etwa 15.000 Anfragen pro Sekunde. Weitere Informationen finden Sie in [diesem Blogbeitrag](http://www.cryptobells.com/freewaf-a-high-performance-scalable-open-web-firewall).

Die Arbeitslast von lua-resty-waf ist fast ausschließlich CPU-gebunden. Der Speicherverbrauch in der Lua-VM (ohne den durch `lua-shared-dict` unterstützten persistenten Speicher) beträgt etwa 2MB.

## Installation

Ein einfaches Makefile wird bereitgestellt:```
# make && sudo make install

lua-resty-waf nutzt den [OPM](https://github.com/openresty/opm)-Paketmanager, der in modernen OpenResty-Distributionen verfügbar ist. Die OPM-Client-Tools setzen voraus, dass das Befehlszeilentool `resty` in der Umgebungsvariable `PATH` Ihres Systems verfügbar ist.

Beachten Sie, dass lua-resty-waf standardmäßig im SIMULATE-Modus läuft, um eine unmittelbare Beeinträchtigung einer Anwendung zu verhindern; Benutzer, die Regelaktionen aktivieren möchten, müssen den Betriebsmodus explizit auf ACTIVE setzen.

## Überblick```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")
        }
    }
}

Zusätzlich kann `load_secrules` ein optionales zweites Argument als Tabelle mit Optionen entgegennehmen, die an verschiedene Übersetzungsfunktionen übergeben werden. Die folgenden Optionen werden erkannt:

* *path*: Definiert einen Dateisystempfad, in dem nach Datendateien für Operatoren wie @pmFromFile gesucht wird. Wenn kein solcher Schlüssel definiert ist, wird das aktuelle Arbeitsverzeichnis (`.`) verwendet.
* *force*: Keinen Fehler ausgeben und nicht abbrechen, wenn das Übersetzen einer Regelvariable fehlschlägt.
* *loose*: Keinen Fehler ausgeben und nicht abbrechen, wenn das Übersetzen einer Regelaktion fehlschlägt.
* *quiet*: Keinen Fehler ausgeben und keine Warnung erzeugen, wenn das Übersetzen einer Regelaktion fehlschlägt.

Diese Funktion kann auch ein drittes Argument als Tabelle entgegennehmen, um Übersetzungsfehler für die spätere Verarbeitung abzufangen. Wenn diese Option nicht vorhanden ist oder keine Tabelle ist, werden Übersetzungsfehler stattdessen im Fehlerprotokoll protokolliert.

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

Führt eine gewisse Vorabberechnung von Regeln und Regelsätzen durch, basierend auf dem, was über die standardmäßig verteilten Regelsätze verfügbar gemacht wurde. Es wird empfohlen, aber nicht verlangt, diese Funktion aufzurufen (wenn dies nicht geschieht, entsteht ein geringer Leistungsnachteil). Diese Funktion sollte niemals außerhalb dieses Geltungsbereichs aufgerufen werden.

*Beispiel*:```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()

Konfigurieren Sie eine Option auf Basis des jeweiligen Geltungsbereichs (per-scope).

*Beispiel*:```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")
}

Beachten Sie, dass das Vorhandensein einer Variablen – wie bei jeder anderen ModSecurity-Regel – keinerlei funktionale Änderung an der WAF-Verarbeitung bewirkt; es liegt in der Verantwortung des Regelautors, die `TX`-Variablen zu verstehen und zu verwenden.

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

Definiert einen Collection-Ausschluss für eine bestimmte Regel.

*Beispiel*:```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()

Schreiben Sie alle Audit-Log-Einträge, die aus der Transaktion generiert wurden. Dies ist nur optional, wenn `exec` in einem `log_by_lua`-Handler aufgerufen wird.

*Beispiel*:```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")
        }
    }
}

### add_ruleset_string

*Standard*: keine

Fügt einen zusätzlichen Regelsatz hinzu, der während der Verarbeitung verwendet wird. Dies ermöglicht Benutzern, benutzerdefinierte Regelsätze zu implementieren, ohne das mitgelieferte Regeln-Verzeichnis zu überschreiben. Regelsätze werden inline als Lua-String definiert, in Form einer übersetzten Regelsatz-JSON-Struktur.

*Beispiel*:```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

*Standard*: keine

Definiert einen oder mehrere Content-Type-Header, die zusätzlich zu den Standard-Content-Types `application/x-www-form-urlencoded` und `multipart/form-data` erlaubt sind. Eine Anfrage, deren Content-Type einem der `allowed_content_types` entspricht, setzt die `REQUEST_BODY`-Sammlung auf einen einzelnen String (anstelle einer Tabelle); eine Anfrage, deren Content-Type keinem dieser Werte entspricht – oder nicht `application/x-www-form-urlencoded` oder `multipart/form-data` – wird abgelehnt.

*Beispiel*:```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

*Standard*: ngx.INFO

Setzt die nginx-Log-Level-Konstante, die für das Debug-Logging verwendet wird.

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

### disable_pcre_optimization

*Default*: false

Entfernt die `oj`-Flags aus allen `ngx.re.match`-, `ngx.re.find`- und `ngx.re.sub`-Aufrufen. Dies kann in einigen Fällen nützlich sein, wenn ältere PCRE-Bibliotheken verwendet werden, führt jedoch zu einer schwerwiegenden Leistungsverschlechterung, sodass die Verwendung dringend abzuraten ist; stattdessen wird den Benutzern empfohlen, OpenResty mit einer modernen, JIT-fähigen PCRE-Bibliothek zu erstellen.

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

Beachte, dass `mode` keinen Einfluss darauf hat, ob eine Transaktion als verändert gilt. Das heißt, wenn eine Regel mit einer `DENY`-Aktion erfüllt wird, aber lua-resty-waf im `SIMULATE`-Modus läuft, gilt die Transaktion weiterhin als verändert, und Regelübereinstimmungen werden protokolliert.

### event_log_buffer_size

*Standard*: 4096

Definiert den Schwellenwert (in Bytes) für den Puffer, der zum Speichern von Ereignisprotokollen verwendet wird. Der Puffer wird geleert, sobald dieser Schwellenwert erreicht ist.

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

### event_log_ngx_vars

*Standard*: leer

Definiert, welche zusätzlichen Variablen aus `ngx.var` in das Log-Ereignis aufgenommen werden. Dies ist eine generische Möglichkeit, den Alert um zusätzlichen Kontext zu erweitern. Der Variablenname wird der Schlüssel des Eintrags unter einem `ngx`-Schlüssel im Log-Eintrag. Wenn die Variable nicht als nginx-Variable vorhanden ist, wird dem Ereignis kein Eintrag hinzugefügt.

*Beispiel*:```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

*Standard*: keine

Definiert ein Intervall in Sekunden, in dem der Ereignisprotokollpuffer regelmäßig geleert wird. Wenn kein Wert konfiguriert ist, wird der Puffer nicht regelmäßig geleert und nur geleert, wenn der Schwellenwert `event_log_buffer_size` erreicht ist. Konfigurieren Sie diese Option für Websites mit sehr geringem Datenverkehr, die über einen langen Zeitraum möglicherweise keine Ereignisprotokolldaten empfangen, um zu verhindern, dass veraltete Daten im Puffer verbleiben.

*Beispiel*:```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

*Standard*: false

Wenn auf `true` gesetzt, enthalten die Logeinträge den Anfragebody unter dem Schlüssel `request_body`.

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

Das resultierende Ereignis enthält diese zusätzlichen Elemente:```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

*Standard*: keine

Legen Sie den SNI-Host für `lua-resty-logger-socket`-Verbindungen fest.

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

### event_log_socket_proto

*Standard*: udp

Definiert, welches IP-Protokoll (TCP oder UDP) beim Versenden von Ereignisprotokollen über einen Remote-Socket verwendet wird. Unabhängig vom Protokoll wird dieselbe Puffer- und wiederkehrende Flush-Logik verwendet.

*Beispiel*:```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")
}

Beachten Sie, dass aufgrund einer Einschränkung der verwendeten Protokollierungsbibliothek nur ein einzelner Ziel-Socket definiert werden kann. Das heißt, Sie dürfen nur ein `socket`-Ziel mit einer bestimmten Host/Port-Kombination konfigurieren; wenn Sie eine zweite Host/Port-Kombination konfigurieren, werden Daten nicht ordnungsgemäß protokolliert.

### event_log_target_host

*Standard*: keine

Definiert den Zielserver für Ereignisprotokolle, die auf einen entfernten Server abzielen.

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

Dieser Pfad muss sich an einem Ort befinden, der vom nginx-Benutzer beschreibbar ist. Beachten Sie, dass die Protokollierung auf der Festplatte naturgemäß zu erheblichen Leistungseinbußen in Umgebungen mit hoher Parallelität führen kann.

### event_log_target_port

*Standard*: keine

Definiert den Zielport für Ereignisprotokolle, die an einen entfernten Server gesendet werden.

*Beispiel*:```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

*Standard*: none

Weist das Modul an, eine angegebene Regel-ID zu ignorieren. Beachten Sie, dass das Ignorieren einer Regel in einer Kette dazu führt, dass die gesamte Kette ignoriert wird, und die Verarbeitung mit der nächsten Regel nach der Kette fortgesetzt wird.

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

### mode

*Standard*: SIMULATE

Legt den Betriebsmodus des Moduls fest. Die Optionen sind ACTIVE, INACTIVE und SIMULATE. Im ACTIVE-Modus werden Regel-Treffer protokolliert und Aktionen ausgeführt. Im SIMULATE-Modus durchläuft lua-resty-waf jede aktivierte Regel und protokolliert Regel-Treffer, führt jedoch die in einem bestimmten Lauf angegebene Aktion nicht aus. Der INACTIVE-Modus verhindert, dass das Modul ausgeführt wird.

Standardmäßig wird SIMULATE ausgewählt, wenn kein Modus explizit festgelegt ist; dies erfordert, dass neue Benutzer das Blockieren aktiv implementieren, indem sie den Modus auf ACTIVE setzen.

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

### process_multipart_body

*Standard* true

Aktiviere die Verarbeitung von multipart/form-data-Anforderungsrumpf (falls vorhanden) mithilfe des Moduls `lua-resty-upload`. In Zukunft könnte lua-resty-waf diese Verarbeitung nutzen, um eine strengere Prüfung von Upload-Bodies durchzuführen; derzeit führt dieses Modul nur minimale Plausibilitätsprüfungen am Anforderungsrumpf durch und protokolliert kein Ereignis, wenn der Anforderungsrumpf ungültig ist. Deaktivieren Sie diese Option, wenn Sie diese Prüfung nicht benötigen oder wenn Fehler im Upstream-Modul Probleme mit HTTP-Uploads verursachen.

*Beispiel*:```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

*Standard*: 1048576 (1 MB)

Definiert die Content-Length-Schwelle, ab der Antworttexte nicht mehr verarbeitet werden. Diese Größe des Antworttexts wird durch den Content-Length-Header der Antwort bestimmt. Wenn dieser Header in der Antwort nicht vorhanden ist, wird der Antworttext niemals verarbeitet.

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

Mehrere MIME-Typen können hinzugefügt werden, indem eine Tabelle von Typen an `set_option` übergeben wird.

### res_tid_header

*Standard*: false

Setzt einen HTTP-Header `X-Lua-Resty-WAF-ID` in der Downstream-Antwort, wobei der Wert die Transaktions-ID ist. Diese ID korreliert mit der Transaktions-ID, die in den Debug-Logs vorhanden ist (falls festgelegt). Dies kann für die Anforderungsverfolgung oder zu Debug-Zwecken nützlich sein.

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

### storage_backend

*Standard*: dict

Definiere eine Engine für die persistente Variablenspeicherung. Derzeit verfügbare Optionen sind *dict* (ngx_lua Shared-Memory-Zone), *memcached* und *redis*.

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

### storage_keepalive_timeout

*Standard*: 10000

Konfiguriert (in Millisekunden) das Timeout für den Cosocket-Keepalive-Pool für entfernte persistente Speicherhosts.

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

### storage_memcached_host

*Standard*: 127.0.0.1

Definieren Sie einen Host, der verwendet werden soll, wenn memcached als persistente Speicher-Engine für Variablen verwendet wird.

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

### storage_redis_host

*Standard*: 127.0.0.1

Definieren Sie einen Host, der verwendet wird, wenn redis als persistenter Variablenspeicher verwendet wird.

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

### storage_zone

*Standard*: none

Definiert das `lua_shared_dict`, das zur Speicherung persistenter Daten verwendet wird. Diese Zone muss im `http{}`-Block der Konfiguration definiert werden.

*Beispiel*:_```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")
    }
}