From c4dd3942f42358e1003e95023492803d2cb888bf Mon Sep 17 00:00:00 2001 From: ADD-SP Date: Wed, 7 Apr 2021 00:15:23 +0800 Subject: [PATCH] :memo: Update docs. --- CHANGES-ZH-CN.md | 15 +++++++++ CHANGES.md | 14 ++++++++ docs/advance/changes.md | 14 ++++++++ docs/advance/issue.md | 10 ------ docs/advance/priority.md | 13 ++------ docs/advance/syntax.md | 60 +++++++--------------------------- docs/guide/overview.md | 5 --- docs/zh-cn/advance/changes.md | 19 ++++++++++- docs/zh-cn/advance/issue.md | 12 +------ docs/zh-cn/advance/priority.md | 12 ++----- docs/zh-cn/advance/syntax.md | 53 ++++-------------------------- docs/zh-cn/guide/overview.md | 6 ---- 12 files changed, 86 insertions(+), 147 deletions(-) diff --git a/CHANGES-ZH-CN.md b/CHANGES-ZH-CN.md index 322a30e3..50f71473 100644 --- a/CHANGES-ZH-CN.md +++ b/CHANGES-ZH-CN.md @@ -2,6 +2,21 @@ ## [未发布] + +### 新增 + + +### 移除 + + +### 变动 + + +### 修复 + + +## [5.0.0] - 2021-04-07 GMT+0800 + ### **警告** **此版本包含不兼容的更新（breaking changes）。** diff --git a/CHANGES.md b/CHANGES.md index a86615e9..5b83d1da 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,6 +2,20 @@ ## [Unreleased] +### Added + + +### Removed + + +### Changed + + +### Fixed + + +## [5.0.0] - 2021-04-07 GMT+0800 + ### **WARNING** **This version contains breaking changes.** diff --git a/docs/advance/changes.md b/docs/advance/changes.md index 6028b2c8..50b39b7a 100644 --- a/docs/advance/changes.md +++ b/docs/advance/changes.md @@ -7,6 +7,20 @@ lang: en ## [Unreleased] +### Added + + +### Removed + + +### Changed + + +### Fixed + + +## [5.0.0] - 2021-04-07 GMT+0800 + ### **WARNING** **This version contains breaking changes.** diff --git a/docs/advance/issue.md b/docs/advance/issue.md index 6392a2cc..c6d7841f 100644 --- a/docs/advance/issue.md +++ b/docs/advance/issue.md @@ -8,13 +8,3 @@ lang: en Bugs that exist in the latest stable release are listed here, bugs that have been fixed in the latest stable release are not listed here. -## segmentation fault - -When the number of worker processes in nginx is greater than one, the module will throw a segmentation fault. - -* Severity: Critical. -* Affected versions of ngx_waf: v3.1.0 ~ v4.1.0-beta.1 -* Status: Fixed -* Priority: Highest -* Note: It has been fixed in the latest development version. - diff --git a/docs/advance/priority.md b/docs/advance/priority.md index 60f6cd11..664fde07 100644 --- a/docs/advance/priority.md +++ b/docs/advance/priority.md @@ -9,9 +9,9 @@ There are many inspection process in this module, so it is important to specify The following is a list of all the tests in order of priority, from top to bottom. -1. CC protection -2. IP whitelist inspection -3. IP blacklist inspection +1. IP whitelist inspection +2. IP blacklist inspection +3. CC protection 4. Url whitelist inspection 5. Url blacklist inspection 6. Get parameter blacklist inspection @@ -27,10 +27,3 @@ The following is a list of all the tests in order of priority, from top to botto You can modify the priority through the configuration file, but the priority of the POST request body detection is not allowed to be modified, it will always have the lowest priority. See [waf_priority](syntax.md#waf-priority) for details ::: - - -::: tip CHANGES IN THE DEVELOPMENT VERSION - -Swaps the default priority of CC protection and IP whitelist inspection. - -::: diff --git a/docs/advance/syntax.md b/docs/advance/syntax.md index 767438f9..b258860c 100644 --- a/docs/advance/syntax.md +++ b/docs/advance/syntax.md @@ -52,12 +52,13 @@ Specify the working mode of the firewall, specifying at least one mode and up to * UA: Enable UA inspecting rules. * COOKIE: Enable COOKIE inspecting rules. * REFERER: Enable REFERER inspecting rules. -* CC: Enable 'Anti Challenge Collapsar'. When you enable this mode, you must set [waf_cc_deny_limit](#waf-cc-deny-limit). +* CC: Enable 'Anti Challenge Collapsar'. When you enable this mode, you must set [waf_cc_deny](#waf-cc-deny). * COMPAT: compatibility mode, used to enable compatibility options with other modules or environments, currently used for compatibility with the ngx_http_rewrite_module, see [compatibility statement](/guide/compatibility.md). * STRICT: Strict mode, which sacrifices some performance for more checks, currently only works when `COMPAT` mode is enabled, and performs a full round of inspections before and after the ngx_http_rewrite_module takes effect. -* STATIC: working mode for static sites, equivalent to `HEAD GET IP URL UA CC`. -* DYNAMIC: working mode for dynamic sites, equivalent to `HEAD GET POST IP URL ARGS UA RBODY COOKIE CC`. -* STD: Equivalent to `HEAD GET POST IP URL RBODY ARGS UA CC COMPAT`. +* CACHE: Enable caching. Enabling this mode will cache the result of the inspection, so that the next time the same target is inspected, there is no need to repeat the inspection. However, the results of the POST body inspection are not cached. For example, if a URL is not in the blacklist after inspection, the next time the same URL is inspected, the cache can be read directly. When you enable this mode, you must set [waf_cache](#waf-cache). +* STD: Standard working mode, equivalent to `HEAD GET POST IP URL RBODY ARGS UA CC COMPAT CACHE`. +* STATIC: working mode for static sites, equivalent to `HEAD GET IP URL UA CC CACHE`. +* DYNAMIC: working mode for dynamic sites, equivalent to `HEAD GET POST IP URL ARGS UA RBODY COOKIE CC COMPAT CACHE`. * FULL: Enable all modes. You can turn off a mode by prefixing a `mode_type` with `! ` prefix to a `mode_type` to turn it off. @@ -73,35 +74,8 @@ The mode of `CC` is independent of other modes, and whether it takes effect or n ::: -::: tip CHANGES IN THE DEVELOPMENT VERSION - -Added a new mode: -* CACHE: Enable caching. Enabling this mode will cache the result of the inspection, so that the next time the same target is inspected, there is no need to repeat the inspection. However, the results of the POST body inspection are not cached. For example, if a URL is not in the blacklist after inspection, the next time the same URL is inspected, the cache can be read directly. When you enable this mode, you must set [waf_cache_size](#waf-cache-size). - -The following modes have changed: - -* STD: Standard working mode, equivalent to `HEAD GET POST IP URL RBODY ARGS UA CC COMPAT CACHE`. -* STATIC: working mode for static sites, equivalent to `HEAD GET IP URL UA CC CACHE`. -* DYNAMIC: working mode for dynamic sites, equivalent to `HEAD GET POST IP URL ARGS UA RBODY COOKIE CC COMPAT CACHE`. - -::: - - -## `waf_cc_deny_limit` - -* syntax: waf_cc_deny_limit \<*rate*\> \<*duration*\> \[*buffer_size*\] -* default: — -* context: server - -Set the parameters related to CC protection. - -* `rate`:Indicates the maximum number of requests per minute (an integer greater than zero). -* `duration`:Indicates how many minutes (an integer greater than zero) to pull the IP after exceeding the limit of the first parameter `rate`. -* `buffer_size`: used to set the size of the memory for recording IP accesses, such as `10m`, `10240k`, must not be less than `10m`, if not specified then the default is `10m`. - - -::: tip CHANGES IN DEVELOPMENT +## `waf_cc_deny` * syntax: waf_cc_deny \ \[duration=*1h*\] \[size=*20m*\] * default: — @@ -109,14 +83,11 @@ Set the parameters related to CC protection. Set the parameters related to CC protection. -* `rate`: indicates the maximum number of requests per minute, e.g. `60r/m` means the maximum number of requests per minute is 60. Exceeding the limit returns a [503 status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) with a [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) response header. -* `duration`: indicates the IP band oh after exceeding the limit of the first parameter `rate`, such as `60s`, `60m`, `60h` and `60d`, if not specified, the default is `1h`. +* `rate`: Indicates the maximum number of requests per minute, e.g. `60r/m` means the maximum number of requests per minute is 60. Exceeding the limit returns a [503 status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) with a [Retry-After](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Retry-After) response header. +* `duration`: Indicates the time to block IP after exceeding the limit of the first parameter `rate`, such as `60s`, `60m`, `60h` and `60d`, if not specified, the default is `1h`. * `size`: Used to set the size of the memory for recording IP accesses, such as `20m`, `2048k`, must not be less than `20m`, if not specified, the default is `20m`. -::: - - ## `waf_cache` @@ -126,18 +97,9 @@ Set the parameters related to CC protection. Set the parameters related to cache rule inspection results. -* `capacity`: for some inspection items with caching mechanism enabled, the maximum number of inspection results per inspection item to be cached for each inspection target. -* `interval`: set the period of the batch cull cache in minutes, such as `60s`, `60m`, `60h` and `60d`, or `1h` if not specified. If not specified, the default is `1h`, which is one hour. -* `percent`: what percentage of the cache is eliminated each time the batch eliminates the cache. Specify an integer greater than 0 and less than or equal to 100. A setting of 50 means that half of the cache is eliminated. If not specified, the default is `50`. - - -::: warning WARNING - -This configuration is a new feature in the development version, -and can only be used in the development version, -and will be merged into the stable version when it is stable. - -::: +* `capacity`: For some inspection items with caching mechanism enabled, the maximum number of inspection results per inspection item to be cached for each inspection target. +* `interval`: Set the period of the batch cull cache in minutes, such as `60s`, `60m`, `60h` and `60d`, or `1h` if not specified. If not specified, the default is `1h`, which is one hour. +* `percent`: What percentage of the cache is eliminated each time the batch eliminates the cache. Specify an integer greater than 0 and less than or equal to 100. A setting of 50 means that half of the cache is eliminated. If not specified, the default is `50`. ::: tip Cache-enabled inspections diff --git a/docs/guide/overview.md b/docs/guide/overview.md index 2e973666..ad1b121f 100644 --- a/docs/guide/overview.md +++ b/docs/guide/overview.md @@ -7,11 +7,6 @@ lang: en A web application firewall module for nginx without complex configuration. -::: danger CRITICAL BUG - -When the number of worker processes in nginx is greater than one, the current stable version of the module will throw a segment error. Please use the latest development version. - -::: ## Function diff --git a/docs/zh-cn/advance/changes.md b/docs/zh-cn/advance/changes.md index 2b7242ee..dcd27706 100644 --- a/docs/zh-cn/advance/changes.md +++ b/docs/zh-cn/advance/changes.md @@ -7,6 +7,21 @@ lang: zh-CN ## [未发布] + +### 新增 + + +### 移除 + + +### 变动 + + +### 修复 + + +## [5.0.0] - 2021-04-07 GMT+0800 + ### **警告** **此版本包含不兼容的更新（breaking changes）。** @@ -35,6 +50,7 @@ lang: zh-CN * 修复了当 worker 进程数量大于一时的段错误。 +* 修复了 CC 防护统计有时不准的错误。 *** @@ -370,4 +386,5 @@ lang: zh-CN * IPV4 黑白名单功能失效（[231f94a](https://github.com/ADD-SP/ngx_waf/commit/231f94aa5383fe8f6cdc0fbc3cd2dcadb7606881)）。 * 当 User-agent 为空时会触发 segmentation fault（[bf33b36](https://github.com/ADD-SP/ngx_waf/commit/bf33b366232b7f5e05379d5e10ab006696189ea6)）。 -* 启用 CC 防御后会有内存泄漏（[be58d18](https://github.com/ADD-SP/ngx_waf/commit/be58d189b4c95be066623604124b02a9bf174e7f)）。 \ No newline at end of file +* 启用 CC 防御后会有内存泄漏（[be58d18](https://github.com/ADD-SP/ngx_waf/commit/be58d189b4c95be066623604124b02a9bf174e7f)）。 + diff --git a/docs/zh-cn/advance/issue.md b/docs/zh-cn/advance/issue.md index 7b71a3a9..3b6e8bb2 100644 --- a/docs/zh-cn/advance/issue.md +++ b/docs/zh-cn/advance/issue.md @@ -5,14 +5,4 @@ lang: zh-CN # 已知问题 -这里只会列出存在于最新的稳定版的问题，已经在最新的稳定版中修复的问题不会列出。 - -## 段错误 - -当 nginx 的 worker 进程数量大于一时，模块会出现段错误。 - -* 严重性：致命性错误 -* 受影响的 ngx_waf 版本：v3.1.0 ~ v4.1.0-beta.1 -* 状态：已修复 -* 优先级：最高 -* 备注：已经在最新的开发版中修复。 \ No newline at end of file +这里只会列出存在于最新的稳定版的问题，已经在最新的稳定版中修复的问题不会列出。 \ No newline at end of file diff --git a/docs/zh-cn/advance/priority.md b/docs/zh-cn/advance/priority.md index 7ee57a38..07a5ac35 100644 --- a/docs/zh-cn/advance/priority.md +++ b/docs/zh-cn/advance/priority.md @@ -9,9 +9,9 @@ lang: zh-CN 下面将按照优先级从高到底地列出所有的检测项目。 -1. CC 防御检测 -2. IP 白名单检测 -3. IP 黑名单检测 +1. IP 白名单检测 +2. IP 黑名单检测 +3. CC 防御检测 4. Url 白名单检测 5. Url 黑名单检测 6. Get 参数黑名单检测 @@ -27,9 +27,3 @@ lang: zh-CN 您可以通过配置文件修改优先级，但是 POST 请求体检测的优先级不允许修改，它的优先级永远是最低的。详见 [waf_priority](syntax.md#waf-priority)。 ::: - -::: tip 开发版中的变动 - -互换了 CC 防护和 IP 白名单检测的默认优先级。 - -::: diff --git a/docs/zh-cn/advance/syntax.md b/docs/zh-cn/advance/syntax.md index 427ffb15..2f517c18 100644 --- a/docs/zh-cn/advance/syntax.md +++ b/docs/zh-cn/advance/syntax.md @@ -52,12 +52,13 @@ lang: zh-CN * UA: 启用 user-agent 的检查规则。 * COOKIE: 启用 cookie 的检查规则。 * REFERER: 启用 referer 的检查规则。 -* CC: 启用 CC 防御。当你启用了此模式，你必须设置 [waf_cc_deny_limit](#waf-cc-deny-limit)。 +* CC: 启用 CC 防御。当你启用了此模式，你必须设置 [waf_cc_deny](#waf-cc-deny)。 * COMPAT：兼容模式，用来启用一些兼容性选项去兼容其它的模块或者环境，目前用于兼容 ngx_http_rewrite_module，详见[兼容性说明](/zh-cn/guide/compatibility.md)。 * STRICT：严格模式，牺牲一些性能进行更多的检查，目前仅在启用了 `COMPAT` 模式时生效，在 ngx_http_rewrite_module 生效前和生效后都进行一轮完整的检查。 -* STD: 标准工作模式，等价于 `HEAD GET POST IP URL RBODY ARGS UA CC COMPAT`。 -* STATIC：适用于静态站点的工作模式，等价于 `HEAD GET IP URL UA CC`。 -* DYNAMIC：适用于动态站点的工作模式，等价于 `HEAD GET POST IP URL ARGS UA RBODY COOKIE CC COMPAT`。 +* CACHE：启用缓存。启用此模式后会缓存检查的结果，下次检查相同的目标时就不需要重复检查了。不过不会缓存 POST 体的检查结果。比如一个 URL 经过检查后并没有在黑名单中，那么下次检查相同的 URL 时就无需再次检查 URL 黑名单了。当你启用了此模式，你必须设置 [waf_cache](#waf-cache)。 +* STD：标准工作模式，等价于 `HEAD GET POST IP URL RBODY ARGS UA CC COMPAT CACHE`。 +* STATIC：适用于静态站点的工作模式，等价于 `HEAD GET IP URL UA CC CACHE`。 +* DYNAMIC：适用于动态站点的工作模式，等价于 `HEAD GET POST IP URL ARGS UA RBODY COOKIE CC COMPAT CACHE`。 * FULL: 启用所有的模式。 您可以通过在某个 `mode_type` 前增加 `!` 前缀来关闭该模式，下面是一个例子。 @@ -74,33 +75,7 @@ waf_mode STD !UA; ::: -::: tip 开发版中的变动 - -增加了一个的模式： - -* CACHE：启用缓存。启用此模式后会缓存检查的结果，下次检查相同的目标时就不需要重复检查了。不过不会缓存 POST 体的检查结果。比如一个 URL 经过检查后并没有在黑名单中，那么下次检查相同的 URL 时就无需再次检查 URL 黑名单了。当你启用了此模式，你必须设置 [waf_cache_size](#waf-cache-size)。 - -下列模式有变化： - -* STD：标准工作模式，等价于 `HEAD GET POST IP URL RBODY ARGS UA CC COMPAT CACHE`。 -* STATIC：适用于静态站点的工作模式，等价于 `HEAD GET IP URL UA CC CACHE`。 -* DYNAMIC：适用于动态站点的工作模式，等价于 `HEAD GET POST IP URL ARGS UA RBODY COOKIE CC COMPAT CACHE`。 - -::: - -## `waf_cc_deny_limit` - -* 配置语法: waf_cc_deny \<*rate*\> \<*duration*\> \[*buffer_size*\]` -* 默认配置：— -* 配置段: server - -设置 CC 防护相关的参数。 - -* `rate`：表示每分钟的最多请求次数（大于零的整数）。 -* `duration`：表示超出第一个参数 `rate` 的限制后拉黑 IP 多少分钟（大于零的整数）. -* `buffer_size`：用于设置记录 IP 访问次数的内存的大小，如 `10m`、`10240k`，不得小于 `10m`，如不指定则默认为 `10m`。 - -::: tip 开发版中的变动 +## `waf_cc_deny` * 配置语法: waf_cc_deny \ \[duration=*1h*\] \[size=*20m*\] * 默认配置：— @@ -109,11 +84,10 @@ waf_mode STD !UA; 设置 CC 防护相关的参数。 * `rate`：表示每分钟的最多请求次数，如 `60r/m` 表示每分钟最多请求 60 次。超出限制后会返回 [503 状态码](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status/503)，并附带 [Retry-After](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Retry-After) 响应头。 -* `duration`：表示超出第一个参数 `rate` 的限制后拉黑 IP 带哦就，如 `60s`、`60m`、`60h` 和 `60d`，如不指定则默认为 `1h`。 +* `duration`：表示超出第一个参数 `rate` 的限制后拉黑 IP 的时间，如 `60s`、`60m`、`60h` 和 `60d`，如不指定则默认为 `1h`。 * `size`：用于设置记录 IP 访问次数的内存的大小，如 `20m`、`2048k`，不得小于 `20m`，如不指定则默认为 `20m`。 -::: ## `waf_cache` @@ -128,12 +102,6 @@ waf_mode STD !UA; * `percent`：每次批量淘汰缓存时淘汰掉多少比例的缓存。需要指定一个大于 0 小于等于 100 的整数。若设置为 50 则代表淘汰掉一半的缓存。如不指定则默认为 `50`。 -::: warning 警告 - -本配置属于开发版新增的功能，只能在开发版中使用，等稳定后会合并到稳定版中。 - -::: - ::: tip 启用了缓存机制的检测项目 @@ -167,13 +135,6 @@ waf_mode STD !UA; * `REFERER`：Referer 黑名单检测 * `COOKIE`：Cookie 黑名单检测 - -::: warning 警告 - -本配置属于开发版新增的功能，只能在开发版中使用，等稳定后会合并到稳定版中。 - -::: - ::: warning 警告 `str` 必须使用单引号或者双引号包裹，且 `str` 必须包含全部的检测项目。 diff --git a/docs/zh-cn/guide/overview.md b/docs/zh-cn/guide/overview.md index b50d9444..b56208b8 100644 --- a/docs/zh-cn/guide/overview.md +++ b/docs/zh-cn/guide/overview.md @@ -7,12 +7,6 @@ lang: zh-CN 一个用于 nginx 的没有复杂配置的 Web 应用防火墙模块。 -::: danger 重大缺陷 - -当 nginx 的 worker 进程数量大于一时，当前稳定版的模块会出现段错误。请使用最新的开发版。 - -::: - ## 功能 * 支持 IPV4 和 IPV6。