يمكنك تنزيل كود مصدر 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). أُجريت الاختبارات على مجموعة أجهزة معقولة (معالج E3-1230، ذاكرة وصول عشوائي 32 جيجابايت، قرصا 840 EVO في RAID 0)، وبلغت الذروة حوالي 15000 طلب في الثانية. راجع [هذه التدوينة](http://www.cryptobells.com/freewaf-a-high-performance-scalable-open-web-firewall) لمزيد من المعلومات.

عبء عمل lua-resty-waf مرتبط بوحدة المعالجة المركزية بشكل شبه حصري. حجم الذاكرة المستهلكة في جهاز Lua الافتراضي (باستثناء التخزين الدائم المدعوم بـ `lua-shared-dict`) يبلغ حوالي 2 ميجابايت.

## التثبيت

يتم توفير Makefile بسيط:```
# make && sudo make install

تستخدم lua-resty-waf مدير الحزم [OPM](https://github.com/openresty/opm)، المتاح في توزيعات OpenResty الحديثة. تتطلب أدوات OPM الخاصة بالعميل توفر أداة سطر الأوامر `resty` في متغير البيئة `PATH` في نظامك.

لاحظ أنه افتراضيًا يعمل lua-resty-waf في وضع SIMULATE، لمنع التأثير الفوري على التطبيق؛ يجب على المستخدمين الذين يرغبون في تفعيل إجراءات القواعد ضبط وضع التشغيل صراحةً إلى ACTIVE.

## ملخص```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

*الافتراضي*: فارغ

يحدد المتغيرات الإضافية من `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

*الافتراضي*: لا شيء

يوجّه الوحدة إلى تجاهل معرف قاعدة محدد. لاحظ أن تجاهل قاعدة داخل سلسلة يؤدي إلى تجاهل السلسلة بأكملها، وستستمر المعالجة إلى القاعدة التالية بعد السلسلة.

*مثال*:```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

*الافتراضي*: 10000

اضبط المهلة (بالمللي ثانية) لمجمع keepalive الخاص بـ 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` الذي سيُستخدم للاحتفاظ ببيانات التخزين الدائم. يجب تعريف هذه المنطقة في كتلة `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")
    }
}