Name

OpenWAF

The first all-round open source Web security protection system, more protection than others.

Version

This document describes OpenWAF v0.0.3.170103_beta released on 03 Jan 2017.

Docker Version

titansec/openwaf:0.0.1.161130_beta
SHA: 596dee9d2b9ce44d59dc445141f72b3607f9fbe6
https://github.com/titansec/OpenWAF/tree/596dee9d2b9ce44d59dc445141f72b3607f9fbe6
titansec/openwaf:0.0.3.170103_beta(titansec/openwaf:latest)
SHA: 28ce1556250301f26f31b46d9cd9dde5a3b3f03f
https://github.com/titansec/OpenWAF/tree/28ce1556250301f26f31b46d9cd9dde5a3b3f03f

Synopsis

    #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;
        }
    }

    #default_config-json

    #main_safe_policy-json

Back to TOC

Description

OpenWAF是第一个全方位开源的Web应用防护系统（WAF），他基于nginx_lua API分析HTTP请求信息。OpenWAF由行为分析引擎和规则引擎两大功能引擎构成。其中规则引擎主要对单个请求进行分析，行为分析引擎主要负责跨请求信息追踪。

规则引擎的启发来自modsecurity及freewaf(lua-resty-waf)，将ModSecurity的规则机制用lua实现。基于规则引擎可以进行协议规范，自动工具，注入攻击，跨站攻击，信息泄露，异常请求等安全防护，支持动态添加规则，及时修补漏洞。

行为分析引擎包含基于频率的模糊识别，防恶意爬虫，人机识别等防探测模块，防CSRF，防CC，防提权，文件上传防护等防攻击模块，cookie防篡改，防盗链，自定义响应头，攻击响应页面等防信息泄露模块。

除了两大引擎之外，还包含统计，日志，攻击响应页面，接入规则等基础模块。除了已有的功能模块，OpenWAF还支持动态修改配置，动态添加第三方模块，使得在不重启引擎中断业务的条件下，升级防护。

OpenWAF支持将上述功能封装为策略，不同的web application应用不同的策略来防护。将来还会打造云平台，策略还可分享供他人参考。

基础模块如下:

功能模块如下:

详细配置文档及示例请看上述各模块文档

Back to TOC

Installation

若用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 接入规则
       vi /opt/OpenWAF/conf/twaf_access_rule.json
       编辑域名，后端服务器地址等信息
   4.2 日志服务器
       vi /opt/OpenWAF/conf/twaf_default_conf.json
       配置twaf_log日志接收服务器地址
   
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. 查看当前openssl版本命令： openssl version
      2. 若更新openssl后，版本未变，请详看http://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参数

Back to TOC

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/[email protected]

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

Community

English Mailing List

The OpenWAF-en mailing list is for English speakers.

Chinese Mailing List

The OpenWAF-cn mailing list is for Chinese speakers.

Personal QQ Mail

[email protected]

QQ Group

579790127

Back to TOC

Bugs and Patches

Please submit bug reports, wishlists, or patches by

creating a ticket on the GitHub Issue Tracker,
or posting to the OpenWAF community.

Back to TOC

TODO

1. 上传人机识别模块
1. 上传防盗链模块
1. 上传防CC模块
1. 上传cookie防篡改模块
1. 上传基于频率的模糊识别防探测模块
1. 上传WebShell上传防护模块
1. 上传防CSRF模块
1. 提供页面体验OpenWAF防护功能
1. 放开动态配置规则引擎API
1. 放开动态配置行为分析引擎API

Back to TOC

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

Copyright and License

This module is licensed under the BSD license.

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

Modules Configuration Directives

twaf_access_rule
twaf_anti_hotlink
twaf_anti_mal_crawler
twaf_reqstat
twaf_log
twaf_secrules

Back to TOC