免費(fèi)AI編程助手
README.md
2018-05-22 10:44 更新
Name
====
OpenWAF
第一個全方位開源的Web應(yīng)用防護(hù)系統(tǒng)（WAF），更全面的防護(hù)功能，更多樣的防護(hù)策略
Table of Contents
=================
* [Name](#name)
* [Version](#version)
* [Synopsis](#synopsis)
* [Description](#description)
* [Installation](#installation)
* [Docker](#docker)
* [Community](#community)
* [English Mailing List](#english-mailing-list)
* [Chinese Mailing List](#chinese-mailing-list)
* [Personal QQ Mail](#personal-qq-mail)
* [Bugs and Patches](#bugs-and-patches)
* [TODO](#todo)
* [Changes](#changes)
* [Copyright and License](#copyright-and-license)
* [Modules Configuration Directives](#modules-configuration-directives)
* [Nginx Variables](#nginx-variables)
* [SecRules](#secrules)
* [Variables](#variables)
* [Transformation Functions](#transformation-functions)
* [Operators](#operators)
* [Others](#others)
Version
=======
This document describes OpenWAF v0.0.3.170103_beta released on 03 Jan 2017.
Docker Version
1. titansec/openwaf:0.0.1.161130_beta
??SHA: 596dee9d2b9ce44d59dc445141f72b3607f9fbe6
??https://github.com/titansec/OpenWAF/tree/596dee9d2b9ce44d59dc445141f72b3607f9fbe6
2. titansec/openwaf:0.0.3.170103_beta(titansec/openwaf:latest)
??SHA: 28ce1556250301f26f31b46d9cd9dde5a3b3f03f
??https://github.com/titansec/OpenWAF/tree/28ce1556250301f26f31b46d9cd9dde5a3b3f03f
Synopsis
========
```nginx
#nginx.conf
lua_package_path '/twaf/?.lua;;';
init_by_lua_file /twaf/app/twaf_init.lua;
lua_shared_dict twaf_shm 50m;
upstream test {
server 0.0.0.1; #just an invalid address as a place holder
balancer_by_lua_file twaf_balancer.lua;
}
server {
listen 443 ssl;
server_name _;
ssl_certificate_by_lua_file twaf_ssl_cert.lua;
rewrite_by_lua_file /twaf/app/twaf_rewrite.lua;
access_by_lua_file /twaf/app/twaf_access.lua;
header_filter_by_lua_file /twaf/app/twaf_header_filter.lua;
body_filter_by_lua_file /twaf/app/twaf_body_filter.lua
log_by_lua_file /twaf/app/twaf_log.lua;
set $twaf_https 1;
set $twaf_upstream_server "";
ssl_certificate nginx.crt;
ssl_certificate_key nginx.key;
location / {
lua_need_request_body on;
proxy_pass $twaf_upstream_server;
}
}
server {
listen 80;
server_name _;
rewrite_by_lua_file /twaf/app/twaf_rewrite.lua;
access_by_lua_file /twaf/app/twaf_access.lua;
header_filter_by_lua_file /twaf/app/twaf_header_filter.lua;
body_filter_by_lua_file /twaf/app/twaf_body_filter.lua
log_by_lua_file /twaf/app/twaf_log.lua;
set $twaf_upstream_server "";
location / {
lua_need_request_body on;
proxy_pass $twaf_upstream_server;
}
}
```
```json
#default_config-json
#main_safe_policy-json
```
[Back to TOC](#table-of-contents)
Description
===========
OpenWAF是第一個全方位開源的Web應(yīng)用防護(hù)系統(tǒng)（WAF），他基于nginx_lua API分析HTTP請求信息。OpenWAF由行為分析引擎和規(guī)則引擎兩大功能引擎構(gòu)成。其中規(guī)則引擎主要對單個請求進(jìn)行分析，行為分析引擎主要負(fù)責(zé)跨請求信息追蹤。
規(guī)則引擎的啟發(fā)來自[modsecurity](https://github.com/SpiderLabs/ModSecurity/wiki/Reference-Manual)及[freewaf(lua-resty-waf)](https://github.com/p0pr0ck5/lua-resty-waf)，將ModSecurity的規(guī)則機(jī)制用lua實(shí)現(xiàn)?；谝?guī)則引擎可以進(jìn)行協(xié)議規(guī)范，自動工具，注入攻擊，跨站攻擊，信息泄露，異常請求等安全防護(hù)，支持動態(tài)添加規(guī)則，及時修補(bǔ)漏洞。
行為分析引擎包含基于頻率的模糊識別，防惡意爬蟲，人機(jī)識別等防探測模塊，防CSRF，防CC，防提權(quán)，文件上傳防護(hù)等防攻擊模塊，cookie防篡改，防盜鏈，自定義響應(yīng)頭，攻擊響應(yīng)頁面等防信息泄露模塊。
除了兩大引擎之外，還包含統(tǒng)計(jì)，日志，攻擊響應(yīng)頁面，接入規(guī)則等基礎(chǔ)模塊。除了已有的功能模塊，OpenWAF還支持動態(tài)修改配置，
動態(tài)添加第三方模塊，使得在不重啟引擎中斷業(yè)務(wù)的條件下，升級防護(hù)。
OpenWAF支持將上述功能封裝為策略，不同的web application應(yīng)用不同的策略來防護(hù)。將來還會打造云平臺，策略還可分享供他人參考。
基礎(chǔ)模塊如下:
* [靜態(tài)配置管理器 openwaf_conf](https://github.com/titansec/openwaf_conf)
* [日志 openwaf_log](https://github.com/titansec/openwaf_log)
* [統(tǒng)計(jì) openwaf_reqstat](https://github.com/titansec/openwaf_reqstat)
* [核心層 openwaf_core](https://github.com/titansec/openwaf_core)
* [接入規(guī)則 openwaf_access_rule](https://github.com/titansec/openwaf_access_rule)
功能模塊如下:
* [規(guī)則引擎 openwaf_rule_engine](https://github.com/titansec/openwaf_rule_engine)
* [攻擊響應(yīng)頁面 openwaf_attack_response](https://github.com/titansec/openwaf_attack_response)
* [API openwaf_api](https://github.com/titansec/openwaf_api)
* [防惡意爬蟲 openwaf_anti_mal_crawler](https://github.com/titansec/openwaf_anti_mal_crawler)
詳細(xì)配置文檔及示例請看上述各模塊文檔
[Back to TOC](#table-of-contents)
Installation
============
若用[docker安裝](#docker)，可省略步驟1-3
```
1. 下載openresty
詳見 https://openresty.org/en/installation.html
1.1 cd /opt
1.2 wget -c https://openresty.org/download/openresty-1.11.2.1.tar.gz
1.3 tar -xzvf openresty-1.11.2.1.tar.gz
2. 安裝OpenWAF
2.1 cd /opt
2.2 獲取OpenWAF源文件
git clone https://github.com/titansec/OpenWAF.git
2.3 移動配置文件
mv /opt/OpenWAF/lib/openresty/ngx_openwaf.conf /etc
2.4 覆蓋openresty的configure文件
mv /opt/OpenWAF/lib/openresty/configure /opt/openresty-1.11.2.1
2.5 移動第三方模塊至openresty中
mv /opt/OpenWAF/lib/openresty/* /opt/openresty-1.11.2.1/bundle/
2.6 刪除OpenWAF/lib/openresty目錄
rm -rf /opt/OpenWAF/lib/openresty
3. 編譯openresty
3.1 cd /opt/openresty-1.11.2.1/
3.2 ./configure --with-pcre-jit --with-ipv6 \
--with-http_stub_status_module \
--with-http_ssl_module \
--with-http_realip_module \
--with-http_sub_module
3.3 make && make install
4. 編輯配置文件
4.1 接入規(guī)則
vi /opt/OpenWAF/conf/twaf_access_rule.json
編輯域名，后端服務(wù)器地址等信息
4.2 日志服務(wù)器
vi /opt/OpenWAF/conf/twaf_default_conf.json
配置twaf_log日志接收服務(wù)器地址
5. 啟動引擎
/usr/local/openresty/nginx/sbin/nginx -c /etc/ngx_openwaf.conf
Problems
1. nginx:[emerg] at least OpenSSL 1.0.2e required but found OpenSSL xxx
更新OpenSSL版本至1.0.2e以上即可
如：wget -c http://www.openssl.org/source/openssl-1.0.2h.tar.gz
./config
make && make install
PS:
1. 查看當(dāng)前openssl版本命令： openssl version
2. 若更新openssl后，版本未變，請?jiān)斂磆ttp://www.cnblogs.com/songqingbo/p/5464620.html
3. 若依然提示版本問題，編譯openresty時帶上--with-openssl=/path/to/openssl-xxx/
2. 提示找不到GeoIP.h
apt-get install libgeoip-dev
3. 提示找不到swig
apt-get install swig
4. 提示PCRE不支持JIT
編譯pcre時，帶上--enable-jit參數(shù)
```
[Back to TOC](#table-of-contents)
Docker
======
```
1. pull docker images from repository
docker pull titansec/openwaf
2. start-up docker
2.1 docker run, named openwaf
docker run -d -p 22:22 -p 80:80 -p 443:443 --name openwaf titansec/openwaf
2.2 enter openwaf
docker exec -it openwaf /bin/bash
3. edit config
3.1 edit access rule
vi /opt/OpenWAF/conf/twaf_access_rule.json
3.2 edit log server addr
vi /opt/OpenWAF/conf/twaf_default_conf.json
4. start-up OpenWAF
/usr/local/openresty/nginx/sbin/nginx -c /etc/ngx_openwaf.conf
PS:
#add bridge address, e.g. 192.168.39.12
pipework br0 ContainerName ip/gateway
如：
pipework br0 openwaf 192.168.39.12/24@192.168.39.253
Problems
1. pipework: command not found
git clone https://github.com/jpetazzo/pipework.git
cp pipework/pipework /usr/local/bin/
2. Warning: arping not found; interface may not be immediately reachable
apt-get install arping
```
[Back to TOC](#table-of-contents)
Community
=========
English Mailing List
--------------------
The [OpenWAF-en](https://groups.google.com/group/openwaf-en) mailing list is for English speakers.
Chinese Mailing List
--------------------
The [OpenWAF-cn](https://groups.google.com/group/openwaf-cn) mailing list is for Chinese speakers.
Personal QQ Mail
----------------
290557551@qq.com
QQ Group
---------
579790127
[Back to TOC](#table-of-contents)
Bugs and Patches
================
Please submit bug reports, wishlists, or patches by
1. creating a ticket on the [GitHub Issue Tracker](https://github.com/titansec/OpenWAF/issues),
1. or posting to the [OpenWAF community](#community).
[Back to TOC](#table-of-contents)
TODO
====
* 01. 上傳人機(jī)識別模塊
* 02. 上傳防盜鏈模塊
* 03. 上傳防CC模塊
* 04. 上傳cookie防篡改模塊
* 05. 上傳基于頻率的模糊識別防探測模塊
* 06. 上傳WebShell上傳防護(hù)模塊
* 07. 上傳防CSRF模塊
* 08. 提供頁面體驗(yàn)OpenWAF防護(hù)功能
* 09. 放開動態(tài)配置規(guī)則引擎API
* 10. 放開動態(tài)配置行為分析引擎API
[Back to TOC](#table-of-contents)
Changes
=======
Time: 2016/12/05
Version: v0.0.2.161205_beta
??1. New Module - twaf_attack_response
????Return Custom response page When the request is rejected by OpenWAF
??2. Api - api/stat[/policy_uuid]
????Show statistical infomation
Time: 2016/12/05
Version: v0.0.1.161130_beta
??1. Docker
????build OpenWAF with docker
Time: 2016/12/05
Version: v0.0.1.161012_beta
??1. log module
????Send tcp/udp log
??2. reqstat module
????Statistics of request infomation
??3. access rule
????Publish applications
??4. rule engine
????Access Control
[Back to TOC](#table-of-contents)
Copyright and License
=====================
This module is licensed under the BSD license.
Copyright (C) 2016-2016, by Jian "Miracle" Qi (齊健) , Titan Co.Ltd.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
[Back to TOC](#table-of-contents)
Modules Configuration Directives
================================
* [twaf_access_rule](#twaf_access_rule)
* [twaf_anti_hotlink](#twaf_anti_hotlink)
* [twaf_anti_mal_crawler](#twaf_anti_mal_crawler)
* [twaf_reqstat](#twaf_reqstat)
* [twaf_log](#twaf_log)
* [twaf_secrules](#twaf_secrules)
[Back to TOC](#table-of-contents)
twaf_access_rule
----------------
```txt
{
"twaf_access_rule": [
"rules": [ -- 注意先后順序
{
"client_ssl": false, -- 客戶端認(rèn)證的開關(guān)，與ngx_ssl組成雙向認(rèn)證
"client_ssl_cert": "path", -- 客戶端認(rèn)證所需PEM證書地址
"ngx_ssl": false, -- nginx認(rèn)證的開關(guān)
"ngx_ssl_cert": "path", -- nginx認(rèn)證所需PEM證書地址
"ngx_ssl_key": "path", -- nginx認(rèn)證所需PEM私鑰地址
"host": "^1\\.1\\.1\\.1$", -- 域名，正則匹配
"port": 80, -- 端口號（缺省80）
"path": "\/", -- 路徑，正則匹配
"server_ssl": false, -- 后端服務(wù)器ssl開關(guān)
"forward": "server_5", -- 后端服務(wù)器upstream名稱
"forward_addr": "1.1.1.2", -- 后端服務(wù)器ip地址
"forward_port": "8080", -- 后端服務(wù)器端口號（缺省80）
"uuid": "access_567b067ff2060", -- 用來標(biāo)記此規(guī)則的uuid
"policy": "policy_uuid" -- 安全策略ID
}
]
}
}
```
###rules
**syntax:** *"rules": table*
**default:** *none*
**context:** *twaf_access_rule*
table類型，接入規(guī)則，順序匹配
###client_ssl
**syntax:** *"client_ssl": true|false*
**default:** *false*
**context:** *twaf_access_rule*
客戶端認(rèn)證開關(guān)，與ngx_ssl組成雙向認(rèn)證，默認(rèn)false
###client_ssl_cert
**syntax:** *"client_ssl_cert": "path"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，客戶端認(rèn)證所需PEM證書地址，目前僅支持絕對地址
###ngx_ssl
**syntax:** *"ngx_ssl": true|false*
**default:** *false*
**context:** *twaf_access_rule*
boolean類型，服務(wù)器端(nginx)認(rèn)證開關(guān)，與client_ssl組成雙向認(rèn)證，默認(rèn)關(guān)閉
###ngx_ssl_cert
**syntax:** *"ngx_ssl_cert": "path"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，服務(wù)器端(nginx)認(rèn)證所需PEM證書地址，目前僅支持絕對地址
###ngx_ssl_key
**syntax:** *"ngx_ssl_key": "path"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，服務(wù)器端(nginx)認(rèn)證所需PEM私鑰地址，目前僅支持絕對地址
###host
**syntax:** *"host": "ip|domain name regex"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，域名，正則匹配
例如:
```
"host": "^1\\.1\\.1\\.1$"
"host": "test\\.com"
"host": "^.*\\.com$"
"host": "www.baidu.com"
```
###port
**syntax:** *"port": number*
**default:** *80*
**context:** *twaf_access_rule*
number類型，端口號
###path
**syntax:** *"path": "regex"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，路徑，正則匹配
例如:
```
"path": "/"
"path": "/images"
"path": "/[a|b]test"
```
###server_ssl
**syntax:** *"server_ssl": true|false*
**default:** *false*
**context:** *twaf_access_rule*
boolean類型，OpenWAF向后端服務(wù)器連接的ssl開關(guān)
例如:
```
upstream test {
server 1.1.1.1;
}
http {
server {
listen 80;
server_name _;
location / {
#server_ssl為true，相當(dāng)于proxy_pass后為https
proxy_pass https://test;
#server_ssl為false，相當(dāng)于proxy_pass后為http
#proxy_pass http://test;
}
}
}
```
###forward
**syntax:** *"forward": "upstream_uuid"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，forward表示后端服務(wù)器的uuid，即upstream的名稱
```
#如：forward值為test
upstream test {
server 1.1.1.1;
}
```
###forward_addr
**syntax:** *"forward_addr": "ip"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，forward_addr表示后端服務(wù)器的ip地址（TODO：支持域名）
```
upstream test {
#如：forward_addr值為1.1.1.1
server 1.1.1.1;
}
```
###forward_port
**syntax:** *"forward_port": port*
**default:** *80*
**context:** *twaf_access_rule*
number類型，forward_port表示后端服務(wù)器端口號，默認(rèn)80
```
upstream test {
#如：forward_port值為50001
server 1.1.1.1:50001;
}
```
###uuid
**syntax:** *"uuid": "string"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，接入規(guī)則的唯一標(biāo)識
###policy
**syntax:** *"policy": "policy_uuid"*
**default:** *none*
**context:** *twaf_access_rule*
string類型，滿足此接入規(guī)則的請求，所使用安全策略的uuid
[Back to twaf_access_rule](#twaf_access_rule)
[Back to TOC](#table-of-contents)
twaf_anti_hotlink
-----------------
```json
{
"twaf_anti_hotlink":{
"state":false,
"log_state":true,
"event_id":"110001",
"event_severity":"medium",
"ct_state":false,
"action_meta":403,
"action":"DENY",
"mode":"referer",
"allow_noreferer":true,
"cookie_name":"TWAF_AH",
"uri_ext":["javascript", "css", "html", ""]
}
}
```
###state
**syntax:** *"state": true|false|"$dynamic_state"*
**default:** *false*
**context:** *twaf_anti_hotlink*
###log_state
**syntax:** *"log_state": true|false|"$dynamic_state"*
**default:** *true*
**context:** *twaf_anti_hotlink*
###ct_state
**syntax:** *"ct_state": true|false|"$dynamic_state"*
**default:** *false*
**context:** *twaf_anti_hotlink*
###event_id
**syntax:** *"event_id": "string"*
**default:** *"110001"*
**context:** *twaf_anti_hotlink*
###event_severity
**syntax:** *"event_severity": "string"*
**default:** *"medium"*
**context:** *twaf_anti_hotlink*
###action
**syntax:** *"action": "string"*
**default:** *"DENY"*
**context:** *twaf_anti_hotlink*
###action_meta
**syntax:** *"action_meta": "string"|number*
**default:** *403*
**context:** *twaf_anti_hotlink*
###mode
**syntax:** *"mode": "string"*
**default:** *"referer"*
**context:** *twaf_anti_hotlink*
###allow_noreferer
**syntax:** *"allow_noreferer": true|false*
**default:** *true*
**context:** *twaf_anti_hotlink*
###cookie_name
**syntax:** *"cookie_name": "string"*
**default:** *TWAF_AH*
**context:** *twaf_anti_hotlink*
cookie_name表示盜鏈模塊發(fā)送COOKIE的名稱，默認(rèn)"TWAF_AH"
此配置只有mode為cookie模式下生效
###uri_ext
**syntax:** *"uri_ext": array|exten|"all"*
**default:** *none*
**context:** *twaf_anti_hotlink*
uri_ext表示對哪些資源進(jìn)行盜鏈防護(hù)
```
#對html類型資源進(jìn)行盜鏈防護(hù)
"uri_ext": "html"
#對未知類型資源進(jìn)行盜鏈防護(hù)，nginx無法解析出資源類型時為空字符串
"uri_ext": ""
#對html、css及未知類型資源進(jìn)行盜鏈防護(hù)
"uri_ext": ["html", "css", ""]
#對所有資源進(jìn)行盜鏈防護(hù)
"uri_ext": "all"
```
[Back to twaf_anti_hotlink](#twaf_anti_hotlink)
[Back to TOC](#table-of-contents)
twaf_anti_mal_crawler
---------------------
```json
{
"state":false,
"cookie_state":true,
"log_state":true,
"event_id":"710001",
"event_severity":"high",
"force_scan_robots_state":false,
"shared_dict_key":["remote_addr", "http_user_agent"],
"timeout":300,
"crawler_cookie_name":"crawler",
"mal_cookie_name":"mcrawler",
"trap_uri":"/abc/abc.html",
"trap_args":"id=1",
"action":"DENY",
"action_meta":403
}
```
###state
**syntax:** *state true|false|$dynamic_state*
**default:** *false*
**context:** *twaf_anti_mal_crawler*
模塊開關(guān)，默認(rèn)false（關(guān)閉），支持動態(tài)開關(guān)
[Back to MCD](#twaf_anti_mal_crawler)
###cookie_state
**syntax:** *cookie_state true|false|$dynamic_state*
**default:** *true*
**context:** *twaf_anti_mal_crawler*
是否發(fā)送cookie,默認(rèn)true（發(fā)送），支持動態(tài)開關(guān)
[Back to MCD](#twaf_anti_mal_crawler)
###log_state
**syntax:** *log_state true|false|$dynamic_state*
**default:** *true*
**context:** *twaf_anti_mal_crawler*
安全日志開關(guān)， 默認(rèn)true（記錄），支持動態(tài)開關(guān)
[Back to MCD](#twaf_anti_mal_crawler)
###event_id
**syntax:** *event_id *
**default:** *"710001"*
**context:** *twaf_anti_mal_crawler*
記錄安全日志時，顯示的事件ID
[Back to MCD](#twaf_anti_mal_crawler)
###event_severity
**syntax:** *event_severity critical|high|medium|low*
**default:** *high*
**context:** *twaf_anti_mal_crawler*
記錄安全日志時，顯示的事件等級
[Back to twaf_anti_mal_crawler](#twaf_anti_mal_crawler)
[Back to TOC](#table-of-contents)
twaf_reqstat
------------
```json
"twaf_reqstat": {
"state":true,
"safe_state":true,
"access_state":true,
"upstream_state":true,
"shared_dict_name":"twaf_reqshm"
}
```
###state
**syntax:** *state true|false|$dynamic_state*
**default:** *true*
**context:** *twaf_reqstat*
統(tǒng)計(jì)模塊開關(guān)，支持動態(tài)開關(guān)，默認(rèn)開啟
###access_state
**syntax:** *access_state true|false|$dynamic_state*
**default:** *true*
**context:** *twaf_reqstat*
訪問信息統(tǒng)計(jì)開關(guān)，支持動態(tài)開關(guān)，默認(rèn)開啟
###safe_state
**syntax:** *safe_state true|false|$dynamic_state*
**default:** *true*
**context:** *twaf_reqstat*
安全信息統(tǒng)計(jì)開關(guān)，支持動態(tài)開關(guān)，默認(rèn)開啟
###upstream_state
**syntax:** *upstream_state true|false|$dynamic_state*
**default:** *true*
**context:** *twaf_reqstat*
轉(zhuǎn)發(fā)信息統(tǒng)計(jì)開關(guān)，支持動態(tài)開關(guān)，默認(rèn)開啟
###shared_dict_name
**syntax:** *shared_dict_name string*
**default:** *openwaf_reqshm*
**context:** *twaf_reqstat*
指定shared_dict名稱，在這之前需在nginx配置文件中配置[lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict)
默認(rèn)shared_dict名稱為openwaf_reqshm
[Back to twaf_reqstat](#twaf_reqstat)
[Back to TOC](#table-of-contents)
twaf_log
--------
```txt
"twaf_log": {
"access_log_state":false, -- 訪問日志開關(guān)
"security_log_state":true, -- 安全日志開關(guān)
"sock_type":"udp", -- 支持tcp和udp兩種協(xié)議
"content_type":"JSON", -- 支持JSON和INFLUXDB兩種日志格式
"host":"127.0.0.1", -- 日志服務(wù)器地址
"port":60055, -- 日志服務(wù)器端口號
"flush_limit":0, -- 緩沖，當(dāng)存儲的日志大于閾值才發(fā)送
"drop_limit":1048576,
"max_retry_times":5, -- 最大容錯次數(shù)
"ssl":false, -- 是否開啟ssl協(xié)議
"access_log":{} -- 訪問日志格式
"security_log":{} -- 安全日志格式
}
```
###access_log_state
**syntax:** *"access_log_state": true|false*
**default:** *false*
**context:** *twaf_log*
訪問日志開關(guān)，默認(rèn)關(guān)閉
###security_log_state
**syntax:** *"security_log_state": true|false*
**default:** *true*
**context:** *twaf_log*
安全事件日志開關(guān)，默認(rèn)開啟
###sock_type
**syntax:** *"sock_type": tcp|udp*
**default:** *udp*
**context:** *twaf_log*
日志傳輸協(xié)議，默認(rèn)udp
###content_type
**syntax:** *"content_type": JSON|INFLUXDB*
**default:** *JSON*
**context:** *twaf_log*
日志格式，默認(rèn)JSON
###host
**syntax:** *"host": string*
**default:** *"127.0.0.1"*
**context:** *twaf_log*
日志接收服務(wù)器的ip地址
###port
**syntax:** *"port": number*
**default:** *60055*
**context:** *twaf_log*
日志接收服務(wù)器的端口號
###flush_limit
**syntax:** *"flush_limit": number*
**default:** *0*
**context:** *twaf_log*
緩沖區(qū)大小，當(dāng)存儲的日志大于閾值才發(fā)送，默認(rèn)值為0，即立即發(fā)送日志
###drop_limit
**syntax:** *"drop_limit": number*
**default:** *1048576*
**context:** *twaf_log*
###max_retry_times
**syntax:** *"max_retry_times": number*
**default:** *5*
**context:** *twaf_log*
最大容錯次數(shù)
###ssl
**syntax:** *"ssl": true|false*
**default:** *false*
**context:** *twaf_log*
是否開啟ssl協(xié)議，默認(rèn)false
###access_log
**syntax:** *"access_log": table*
**default:** *false*
**context:** *twaf_log*
訪問日志格式
###security_log
**syntax:** *"security_log": table*
**default:** *false*
**context:** *twaf_log*
安全事件日志格式
若content_type為JSON，則日志格式為
```
[
variable_key_1,
variable_key_2,
...
]
```
若content_type為INFLUXDB，則日志格式為
```
{
"db":MEASUREMENT名稱,
"tags":[variable_key_1, variable_key_2, ...],
"fileds"[variable_key_1, variable_key_2, ...],
"time":true|false
}
```
變量名稱詳見規(guī)則引擎模塊[twaf_secrules](#https://github.com/titansec/openwaf_rule_engine#variables)
```
#日志格式舉例
#JSON格式
"security_log": [
"remote_addr",
"remote_port",
"userid",
"dev_uuid",
"original_dst_addr",
"original_dst_port",
"remote_user",
"time_local",
"msec",
"request_method",
"request_uri",
"request_protocol",
"status",
"bytes_sent",
"http_referer",
"http_user_agent",
"gzip_ratio",
"http_host",
"raw_header"
]
#INFLUXDB格式
"security_log": {
"db":"test", -- MEASUREMENT名稱
"tags":[], -- tags keys
"fileds":[ -- fileds keys
"remote_addr",
"remote_port",
"userid",
"dev_uuid",
"original_dst_addr",
"original_dst_port",
"remote_user",
"time_local",
"msec",
"request_method",
"request_uri",
"request_protocol",
"status",
"bytes_sent",
"http_referer",
"http_user_agent",
"gzip_ratio",
"http_host",
"raw_header"
],
"time":true -- 日志是否攜帶時間戳
}
```
[Back to twaf_log](#twaf_log)
[Back to TOC](#table-of-contents)
twaf_secrules
-------------
```txt
"twaf_secrules":{
"state": true, -- 總開關(guān)
"reqbody_state": true, -- 請求體檢測開關(guān)
"header_filter_state": true, -- 響應(yīng)頭檢測開關(guān)
"body_filter_state": true, -- 響應(yīng)體檢測開關(guān)
"reqbody_limit":134217728, -- 請求體檢測閾值，大于閾值不檢測
"respbody_limit":524288, -- 響應(yīng)體檢測閾值，大于閾值不檢測
"pre_path": "/opt/OpenWAF/", -- OpenWAF安裝路徑
"path": "lib/twaf/inc/knowledge_db/twrules", -- 特征規(guī)則庫在OpenWAF中的路徑
"rules_id":{ -- 特征排除
"111112": [{"REMOTE_HOST":"a.com", "URI":"^/ab"}] -- 匹配中數(shù)組中信息則對應(yīng)規(guī)則失效，數(shù)組中key為變量名稱，值支持正則
"111113": {} -- 特征未被排除
"111114": [{}] -- 特征被無條件排除
}
}
```
###state
**syntax:** *state true|false*
**default:** *true*
**context:** *twaf_secrules*
規(guī)則引擎總開關(guān)
###reqbody_state
**syntax:** *reqbody_state true|false*
**default:** *true*
**context:** *twaf_secrules*
請求體檢測開關(guān)
###header_filter_state
**syntax:** *header_filter_state true|false*
**default:** *true*
**context:** *twaf_secrules*
響應(yīng)頭檢測開關(guān)
###body_filter_state
**syntax:** *body_filter_state true|false*
**default:** *false*
**context:** *twaf_secrules*
響應(yīng)體檢測開關(guān)，默認(rèn)關(guān)閉，若開啟需添加第三方模塊[ngx_http_twaf_header_sent_filter_module暫未開源]
###reqbody_limit
**syntax:** *reqbody_limit number*
**default:** *134217728*
**context:** *twaf_secrules*
請求體檢測大小上限，默認(rèn)134217728B(128MB)，若請求體超過設(shè)置上限，則不檢測
PS：reqbody_limit值要小于nginx中client_body_buffer_size的值才會生效
###respbody_limit
**syntax:** *respbody_limit number*
**default:** *134217728*
**context:** *twaf_secrules*
響應(yīng)體檢測大小上限，默認(rèn)134217728B(128MB)，若響應(yīng)體大小超過設(shè)置上限，則不檢測
###pre_path
**syntax:** *pre_path string*
**default:** */opt/OpenWAF/*
**context:** *twaf_secrules*
OpenWAF的安裝路徑
###path
**syntax:** *path string*
**default:** *lib/twaf/inc/knowledge_db/twrules*
**context:** *twaf_secrules*
特征規(guī)則庫在OpenWAF中的路徑
###rules_id
**syntax:** *rules_id table*
**default:** *none*
**context:** *twaf_secrules*
用于排除特征
[Back to twaf_secrules](#twaf_secrules)
[Back to TOC](#table-of-contents)
Nginx Variables
===============
###$twaf_https
**syntax:** *set $twaf_https 0|1*
**default:** *0*
**context:** *server*
用于標(biāo)記請求是否通過ssl加密
"set $twaf_https 1"，則表示請求通過ssl加密
"set $twaf_https 1"，則表示請求未通過ssl加密
```
server {
listen 443 ssl;
set $twaf_https 1;
...
}
server {
listen 80;
set $twaf_https 0;
...
}
```
###$twaf_upstream_server
**syntax:** *set $twaf_upstream_server ""*
**default:** *none*
**context:** *server*
用于指定后端服務(wù)器地址，只需初始化為空字符串即可，其值由"server_ssl"和"forward"確定
```
upstream server_1 {
...
}
upstream server_2 {
...
}
server {
...
set $twaf_upstream_server "";
location / {
...
proxy_pass $twaf_upstream_server;
}
}
若"server_ssl"值為true, "forward"值為"server_1"
等價于proxy_pass https://server_1;
若"server_ssl"值為false, "forward"值為"server_2"
等價于proxy_pass http://server_2;
```
[Back to TOC](#table-of-contents)
SecRules
========
Variables
---------
* [ARGS](#args)
* [ARGS_COMBINED_SIZE](#args_combined_size)
* [ARGS_GET](#args_get)
* [ARGS_GET_NAMES ](#args_get_names)
* [ARGS_NAMES](#args_names)
* [ARGS_POST ](#args_post)
* [ARGS_POST_NAMES ](#args_post_names)
* [BYTES_IN](#bytes_in)
* [CONNECTION_REQUESTS](#connection_requests)
* [DURATION](#duration)
* [FILES](#files)
* [FILES_NAMES](#files_names)
* [GEO](#geo)
* [GEO_CODE3](#geo_code3)
* [GEO_CODE3](#geo_code)
* [GEO_ID](#geo_id)
* [GEO_CONTINENT](#geo_continent)
* [GEO_NAME](#geo_name)
* [GZIP_RATIO](#gzip_ratio)
* [HTTP_COOKIE](#http_cookie)
* [HTTP_HOST](#http_host)
* [HTTP_REFERER](#http_referer)
* [HTTP_USER_AGENT](#http_user_agent)
* [IP_VERSION](#ip_version)
* [MATCHED_VAR](#matched_var)
* [MATCHED_VARS](#matched_vars)
* [MATCHED_VAR_NAME](#matched_var_name)
* [MATCHED_VARS_NAMES](#matched_var_names)
* [ORIGINAL_DST_ADDR](#original_dst_addr)
* [ORIGINAL_DST_PORT](#original_dst_port)
* [POLICYID](#policyid)
* [QUERY_STRING](#query_string)
* [RAW_HEADER](#raw_header)
* [RAW_HEADER_TRUE](#raw_header_true)
* [REMOTE_ADDR](#remote_addr)
* [REMOTE_HOST](#remote_host)
* [REMOTE_PORT](#remote_port)
* [REMOTE_USER](#remote_user)
* [REQUEST_BASENAME](#request_basename)
* [REQUEST_BODY](#request_body)
* [REQUEST_COOKIES](#request_cookies)
* [REQUEST_COOKIES_NAMES](#request_cookies_names)
* [REQUEST_FILENAME](#request_filename)
* [REQUEST_HEADERS](#request_headers)
* [REQUEST_HEADERS_NAMES](#request_headers_names)
* [REQUEST_LINE](#request_line)
* [REQUEST_METHOD](#request_method)
* [REQUEST_PROTOCOL](#request_protocol)
* [HTTP_VERSION](#http_version)
* [URI](#uri)
* [URL](#url)
* [REQUEST_URI](#request_uri)
* [RESPONSE_BODY](#response_body)
* [RESPONSE_HEADERS](#response_headers)
* [RESPONSE_STATUS](#response_status)
* [SCHEME](#scheme)
* [SERVER_ADDR](#server_addr)
* [SERVER_NAME](#server_name)
* [SERVER_PORT](#server_port)
* [SESSION](#session)
* [SESSION_DATA](#session_data)
* [TIME](#time)
* [TIME_DAY](#time_day)
* [TIME_EPOCH](#time_epoch)
* [TIME_HOUR](#time_hour)
* [TIME_MIN](#time_min)
* [TIME_MON](#time_mon)
* [TIME_SEC](#time_sec)
* [TIME_WDAY](#time_wday)
* [TIME_YEAR](#time_year)
* [TIME_LOCAL](#time_local)
* [TX](#tx)
* [UNIQUE_ID](#unique_id)
* [UPSTREAM_CACHE_STATUS](#upstream_cache_status)
* [USERID](#userid)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ARGS
table類型，所有的請求參數(shù)，包含ARGS_GET和ARGS_POST
```
例如：POST http://www.baidu.com?name=miracle&age=5
請求體為：time=123456&day=365
ARGS變量值為{"name": "miracle", "age": "5", "time": "123456", "day": "365"}
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ARGS_COMBINED_SIZE
number類型，請求參數(shù)總長度，只包含key和value的長度，不包含'&'或'='等符號
```
例如：GET http://www.baidu.com?name=miracle&age=5
ARGS_COMBINED_SIZE變量值為15，而不是18
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ARGS_GET
table類型，querystring參數(shù)
```
例如：GET http://www.baidu.com?name=miracle&age=5
ARGS_GET變量值為{"name": "miracle", "age": "5"}
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ARGS_GET_NAMES
table類型，querystring參數(shù)key值
```
例如：GET http://www.baidu.com?name=miracle&age=5
ARGS_GET_NAMES變量值為["name", "age"]
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ARGS_NAMES
table類型，querystring參數(shù)key值及post參數(shù)key值
```
例如：POST http://www.baidu.com?name=miracle&age=5
請求體為：time=123456&day=365
ARGS_NAMES變量值為["name", "age", "time", "day"]
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ARGS_POST
table類型，POST參數(shù)
```
例如：
POST http://www.baidu.com/login.html
請求體為：time=123456&day=365
ARGS_POST變量值為{"time": "123456", "day": "365"}
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ARGS_POST_NAMES
table類型，POST參數(shù)key值
```
例如：
POST http://www.baidu.com/login.html
請求體為：time=123456&day=365
ARGS_POST_NAMES變量值為["time", "day"]
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##BYTES_IN
number類型，接收信息字節(jié)數(shù)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##CONNECTION_REQUESTS
number類型，當(dāng)前連接中的請求數(shù)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##DURATION
string類型，處理事務(wù)用時時間，單位:微秒(μs)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##FILES
table類型，從請求體中得到的原始文件名(帶有文件后綴名)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##FILES_NAMES
table類型，上傳文件名稱（不帶有后綴名）
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##GEO
table類型，包含code3,code,id,continent,name等字段信息
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##GEO_CODE3
string類型，3個字母長度的國家縮寫
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##GEO_CODE
string類型，2個字母長度的國家縮寫
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##GEO_ID
number類型，國家ID
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##GEO_CONTINENT
string類型，國家所在大洲
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##GEO_NAME
string類型，國家全稱
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##GZIP_RATIO
string類型，壓縮比率
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##HTTP_COOKIE
string類型，請求頭中的cookie字段
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##HTTP_HOST
string類型，請求頭中的host字段值，既域名:端口(80缺省)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##HTTP_REFERER
string類型，請求頭中的referer字段
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##HTTP_USER_AGENT
string類型，請求頭中的user-agent字段
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##IP_VERSION
string類型，IPv4 or IPv6
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##MATCHED_VAR
類型不定，當(dāng)前匹配中的變量
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##MATCHED_VARS
table類型，單條規(guī)則匹配中的所有變量
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##MATCHED_VAR_NAME
string類型，當(dāng)前匹配中的變量名稱
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##MATCHED_VARS_NAMES
table類型，單條規(guī)則匹配中的所有變量名稱
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ORIGINAL_DST_ADDR
string類型，服務(wù)器地址，應(yīng)用代理模式為WAF地址，透明模式為后端服務(wù)器地址
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##ORIGINAL_DST_PORT
string類型，服務(wù)器端口號，應(yīng)用代理模式為WAF端口號，透明模式為后端服務(wù)器端口號
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##POLICYID
string類型，策略ID
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##QUERY_STRING
string類型，未解碼的請求參數(shù)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##RAW_HEADER
string類型，請求頭信息，帶請求行
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##RAW_HEADER_TRUE
string類型，請求頭信息，不帶請求行
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REMOTE_ADDR
string類型，客戶端地址
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REMOTE_HOST
string類型，域名
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REMOTE_PORT
number類型，端口號
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REMOTE_USER
string類型，用于身份驗(yàn)證的用戶名
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_BASENAME
string類型，請求的文件名
```
例如: GET http://www.baidu.com/test/login.php
REQUEST_BASENAME值為/login.php
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_BODY
類型不定，請求體
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_COOKIES
table類型，請求攜帶的cookie
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_COOKIES_NAMES
table類型，請求攜帶cookie的名稱
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_FILENAME
string類型，relative request URL(相對請求路徑)
```
例如: GET http://www.baidu.com/test/login.php
REQUEST_FILENAME值為/test/login.php
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_HEADERS
table類型，請求頭信息
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_HEADERS_NAMES
table類型，請求頭key值
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_LINE
string類型，請求行
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_METHOD
string類型，請求方法
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_PROTOCOL
string類型，http請求協(xié)議，如: HTTP/1.1
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##HTTP_VERSION
string類型，http請求協(xié)議版本，如: 1.1
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##URI
string類型，請求路徑，既不帶域名，也不帶參數(shù)
```
例如: GET http://www.baid.com/test/login.php?name=miracle
URI變量值為/test/login.php
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##URL
string類型，統(tǒng)一資源定位符，SCHEME與HTTP_HOST與URI的拼接
```
例如: GET http://www.baid.com/test/login.php?name=miracle
URL變量值為http://www.baid.com/test/login.php
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##REQUEST_URI
string類型，請求路徑，帶參數(shù)，但不帶有域名
```
例如: GET http://www.baid.com/test/login.php?name=miracle
REQUEST_URI變量值為/test/login.php?name=miracle
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##RESPONSE_BODY
string類型，響應(yīng)體
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##RESPONSE_HEADERS
table類型，響應(yīng)頭信息
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##RESPONSE_STATUS
function類型，響應(yīng)狀態(tài)碼
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##SCHEME
string類型，http or https
```
例如：GET http://www.baidu.com/
SCHEME變量值為http
```
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##SERVER_ADDR
string類型，服務(wù)器地址
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##SERVER_NAME
string類型，服務(wù)器名稱
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##SERVER_PORT
number類型，服務(wù)器端口號
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##SESSION
table類型，第三方模塊lua-resty-session提供的變量
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##SESSION_DATA
table類型，session信息，第三方模塊lua-resty-session提供的變量
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME
string類型，hour:minute:second
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_DAY
number類型，天(1-31)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_EPOCH
number類型，時間戳，seconds since 1970
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_HOUR
number類型，小時(0-23)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_MIN
number類型，分鐘(0-59)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_MON
number類型，月份(1-12)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_SEC
number類型，秒(0-59)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_WDAY
number類型，周(0-6)
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_YEAR
number類型，年份，four-digit，例如: 1997
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TIME_LOCAL
string類型，當(dāng)前時間，例如: 26/Aug/2016:01:32:16 -0400
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##TX
table類型，用于存儲當(dāng)前請求信息的變量，作用域僅僅是當(dāng)前請求
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##UNIQUE_ID
string類型，ID標(biāo)識，隨機(jī)生成的字符串，可通過配置來控制隨機(jī)字符串的長度
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##UPSTREAM_CACHE_STATUS
keeps the status of accessing a response cache (0.8.3). The status can be either “MISS”, “BYPASS”, “EXPIRED”, “STALE”, “UPDATING”, “REVALIDATED”, or “HIT”.
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
##USERID
string類型，從接入規(guī)則配置得到的用于ID標(biāo)識
[Back to Var](#variables)
[Back to TOC](#table-of-contents)
Transformation Functions
------------------------
* [base64_decode](#base64_decode)
* [sql_hex_decode](#sql_hex_decode)
* [base64_encode](#base64_encode)
* [counter](#counter)
* [compress_whitespace ](#compress_whitespace )
* [hex_decode](#hex_decode)
* [hex_encode](#hex_encode)
* [html_decode](#html_decode)
* [length](#length)
* [lowercase](#lowercase)
* [md5](#md5)
* [normalise_path](#normalise_path)
* [remove_nulls](#remove_nulls)
* [remove_whitespace](#remove_whitespace)
* [replace_comments](#replace_comments)
* [remove_comments_char](#remove_comments_char)
* [remove_comments](#remove_comments)
* [uri_decode](#uri_decode)
* [uri_encode](#uri_encode)
* [sha1](#sha1)
* [trim_left](#trim_left)
* [trim_right](#trim_right)
* [trim](#trim)
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##base64_decode
Decodes a Base64-encoded string.
Note: 注意transform的執(zhí)行順序
```
例如：
{
"id": "xxxx",
...
"transform": ["base64_decode", "lowercase"],
...
}
先執(zhí)行base64解碼，然后字符串最小化，若順序調(diào)換，會影響結(jié)果
```
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##sql_hex_decode
Decode sql hex data.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##base64_encode
Encodes input string using Base64 encoding.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##counter
計(jì)數(shù)，相當(dāng)于modsecurity中的'&'符號
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##compress_whitespace
Converts any of the whitespace characters (0x20, \f, \t, \n, \r, \v, 0xa0) to spaces (ASCII 0x20), compressing multiple consecutive space characters into one.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##hex_decode
Decodes a string that has been encoded using the same algorithm as the one used in hexEncode
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##hex_encode
Encodes string (possibly containing binary characters) by replacing each input byte with two hexadecimal characters.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##html_decode
Decodes the characters encoded as HTML entities.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##length
Looks up the length of the input string in bytes
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##lowercase
Converts all characters to lowercase
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##md5
Calculates an MD5 hash from the data in input. The computed hash is in a raw binary form and may need encoded into text to be printed (or logged). Hash functions are commonly used in combination with hex_encode (for example: "transform": ["md5", "hex_encode").
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##normalise_path
Removes multiple slashes, directory self-references, and directory back-references (except when at the beginning of the input) from input string.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##remove_nulls
Removes all NUL bytes from input
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##remove_whitespace
Removes all whitespace characters from input.
移除空白字符\s，包含水平定位字符 ('\t')、歸位鍵('\r')、換行('\n')、垂直定位字符('\v')或翻頁('\f')等
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##replace_comments
用一個空格代替/*...*/注釋內(nèi)容
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##remove_comments_char
Removes common comments chars (/*, */, --, #).
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##remove_comments
去掉/*...*/注釋內(nèi)容
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##uri_decode
Unescape str as an escaped URI component.
```
例如:
"b%20r56+7" 使用uri_decode轉(zhuǎn)換后為 b r56 7
```
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##uri_encode
Escape str as a URI component.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##sha1
Calculates a SHA1 hash from the input string. The computed hash is in a raw binary form and may need encoded into text to be printed (or logged). Hash functions are commonly used in combination with hex_encode (for example, "transform": ["sha1", "hex_encode"]).
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##trim_left
Removes whitespace from the left side of the input string.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##trim_right
Removes whitespace from the right side of the input string.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
##trim
Removes whitespace from both the left and right sides of the input string.
[Back to TFF](#transformation-functions)
[Back to TOC](#table-of-contents)
Operators
---------
* [begins_with](#begins_with)
* [contains](#contains)
* [contains_word](#contains_word)
* [detect_sqli](#detect_sqli)
* [detect_xss](#detect_xss)
* [ends_with](#ends_with)
* [equal](#equal)
* [greater_eq](#greater_eq)
* [greater](#greater)
* [ip_utils](#ip_utils)
* [less_eq](#less_eq)
* [less](#less)
* [pf](#pf)
* [regex](#regex)
* [str_match](#str_match)
* [validate_url_encoding](#validate_url_encoding)
* [num_range](#num_range)
* [str_range](#str_range)
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##begins_with
Returns true if the parameter string is found at the beginning of the input.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##contains
Returns true if the parameter string is found anywhere in the input.
operator為contains且pattern為數(shù)組，相當(dāng)于modsecurity的pm
PS: modsecurity的pm忽略大小寫，OpenWAF中contains不忽略大小寫
```
例如:
{
"id": "xxx",
...
"operator": "contains",
"pattern": ["abc", "def"],
...
}
```
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##contains_word
Returns true if the parameter string (with word boundaries) is found anywhere in the input.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##detect_sqli
This operator uses LibInjection to detect SQLi attacks.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##detect_xss
This operator uses LibInjection to detect XSS attacks.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##ends_with
Returns true if the parameter string is found at the end of the input.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##equal
Performs a string comparison and returns true if the parameter string is identical to the input string.
相當(dāng)于modsecurity的eq和streq
```
例如:
{
"id": "xxx",
...
"operator": "equal",
"pattern": [12345, "html", "23456"]
...
}
```
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##greater_eq
Performs numerical comparison and returns true if the input value is greater than or equal to the provided parameter.
return false, if a value is provided that cannot be converted to a number.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##greater
Performs numerical comparison and returns true if the input value is greater than the operator parameter.
return false, if a value is provided that cannot be converted to a number.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##ip_utils
Performs a fast ipv4 or ipv6 match of REMOTE_ADDR variable data. Can handle the following formats:
Full IPv4 Address: 192.168.1.100
Network Block/CIDR Address: 192.168.1.0/24
IPv4 Address Region: 1.1.1.1-2.2.2.2
ip_utils與pf的組合相當(dāng)于modsecurity中的ipMatchF和ipMatchFromFile
```
例如:
規(guī)則如下：
{
"id": "xxxx",
...
"operator": "ip_utils",
"pf": "/tmp/ip_blacklist.txt",
...
}
"/tmp/ip_blacklist.txt"文件內(nèi)容如下：
192.168.1.100
192.168.1.0/24
1.1.1.1-2.2.2.2
```
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##less_eq
Performs numerical comparison and returns true if the input value is less than or equal to the operator parameter.
return false, if a value is provided that cannot be converted to a number.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##less
Performs numerical comparison and returns true if the input value is less than to the operator parameter.
return false, if a value is provided that cannot be converted to a number.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##pf
pattern是operator操作的參數(shù)
pf是指pattern from file，與pattern互斥（二者不可同時出現(xiàn)），目前僅支持絕對路徑
pf與contains組合，相當(dāng)于modsecurity的pmf或pmFromFile
pf與ip_utils組合，相當(dāng)于modsecurity的ipMatchF或ipMatchFromFile
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##regex
Performs a regular expression match of the pattern provided as parameter.
regex還有modecurity的capture捕獲功能
modsecurity有關(guān)capture的描述如下：
When used together with the regular expression operator (@rx), the capture action will create copies of the regular expression captures and place them into the transaction variable collection.
OpenWAF中無capture指令，但使用regex默認(rèn)開啟capture功能
```
例如:
{
"id": "000031",
"release_version": "858",
"charactor_version": "001",
"opts": {
"nolog": false
},
"phase": "access",
"action": "deny",
"meta": 403,
"severity": "low",
"rule_name": "protocol.reqHeader.c",
"desc": "協(xié)議規(guī)范性約束，檢測含有不合規(guī)Range或Request-Range值的HTTP請求",
"match": [
{
"vars": [
{
"var": "REQUEST_HEADERS",
"parse": {
"specific": "Range"
}
},
{
"var": "REQUEST_HEADERS",
"parse": {
"specific": "Request-Range"
}
}
],
"operator": "regex",
"pattern": "(\\d+)\\-(\\d+)\\,"
},
{
"vars": [{
"var": "TX",
"parse": {
"specific": "2"
}
}],
"operator": "greater_eq",
"pattern": "%{TX.1}",
"parse_pattern": true,
"op_negated": true
}
]
}
```
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##str_match
等同于contains
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##validate_url_encoding
Validates the URL-encoded characters in the provided input string.
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##num_range
判斷是否在數(shù)字范圍內(nèi)
它與transform的length組合，相當(dāng)于modsecurity的validateByteRange
```
{
"id": "xxx",
...
"operator": "num_range",
"pattern": [10, "13", "32-126"],
"transform": "length",
...
}
```
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
##str_range
判斷是否在字符串范圍內(nèi)
```
例如時間區(qū)間判斷:
{
"id": "xxx",
...
"operator": "str_range",
"pattern": ["01:42:00-04:32:00"],
...
}
```
[Back to OPERATORS](#operators)
[Back to TOC](#table-of-contents)
Others
------
* [allow](#allow)
* [deny](#deny)
* [id](#id)
* [nolog](#nolog)
* [op_negated](#op_negated)
* [parse](#parse)
* [pass](#pass)
* [phase](#phase)
* [proxy_cache](#proxy_cache)
* [redirect](#redirect)
* [charactor_version](#charactor_version)
* [severity](#severity)
* [setvar](#setvar)
* [meta](#meta)
* [transform](#transform)
* [tag](#tag)
* [release_version](#release_version)
* [robot](#robot)
* [add_resp_headers](#add_resp_headers)
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##allow
Stops rule processing of the current phase on a successful match and allows the transaction to proceed.
```
"action": "allow"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##deny
Stops rule processing and intercepts transaction.
```
"action": "deny",
"meta": 403
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##id
Stops rule processing and intercepts transaction.
```
"id": "xxxxxxx"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##nolog
不記錄日志
```
"opts": {
"nolog": true
}
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##op_negated
對operator結(jié)果的取反
```
"match": [{
"vars": [{
"var": "HTTP_USER_AGENT"
}],
"transform": "length",
"operator": "less_eq",
"pattern": 50,
"op_negated": true
}]
等價于
"match": [{
"vars": [{
"var": "HTTP_USER_AGENT"
}],
"transform": "length",
"operator": "greater",
"pattern": 50
}]
若請求頭中user_agent字段長度大于50，則匹配中此條規(guī)則
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##parse
對變量進(jìn)一步解析
```
若請求GET http://www.baidu.com?name=miracle&age=5
"match": [{
"vars": [{
"var": "ARGS_GET"
}]，
...
}]
得到的值為{"name": "miracle", "age": "5"}
"match": [{
"vars": [{
"var": "ARGS_GET",
"parse": {
"specific": "name"
}
}]
}]
得到的值為["miracle"]
"match": [{
"vars": [{
"var": "ARGS_GET",
"parse": {
"specific": ["name", "age"]
}
}]
}]
得到的值為["miracle", "5"]
"match": [{
"vars": [{
"var": "ARGS_GET",
"parse": {
"ignore": "name"
}
}]
}]
得到的值為{"age": "5"}
"match": [{
"vars": [{
"var": "ARGS_GET",
"parse": {
"ignore": ["name", "age"]
}
}]
}]
得到的值為[]
"match": [{
"vars": [{
"var": "ARGS_GET",
"parse": {
"keys": true
}
}]
}]
得到的值為["name", "age"]
"match": [{
"vars": [{
"var": "ARGS_GET",
"parse": {
"values": true
}
}]
}]
得到的值為["miracle", "5"]
"match": [{
"vars": [{
"var": "ARGS_GET",
"parse": {
"all": true
}
}]
}]
得到的值為["name", "age", "miracle", "5"]
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##pass
Continues processing with the next rule in spite of a successful match.
```
"action": "pass"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##phase
規(guī)則執(zhí)行的階段，取值可為"access","header_filter","body_filter"的組合
```
{
"id": "xxx_01",
"phase": "access",
...
}
"xxx_01"規(guī)則在access階段執(zhí)行
{
"id": "xxx_02",
"phase": ["access", "header_filter"],
...
}
"xxx_02規(guī)則在access階段和"header_filter"階段各執(zhí)行一次
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##proxy_cache
```
{
...
phase = "header_filter", -- 緩存開關(guān)需在header_filter階段配置
action = "pass", -- 無需攔截請求
opts = {
nolog = true, -- 不需記錄日志
proxy_cache = {
state = true|false, -- 緩存開關(guān)
expired = 600 -- 緩存時長（單位秒）,默認(rèn)600秒
}
}
...
}
若state為true，且得到的緩存狀態(tài)為"MISS"或"EXPIRED"，則對響應(yīng)內(nèi)容進(jìn)行緩存，同時設(shè)置緩存時長
若state為false，則清除對應(yīng)緩存鍵的緩存（包含其緩存文件）
```
舉例如下：
```
# nginx.conf 有關(guān)proxy cache 配置如下
http {
proxy_cache_path /opt/cache/OpenWAF-proxy levels=2:2 keys_zone=twaf_cache:101m max_size=100m use_temp_path=off;
proxy_cache_key $host$uri;
proxy_cache twaf_cache;
proxy_ignore_headers X-Accel-Expires Cache-Control Set-Cookie;
proxy_no_cache $twaf_cache_flag;
server {
set $twaf_cache_flag 1; #默認(rèn)不緩存
}
}
# lua 格式 配置
{
id = "test_x01", -- id 全局唯一
opts = {
nolog = true,
proxy_cache = {
state = true,
expired = 300
}
},
phase = "header_filter",
action = "pass",
match = {{
vars = {{
var = "URI"
},{
var = "REQUEST_HEADERS",
parse = {
specific = "Referer"
}
}},
operator = "equal",
pattern = {"/xampp/", "%{SCHEME}://%{HTTP_HOST}/xampp/"},
parse_pattern = true
}}
}
此規(guī)則將緩存URI為'/xampp/'的頁面，更新時間為300秒
若match中過濾條件為響應(yīng)碼，則相當(dāng)于Nginx的proxy_cache_valid指令
若match中過濾條件為請求方法，則相當(dāng)于Nginx的proxy_cache_methods指令
若macth中過濾條件為資源類型，則相當(dāng)于Nginx的proxy_cache_content_type指令
PS: proxy_cache_content_type指令為官方指令，是miracle Qi修改Nginx源碼擴(kuò)展的功能
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##redirect
```
"action": "redirect",
"meta": "/index.html"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##charactor_version
指定此條規(guī)則的版本，同modsecurity中Action的rev功能
```
"charactor_version": "001"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##severity
Assigns severity to the rule in which it is used.
The data below is used by the OWASP ModSecurity Core Rule Set (CRS):
EMERGENCY: is generated from correlation of anomaly scoring data where there is an inbound attack and an outbound leakage.
ALERT: is generated from correlation where there is an inbound attack and an outbound application level error.
CRITICAL: Anomaly Score of 5. Is the highest severity level possible without correlation. It is normally generated by the web attack rules (40 level files).
ERROR: Error - Anomaly Score of 4. Is generated mostly from outbound leakage rules (50 level files).
WARNING: Anomaly Score of 3. Is generated by malicious client rules (35 level files).
NOTICE: Anomaly Score of 2. Is generated by the Protocol policy and anomaly files.
INFO
DEBUG
也可自定義嚴(yán)重等級，如:low，medium，high，critical等
```
"severity": "high"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##setvar
Creates, removes, or updates a variable.
```
{
"id": "xxx_01",
"opts":{
"nolog": false,
"setvar": [{
"column": "TX",
"key": "score",
"value": 5,
"incr": true
}]
},
...
}
"xxx_01"規(guī)則中，給變量TX中score成員的值加5，若TX中無score成員，則初始化為0，再加5
{
"id": "xxx_02",
"opts":{
"nolog": false,
"setvar": [{
"column": "TX",
"key": "score",
"value": 5
}]
},
...
}
"xxx_02"規(guī)則中，給變量TX中score成員的值賦為5
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##meta
"action"的附屬信息
```
若"action"為"deny"，則"meta"為響應(yīng)碼
"action": "deny",
"meta": 403
若"action"為"redirect"，則"meta"為重定向地址
"action": "redirect",
"meta": "/index.html"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##transform
This action is used to specify the transformation pipeline to use to transform the value of each variable used in the rule before matching.
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##tag
Assigns a tag (category) to a rule.
```
支持?jǐn)?shù)組 "tag": ["xxx_1", "xxx_2"]
支持字符串 "tag": "xxx_3"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##release_version
規(guī)則集版本，等同于modsecurity中Action的ver功能
```
"release_version": "858"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##robot
人機(jī)識別
需提前配置人機(jī)識別模塊配置，此功能暫未放開
```
"action": "robot"
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
##add_resp_headers
增刪改響應(yīng)頭
```
例如隱藏server字段:
"opts": {
"add"_resp_headers": {
"server": ""
}
}
```
[Back to OTHERS](#others)
[Back to TOC](#table-of-contents)
以上內(nèi)容是否對您有幫助：
更多建議：