Skip to content

Commit 965a106

Browse files
author
zhaohaifeng [赵海锋]
committed
commit docs
0 parents  commit 965a106

File tree

6 files changed

+375
-0
lines changed

6 files changed

+375
-0
lines changed

‎.vscode/.browse.VC.db‎

1 KB
Binary file not shown.

‎.vscode/.browse.VC.db-wal‎

332 KB
Binary file not shown.

‎TOC.ini‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
-: intro
2+
-: faqs
3+
4+
[intro]
5+
-: README
6+
-: installation
7+
-: getting_started
8+
9+
[faqs]
10+
-: README

‎zh-CN/intro/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
name: 简介
3+
---
4+
5+
# xsec-waf
6+
7+
xsec-waf是一款适用小企业的云waf系统。
8+
9+
# 主要特性
10+
11+
- 安装、部署与维护非常简单，小企业也可以非常方便地拥有自己的云WAF
12+
- 规则可以后台管理
13+
- 后端服务器可以后端管理
14+
- 支持IP和URL的黑白名单
15+
- 支持对get\post\cookies\user_agent参数进行过滤
16+
- 多台waf的配置可自动同步
17+
18+
# 架构
19+
xsec-waf由waf与Waf管理后台组成：
20+
21+
- waf是基于openresty + lua开发的
22+
- waf管理后台是采用golang + xorm + macrom开发的

‎zh-CN/intro/getting_started.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
name: 开始使用
3+
---
4+
5+
## 后端服务器管理
6+
当多台waf做负载均衡时，也只需登录其中一台进行管理即可，所有的配置信息会自动同步到所有的服务器中。
7+
管理地址为：http://ip:5000/login/，默认账户及口令为：admin，[email protected]，请管理员登录系统后第一时间修改密码。
8+
9+
### 新增站点
10+
在`Site Manager`选项中，可以新增一个后端服务器，需要填写以下内容：
11+
- Site Name，表示要加入waf的网站的域名
12+
- 80表示该网站监听的端口
13+
- Backend，表示有多少个后台app server，可以写多个（换行分割），例如：
14+
```bash
15+
1.1.1.1:80
16+
8.8.8.8:80
17+
```
18+
- SSL Status，表示是否启用ssl，参数为on或off（如果要启用的话，需要在nginx中配置有效的证书）
19+
- Debug Level，表示日志级别，可选的参数有`debug, info, notice, warn, error, crit, alert, emerg`
20+
21+
### 站点配置同步
22+
新增站点后，需要在后台同步站点信息后方可生效，同步的方式有2种：
23+
1. 全部同步
24+
1. 针对某一新增的站点进行同步
25+
26+
## waf规则管理
27+
在`waf Rules`选项中，可以修改waf的规则，修改完后可以点击“同步全部策略”按钮，将最新的规则同步到所有的服务器并让openresty重新加载。

‎zh-CN/intro/installation.md‎

Lines changed: 316 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,316 @@
1+
---
2+
name: 安装与部署
3+
---
4+
5+
# 下载安装
6+
## waf安装
7+
### centos平台
8+
9+
从[openresty](http://openresty.org/en/download.html)官方下载最新版本的源码包。
10+
11+
编译安装openresty：
12+
13+
```bash
14+
yum -y install pcre pcre-devel
15+
wget https://openresty.org/download/openresty-1.9.15.1.tar.gz
16+
tar -zxvf openresty-1.9.15.1.tar.gz
17+
cd openresty-1.9.15.1
18+
./configure
19+
gmake && gmake install
20+
21+
/usr/local/openresty/nginx/sbin/nginx -t
22+
nginx: the configuration file /usr/local/openresty/nginx/conf/nginx.conf syntax is ok
23+
nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful
24+
/usr/local/openresty/nginx/sbin/nginx
25+
```
26+
27+
安装luarocks
28+
29+
```bash
30+
wget http://keplerproject.github.io/luarocks/releases/luarocks-2.3.0.tar.gz
31+
tar -zxvf luarocks-2.3.0.tar.gz
32+
cd luarocks-2.3.0
33+
./configure --prefix=/usr/local/openresty/luajit \
34+
--with-lua=/usr/local/openresty/luajit/ \
35+
--lua-suffix=jit-2.1.0-beta2 \
36+
--with-lua-include=/usr/local/openresty/luajit/include/luajit-2.1
37+
make build && make install
38+
yum -y install sqlite sqlite-devel unzip
39+
/usr/local/openresty/luajit/bin/luarocks install luafilesystem
40+
```
41+
42+
### ubuntu平台安装
43+
44+
编译安装openresty：
45+
46+
```bash
47+
apt-get install libreadline-dev libncurses5-dev libpcre3-dev libssl-dev perl make build-essential
48+
sudo ln -s /sbin/ldconfig /usr/bin/ldconfig
49+
wget https://openresty.org/download/openresty-1.9.15.1.tar.gz
50+
tar -zxvf openresty-1.9.15.1.tar.gz
51+
cd openresty-1.9.15.1
52+
make && sudo make install
53+
```
54+
安装luarocks
55+
```bash
56+
wget http://keplerproject.github.io/luarocks/releases/luarocks-2.3.0.tar.gz
57+
tar -zxvf luarocks-2.3.0.tar.gz
58+
cd luarocks-2.3.0
59+
./configure --prefix=/usr/local/openresty/luajit \
60+
--with-lua=/usr/local/openresty/luajit/ \
61+
--lua-suffix=jit-2.1.0-beta2 \
62+
--with-lua-include=/usr/local/openresty/luajit/include/luajit-2.1
63+
make build && make install
64+
yum -y install sqlite sqlite-devel unzip
65+
/usr/local/openresty/luajit/bin/luarocks install luafilesystem
66+
```
67+
## 安装waf管理后台xsec-waf-web
68+
### 二进制安装
69+
直接从github中下载二进制版本
70+
71+
### 源码安装
72+
73+
- 首先需要搭建好go语言开发环境，可以参考[Go Web 编程](https://github.com/astaxie/build-web-application-with-golang/blob/master/zh/01.1.md)
74+
- 安装依赖包
75+
76+
```bash
77+
go get gopkg.in/macaron.v1
78+
go get gopkg.in/ini.v1
79+
go get github.com/go-sql-driver/mysql
80+
go get github.com/go-xorm/xorm
81+
82+
```
83+
84+
- 从github中下载最新的版本
85+
- 执行go build server.go编译出二进制版本，然后将server、conf、publib和templates目录一起打包上传到服务器中即可。
86+
87+
# 部署与配置
88+
## waf部署与配置
89+
### nginx的配置
90+
- 将xsec-waf的代码目录`waf`放置到openresty的`/usr/local/openresty/nginx/conf`目录下；
91+
- 在nginx的conf的目录下新建vhosts目录
92+
93+
```bash
94+
mkdir -p /usr/local/openresty/nginx/conf/vhosts
95+
```
96+
- nginx.conf的配置可以参考以下：
97+
98+
```ini
99+
user nginx;
100+
worker_processes auto;
101+
worker_cpu_affinity auto;
102+
103+
#error_log logs/error.log;
104+
#error_log logs/error.log debug;
105+
#error_log logs/error.log info;
106+
107+
#pid logs/nginx.pid;
108+
109+
events {
110+
worker_connections 409600;
111+
}
112+
113+
http {
114+
include mime.types;
115+
default_type application/octet-stream;
116+
117+
lua_package_path "/usr/local/openresty/nginx/conf/waf/code/?.lua;/usr/local/lib/lua/?.lua;;";
118+
lua_shared_dict limit 100m;
119+
lua_shared_dict badGuys 100m;
120+
lua_code_cache on;
121+
init_by_lua_file /usr/local/openresty/nginx/conf/waf/code/init.lua;
122+
access_by_lua_file /usr/local/openresty/nginx/conf/waf/code/access.lua;
123+
124+
#log_format shield_access '$remote_addr - $http_host - "$request" - "$http_cookie"';
125+
#access_log pipe:/usr/local/shield/redisclient shield_access;
126+
127+
#ssl on;
128+
#ssl_certificate certs/cert_chain.crt;
129+
#ssl_certificate_key certs/server.key;
130+
ssl_session_timeout 5m;
131+
ssl_protocols SSLv2 SSLv3 TLSv1;
132+
ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP;
133+
ssl_prefer_server_ciphers on;
134+
135+
136+
sendfile on;
137+
#tcp_nopush on;
138+
139+
#keepalive_timeout 0;
140+
keepalive_timeout 65;
141+
142+
#gzip on;
143+
include vhosts/*.conf;
144+
}
145+
```
146+
### waf的配置
147+
waf的配置文件位于`/usr/local/openresty/nginx/conf/waf/config.lua`中，详细的配置项如下：
148+
149+
```lua
150+
--WAF config file, enable = "on", disable = "off"
151+
local _M = {
152+
--waf status
153+
config_waf_enable = "on",
154+
--log dir
155+
config_log_dir = "/tmp/waf_logs",
156+
--rule setting
157+
config_rule_dir = "/usr/local/openresty/nginx/conf/waf/rules",
158+
--enable/disable white url
159+
config_white_url_check = "on",
160+
--enable/disable white ip
161+
config_white_ip_check = "on",
162+
--enable/disable block ip
163+
config_black_ip_check = "on",
164+
--enable/disable url filtering
165+
config_url_check = "on",
166+
--enalbe/disable url args filtering
167+
config_url_args_check = "on",
168+
--enable/disable user agent filtering
169+
config_user_agent_check = "on",
170+
--enable/disable cookie deny filtering
171+
config_cookie_check = "on",
172+
--enable/disable cc filtering
173+
config_cc_check = "on",
174+
--cc rate the xxx of xxx seconds
175+
config_cc_rate = "10/60",
176+
--enable/disable post filtering
177+
config_post_check = "on",
178+
--config waf output redirect/html/jinghuashuiyue
179+
config_waf_model = "html",
180+
--if config_waf_output ,setting url
181+
config_waf_redirect_url = "http://xsec.io",
182+
config_expire_time = 600,
183+
config_output_html=[[
184+
<html >
185+
<head>
186+
<meta charset="UTF-8">
187+
<title>xsec waf</title>
188+
<style type="text/css">
189+
body {
190+
font-family: "Helvetica Neue", Helvetica, Arial;
191+
font-size: 14px;
192+
line-height: 20px;
193+
font-weight: 400;
194+
color: #3b3b3b;
195+
-webkit-font-smoothing: antialiased;
196+
font-smoothing: antialiased;
197+
background: #f6f6f6;
198+
}
199+
.wrapper {
200+
margin: 0 auto;
201+
padding: 40px;
202+
max-width: 980px;
203+
}
204+
.table {
205+
margin: 0 0 40px 0;
206+
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
207+
display: table;
208+
}
209+
@media screen and (max-width: 580px) {
210+
.table {
211+
display: block;
212+
}
213+
}
214+
.row {
215+
display: table-row;
216+
background: #f6f6f6;
217+
}
218+
.row:nth-of-type(odd) {
219+
background: #e9e9e9;
220+
}
221+
.row.header {
222+
font-weight: 900;
223+
color: #ffffff;
224+
background: #ea6153;
225+
}
226+
.row.green {
227+
background: #27ae60;
228+
}
229+
.row.yellow {
230+
background: #FF8C00;
231+
}
232+
@media screen and (max-width: 580px) {
233+
.row {
234+
padding: 8px 0;
235+
display: block;
236+
}
237+
}
238+
.cell {
239+
padding: 6px 12px;
240+
display: table-cell;
241+
}
242+
@media screen and (max-width: 580px) {
243+
.cell {
244+
padding: 2px 12px;
245+
display: block;
246+
}
247+
}
248+
</style>
249+
</head>
250+
<body>
251+
<div class="wrapper">
252+
<div class="table">
253+
<div class="row header yellow">
254+
<div class="cell">
255+
您的IP为 %s
256+
</div>
257+
<div class="cell">
258+
欢迎在遵守白帽子道德准则的情况下进行安全测试。
259+
</div>
260+
<div class="cell">
261+
联系方式：[email protected]
262+
</div>
263+
</div>
264+
</div>
265+
266+
</div>
267+
</body>
268+
</html>
269+
]],
270+
}
271+
return _M
272+
```
273+
274+
- waf启动测试，如果测试返回ok则表示配置正确
275+
```bash
276+
$ sudo /usr/local/openresty/nginx/sbin/nginx -t
277+
[sudo] hartnett 的密码：
278+
nginx: the configuration file /usr/local/openresty/nginx/conf/nginx.conf syntax is ok
279+
nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful
280+
```
281+
282+
- 启动waf
283+
284+
```bash
285+
$ sudo /usr/local/openresty/nginx/sbin/nginx
286+
```
287+
288+
- waf有效性测试。
289+
290+
在服务器中提交`curl http://127.0.0.1/\?id\=1%20union%20select%201,2,3`，
291+
如果返回` 欢迎在遵守白帽子道德准则的情况下进行安全测试`就表示waf已经正常运行了。
292+
293+
## waf-admin的配置
294+
- waf-admin需要mysql的支持，事先需要准备一个mysql数据库的账户，以下为详细的配置信息
295+
296+
```ini
297+
RUN_MODE = dev
298+
;RUN_MODE = prod
299+
300+
[server]
301+
HTTP_PORT = 5000
302+
API_KEY = xsec.io||secdevops.cn
303+
NGINX_BIN = /usr/local/openresty/nginx/sbin/nginx
304+
NGINX_VHOSTS = /usr/local/openresty/nginx/conf/vhosts/
305+
API_SERVERS = 127.0.0.1, 8.8.8.8
306+
307+
[database]
308+
USER = waf-admin
309+
PASSWD = passw0rd
310+
HOST = mysqlhost:3306
311+
NAME = waf
312+
313+
[waf]
314+
RULE_PATH = /usr/local/openresty/nginx/conf/waf/rules/
315+
```
316+
- 然后在当前目录执行./server测试程序是否可以正常启动，如可以正常启动，则可能通过supversisor、nohup、systemd等将server跑在后台。

0 commit comments

Comments
 (0)