diff --git a/content/nginx-one/waf-integration/_index.md b/content/nginx-one/waf-integration/_index.md index be31db322..168f7cee6 100644 --- a/content/nginx-one/waf-integration/_index.md +++ b/content/nginx-one/waf-integration/_index.md @@ -2,5 +2,5 @@ title: Secure with F5 WAF for NGINX description: weight: 400 -url: /nginx-one/nap-integration +url: /nginx-one/waf-integration --- diff --git a/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md b/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md index ad9c976a6..10bf08c63 100644 --- a/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md +++ b/content/nginx/admin-guide/installing-nginx/installing-nginx-plus.md @@ -5,7 +5,7 @@ description: Install and upgrade F5 NGINX Plus with step-by-step instructions fo toc: true weight: 100 nd-content-type: how-to -nd-product: NGINX+ +nd-product: NPL nd-docs: DOCS-414 --- @@ -581,7 +581,7 @@ NGINX Certified Partner dynamic modules are partner-built extensions that enhanc | [ForgeRock Policy Agent](https://backstage.forgerock.com/downloads/browse/am/featured/web-agents) | In conjunction with ForgeRock Access Management, allows you to authenticate your application and API access. | [Support](https://support.pingidentity.com/s/) and [docs](https://backstage.forgerock.com/docs/openam-web-policy-agents/2023.9/installation-guide/install-nginx.html) provided by [PingIdentity](https://www.pingidentity.com) | | [HUMAN Security for F5 NGINX](https://www.humansecurity.com/contact-us/) | Provides the required enforcement layer to protect websites and apps from modern automated security threats. | Support provided by [HUMAN Security](https://www.humansecurity.com/) | | [IDFConnect SSO/Rest](http://www.idfconnect.com/about/contact/) | Integrates your web access management platform's full capabilities with NIGNX Plus. | [Support](http://www.idfconnect.com/about/contact/) and [docs](https://www.idfconnect.com/nginx-ssorest-plugin/) provided by [IDFConnect](http://www.idfconnect.com) | -| [OPSWAT](https://www.f5.com/go/product/nginx-modules/opswat) | Scalable solutions to protect your networks and applications from malware and unknown (zero-day) malicious file content. | [Support](https://www.opswat.com/support) and [docs](https://www.opswat.com/docs/mdicap/integrations/nginx-integration-module) provided by [OPSWAT](https://www.opswat.com/) | +| [OPSWAT](https://www.f5.com/go/product/nginx-modules) | Scalable solutions to protect your networks and applications from malware and unknown (zero-day) malicious file content. | [Support](https://www.opswat.com/support) and [docs](https://www.opswat.com/docs/mdicap/integrations/nginx-integration-module) provided by [OPSWAT](https://www.opswat.com/) | | [Passenger Enterprise](https://www.phusionpassenger.com/features) | An application server with support for Meteor, Node.js, Python, and Ruby apps. | [Support](https://www.phusionpassenger.com/support) and [docs](https://www.phusionpassenger.com/docs/advanced_guides/install_and_upgrade/nginx/install_as_nginx_module.html) provided by [Phusion](https://www.phusionpassenger.com/) | | [Ping Access](https://support.pingidentity.com/s/marketplace-integration/a7i1W0000004ICRQA2/pingaccess-agent-for-nginx-plus) | Centralized management of access security with advanced contextual policies to secure your mobile and web properties in any domain. | [Support](https://support.pingidentity.com/s/) and [docs](https://docs.pingidentity.com/pingaccess/latest/agents_and_integrations/pa_agent_for_nginx.html) provided by [PingIdentity](https://www.pingidentity.com) | | [PingIntelligence](https://hub.pingidentity.com/datasheets/3742-pingintelligence-apis) | A complete solution to secure an organization's API across on-premises, public and private clouds, and hybrid IT environments. | [Support](https://support.pingidentity.com/s/) and [docs](https://docs.pingidentity.com/pingintelligence/5.1/pingintelligence_integrations/pingintelligence_nginx_plus_integration.html) provided by [PingIdentity](https://www.pingidentity.com) | diff --git a/content/waf/logging/security-logs.md b/content/waf/logging/security-logs.md index e90cbc776..0105df5bb 100644 --- a/content/waf/logging/security-logs.md +++ b/content/waf/logging/security-logs.md @@ -13,11 +13,8 @@ F5 WAF for NGINX uses its own logging mechanism for request logging rather than The Security log has the following properties: * **Log Configuration**: `app_protect_security_log` directive referencing a custom logging profile bundle file (tgz) or a built-in logging profile name, for example - `log_all`. - * **Configuration contexts**: nginx.conf: `http`, `server`, `location` - * **File Destination?** The destination can be set to either `stderr` or an absolute path to a local file. It is important to ensure that the path is mounted to the host, as the log will be generated from the `waf-enforcer` container. - * **Syslog Destination?** Yes ## Directives in nginx.conf @@ -34,16 +31,15 @@ The security log attributes are determined by the `app_protect_security_log` dir * Example: app_protect_security_log_enable on -| Argument | Mandatory | Meaning | Default | -| ---| ---| ---| --- | -|ON-OFF | Yes | Whether to enable logging or not | off | +| Argument | Mandatory | Meaning | Default | +| ---------| ----------| -------- | ------- | +| ON-OFF | Yes | Whether to enable logging or not | off | ### app_protect_security_log The security log attributes are determined by the `app_protect_security_log` directive, if it was enabled in the respective context. The directive can be at the following context levels: `http`, `server` and `location`. Multiple occurrences of this directive are allowed in a single context, and all the configured logs in this context will be used. When not present in a certain context, all the directives are inherited from the context above it: `location` from `server`, then from `http`. If there is no directive at any of these context levels, but logging is enabled then the default is used for the respective context. * Syntax: app_protect_security_log [LOG-BUNDLE-FILE-OR-NAME] [DESTINATION] - * Levels: http, server, location ```nginx @@ -55,10 +51,10 @@ app_protect_security_log log_illegal syslog:server=192.168.12.34:51400; app_protect_security_log /shared_volume/logging_profile_02.tgz syslog:server=my.domain.com:514; ``` -|Argument | Mandatory | Meaning | Default | -| ---| ---| ---| --- | -|LOG-BUNDLE-FILE-OR-NAME | No | The path to the **compiled** logging profile bundle, or built-in profile name. See details below. | `log_default` (identical to `log_illegal`)| -|DESTINATION | No | The destination of the log messages in NGINX format. The supported destinations options are `stderr`, or an absolute path to a local file, or syslog server as localhost, hostname, IP address or FQDN with an optional port.| syslog:server=localhost:514 | +| Argument | Mandatory | Meaning | Default | +| ---------| ----------| -------- | ------- | +| LOG-BUNDLE-FILE-OR-NAME | No | The path to the **compiled** logging profile bundle, or built-in profile name. See details below. | `log_default` (identical to `log_illegal`)| +| DESTINATION | No | The destination of the log messages in NGINX format. The supported destinations options are `stderr`, or an absolute path to a local file, or syslog server as localhost, hostname, IP address or FQDN with an optional port.| syslog:server=localhost:514 | ## Security log configuration file @@ -71,20 +67,20 @@ The file is in JSON format and consists of two parts: The filter is mandatory, although it may be left blank. -|Element | Meaning | Type/Values | Default | -| ---| ---| ---| --- | +| Element | Meaning | Type/Values | Default | +| ------- | ------- | ----------- | ------- | |request_type | Log according to what App Protect detected in the request. | Enumerated values: | all | The content part of the configuration file specifies what will be logged, the format of the message, and size restrictions. Content is mandatory. If the entire content field or any of its attributes are not defined, system-defined default values are used. -|Element | Meaning | Type/Values | Mandatory | Default | Comment | -| ---| ---| ---| ---| ---| --- | -|format | Selects one of the predefined formats of log messages or a custom format that will be defined by the **format_string** field. | Enumerated values: | No | default | | -|format_string | Layout template of the logged fields in the log message. | String representing the template of the message with placeholders for the message attributes. The currently available security log attributes are specified below in the `Available Security Log Attributes` section. Each attribute name is delimited by percent signs, for example: %violation_rating% | If, and only if, format=user-defined | N/A | | -|max_message_size | Limit in KB for the total size of the message. | Range of values between 1k-64k, must not be smaller than the max_request_size | No | 2k | | -|max_request_size | Limit in bytes for the sizes of the `request` and `request_body_base64` fields in the log. Must be smaller than max_message_size. | Integer representing bytes in the range of 1-10240, or **any**. **any** is synonymous with 10240. The type is string in terms of JSON schema, to accommodate the **any** option. The limit for “max_request_size” in log configuration is increased from 2k to 10k. | No | 2k | Relevant only if the request field is present in the log. | +| Element | Meaning | Type/Values | Mandatory | Default | Comment | +| --------| ------- | ----------- | --------- | ------- | ------- | +| format | Selects one of the predefined formats of log messages or a custom format that will be defined by the **format_string** field. | Enumerated values: | No | default | | +| format_string | Layout template of the logged fields in the log message. | String representing the template of the message with placeholders for the message attributes. The currently available security log attributes are specified below in the `Available Security Log Attributes` section. Each attribute name is delimited by percent signs, for example: %violation_rating% | If, and only if, format=user-defined | N/A | | +| max_message_size | Limit in KB for the total size of the message. | Range of values between 1k-64k, must not be smaller than the max_request_size | No | 2k | | +| max_request_size | Limit in bytes for the sizes of the `request` and `request_body_base64` fields in the log. Must be smaller than max_message_size. | Integer representing bytes in the range of 1-10240, or **any**. **any** is synonymous with 10240. The type is string in terms of JSON schema, to accommodate the **any** option. The limit for “max_request_size” in log configuration is increased from 2k to 10k. | No | 2k | Relevant only if the request field is present in the log. | | escaping_characters | Allows to replace a character in security log value with another character. There are two subfields to configure: | String both for *from* and *to* fields | No | N/A | | | list_prefix | Defines the prefix of a list of values in the log. | String | No | N/A | | | list_delimiter | Defines the delimiter of a list of values in the log. | String | No | `,` | | @@ -217,52 +213,54 @@ NGINX will provide example configuration files under /opt/app_protect/share/defa The table below lists attributes that are generated in the security logs. When using customized logs (that is, format=user-defined), you can add or remove entries from the list below. Per each attribute we show whether it is included in each of the predefined formats: `default` and `grpc`. -|Attribute Name | Description | Included in formats | -| ---| ---| --- | +| Name | Description | Included in formats | +| -----| ------------| ------------------- | | attack_type | A list of comma separated names of suspected attacks identified in a transaction. | default, grpc | | blocking_exception_reason | The blocking exception reason when a configured violation was not blocked. | default, grpc | | bot_anomalies | Comma-separated list of anomalies that were detected. | default, grpc | | bot_category | The category of the detected bot. | default, grpc | | bot_signature_name | The name of the detected bot. | default, grpc | | client_class | The classification of the client. It can have one of the following values: `N/A`, `Suspicious Browser`, `Malicious Bot`, `Trusted Bot`, `Untrusted Bot`. If the client is classified as standard browser, then the value is `N/A`. | default, grpc | -| date_time | The date and time the request was received by App Protect. | default, grpc | +| date_time | The date and time the request was received by F5 WAF for NGINX | default, grpc | +| dest_ip | Requested service IP address | default, grpc | | dest_port | The port assigned to listen to incoming requests. | default, grpc | | enforced_bot_anomalies | Comma-separated list of anomalies that caused the request to be blocked. | default, grpc | | grpc_method | The method name of the gRPC request (derived from the URI). Not to be confused with 'http_method`. Applicable only to requests that are processed by a gRPC Content Profile. The value is `N/A` in other cases. | grpc | | grpc_service | The service name of the gRPC request (derived from the URI). Applicable only to requests that are processed by a gRPC Content Profile. The value is `N/A` in other cases. | grpc | | compression_method | The compression algorithm used for the present message. Currently one of: | grpc | -|headers | The headers part of the request including the query string but not the body. | grpc | -|ip_client | The source IP of the client initiating the request
Note: if a proxy is being used, this may differ from the IP in the `X-Forwarded-For` header. | default, grpc | -|is_truncated_bool | A flag that returns `true` if a request is truncated in the security logs, or `false` if it is not. | default, grpc

**Note:** The log field name used for this attribute is `is_truncated`.| -|json_log | Contains the violations and applicable signature names and IDs associated with a transaction. See [Blocking Observability](#blocking-observability) for more information.
**Note:** Starting with release 4.3, the `json_log` field will include the Violation details formatted in JSON format. | default, grpc | +| headers | The headers part of the request including the query string but not the body. | grpc | +| ip_client | The source IP of the client initiating the request
Note: if a proxy is being used, this may differ from the IP in the `X-Forwarded-For` header. | default, grpc | +| is_truncated_bool | A flag that returns `true` if a request is truncated in the security logs, or `false` if it is not. | default, grpc

**Note:** The log field name used for this attribute is `is_truncated`.| +| json_log | Contains the violations and applicable signature names and IDs associated with a transaction. See [Blocking Observability](#blocking-observability) for more information.
**Note:** Starting with release 4.3, the `json_log` field will include the Violation details formatted in JSON format. | default, grpc | | json_log.stream.id | The id of the gRPC stream (request) to which the current message belongs. This is used to correlate all the messages in the stream. Currently this number is identical to the support id of the headers message. | grpc | | json_log.stream.index | The ordinal sequence number of the message in the stream. The numbering starts from 0 which is always the request headers event. In Unary rpcs there will only be indexes 0 and 1. | grpc | | json_log.stream.controlState | The current state of the client stream as reflected by the message: | grpc | -|method | The method of request. For example, GET, POST, HEAD. | default, grpc | -|outcome | One of the following: | default, grpc | -|outcome_reason | One of the following: | default| -|policy_name | The name of the App Protect policy for which the violation was triggered. | default, grpc | -|protocol | The protocol used, either HTTP or HTTPS if terminating SSL on App Protect. | default, grpc | -|request | The entire request including headers, query string, and data in its original encoding. If the request contains binary content or uses text encoding that the log destination does not support, then this field may not be rendered correctly. In such cases we recommend using the `request_body_base64` and `headers` fields instead. | default | -|request_body_base64 | The body of the request (if exists) encoded in Base64. Suitable for binary content. | grpc | -|request_status | The status of client request made to Web Application as assigned by the App Protect policy. The possible values are: | default, grpc | -|response_code | The response code returned by the server. | default, grpc | -|severity | The maximum severity calculated from all violations found in the request. It is a static value coming from the Violations. | default, grpc | -|sig_cves | Signature CVEs value of the matched signatures. | default, grpc | -|sig_ids | Signature ID value of the matching signature that resulted in the violation. | default, grpc | -|sig_names | Signature name of the matching signature that resulted in the violation. | default, grpc | -|sig_set_names | The signature set names of the matched signatures. | default, grpc | -|src_port | The source port of the client. | default, grpc | -|sub_violations | Refers to the sub-violations detected under the ‘HTTP protocol compliance failed’ and the ‘Evasion technique detected’ violations. | default, grpc | -|support_id | A unique identifier for a transaction. | default, grpc | -|threat_campaign_names | Names of the Threat Campaigns detected in the request, separated by commas. | default, grpc | -|unit_hostname | host name of the app-protect instance | default, grpc | -|uri | The URI or Uniform Resource Identifier of the request. | default, grpc | -|violation_details | XML including details about each violation. | default, grpc | -|violation_rating | Estimation of the likelihood that the request is indeed a threat on a scale of 0 to 5: 0 - not a threat (no violations), 5 - most likely a threat | default, grpc | -|violations | Comma-separated list of logical violation names (for example, `VIOL_ATTACK_SIGNATURES`, `VIOL_HTTP_PROTOCOL`). | default, grpc | -|vs_name | A unique identifier of the location in the nginx.conf file that this request is associated with. It contains the line number of the containing server block in nginx.conf, the server name, a numeric discriminator that distinguishes between multiple entries within the same server, and the location name. For example: ’34-mydomain.com:0-~/.*php(2). | default, grpc | -|x_forwarded_for_header_value | `X-Forwarded-For` header information. This option is commonly used when proxies are involved to track the originator of the request. | default, grpc | +| method | The method of request. For example, GET, POST, HEAD. | default, grpc | +| outcome | One of the following: | default, grpc | +| outcome_reason | One of the following: | default| +| policy_name | The name of the App Protect policy for which the violation was triggered. | default, grpc | +| protocol | The protocol used, either HTTP or HTTPS if terminating SSL on App Protect. | default, grpc | +| request | The entire request including headers, query string, and data in its original encoding. If the request contains binary content or uses text encoding that the log destination does not support, then this field may not be rendered correctly. In such cases we recommend using the `request_body_base64` and `headers` fields instead. | default | +| request_body_base64 | The body of the request (if exists) encoded in Base64. Suitable for binary content. | grpc | +| request_status | The status of client request made to Web Application as assigned by the App Protect policy. The possible values are: | default, grpc | +| response_code | The response code returned by the server. | default, grpc | +| severity | The maximum severity calculated from all violations found in the request. It is a static value coming from the Violations. | default, grpc | +| sig_cves | Signature CVEs value of the matched signatures. | default, grpc | +| sig_ids | Signature ID value of the matching signature that resulted in the violation. | default, grpc | +| sig_names | Signature name of the matching signature that resulted in the violation. | default, grpc | +| sig_set_names | The signature set names of the matched signatures. | default, grpc | +| src_port | The source port of the client. | default, grpc | +| sub_violations | Refers to the sub-violations detected under the ‘HTTP protocol compliance failed’ and the ‘Evasion technique detected’ violations. | default, grpc | +| support_id | A unique identifier for a transaction. | default, grpc | +| threat_campaign_names | Names of the Threat Campaigns detected in the request, separated by commas. | default, grpc | +| unit_hostname | host name of the app-protect instance | default, grpc | +| uri | The URI or Uniform Resource Identifier of the request. | default, grpc | +| username | User name for client session | default, grpc | +| violation_details | XML including details about each violation. | default, grpc | +| violation_rating | Estimation of the likelihood that the request is indeed a threat on a scale of 0 to 5: 0 - not a threat (no violations), 5 - most likely a threat | default, grpc | +| violations | Comma-separated list of logical violation names (for example, `VIOL_ATTACK_SIGNATURES`, `VIOL_HTTP_PROTOCOL`). | default, grpc | +| vs_name | A unique identifier of the location in the nginx.conf file that this request is associated with. It contains the line number of the containing server block in nginx.conf, the server name, a numeric discriminator that distinguishes between multiple entries within the same server, and the location name. For example: ’34-mydomain.com:0-~/.*php(2). | default, grpc | +| x_forwarded_for_header_value | `X-Forwarded-For` header information. This option is commonly used when proxies are involved to track the originator of the request. | default, grpc | ## Blocking Observability