-
Notifications
You must be signed in to change notification settings - Fork 38
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
76 changed files
with
499 additions
and
451 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,177 +1,252 @@ | ||
| # Directives | ||
| # **Naxsi Directives** | ||
|
|
||
| ## DeniedUrl | ||
| * alias: denied_url | ||
| * context: location | ||
| This section explains all the directives, with examples, that are available when the Naxsi module (`ngx_http_naxsi_module.so`) is enabled. | ||
|
|
||
| `DeniedUrl` is a directive that indicates where naxsi will redirect (nginx's internal redirect) blocked requests. | ||
| ## **SecRulesEnabled** | ||
|
|
||
| As the request might be modified during redirect (url & arguments), extra http headers orig_url (original url), | ||
| orig_args (original GET args) and naxsi_sig (NAXSI_FMT) are added. | ||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| The headers that are forwarded to the location denied page are : | ||
| This directive is mandatory to `enable` naxsi in a NGINX `location`. | ||
|
|
||
| NAXSI_HEADER_ORIG_URL "x-orig_url" | ||
| NAXSI_HEADER_ORIG_ARGS "x-orig_args" | ||
| NAXSI_HEADER_NAXSI_SIG "x-naxsi_sig" | ||
| ### Example: | ||
|
|
||
| example: | ||
| ``` | ||
| location / { | ||
| ... | ||
| DeniedUrl "/RequestDenied"; | ||
| SecRulesEnabled; | ||
| } | ||
| ``` | ||
|
|
||
| location /RequestDenied { | ||
| return 418; #I'm a teapot | ||
| ## **CheckRule** | ||
|
|
||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| This directive is required to instruct Naxsi on which action to take when there is a rule match. | ||
|
|
||
| The directive requires you to specify a **score** with a variable name and its min/max value (for example `$FOO_BAR >= 4`); the score is then followed by an action to take (`LOG`, `BLOCK`, `DROP`, or `ALLOW`) when is met. | ||
|
|
||
| > 📣 Important | ||
| > | ||
| > Score variable names must starts with a "dollar sign" `$` and can contains "underscores" `_`. | ||
| > ⚠️ Warning | ||
| > | ||
| > The action `BLOCK` will behave like `DROP` only when `LearningMode` is not enabled. | ||
| ### Example: | ||
|
|
||
| ``` | ||
| location / { | ||
| CheckRule "$FOO_UU >= 8" LOG; | ||
| CheckRule "$BARRRR < 99" DROP; | ||
| CheckRule "$SOMETHING <= 33" BLOCK; | ||
| } | ||
| ``` | ||
|
|
||
| ## LearningMode | ||
| * alias: learning_mode | ||
| * context: location | ||
| ## **LibInjectionXss** | ||
|
|
||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| `LearningMode` if instructs naxsi to enable learning mode (don't honor `BLOCK` directive) in the location. | ||
| When defined, this directive enables [libinjection's](https://github.com/libinjection/libinjection) xss detection on *all* requests. | ||
|
|
||
| For example: | ||
| > 📣 Important | ||
| > | ||
| > The detected XSS will increase the score `$LIBINJECTION_XSS` by `1` for each match; this means that is required to define `$LIBINJECTION_XSS` as a `CheckRule`. | ||
| ```nginx | ||
| location /a { | ||
| # request triggering BLOCK score won't be blocked here, but simply logued. | ||
| LearningMode; | ||
| ### Example: | ||
|
|
||
| ``` | ||
| location / { | ||
| # enable libinjection xss | ||
| LibInjectionXss; | ||
| # define LIBINJECTION_XSS for libinjection | ||
| CheckRule "$LIBINJECTION_XSS >= 8" BLOCK; | ||
| } | ||
| ``` | ||
|
|
||
| Keep in mind that internal rules (those with an `id` inferior to 1000) will drop the request even in learning mode, because it means that something fishy is going on, since naxsi can't correctly process the request. | ||
| You can of course apply [whitelist](whitelists-bnf.md) if those are false-positives. | ||
| ## **LibInjectionSql** | ||
|
|
||
| ## SecRulesEnabled | ||
| * alias: rules_enabled | ||
| * context: location | ||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| `SecRulesEnabled` is a mandatory keyword to enable naxsi in a location. | ||
| When defined, this directive enables [libinjection's](https://github.com/libinjection/libinjection) sqli detection on *all* requests. | ||
|
|
||
| ## SecRulesDisabled | ||
| * alias: rules_disabled | ||
| * context: location | ||
| > 📣 Important | ||
| > | ||
| > The detected SQLi will increase the score `$LIBINJECTION_SQL` by `1` for each match; this means that is required to define `$LIBINJECTION_SQL` as a `CheckRule`. | ||
| `SecRulesDisabled` can be used to explicitely disable naxsi in a location. | ||
| ### Example: | ||
|
|
||
| ## CheckRule | ||
| * alias: check_rule | ||
| * context: location | ||
| ``` | ||
| location / { | ||
| # enable libinjection sqli | ||
| LibInjectionSql; | ||
| # define LIBINJECTION_SQL for libinjection | ||
| CheckRule "$LIBINJECTION_SQL >= 8" BLOCK; | ||
| } | ||
| ``` | ||
|
|
||
| See [CheckRule](checkrules-bnf.md) | ||
| ## **LearningMode** | ||
|
|
||
| ## BasicRule | ||
| * alias: basic_rule | ||
| * context: location | ||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| A directive used to declare a [rule](rules-bnf.md) or a [whitelist](whitelist-bnf.md). | ||
| This directive instructs Naxsi that to not honor `CheckRules` which defines actions as `BLOCK` in a NGINX `location`. | ||
|
|
||
| ## MainRule | ||
| * alias: main_rule | ||
| * context: http | ||
| All the `BLOCK` actions will be interpreted as `LOG`; this is a useful mode when deploying a new web application and detect all false positives that might be generated by the WAF. | ||
|
|
||
| A directive used to declare a [rule](rule-bnf.md) or a [whitelist](whitelist-bnf.md). | ||
| > 📣 Important | ||
| > | ||
| > Keep in mind that internal rules (those with an `id` inferior to 1000) will drop the request even in learning mode, because it means something fishy is going on and Naxsi can't correctly process the request. You can of course apply whitelists if those are false positives. | ||
| ## LibInjectionXss | ||
| * alias: libinjection_xss | ||
| * context: location | ||
| ### Example: | ||
|
|
||
| A directive to enable [libinjection's xss detection](libinjection-integration.md) on *all* part of the http request. | ||
| ``` | ||
| location / { | ||
| # enable Naxsi learning mode | ||
| LearningMode; | ||
| } | ||
| ``` | ||
|
|
||
| ## LibInjectionSql | ||
| * alias: libinjection_sql | ||
| * context: location | ||
| ## **DeniedUrl** | ||
|
|
||
| A directive to enable [libinjection's sqli detection](libinjection-integration.md) on *all* part of the http request. | ||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| ## naxsi_extensive_log | ||
| * context: server | ||
|
|
||
| A flag that can be set at [runtime](runtime-modifiers.md) to enable [naxsi extensive logs](naxsilogs.md#naxsi_exlog). | ||
| This directive is used to define where Naxsi has to redirect (it's an NGINX's internal redirect) when blocking, dropping or logging requests. | ||
|
|
||
| ``` | ||
| server { | ||
| ... | ||
| The following headers that are added are when blocking, dropping or logging requests: | ||
| - `x-orig_url` | ||
| - `x-orig_args` | ||
| - `x-naxsi_sig` | ||
|
|
||
| if ($remote_addr = "1.2.3.4") { | ||
| set $naxsi_extensive_log 1; | ||
| } | ||
| > 💡 Tip | ||
| > | ||
| > It is **strongly** suggested to mark the `DeniedUrl` location as `internal` to prevent possible pre-detection of the WAF as per example. | ||
| ### Example: | ||
|
|
||
| ``` | ||
| location / { | ||
| ... | ||
| } | ||
| DeniedUrl "/RequestDenied"; | ||
| } | ||
| location /RequestDenied { | ||
| # Mark this location as internal only to prevent possible pre-detection of the WAF | ||
| internal; | ||
| # return code of the location. | ||
| return 403; | ||
| } | ||
| ``` | ||
|
|
||
| ## naxsi_json_log | ||
| * context: server | ||
| ## **MainRule** | ||
|
|
||
| Enable JSON in logs. Examples: | ||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `http` | ||
| This directive is required to declare a **global** [rule](rules.md) or a [whitelist](whitelist.md). | ||
|
|
||
| > 💡 Tip | ||
| > | ||
| > You can define these within a config file and use the `include` directive to include them within the NGINX configuration. | ||
| You can find within the [Naxsi source code a list of global rules](https://github.com/wargio/naxsi/blob/main/naxsi_rules/) which provides a basic ruleset to protect any web application; these rules requires to include the following `CheckRules`: | ||
|
|
||
| ``` | ||
| # normal log in JSON format | ||
| 2022/12/22 20:36:35 [error] 1189262#0: *1 {"ip":"127.0.0.1","server":"localhost","uri":"/a","config":"block","rid":"a0333f697ff8f12b6a200a24117ff320","cscore0":"$SQL","score0":"8","cscore1":"$XSS","score1":"8","zone0":"ARGS","id0":"1001","var_name0":"b"}, client: 127.0.0.1, server: localhost, request: "GET /a?b="\dasdasdasdadsa HTTP/1.1", host: "localhost" | ||
| # extended log in json format | ||
| 2022/12/22 20:36:35 [error] 1189262#0: *1 {"ip":"127.0.0.1","server":"localhost","uri":"/a","config":"block","rid":"a0333f697ff8f12b6a200a24117ff320","cscore0":"$SQL","score0":"8","cscore1":"$XSS","score1":"8","zone0":"ARGS","id0":"1001","var_name0":"b"}, client: 127.0.0.1, server: localhost, request: "GET /a?b="\dasdasdasdadsa HTTP/1.1", host: "localhost" | ||
| CheckRule "$SQL >= 8" BLOCK; | ||
| CheckRule "$RFI >= 8" BLOCK; | ||
| CheckRule "$TRAVERSAL >= 5" BLOCK; | ||
| CheckRule "$UPLOAD >= 5" BLOCK; | ||
| CheckRule "$XSS >= 8" BLOCK; | ||
| CheckRule "$UWA >= 8" BLOCK; | ||
| CheckRule "$EVADE >= 8" BLOCK; | ||
| ``` | ||
|
|
||
| TODO DOCUMENTATION | ||
|
|
||
| ## naxsi_flag_enable | ||
| * context: server | ||
|
|
||
| A flag that can be set at [runtime](runtime-modifiers.md) to enable or disable naxsi. | ||
| ### Example: | ||
|
|
||
| ``` | ||
| server { | ||
| set $naxsi_flag_enable 1; | ||
| location / { | ||
| ... | ||
| } | ||
| http { | ||
| # global whitelist | ||
| MainRule wl:12345 "mz:$URL:/robots.txt|URL"; | ||
| # global rule | ||
| MainRule id:45678 "s:$UWA:8" "str:nmap" "mz:$HEADERS_VAR:User-Agent" "msg:nmap in user-agent"; | ||
| } | ||
| ``` | ||
|
|
||
| ## naxsi_flag_learning | ||
| * context: server | ||
| ## **BasicRule** | ||
|
|
||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| This directive is required to declare a **location-specific** (i.e. not global) [rule](rules.md) or a [whitelist](whitelist.md). | ||
|
|
||
| A flag that can be set at [runtime](runtime-modifiers.md) to enable or disable learning. | ||
| > 💡 Tip | ||
| > | ||
| > You can define these within a config file and use the `include` directive to include them within the NGINX configuration. | ||
| > 💡 Tip | ||
| > | ||
| > You can find within the [Naxsi source code a list of location-specific whitelist](https://github.com/wargio/naxsi/tree/main/naxsi_rules/whitelists) which can be used for known web applications like Wordpress, Etherpad, Drupal, and more... | ||
| ### Example: | ||
|
|
||
| ``` | ||
| server { | ||
| set $naxsi_flag_learning 1; | ||
| location / { | ||
| ... | ||
| } | ||
| location / { | ||
| # location-specific whitelist | ||
| BasicRule wl:12345 "mz:$URL:/robots.txt|URL"; | ||
| # location-specific rule | ||
| BasicRule id:45678 "s:$UWA:8" "str:nmap" "mz:$HEADERS_VAR:User-Agent" "msg:nmap in user-agent"; | ||
| } | ||
| ``` | ||
|
|
||
| ## naxsi_flag_libinjection_sql | ||
| * context: server | ||
| ## **IgnoreIP** | ||
|
|
||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| This directive can be used to whitelist requests from certain IPs. | ||
|
|
||
| > 💡 Tip | ||
| > | ||
| > You can define these within a config file and use the `include` directive to include them within the NGINX configuration. | ||
| A flag that can be set at [runtime](runtime-modifiers.md) to enable or disable [libinjection's sql detection](libinjection-integration.md) | ||
| ### Example: | ||
|
|
||
| ``` | ||
| server { | ||
| set $naxsi_flag_libinjection_sql 1; | ||
| location / { | ||
| ... | ||
| } | ||
| location / { | ||
| IgnoreIP "1.2.3.4"; | ||
| IgnoreIP "2001:4860:4860::8844"; | ||
| } | ||
| ``` | ||
|
|
||
| ## naxsi_flag_libinjection_xss | ||
| ## **IgnoreCIDR** | ||
|
|
||
| > ℹ️ Info | ||
| > | ||
| > NGINX block: `location` | ||
| This directive can be used to whitelist requests from certain IP ranges. | ||
|
|
||
| A flag that can be set at [runtime](runtime-modifiers.md) to enable or disable [libinjection's xss detection](libinjection-integration.md) | ||
| > 💡 Tip | ||
| > | ||
| > You can define these within a config file and use the `include` directive to include them within the NGINX configuration. | ||
| ### Example: | ||
|
|
||
| ``` | ||
| server { | ||
| set $naxsi_flag_libinjection_xss 1; | ||
| location / { | ||
| ... | ||
| } | ||
| location / { | ||
| IgnoreCIDR "192.168.0.0/24"; | ||
| IgnoreCIDR "2001:4860:4860::/112"; | ||
| } | ||
| ``` | ||
|
|
Oops, something went wrong.