generated from nginx/template-repository
-
Notifications
You must be signed in to change notification settings - Fork 117
N1 waf signature sets release #1251
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
23 commits
Select commit
Hold shift + click to select a range
0b1006a
n1c: add docs for adding signature sets and exceptions
sylwang fd22e59
add instructions for urls/cookies/parameters
sylwang e6d2ca2
add titles for all instruction files
sylwang 0b43b1a
Update content/nginx-one/nap-integration/add-signature-sets.md
sylwang 77cf361
Update content/nginx-one/nap-integration/add-signature-sets.md
sylwang 960b8f8
Update content/nginx-one/nap-integration/add-signature-sets.md
sylwang 09f53a2
Update content/nginx-one/nap-integration/add-signature-sets.md
sylwang 7768199
Update content/nginx-one/nap-integration/add-signature-sets.md
sylwang 7fd62c0
address feedback
sylwang 39442b5
reassign weights for pages
sylwang b6f6f36
update links to doc ref
sylwang 1691ef3
remove unnecessary top-level titles
sylwang 9c2366b
Merge branch 'main' of github.com:nginx/documentation
sylwang 6ddd4a4
Update content/nginx-one/nap-integration/add-cookies.md
sylwang e3498d1
Update content/nginx-one/nap-integration/add-urls.md
sylwang 9b94e6e
Update content/nginx-one/nap-integration/add-parameters.md
sylwang 7410795
Update content/nginx-one/nap-integration/add-parameters.md
sylwang 352cc00
Update content/nginx-one/nap-integration/add-signature-sets.md
sylwang 7135341
Update content/nginx-one/nap-integration/add-urls.md
sylwang 9fcbf4e
address feedback
sylwang fa2dedc
change headings
sylwang 1fec602
address feedback
sylwang 86ada3f
add changelog for new WAF release
sylwang File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or 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
132 changes: 132 additions & 0 deletions
132
content/nginx-one/nap-integration/add-signature-sets.md
This file contains hidden or 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 |
---|---|---|
@@ -0,0 +1,132 @@ | ||
--- | ||
title: "Add signature sets and exceptions" | ||
weight: 300 | ||
toc: true | ||
nd-content-type: how-to | ||
nd-product: NGINX One Console | ||
--- | ||
|
||
This document describes how you can configure signature sets and signature exceptions in F5 WAF for NGINX policies. When you add a policy, NGINX One Console provides options to customize attack signatures to better protect your applications. | ||
|
||
## Understanding signature sets and exceptions | ||
|
||
Attack signatures are rules or patterns that identify attack sequences or classes of attacks on a web application. F5 WAF for NGINX includes predefined attack signatures grouped into signature sets. | ||
|
||
### Signature set | ||
|
||
A **signature set** is a collection of attack signatures with a specific name and purpose. These sets are predefined and can be enabled or disabled in your policy. | ||
|
||
For example, you might have sets for SQL Injection Signatures, Cross-Site Scripting Signatures, or Buffer Overflow Signatures. | ||
|
||
### Signature exception | ||
|
||
A **signature exception** allows you to explicitly enable or disable individual attack signatures within a set. This gives you granular control over your policy. For example: | ||
- If a signature in a set causes false positives (blocking legitimate traffic), you can create an exception to disable just that signature while keeping the rest of the set active. | ||
- If you want to enable blocking for one specific attack signature rather than an entire set, you can create an exception to enable just that signature. | ||
|
||
## Add signature sets | ||
|
||
From NGINX One Console, select **App Protect > Policies**. In the screen that appears, select **Add Policy**. That action opens a screen where you can: | ||
|
||
1. In **General Settings**, name and describe the policy. | ||
1. Go to the **Web Protection** section and select **Attack Signature Sets**. Here, you can: | ||
- View all enabled attack signature sets, including the default ones | ||
- Add new signature sets | ||
- Modify existing signature sets | ||
|
||
### Configure signature sets | ||
|
||
For each signature set, you can configure: | ||
- **Alarm**: When enabled, matching requests are logged | ||
- **Block**: When enabled, matching requests are blocked | ||
|
||
For example, to configure Buffer Overflow Signatures to log but not block: | ||
|
||
```json | ||
{ | ||
"policy": { | ||
"name": "buffer_overflow_signature", | ||
"template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }, | ||
"signature-sets": [ | ||
{ | ||
"name": "Buffer Overflow Signatures", | ||
"alarm": true, | ||
"block": false | ||
} | ||
] | ||
} | ||
} | ||
``` | ||
|
||
### Remove signature sets | ||
|
||
To remove a signature set from your policy, you have two options: | ||
|
||
1. Disable the set by setting both `alarm` and `block` to `false`: | ||
|
||
```json | ||
{ | ||
"policy": { | ||
"name": "no_xpath_policy", | ||
"template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }, | ||
"signature-sets": [ | ||
{ | ||
"name": "XPath Injection Signatures", | ||
"block": false, | ||
"alarm": false | ||
} | ||
] | ||
} | ||
} | ||
``` | ||
|
||
1. Use the `$action` meta-property to delete the set (preferred for better performance): | ||
|
||
```json | ||
{ | ||
"policy": { | ||
"name": "no_xpath_policy", | ||
"template": { "name": "POLICY_TEMPLATE_NGINX_BASE" }, | ||
"signature-sets": [ | ||
{ | ||
"name": "XPath Injection Signatures", | ||
"$action": "delete" | ||
} | ||
] | ||
} | ||
} | ||
``` | ||
|
||
## Add signature exceptions | ||
|
||
From the **Web Protection** section, select **Attack Signature Exceptions**. This allows you to override settings for individual signatures. | ||
|
||
1. Click **Add Item** to create a new exception. | ||
1. Select the signature(s) you want to modify. | ||
1. Configure the exception. For example, to disable a specific signature: | ||
|
||
```json | ||
{ | ||
"signatures": [ | ||
{ | ||
"name": "_mem_bin access", | ||
"enabled": false, | ||
"signatureId": 200100022 | ||
} | ||
] | ||
} | ||
``` | ||
|
||
## Add and deploy your policy | ||
|
||
After configuring signature sets and exceptions: | ||
|
||
1. Select **Add Policy**. The policy JSON will be updated with your changes. | ||
1. Your policy will appear in the list under the name you provided. | ||
1. You can then [deploy]({{< ref "/nginx-one/nap-integration/deploy-policy.md/" >}}) the policy to either: | ||
- An instance | ||
- A Config Sync Group | ||
|
||
From NGINX One Console, you can [review and modify]({{< ref "/nginx-one/nap-integration/review-policy.md/" >}}) your saved policies at any time by selecting **App Protect > Policies**. | ||
|
||
For a complete list of available signature sets and detailed information about attack signatures, see the [Attack Signatures]({{< ref "/waf/policies/attack-signatures.md" >}}) documentation. |
197 changes: 197 additions & 0 deletions
197
content/nginx-one/nap-integration/cookies-params-urls.md
This file contains hidden or 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 |
---|---|---|
@@ -0,0 +1,197 @@ | ||
--- | ||
title: "Add cookies, parameters and URLs" | ||
weight: 400 | ||
toc: true | ||
nd-content-type: how-to | ||
nd-product: NGINX One Console | ||
--- | ||
|
||
# Add cookies | ||
|
||
Cookie protections can be configured and managed directly within the policy editor by selecting the **Cookies** option. | ||
|
||
## Cookie properties and types | ||
|
||
Each cookie configuration includes: | ||
- `Cookie Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/nap-integration/waf-policy-matching-types.md" >}}) section. | ||
- `Cookie Name`: The name of the cookie to be monitored or protected | ||
- `Enforcement Type`: | ||
- **Allow**: Specifies that this cookie may be changed by the client. The cookie is not protected from modification | ||
- **Enforce**: Specifies that this cookie may not be changed by the client | ||
- `Attack Signatures`: Indicates whether attack signatures and threat campaigns are enabled, disabled, or not applicable | ||
- `Mask value in logs`: When enabled, the cookie's value will be masked in the request log for enhanced security and privacy | ||
|
||
For a complete list of configurable cookie properties and options, see the [Cookie Configuration Parameters]({{< ref "/waf/policies/parameter-reference.md" >}}) documentation under the `cookies` section. | ||
|
||
## Cookie violations | ||
|
||
Select **Edit Configuration** to configure cookie violations. The following violations can be configured for cookies: | ||
|
||
- `VIOL_COOKIE_EXPIRED`: Triggered when a cookie's timestamp is expired | ||
- `VIOL_COOKIE_LENGTH`: Triggered when cookie length exceeds the configured limit | ||
- `VIOL_COOKIE_MALFORMED`: Triggered when cookies are not RFC-compliant | ||
- `VIOL_COOKIE_MODIFIED`: Triggered when domain cookies have been tampered with | ||
|
||
For each violation type, you can: | ||
- Set the enforcement action | ||
- Toggle `Alarm`, `Alarm and Block`, or `Disabled` settings | ||
|
||
For more details about enforcement modes, see the [Glossary]({{< ref "/nginx-one/glossary.md#nginx-app-protect-waf-terminology" >}}), specifically the entry: **Enforcement mode**. | ||
|
||
See the [Supported Violations]({{< ref "/waf/policies/violations.md#supported-violations" >}}) for additional details. | ||
|
||
## Add a cookie to your policy | ||
|
||
1. Choose Cookie Type: | ||
- Select either `Explicit` for exact cookie matching or `Wildcard` for pattern-based matching | ||
|
||
1. Configure Basic Properties: | ||
- Enter the `Cookie Name` | ||
- Choose whether to mask the cookie value in logs | ||
|
||
1. Set Enforcement Type: | ||
- Choose either `Allow` or `Enforce` | ||
|
||
1. Optional: Configure Attack Signatures | ||
- If enabled, you can overwrite attack signatures for this specific cookie | ||
- For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/nap-integration/add-signature-sets.md/" >}}) | ||
|
||
1. Select **Add Cookie** to save your configuration | ||
|
||
# Add parameters | ||
|
||
Parameter protections can be configured and managed directly within the policy editor by selecting the **Parameters** option. | ||
|
||
## Parameter properties and types | ||
|
||
Each parameter configuration includes: | ||
- `Parameter Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/nap-integration/waf-policy-matching-types.md" >}}) section. | ||
- `Parameter Name`: The name of the parameter | ||
- `Location`: Where the parameter is expected (URL query string, POST data, etc.) | ||
- `Value Type`: The expected type of the parameter value (e.g., alpha-numeric, integer, email) | ||
- `Attack Signatures`: Whether attack signature checking is enabled for this parameter | ||
- `Mask value in logs`: When enabled, the parameter's value will be masked in the request log for enhanced security and privacy. This sets `sensitiveParameter` property of the parameter item. | ||
|
||
For a complete list of configurable parameter properties and options, see the [Parameter Configuration Parameters]({{< ref "/waf/policies/parameter-reference.md" >}}) documentation under the `parameters` section. | ||
|
||
## Parameter violations | ||
|
||
Select **Edit Configuration** to configure parameter violations. The following violations can be configured for parameters: | ||
sylwang marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
- `VIOL_PARAMETER`: Triggered when an illegal parameter is detected | ||
- `VIOL_PARAMETER_ARRAY_VALUE`: Triggered when an array parameter value is illegal | ||
- `VIOL_PARAMETER_DATA_TYPE`: Triggered when parameter data type doesn't match configured security policy | ||
- `VIOL_PARAMETER_EMPTY_VALUE`: Triggered when a parameter value is empty but shouldn't be | ||
- `VIOL_PARAMETER_LOCATION`: Triggered when a parameter is found in wrong location | ||
- `VIOL_PARAMETER_MULTIPART_NULL_VALUE`: Triggered when the multi-part request has a parameter value that contains the NULL character (0x00) | ||
- `VIOL_PARAMETER_NAME_METACHAR`: Triggered when illegal meta characters are found in parameter name | ||
- `VIOL_PARAMETER_NUMERIC_VALUE`: Triggered when numeric parameter value is outside allowed range | ||
- `VIOL_PARAMETER_REPEATED`: Triggered when a parameter name is repeated illegally | ||
- `VIOL_PARAMETER_STATIC_VALUE`: Triggered when a static parameter value doesn't match configured security policy | ||
- `VIOL_PARAMETER_VALUE_BASE64`: Triggered when the value is not a valid Base64 string | ||
- `VIOL_PARAMETER_VALUE_LENGTH`: Triggered when parameter value length exceeds limits | ||
- `VIOL_PARAMETER_VALUE_METACHAR`: Triggered when illegal meta characters are found in parameter value | ||
- `VIOL_PARAMETER_VALUE_REGEXP`: Triggered when parameter value doesn't match required pattern | ||
|
||
For each violation type, you can: | ||
- Set the enforcement action | ||
- Toggle `Alarm`, `Alarm and Block`, or `Disabled` settings | ||
|
||
For more details about enforcement modes, see the [Glossary]({{< ref "/nginx-one/glossary.md#nginx-app-protect-waf-terminology" >}}), specifically the entry: **Enforcement mode**. | ||
|
||
See the [Supported Violations]({{< ref "/waf/policies/violations.md#supported-violations" >}}) for additional details. | ||
|
||
## Add a parameter to your policy | ||
|
||
1. Choose Parameter Type: | ||
- Select either `Explicit` for exact parameter matching or `Wildcard` for pattern-based matching | ||
|
||
1. Configure Basic Properties: | ||
- Enter the parameter `Parameter Name` | ||
- Select the `Location` where the parameter is expected | ||
- Choose the `Value Type` (alpha-numeric, integer, email, etc.) | ||
- Set the `Data Type` if applicable | ||
|
||
1. Set Security Options: | ||
- Choose whether to enable attack signatures | ||
|
||
{{< call-out "important" >}} | ||
|
||
Attack Signatures are only applicable when the Value Type is `User Input` or `Array` **and** the Data Type is either `Alphanumeric` or `Binary` | ||
|
||
{{< /call-out >}} | ||
|
||
- Decide if parameter value should be masked in logs which sets `sensitiveParameter` in [Parameter Configuration Reference]({{< ref "/waf/policies/parameter-reference.md" >}}) | ||
|
||
1. Optional: Configure Attack Signatures | ||
- If enabled, you can overwrite attack signatures for this specific parameter | ||
- For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/nap-integration/add-signature-sets.md/" >}}) | ||
|
||
1. Select **Add Parameter** to save your configuration | ||
|
||
# Add URLs | ||
|
||
URL protections can be configured and managed directly within the policy editor by selecting the **URLs** option. | ||
|
||
## URL properties and types | ||
|
||
Each URL configuration includes: | ||
- `URL Type`: `Explicit` or `Wildcard`. For details on explicit and wildcard matching, see the [Matching Types: Explicit vs Wildcard]({{< ref "/nginx-one/nap-integration/waf-policy-matching-types.md" >}}) section. | ||
- `Method`: Specifies the HTTP method(s) for the URL (`GET`, `POST`, `PUT`, etc.) | ||
- `Protocol`: The protocol for the URL (`HTTP`/`HTTPS`) | ||
- `Enforcement Type`: | ||
- **Allow**: Permits access to the URL with optional attack signature checks | ||
- **Disallow**: Blocks access to the URL entirely | ||
- `Attack Signatures`: Indicates whether attack signatures and threat campaigns are enabled, disabled, or not applicable | ||
|
||
{{< call-out "important" >}} | ||
|
||
**⚠️ Important:** Attack Signatures are automatically shown as "Not Applicable" when Enforcement Type is set to `Disallow` since the URL is explicitly blocked and signature checking is unnecessary. | ||
|
||
{{< /call-out >}} | ||
|
||
For a complete list of configurable URL properties and options, see the [URL Configuration Parameters]({{< ref "/waf/policies/parameter-reference.md" >}}) documentation under the `urls` section. | ||
|
||
## URL violations | ||
|
||
Select **Edit Configuration** to configure URL violations. The following violations can be configured for URLs: | ||
|
||
- `VIOL_URL`: Triggered when an illegal URL is accessed | ||
- `VIOL_URL_CONTENT_TYPE`: Triggered when there's an illegal request content type | ||
- `VIOL_URL_LENGTH`: Triggered when URL length exceeds the configured limit | ||
- `VIOL_URL_METACHAR`: Triggered when illegal meta characters are found in the URL | ||
|
||
For each violation type, you can: | ||
- Set the enforcement action | ||
- Toggle `Alarm`, `Alarm and Block`, or `Disabled` settings | ||
|
||
For more details about enforcement modes, see the [Glossary]({{< ref "/nginx-one/glossary.md#nginx-app-protect-waf-terminology" >}}), specifically the entry: **Enforcement mode**. | ||
|
||
See the [Supported Violations]({{< ref "/waf/policies/violations.md#supported-violations" >}}) for additional details. | ||
|
||
## Add a URL to your policy | ||
|
||
1. Choose URL Type: | ||
- Select either `Explicit` for exact URL matching or `Wildcard` for pattern-based matching | ||
|
||
1. Configure Basic Properties: | ||
- Enter the `URL` path (e.g., `/index.html`, `/api/data`) | ||
- The URL path must start with `/` | ||
- Select HTTP `Method(s)` (e.g., `GET`, `POST`, *) | ||
- Choose the `Protocol` (`HTTP`/`HTTPS`) | ||
|
||
1. Set Enforcement: | ||
- Choose whether to allow or disallow the URL | ||
- If `Allow URL` is selected, you can optionally enable attack signatures | ||
|
||
{{< call-out "important" >}} | ||
|
||
**⚠️ Important:** Attack signatures cannot be enabled for disallowed URLs. | ||
|
||
{{< /call-out >}} | ||
|
||
1. **Optional**: Configure Attack Signatures | ||
- If enabled, you can overwrite attack signatures for this specific URL | ||
- For details on signature configuration, refer to the documentation on [Add Signature Sets]({{< ref "/nginx-one/nap-integration/add-signature-sets.md/" >}}) | ||
|
||
1. Select **Add URL** to save your configuration |
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.