Logo
Project Icon

zhongkui-waf

基于lua-nginx-module的高性能Web应用防火墙

ZhongKui-WAFWeb应用防火墙安全防护OpenRestyNginxGithub开源项目

Zhongkui-WAF是基于lua-nginx-module开发的轻量级Web应用防火墙。它提供多种防护模式和自定义规则，可拦截SQL注入、XSS、SSRF等攻击。功能包括IP黑白名单、CC攻击防御、敏感数据脱敏，并提供攻击日志和流量统计可视化。配置简单，适用于多种Web应用安全防护场景。

GithubGithub文档文档论文论文
介绍相关项目

ZhongKui-WAF

钟馗是中国传统文化中的一个神话人物，被誉为"捉鬼大师"，专门驱逐邪恶之物。Zhongkui-WAF的命名灵感来源于这一神话人物，寓意着该软件能够像钟馗一样，有效地保护Web应用免受各种恶意攻击和威胁。

Zhongkui-WAF基于lua-nginx-module，可以多维度检查和拦截恶意网络请求，具有简单易用、高性能、轻量级的特点。它的配置简单，你可以根据实际情况设置不同的安全规则和策略。

dashboard

主要特性

  • 多种工作模式，可随时切换
    1. 关闭模式：放行所有网络请求
    2. 保护模式（protection）：拦截攻击请求并记录攻击日志
    3. 监控模式（monitor）：记录攻击日志但不拦截攻击请求
  • 支持规则自动排序，开启后按规则命中次数降序排序，可提高拦截效率
  • 支持ACL自定义规则，灵活配置拦截规则
  • 防护站点添加
  • IP黑名单、白名单，支持网段配置，"127.0.0.1/24"或"127.0.0.1/255.255.255.0"
  • HTTP Method白名单
  • URL黑名单、白名单
  • URL恶意参数拦截
  • 恶意Header拦截
  • 请求体检查
  • 上传文件类型黑名单，防止webshell上传
  • 恶意Cookie拦截
  • CC攻击拦截，浏览器验证失败后可以自动限时或永久拉黑IP地址
  • Sql注入、XSS、SSRF等攻击拦截
  • 可设置仅允许指定国家的IP访问
  • 敏感数据（身份证号码、手机号码、银行卡号、密码）脱敏及关键词过滤
  • 支持Redis，开启后IP请求频率、IP黑名单等数据将从Redis中读写
  • 攻击日志记录，包含IP地址、IP所属地区、攻击时间、防御动作、拦截规则等，支持JSON格式日志
  • 流量统计可视化

安装

可以执行安装脚本install.sh，自动安装OpenResty、ZhongKui、libmaxminddb、luafilesystem和geoipupdate。也可以自行逐个安装。

OpenResty

由于Zhongkui-WAF基于lua-nginx-module，所以要先安装Nginx或OpenResty，强烈推荐使用OpenResty。

如果你使用Nginx，则需要安装以下第三方模块：

  1. 安装LuaJIT和lua-nginx-module模块
  2. 下载lua-resty-redis库到path-to-zhongkui-waf/lib/resty目录
  3. 安装lua-cjson库

zhongkui-waf

假设OpenResty安装路径为：/usr/local/openresty，下载zhongkui-waf文件并放置在/usr/local/openresty/zhongkui-waf目录。

修改nginx.conf，在http模块下添加zhongkui-waf相关配置：

include /usr/local/openresty/zhongkui-waf/admin/conf/waf.conf;
include /usr/local/openresty/zhongkui-waf/admin/conf/admin.conf;
include /usr/local/openresty/zhongkui-waf/admin/conf/sites.conf;

可根据访问量大小适当调整waf.conf文件中配置的字典内存大小。

lua_shared_dict dict_cclimit 10m;
lua_shared_dict dict_accesstoken 5m;
lua_shared_dict dict_blackip 10m;
lua_shared_dict dict_locks 100k;
lua_shared_dict dict_config 100k;
lua_shared_dict dict_config_rules_hits 100k;
lua_shared_dict dict_req_count 5m;
lua_shared_dict dict_req_count_citys 10m;
lua_shared_dict dict_sql_queue 10m;

lua_package_path "/usr/local/openresty/zhongkui-waf/?.lua;/usr/local/openresty/zhongkui-waf/lib/?.lua;/usr/local/openresty/zhongkui-waf/admin/lua/?.lua;;";
init_by_lua_file  /usr/local/openresty/zhongkui-waf/init.lua;
init_worker_by_lua_file /usr/local/openresty/zhongkui-waf/init_worker.lua;
access_by_lua_file /usr/local/openresty/zhongkui-waf/waf.lua;
body_filter_by_lua_file /usr/local/openresty/zhongkui-waf/body_filter.lua;
header_filter_by_lua_file /usr/local/openresty/zhongkui-waf/header_filter.lua;
log_by_lua_file /usr/local/openresty/zhongkui-waf/log_and_traffic.lua;

libmaxminddb库

IP地理位置识别需要下载MaxMind的IP地址数据文件及安装该IP数据文件的读取库。

  1. 从MaxMind官网下载GeoLite2 City数据文件，后续可使用官方工具对该数据文件自动更新。

  2. 安装libmaxminddb库

    wget -P /usr/local/src https://github.com/maxmind/libmaxminddb/releases/download/1.7.1/libmaxminddb-1.7.1.tar.gz
tar -zxvf libmaxminddb-1.7.1.tar.gz
cd libmaxminddb-1.7.1
./configure
make && make install
echo /usr/local/lib >> /etc/ld.so.conf.d/local.conf
ldconfig

    Windows系统用户要自行编译，生成libmaxminddb.dll文件，具体参考maxmind/libmaxminddb官方文档using-cmake。

luaossl库

wget -O /usr/local/src/luaossl-rel-20220711.tar.gz https://github.com/wahern/luaossl/archive/refs/tags/rel-20220711.tar.gz
tar -zxf luaossl-rel-20220711.tar.gz
cd ./luaossl-rel-20220711
make all5.1 includedir=/usr/local/openresty/luajit/include/luajit-2.1 && make install5.1

LuaFileSystem库

wget -O /usr/local/src/luafilesystem-master.zip https://github.com/lunarmodules/luafilesystem/archive/refs/heads/master.zip
unzip luafilesystem-master.zip
cd ./luafilesystem-master
make INCS=/usr/local/openresty/luajit/include/luajit-2.1
mv ./src/lfs.so /usr/local/openresty/lualib/lfs.so

安装完成后重启OpenResty，使用测试命令：

curl http://localhost/?t=../../etc/passwd

看到拦截信息则说明安装成功。

配置

Zhongkui-WAF内置了管理界面，但你依然可以通过直接修改相应配置文件来进行自定义配置。

Zhongkui-WAF的基本配置在/conf/zhongkui.conf文件中，你可以对它进行修改。

IP黑名单列表可以配置在/conf/zhongkui.conf文件中，也可以配置在path-to-zhongkui-waf/rules/ipBlackList文件中。

不管是基本配置还是规则文件，修改完后都要执行nginx -s reload命令来重新载入配置。

path-to-zhongkui-waf/rules目录下是一系列规则文件，文件内容都是json格式。你可以新增自己的规则，也可以对每条规则进行单独设置，如打开、关闭或者修改其拦截动作等。

拦截动作有如下几种：

  • allow：允许当前请求并记录日志。
  • deny：拒绝当前请求，返回HTTP状态码403并记录日志。
  • redirect：拒绝当前请求，返回拦截页面并记录日志。
  • coding：对匹配到的内容进行过滤，替换为*。
  • redirect_js：浏览器验证，JavaScript重定向。
  • redirect_302：浏览器验证，302重定向。

一些通用配置项：

  • state：该规则的开关状态，on为开启，off为关闭。
  • description：对该规则的描述，便于管理。

配置项secret是Zhongkui-WAF的私钥，用于浏览器验证请求签名等，应妥善保管，安装后建议修改，格式为任意字符组合，建议较长。

CC攻击防御

CC攻击配置文件位于path-to-zhongkui-waf/rules/cc.json，可按单URL和单IP统计，超过阈值时直接拒绝请求或进行浏览器验证，验证失败后可自动屏蔽IP地址。

配置项说明：

  • countType：统计类型，值为"url"或"ip"。
  • pattern：匹配内容，对统计类型进行匹配的正则表达式，设为""时匹配所有请求。
  • duration：统计时长，单位为秒。
  • threshold：阈值，单位为次。
  • action：CC攻击处置动作，redirect_js、redirect_302仅适用于网页或H5，APP或API等环境应设置为deny。
  • autoIpBlock：浏览器验证失败后自动屏蔽IP，on为开启，off为关闭。拉黑日志保存在./logPath/ipBlock.log文件中。
  • ipBlockTimeout：IP禁止访问时间，单位为秒，设为0则永久禁止并保存在./rules/ipBlackList文件中。

Bot管理

Bot管理配置文件位于path-to-zhongkui-waf/rules/user-agent.json。可配置对bot采取阻止、放行、浏览器验证或IP屏蔽等处置动作。

bot黑名单

zhongkui-waf内置了一些自动扫描工具及恶意爬虫等的User-Agent，默认会阻止User-Agent在黑名单中的请求。

bot白名单

开启后，一些常见的搜索引擎爬虫将被放行，目前包括Google、百度、搜狗、Bing、360、Yandex等。

bot陷阱

bot陷阱配置在/conf/zhongkui.conf文件中，开启后会在上游服务器返回的HTML页面中添加配置的陷阱URL，此URL对普通用户不可见，访问此URL的请求被视为bot。

建议bot陷阱结合robots协议使用，将陷阱URI配置为禁止所有bot访问，不遵守的bot将访问陷阱URL从而被识别，而遵循robots协议的友好bot不会被捕获。

可在robots.txt中这样配置：

User-agent: *
Disallow: /zhongkuiwaf/honey/trap

ACL自定义规则

自定义规则配置文件位于path-to-zhongkui-waf/rules/acl.json，可根据实际需要灵活配置规则组合。

配置项说明：

  • rule：规则名称。
  • conditions：匹配条件，可为多个条件组合，条件间为"且"关系。
    • field：匹配字段，可为URL、Cookie、Header、Referer、User-Agent。
    • pattern：匹配内容，对字段进行匹配的正则表达式，设为""时表示匹配对应field不存在的请求。
    • name：当field为Cookie或Header时，可匹配具体的Cookie Name或Header Name。
  • action：匹配规则后的处置动作，redirect_js、redirect_302仅适用于网页或H5，APP或API等环境应设置为deny。
  • autoIpBlock：匹配规则后自动屏蔽IP，on为开启，off为关闭。拉黑日志保存在./logPath/ipBlock.log文件中。
  • ipBlockTimeout：IP禁止访问时间，单位为秒，设为0则永久禁止并保存在./rules/ipBlackList文件中。

示例：拦截URL为/test/12345.html且无Cookie的请求：

{
    "rules": [
        {
            "state": "on",
            "rule": "no Cookie",
            "conditions": [
                {
                    "field": "URL",
                    "pattern": "/test/\\d+\\.html"
                },
                {
                    "field": "Cookie",
                    "pattern": ""
                }
            ],
            "action": "deny",
            "autoIpBlock": "off",
            "ipBlockTimeout": 60,
            "description": "拦截不带Cookie的请求"
        }
    ]
}

拦截Cookie name为JSESSIONID，值为aaaROKLSA3MYZ9rvxgLHy的请求：

{
    "rules": [
        {
            "state": "on",
            "rule": "Cookie JSESSIONID",
            "conditions": [
                {
                    "field": "Cookie",
                    "name": "JSESSIONID",
                    "pattern": "aaaROKLSA3MYZ9rvxgLHy"
                }
            ],
            "action": "deny",
            "autoIpBlock": "off",
            "ipBlockTimeout": 60,
            "description": "拦截JSESSIONID为aaaROKLSA3MYZ9rvxgLHy的请求"
        }
    ]
}

敏感数据过滤

开启敏感信息过滤后，Zhongkui-WAF将对响应数据进行过滤。

Zhongkui-WAF内置了对响应内容中的身份证号码、手机号码、银行卡号、密码信息进行脱敏处理。需注意，内置的敏感信息脱敏功能目前仅支持处理中国境内使用的数据格式（如身份证号、电话号码、银行卡号），暂不支持处理中国境外的相关数据格式。但你可以使用正则表达式配置不同规则，以过滤请求响应内容中任何你想要过滤的数据。

敏感信息过滤配置在sensitive.json文件中。

例如：

{
	"rules": [{
			"state": "on",
			"action": "coding",
			"codingRange": "4,-5",
			"rule": "(?:(?:\\+|00)86)?1(?:(?:3[\\d])|(?:4[5-79])|(?:5[0-35-9])|(?:6[5-7])|(?:7[0-8])|(?:8[\\d])|(?:9[189]))\\d{8}",
			"description": "mobile number"
		},
		{
			"state": "on",
			"action": "coding",
			"codingRange": "$1",
			"rule": "(?:password|passwd)\"\\s*[:=]\\s*\"(\\S+)\"",
			"description": "password"
		}
	],
	"words": ["fuck", "bitch", "balabala"]
}

action是匹配该规则后的响应动作，目前敏感信息过滤只有coding这一种有效，即对敏感信息脱敏处理。

rule是要处理的信息的匹配规则，通常是一个正则表达式。

codingRange是匹配到的字符串中要处理的子字符串范围，有两种形式：

  1. 直接标明要处理的子字符串的起始位置：
    1. 如字符串15800000000的codingRange为 "4,7"，则会将从第四个位置开始到第七个位置之间的所有字符进行处理，结果为158****0000。
    2. 起始位置也可以是一个负数，如字符串15800000000的codingRange为 "4,-5"，则会将从第四个位置开始到倒数第五个位置之间的所有字符进行处理，结果为158****0000。
  2. 使用$字面量加数字，比如：$0指的是由该模式匹配的整个子串，而$1指第一个带括号的捕获子串。

words是一个数组，可以用来配置一些需要过滤掉的关键词。

管理页面

安装配置完成后，浏览器访问http://localhost:1226，账号admin，默认密码为zhongkui。

从v1.2版本开始，一些数据统计依赖Mysql数据库，因此需要配置Mysql数据库并自行创建数据库(zhongkui_waf)，waf启动后，表结构会自动创建。

常见问题

一个常见问题是：用安装脚本安装后无法产生日志，在管理界面修改配置项，无法保存或可以保存但必须手动执行nginx -s reload才能生效，这些都是因为nginx默认是用nobody用户启动的，而nobody用户没有对日志目录和钟馗目录下的文件读写权限。

请确保Openresty对zhongkui-waf目录和OpenResty日志目录（\logs\hack）有读、写权限，否则WAF会无法修改配置文件和生成日志文件。最佳实践是：新建一个nginx用户，并将这个nginx用户添加到sudoers，允许其执行nginx命令，然后将zhongkui-waf目录所属用户改为nginx用户，最后修改nginx配置文件，以nginx用户启动nginx。

# 添加nginx用户
sudo useradd nginx
# 使用sudo visudo命令将下面这行规则添加进去，将nginx用户添加到sudoers，仅允许其执行nginx命令
# nginx ALL=NOPASSWD: /usr/local/openresty/nginx/sbin/nginx
# 修改zhongkui-waf和日志目录归属用户
sudo chown -R nginx:nginx /usr/local/openresty/zhongkui-waf
sudo chown -R nginx:nginx /usr/local/openresty/nginx/logs/hack

修改nginx.conf：

user nginx;

交流群

欢迎大家进群交流，如果遇到bug或有新的需求，请优先提交Issues。

QQ群：903430639

捐赠

如果你觉得这个项目还不错，点击这里或扫描下方二维码为作者买杯咖啡吧！

donate_wechat

版权和许可

ZhongKui-WAF 基于 Apache License, Version 2 授权。

版权所有 2023 bukale bukale2022@163.com

根据 Apache License, Version 2.0（以下简称"许可证"）获得许可； 除非遵守许可证，否则您不得使用此文件。 您可以在以下位置获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用法律要求或书面同意，否则根据许可证分发的软件是基于"按原样"分发的， 不附带任何明示或暗示的担保或条件。 有关许可证下的特定语言管理权限和限制，请参阅许可证。

相关项目
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手，通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能，支持100+编程语言，与主流编辑器无缝集成，显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台，能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐，Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

白日梦AI

白日梦AI提供专注于AI视频生成的多样化功能，包括文生视频、动态画面和形象生成等，帮助用户快速上手，创造专业级内容。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案，通过智能技术简化视频制作流程。无论是企业宣传还是个人分享，有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持，能够阅读和理解用户上传的文件内容，解析网页信息，并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题，Kimi都能以友好、专业的方式提供帮助。

Project Cover

讯飞绘镜

讯飞绘镜是一个支持从创意到完整视频创作的智能平台，用户可以快速生成视频素材并创作独特的音乐视频和故事。平台提供多样化的主题和精选作品，帮助用户探索创意灵感。

Project Cover

讯飞文书

讯飞文书依托讯飞星火大模型，为文书写作者提供从素材筹备到稿件撰写及审稿的全程支持。通过录音智记和以稿写稿等功能，满足事务性工作的高频需求，帮助撰稿人节省精力，提高效率，优化工作与生活。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术，为商家提供一键生成商品图和营销文案的服务，显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台，让商品第一时间被种草。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具，简化了选题、文献检索至论文撰写的整个过程。通过简单设定，平台可快速生成高质量论文大纲和全文，配合图表、参考文献等一应俱全，同时提供开题报告和答辩PPT等增值服务，保障数据安全，有效提升写作效率和论文质量。

使用协议隐私政策广告服务
投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号