From 81616871e976af5722f463ae98dba1054f6d7d5e Mon Sep 17 00:00:00 2001
From: potatso <bangzhiliang@gmail.com>
Date: Wed, 5 Jul 2023 11:21:53 +0800
Subject: [PATCH] release

---
 README.md                         | 80 +++++++++++++++++--------------
 README_CN.md                      | 46 ++++++++++++++++++
 lua-resty-coraza-1.0.0-0.rockspec | 24 ++++++++++
 3 files changed, 115 insertions(+), 35 deletions(-)
 create mode 100644 README_CN.md
 create mode 100644 lua-resty-coraza-1.0.0-0.rockspec

diff --git a/README.md b/README.md
index 35dc62e..05b6c88 100644
--- a/README.md
+++ b/README.md
@@ -1,46 +1,56 @@
-1 . ffi 调用 C动态库中函数时，如果函数时有类似 char** （char的指针的指针）类型的的参数时，lua 代码中，按如下方式申明变量，并分配好内存空间：
+# lua-resty-coraza
 
-local initValue = "这是初始值"
-local inLen = string.len(initValue)
-local inStr  = ffi.new("char[?]", inLen + 2, initValue)
-local inPtr  = ffi.new("char*[1]", inStr);
--- 这里的 inPtr 就可以传入 C 函数中了，对应是参数类型应是 char**, 如果有C函数中对此参数有变更，
--- 则可以在lua中获取到返回值
+## Name
 
-2. 如何集成到openresty里？
+Lua implementation of the [libcoraza](https://github.com/corazawaf/libcoraza) for modsecurity Web Application Firewall.
 
-因为cgo的多线程会死锁 https://www.v2ex.com/t/568117
-所以必须在init_worker阶段加载cgo代码 必须这样配置
 
+## Installation
+
+```bash
+luarocks install lua-resty-t1k
 ```
-    init_worker_by_lua_block{
-            local coraza = require "resty.coraza"
-            coraza.do_init()
-            coraza.rules_add([[SecRule REQUEST_HEADERS:User-Agent "Mozilla" "phase:1, id:3,drop,status:452,log,msg:'Blocked User-Agent'"]])
+
+## Synopsis
+
+```lua
+
+init_worker_by_lua_block{
+    coraza = require "resty.coraza"
+    waf = coraza.create_waf()
+    -- add rule from file
+    coraza.rules_add_file(waf, "%s/t/coraza.conf")
+
+    -- your corerule set, add rule from directive
+    coraza.rules_add(waf, "Include %s/t/coreruleset/crs-setup.conf.example")
+    coraza.rules_add(waf, "Include %s/t/coreruleset/rules/*.conf")
+}
+
+location /t {
+    access_by_lua_block {
+        coraza.do_create_transaction(waf)
+        coraza.do_access_filter()
+        coraza.do_interrupt()
     }
-```
-其他一切正常
-```
-    location /t {
-        access_by_lua_block {
-            local coraza = require "resty.coraza"
-            coraza.do_access_filter()
-        }
 
-        header_filter_by_lua_block{
-            local coraza = require "resty.coraza"
-            coraza.do_header_filter()
-        }
+    content_by_lua_block {
+        ngx.say("passed")
+    }
 
-        log_by_lua_block{
-            local coraza = require "resty.coraza"
-            coraza.do_free()
-        }
+    header_filter_by_lua_block{
+        coraza.do_header_filter()
+        coraza.do_interrupt()
+    }
+
+    log_by_lua_block{
+        coraza.do_log()
+        coraza.do_free_transaction()
+    }
+}
 ```
 
-3. 因为在调用go的时候，go并没有转换`char *`到go中string，只是单纯做了类型转换。也就是说，在调用期间一定要保证lua字符串不会被free，不然go中很有可能产生UAF漏洞。但是好在lua vm会自动管理内存，这点不必担心
+if you need more log for debug, please turn on the debug on nginx.
 
-4. 编译好的动态共享库，macos放到`/usr/local/lib/libcoraza.dylib` linux同样也在`/usr/local/lib/libcoraza.so`
-
-5. 如何测试？
-在根目录下，执行`prove -t` 就行。具体请参考test::nginx测试框架，记得在测试之前，添加openresty的环境变量，例如`export PATH=/opt/homebrew/Cellar/openresty/1.21.4.1_2/nginx/sbin:$PATH`
\ No newline at end of file
+```
+error_log logs/error.log debug;
+```
\ No newline at end of file
diff --git a/README_CN.md b/README_CN.md
new file mode 100644
index 0000000..35dc62e
--- /dev/null
+++ b/README_CN.md
@@ -0,0 +1,46 @@
+1 . ffi 调用 C动态库中函数时，如果函数时有类似 char** （char的指针的指针）类型的的参数时，lua 代码中，按如下方式申明变量，并分配好内存空间：
+
+local initValue = "这是初始值"
+local inLen = string.len(initValue)
+local inStr  = ffi.new("char[?]", inLen + 2, initValue)
+local inPtr  = ffi.new("char*[1]", inStr);
+-- 这里的 inPtr 就可以传入 C 函数中了，对应是参数类型应是 char**, 如果有C函数中对此参数有变更，
+-- 则可以在lua中获取到返回值
+
+2. 如何集成到openresty里？
+
+因为cgo的多线程会死锁 https://www.v2ex.com/t/568117
+所以必须在init_worker阶段加载cgo代码 必须这样配置
+
+```
+    init_worker_by_lua_block{
+            local coraza = require "resty.coraza"
+            coraza.do_init()
+            coraza.rules_add([[SecRule REQUEST_HEADERS:User-Agent "Mozilla" "phase:1, id:3,drop,status:452,log,msg:'Blocked User-Agent'"]])
+    }
+```
+其他一切正常
+```
+    location /t {
+        access_by_lua_block {
+            local coraza = require "resty.coraza"
+            coraza.do_access_filter()
+        }
+
+        header_filter_by_lua_block{
+            local coraza = require "resty.coraza"
+            coraza.do_header_filter()
+        }
+
+        log_by_lua_block{
+            local coraza = require "resty.coraza"
+            coraza.do_free()
+        }
+```
+
+3. 因为在调用go的时候，go并没有转换`char *`到go中string，只是单纯做了类型转换。也就是说，在调用期间一定要保证lua字符串不会被free，不然go中很有可能产生UAF漏洞。但是好在lua vm会自动管理内存，这点不必担心
+
+4. 编译好的动态共享库，macos放到`/usr/local/lib/libcoraza.dylib` linux同样也在`/usr/local/lib/libcoraza.so`
+
+5. 如何测试？
+在根目录下，执行`prove -t` 就行。具体请参考test::nginx测试框架，记得在测试之前，添加openresty的环境变量，例如`export PATH=/opt/homebrew/Cellar/openresty/1.21.4.1_2/nginx/sbin:$PATH`
\ No newline at end of file
diff --git a/lua-resty-coraza-1.0.0-0.rockspec b/lua-resty-coraza-1.0.0-0.rockspec
new file mode 100644
index 0000000..893c678
--- /dev/null
+++ b/lua-resty-coraza-1.0.0-0.rockspec
@@ -0,0 +1,24 @@
+package = "lua-resty-coraza"
+version = "1.0.0-0"
+source = {
+    url = "https://github.com/potats0/lua-resty-coraza",
+    tag = "v1.0.0"
+}
+
+description = {
+    summary = "Lua implementation of the libcoraza for modsecurity",
+    homepage = "https://github.com/potats0/lua-resty-coraza",
+    license = "Apache License 2.0",
+    maintainer = "potats0 <bangzhiliang@gmail.com>"
+}
+
+build = {
+   type = "builtin",
+   modules = {
+    ["resty.coraza"] = "lib/resty/coraza.lua",
+    ["resty.coraza.coraza"] = "lib/resty/coraza/coraza.lua",
+    ["resty.coraza.constants"] = "lib/resty/coraza/constants.lua",
+    ["resty.coraza.log"] = "lib/resty/coraza/log.lua",
+    ["resty.coraza.request"] = "lib/resty/coraza/request.lua",
+   },
+}
\ No newline at end of file