From 6c61ec1da370b2e6db26880fd8b0bc06710390de Mon Sep 17 00:00:00 2001 From: Travis Martin Date: Tue, 21 Jan 2025 16:23:24 -0800 Subject: [PATCH 1/2] docs: Revise Security Monitoring guides and remove outdated install guide --- content/nap-waf/v4/admin-guide/install-nms.md | 2 +- .../security-monitoring/configure/_index.md | 5 - .../create-role-security-monitoring.md | 68 ---- .../configure/set-up-app-protect-instances.md | 247 -------------- .../configure/update-geo-db.md | 46 --- .../configure/update-signatures.md | 52 --- ...ccess-to-security-monitoring-dashboards.md | 65 ++++ .../install-security-monitoring.md | 157 --------- .../security-monitoring/releases/_index.md | 5 - .../releases/known-issues.md | 120 ------- .../releases/release-notes.md | 317 ------------------ .../set-up-app-protect-instances.md | 192 +++++++++++ .../security-monitoring/troubleshooting.md | 43 ++- .../security-monitoring/update-geo-db.md | 42 +++ .../security-monitoring/update-signatures.md | 49 +++ .../setup-waf-config-management.md | 6 +- content/nms/acm/how-to/install-acm.md | 4 - .../acm/how-to/policies/advanced-security.md | 2 +- 18 files changed, 373 insertions(+), 1049 deletions(-) delete mode 100644 content/nim/monitoring/security-monitoring/configure/_index.md delete mode 100644 content/nim/monitoring/security-monitoring/configure/create-role-security-monitoring.md delete mode 100644 content/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md delete mode 100644 content/nim/monitoring/security-monitoring/configure/update-geo-db.md delete mode 100644 content/nim/monitoring/security-monitoring/configure/update-signatures.md create mode 100644 content/nim/monitoring/security-monitoring/give-access-to-security-monitoring-dashboards.md delete mode 100644 content/nim/monitoring/security-monitoring/install-security-monitoring.md delete mode 100644 content/nim/monitoring/security-monitoring/releases/_index.md delete mode 100644 content/nim/monitoring/security-monitoring/releases/known-issues.md delete mode 100644 content/nim/monitoring/security-monitoring/releases/release-notes.md create mode 100644 content/nim/monitoring/security-monitoring/set-up-app-protect-instances.md create mode 100644 content/nim/monitoring/security-monitoring/update-geo-db.md create mode 100644 content/nim/monitoring/security-monitoring/update-signatures.md diff --git a/content/nap-waf/v4/admin-guide/install-nms.md b/content/nap-waf/v4/admin-guide/install-nms.md index a91b0a06a..ac94a2a68 100644 --- a/content/nap-waf/v4/admin-guide/install-nms.md +++ b/content/nap-waf/v4/admin-guide/install-nms.md @@ -21,7 +21,7 @@ weight: 100 [NGINX Management Suite Security Monitoring]({{< relref "/nms/about.md#security-monitoring" >}}) provides a centralized visualization tool that lets you analyze threats, view protection insights, and identify areas for policy tuning. -- For more information on how to configure Security Monitoring, see [Set Up App Protect Instances for Security Monitoring]({{< relref "/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md" >}}). +- For more information on how to configure Security Monitoring, see [Set Up App Protect Instances for Security Monitoring]({{< relref "/nim/monitoring/security-monitoring/set-up-app-protect-instances.md" >}}). --- diff --git a/content/nim/monitoring/security-monitoring/configure/_index.md b/content/nim/monitoring/security-monitoring/configure/_index.md deleted file mode 100644 index f2c40cdbe..000000000 --- a/content/nim/monitoring/security-monitoring/configure/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Configure -description: -weight: 200 ---- \ No newline at end of file diff --git a/content/nim/monitoring/security-monitoring/configure/create-role-security-monitoring.md b/content/nim/monitoring/security-monitoring/configure/create-role-security-monitoring.md deleted file mode 100644 index a3e26dc77..000000000 --- a/content/nim/monitoring/security-monitoring/configure/create-role-security-monitoring.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Add user access to Security Monitoring dashboards -description: Learn how to grant users access to the F5 NGINX Security Monitoring dashboards. -toc: true -weight: 200 -doctype: how-to -product: NIM -docs: DOCS-1026 - ---- - -## Overview - -You can use F5 NGINX Security Monitoring to monitor NGINX App Protect WAF instances. The Security Monitoring analytics dashboards and security logs provide protection insights and help you analyze possible threats or identify opportunities to tune your security policies. - -By completing the steps in this topic, you will create a role that gives users access to the Security Monitoring module and logs, and assign it to user accounts or groups. - -{{< note >}} The recommendations in this guide follow the principle of least privilege and do not grant users access to NGINX Instance Manager. You can create additional roles with custom modules, features, and permissions to suit your use case. {{}} - ---- - -## Before you begin - -Complete the following prerequisites before proceeding with this guide: - -- NGINX Security Monitoring is [installed]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and running. -- Your user account needs to be able to access the User Management settings in NGINX Instance Manager. - The minimum required role permissions are: - - - **Module**: Settings - - **Feature**: User Management - - **Access**: `READ`, `CREATE`, `UPDATE` - -- Review the table below to determine the minimum permissions needed for your use case. - - {{}} - - | Module(s) | Feature(s) | Access | Description | - |-------|--------|----|--------| - | Instance Manager
Security Monitoring | Analytics
Security Monitoring | READ
READ | Read-only access that allows users to view the Security Monitoring dashboards. Users cannot access NGINX Instance Manager or Settings.| - | Instance Manager
Security Monitoring
Settings | Analytics
Security Monitoring
User Management | READ
READ
CREATE, READ, UPDATE| Allows users to view the Security Monitoring dashboards and manage user accounts and roles.

{{< fa "lightbulb" >}} Recommended for a "super-user" who is responsible for managing other users' access to the security dashboards. This permission set does not allow the user to delete user accounts.| - - - {{}} - ---- - -## Create a role - -{{< include "nim/rbac/create-roles.md" >}} - ---- - -## Assign the role - -After you've created a role for Security Monitoring, assign the role to one or more users or to a user group. - ---- - -### Assign the role to users - -{{< include "nim/rbac/assign-roles-to-users.md" >}} - ---- - -### Assign the role to user groups - -{{< include "nim/rbac/assign-roles-to-user-groups.md" >}} diff --git a/content/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md b/content/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md deleted file mode 100644 index 4b252c247..000000000 --- a/content/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Create App Protect WAF instances for Security Monitoring -description: Learn how to set up F5 NGINX App Protect data plane instances for use with - the NGINX Security Monitoring and NGINX Instance Manager. -toc: true -weight: 100 -type: how-to -product: NIM -docs: DOCS-1107 ---- - -## Overview - -F5 NGINX Security Monitoring supports the following use cases: - -- **Security Monitoring only**: Use only the Security Monitoring module to monitor data from NGINX App Protect WAF instances. You will be able to review the security dashboards to assess potential threats and identify opportunities to fine-tune your policies. Your NGINX App Protect WAF configurations are managed outside of the NGINX Instance Manager context. -- **Security Monitoring and Instance Manager**: Use the Security Monitoring module with the NGINX Instance Manager. In addition to monitoring your application security, you will be able to manage your NGINX App Protect WAF configurations and security policies in a single location and push pre-compiled updates to an instance or instance group. - ---- - -## Before you begin - -Complete the following prerequisites before proceeding with the steps in this guide. - -1. If you are new to NGINX App Protect WAF, follow the instructions in the installation and configuration guides to get up and running: - - - [Install NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/admin-guide/install/) on one or more data plane instances. Each data plane instance must have connectivity to the NGINX Instance Manager host. - - [Configure NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-configuration-overview) according to your needs on each of the data plane instance. - -1. Review the dependencies with NGINX App Protect WAF and NGINX Plus. - - {{< include "nim/tech-specs/security-data-plane-dependencies.md" >}} - -1. Determine your use case: **Security Monitoring only** or **Security Monitoring and Configuration Management**. -1. [Install the NGINX Security Monitoring module]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and [upload your license]({{< relref "/nim/admin-guide/license/add-license.md" >}}). - ---- - -## Install NGINX Agent - -NGINX Agent is a companion daemon for NGINX Open Source or NGINX Plus instance that provides: - -- Remote management of NGINX configurations -- Collection and reporting of real-time NGINX performance and operating system metrics -- Notifications of NGINX events - -Repeat the steps in this section on each NGINX App Protect WAF data plane host to install and configure NGINX Agent for use with Security Monitoring. **These settings apply to both of the Security Monitoring use cases.** - -1. Use SSH to connect to the data plane host. -1. Install the NGINX Agent package from the NGINX Instance Manager host. - - {{< include "agent/installation/install-agent-api.md" >}} - -1. Edit the `/etc/nginx-agent/nginx-agent.conf` file to add the `nap_monitoring` configuration. - - Add the lines below to the end of the file. This enables NGINX Agent to send NGINX App Protect messages to the NGINX Instance Manager management plane. - - ```yaml - dataplane: - status: - # poll interval for data plane status - the frequency the NGINX Agent will query the data plane for changes - poll_interval: 30s - # report interval for data plane status - the maximum duration to wait before syncing data plane information if no updates have been observed - report_interval: 24h - events: - # report data plane events back to the management plane - enable: true - metrics: - # specify the size of a buffer to build before sending metrics - bulk_size: 20 - # specify metrics poll interval - report_interval: 1m - collection_interval: 15s - mode: aggregated - - # OSS NGINX default config path - # path to aux file dirs can also be added - config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" - - # Enable reporting NGINX App Protect details to the management plane. - extensions: - - nginx-app-protect - - nap-monitoring - - # Enable reporting NGINX App Protect details to the control plane. - nginx_app_protect: - # Report interval for NGINX App Protect details - the frequency the NGINX Agent checks NGINX App Protect for changes. - report_interval: 15s - # Enable precompiled publication from the NGINX Instance Manager (true) or perform compilation on the data plane host (false). - precompiled_publication: true - - # NGINX App Protect Monitoring config - nap_monitoring: - # Buffer size for collector. Will contain log lines and parsed log lines - collector_buffer_size: 50000 - # Buffer size for processor. Will contain log lines and parsed log lines - processor_buffer_size: 50000 - # Syslog server IP address the collector will be listening to - syslog_ip: "127.0.0.1" - # Syslog server port the collector will be listening to - syslog_port: 514 - ``` - -1. If the `location /api` directive has not been set up in the `nginx.conf` file, follow the example below to add it: - - ```nginx - server{ - location /api { - api write=on; - allow 127.0.0.1; - deny all; - } - } - ``` - - After adding the directive, restart NGINX to apply the changes: - - ```bash - sudo systemctl restart nginx - ``` - - {{}}You can change the values of `syslog_ip` and `syslog_port` to meet your needs. - You must use the same values when configuring logging for the Security Monitoring module. If the `syslog:` configuration does not match these settings, the monitoring dashboards will not display any data. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{}} - - {{}}You can use the NGINX Agent installation script to add the fields for `nginx_app_protect` and `nap_monitoring`: - -```bash -# Download install script via API -curl https:///install/nginx-agent > install.sh - -# Use the flag --nap-monitoring to set the child fields for the field 'nap_monitoring', the -# child field values will be set to the values in the example configuration from above. Specify -# the -m | --nginx-app-protect-mode flag to set up management of NGINX App Protect on the instance. -# In the example below we specify 'precompiled-publication' for the flag value which will make the -# config field 'precompiled_publication' set to 'true', if you would like to set the config field -# 'precompiled_publication' to 'false' you can specify 'none' as the flag value. -sudo sh ./install.sh --nap-monitoring true --nginx-app-protect-mode precompiled-publication -``` - - {{}} - -1. Restart NGINX Agent: - - ``` bash - sudo systemctl restart nginx-agent - ``` - ---- - -## Create instances for Security Monitoring only - -Complete the steps in this section if you are only using the Security Monitoring module to monitor your application security. In this use case, you are **not using Instance Manager** to manage your WAF security policies. - -Repeat the steps below on each NGINX App Protect WAF data plane instance. - -1. Use SSH to connect to the data plane host. - -1. Create a new log format definition file with the name `/etc/app_protect/conf/log_sm.json` and the contents shown below. - This defines the log format for the Security Monitoring module. - - This configuration sets the maximum accepted request payload to 2048 bytes and the maximum message size to 5k. The latter setting truncates messages larger than 5k. -2. Add character escaping for the used separator `,` to be escaped with its standard URL encoding `%2C`. - - ``` json - { - "filter": { - "request_type": "illegal" - }, - "content": { - "format": "user-defined", - "format_string": "%blocking_exception_reason%,%dest_port%,%ip_client%,%is_truncated_bool%,%method%,%policy_name%,%protocol%,%request_status%,%response_code%,%severity%,%sig_cves%,%sig_set_names%,%src_port%,%sub_violations%,%support_id%,%threat_campaign_names%,%violation_rating%,%vs_name%,%x_forwarded_for_header_value%,%outcome%,%outcome_reason%,%violations%,%violation_details%,%bot_signature_name%,%bot_category%,%bot_anomalies%,%enforced_bot_anomalies%,%client_class%,%client_application%,%client_application_version%,%transport_protocol%,%uri%,%request%", - "escaping_characters": [ - { - "from": ",", - "to": "%2C" - } - ], - "max_request_size": "2048", - "max_message_size": "5k", - "list_delimiter": "::" - } - } - ``` - -1. Find the context in your NGINX configuration where NGINX App Protect WAF logging is enabled. - In the same context, add the `app_protect_security_log` directive shown in the example below to configure attack data logging for use with the Security Monitoring dashboards. - - ```nginx - app_protect_security_log_enable on; - app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; - ``` - - {{}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The dashboards won't display any data if these settings don't match. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{}} - -1. Restart NGINX Agent and the NGINX web server. - - ```bash - sudo systemctl restart nginx-agent - sudo systemctl restart nginx - ``` - -You should now be able to view data from your NGINX App Protect instances in the NGINX Security Monitoring dashboards. - ---- - -## Create instances for Security Monitoring with Instance Manager - -Complete the steps in this section if you want to use the Security Monitoring module **and** Instance Manager. In this use case, you will use NGINX Instance Manager to monitor threats and to manage your NGINX App Protect WAF configurations and security policies. - -Take the steps below to update your NGINX App Protect WAF configurations by using Instance Manager. - -1. Log in to the NGINX Instance Manager user interface and go to **Modules** > **Instance Manager**. -1. Select **Instances** or **Instance Groups**, as appropriate. -1. Select **Edit Config** from the **Actions** menu for the desired instance or instance group. -1. Next, edit the desired configuration file. You will add directives that reference the security policies bundle and enable the NGINX App Protect WAF logs required by the Security Monitoring dashboards. An example configuration is provided below. - - ```nginx - app_protect_enable on; - app_protect_enable on; - app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz"; - app_protect_security_log_enable on; - app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; - ``` - - - Add the `app_protect_policy_file` directive with a reference to a security policy. - - The policy reference must use the `.tgz` file extension when using Instance Manager to perform precompiled publication of NGINX App Protect WAF policies and log profiles. The file path referenced must exist on the NGINX Instance Manager host, but it's ok if the policy file doesn't exist yet. If your Instance is not configured for precompiled publication, then use the `.json` file extension for polcies and log profiles. In this case, the file path referenced in the NGINX configuration must reside on the Instance. - - If you are using custom security policies, at this stage, it's fine to use the default security policy shown in the example above. After completing the steps in this guide, refer to the instructions in [Set Up App Protect WAF Configuration Management]({{< relref "/nim/nginx-app-protect/setup-waf-config-management#add-waf-config" >}}) to add your custom security policy files to NGINX Instance Manager and update your NGINX configuration. - - - Add the `app_protect_security_log_enable on` and the `app_protect_security_log` directive to any NGINX context where NGINX App Protect WAF is enabled and you want to be able to review attack data. - - The logging configuration must reference `"/etc/nms/secops_dashboard.tgz"`, as shown in the example. - - If the `app_protect_security_log_enable` setting is already present, just add the `app_protect_security_log` beneath it in the same context. - - {{}}The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values specified in the [NGINX Agent configuration file](#agent-config). The Security Monitoring dashboards won't display any data if these settings don't match. Also, the networking changes for NGINX App Protect Version 5 preclude the use of `127.0.0.1` as a syslog server address. For Version 5, the address of the `docker0` interface (typically `192.0.10.1`) or the IP address of the data plane host can be used for the syslog server address.{{}} - -1. Select **Publish** to immediately push the configuration file updates out to your NGINX instance or instance group. - -You should now be able to view data from your NGINX App Protect WAF instances in the Security Monitoring dashboard. - -## See also - -- [Grant Users Access to the Security Monitoring Dashboards]({{< relref "create-role-security-monitoring" >}}): Follow the steps in this guide to allow other users in your organization to access the Security Monitoring Dashboards. - -- If you are using Security Monitoring with Instance Manager, proceed to the [Set Up App Protect WAF Configuration Management]({{< relref "/nim/nginx-app-protect/setup-waf-config-management" >}}) guide. diff --git a/content/nim/monitoring/security-monitoring/configure/update-geo-db.md b/content/nim/monitoring/security-monitoring/configure/update-geo-db.md deleted file mode 100644 index 7eadcef1d..000000000 --- a/content/nim/monitoring/security-monitoring/configure/update-geo-db.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Update the geolocation database used in dashboards -description: Learn how to update the Geolocation Database used in F5 NGINX Management - Suite Security Monitoring dashboards. -toc: true -weight: 400 -type: how-to -product: NIM -docs: DOCS-1108 ---- - -## Overview - -You can use F5 NGINX Security Monitoring to monitor NGINX App Protect WAF instances. The Security Monitoring analytics dashboard uses MaxMind's GeoLite2 Free Database to provide extra Geolocation data for Security Violations. - -By completing the steps in this topic, you will be able to update the Security Monitoring module to get the latest Geolocation database such that the dashboards can provide accurate data. - ---- - -## Before you begin - -Complete the following prerequisites before proceeding with this guide: - -- NGINX Security Monitoring is [installed]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and running. -- NGINX App Protect is configured, and the Security Monitoring dashboard is gathering security violations - - ---- - -## Update the geolocation database - -1. Create a [MaxMind](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/) account and subscribe to get the latest updates to the Geolocation database. -1. Download the GeoLite2 Country (Edition ID: GeoLite2-Country) database in a GeoIP2 Binary `.mmdb` format from the [MaxMind](https://www.maxmind.com/en/accounts/current/geoip/downloads) website. The database will be present in a `gzip` downloaded file. -1. Unzip the downloaded `gzip` file, which contains the binary data of the GeoLite2 Country database with a filename `GeoLite2-Country.mmdb` -1. Replace the `GeoLite2-Country.mmdb` present on your NGINX Instance Manager's Control Plane at `/usr/share/nms/geolite2/GeoLite2-Country.mmdb` with the newly downloaded GeoLite2 Country database. - - ```bash - sudo scp /path/to/GeoLite2-Country.mmdb {user}@{host}:/usr/share/nms/geolite2/GeoLite2-Country.mmdb - ``` - -1. Restart the NGINX Instance Manager services - - ```bash - sudo systemctl restart nms-ingestion - sudo systemctl restart nms-core - ``` diff --git a/content/nim/monitoring/security-monitoring/configure/update-signatures.md b/content/nim/monitoring/security-monitoring/configure/update-signatures.md deleted file mode 100644 index 6301708d9..000000000 --- a/content/nim/monitoring/security-monitoring/configure/update-signatures.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Update the Attack Signature Database -description: Learn how to update the Attack Signature Database used in F5 NGINX Management - Suite Security Monitoring dashboards. -toc: true -weight: 300 -type: how-to -product: NIM -docs: DOCS-1109 ---- - -## Overview - -You can use the F5 NGINX Security Monitoring module to monitor NGINX App Protect WAF instances for security. The Security Monitoring module analytics dashboards utilize a Signature Database to give more detail about the Attack Signatures that have caused a Security Violation, like the Signature's name, accuracy, and risk. - -If the Signature Database is not updated to match the Attack Signature version used for App Protect WAF protection, new signatures may be triggered without a name or other attributes like risk and accuracy. - -The steps in this topic ensure that dashboards show the correct information by updating the Security Monitoring module with the newest Attack Signature data. - ---- - -## Before you begin - -Complete the following prerequisites before proceeding with this guide: - -- NGINX Security Monitoring is [installed]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and running -- NGINX App Protect is configured, and the Security Monitoring dashboard is gathering security violations - ---- - -## Update the Signature Database - -1. Open an SSH connection to the data plane host and log in. -1. Use the [Attack Signature Report Tool]({{< relref "/nap-waf/v4/configuration-guide/configuration.md#attack-signature-report-tool" >}}) to generate a Signature Report file. The filename must be `signature-report.json`. - - ```bash - sudo /opt/app_protect/bin/get-signatures -o ./signature-report.json - ``` - -1. Open an SSH connection to the management plane host and log in. -1. Replace the `signature-report.json` on your NGINX Instance Manager's control plane at `/usr/share/nms/sigdb/signature-report.json` with the newly generated Signature Report. - - ```bash - sudo scp /path/to/signature-report.json {user}@{host}:/usr/share/nms/sigdb/signature-report.json - ``` - -1. Restart the NGINX Instance Manager services: - - ```bash - sudo systemctl restart nms-ingestion - sudo systemctl restart nms-core - ``` \ No newline at end of file diff --git a/content/nim/monitoring/security-monitoring/give-access-to-security-monitoring-dashboards.md b/content/nim/monitoring/security-monitoring/give-access-to-security-monitoring-dashboards.md new file mode 100644 index 000000000..ffb2a1cfe --- /dev/null +++ b/content/nim/monitoring/security-monitoring/give-access-to-security-monitoring-dashboards.md @@ -0,0 +1,65 @@ +--- +title: Add user access to Security Monitoring dashboards +weight: 200 +toc: true +type: how-to +product: NIM +docs: DOCS-1026 +--- + +## Overview + +F5 NGINX Security Monitoring tracks activity on NGINX App Protect WAF instances. The dashboards and logs show insights, detect threats, and help improve security policies. + +This guide explains how to create a role to give users access to Security Monitoring and assign it to users or groups. + +{{< note >}} +This guide follows the principle of least privilege, so users only get access to Security Monitoring. You can create roles with different permissions if needed. +{{}} + +--- + +## Before you begin + +Make sure you complete these steps: + +- Your account must have access to User Management in NGINX Instance Manager. Minimum permissions are: + + - **Module**: Settings + - **Feature**: User Management + - **Access**: `READ`, `CREATE`, `UPDATE` + +- Use the table below to find the permissions you need: + + {{}} + + | Module(s) | Feature(s) | Access | Description | + |-----------------------------------|-----------------------|----------------------------|----------------------------------------------------------------------------------------------------------| + | Instance Manager
Security Monitoring | Analytics
Security Monitoring | `READ`
`READ` | Gives read-only access to Security Monitoring dashboards. Users cannot access NGINX Instance Manager or Settings. | + | Instance Manager
Security Monitoring
Settings | Analytics
Security Monitoring
User Management | `READ`
`READ`
`CREATE`, `READ`, `UPDATE` | Lets users view dashboards and manage accounts and roles.

{{< fa "lightbulb" >}} Best for "super-users" who manage dashboard access. Does not allow deleting accounts. | + + {{}} + +--- + +## Create a role + +{{< include "nim/rbac/create-roles.md" >}} + +--- + +## Assign the role + +Assign the Security Monitoring role to users or groups. + +--- + +### Assign the role to users + +{{< include "nim/rbac/assign-roles-to-users.md" >}} + +--- + +### Assign the role to user groups + +{{< include "nim/rbac/assign-roles-to-user-groups.md" >}} \ No newline at end of file diff --git a/content/nim/monitoring/security-monitoring/install-security-monitoring.md b/content/nim/monitoring/security-monitoring/install-security-monitoring.md deleted file mode 100644 index db0164269..000000000 --- a/content/nim/monitoring/security-monitoring/install-security-monitoring.md +++ /dev/null @@ -1,157 +0,0 @@ ---- -title: "Install or upgrade Security Monitoring" -toc: true -weight: 100 -doctype: how-to -product: NIM -docs: DOCS-1208 ---- - -## Overview - -Follow the steps in this guide to install or upgrade or upgrade the NGINX Security Monitoring module. - ---- - -## Before you begin - -### Security considerations - -{{< include "installation/secure-installation.md" >}} - ---- - -### Installation prerequisites - -{{< include "installation/nms-prerequisites.md" >}} - ---- - -### Dependencies with Instance Manager - -{{< include "nim/tech-specs/security-management-plane-dependencies.md" >}} - ---- - -## Install Security Monitoring - -{{}} - -{{%tab name="CentOS, RHEL, RPM-Based"%}} - -1. To install the latest version of the Security Monitoring module, run the following command: - - ```bash - sudo yum -y install nms-sm - ``` - -{{%/tab%}} -{{%tab name="Debian, Ubuntu, Deb-Based"%}} - -1. To install the latest version of the Security Monitoring module, run the following commands: - - ```bash - sudo apt-get update - sudo apt-get install -y nms-sm - ``` - -{{%/tab%}} - -{{}} - -2. Restart the F5 NGINX Instance Manager services: - - ```bash - sudo systemctl restart nms - ``` - - NGINX Instance Manager components started this way run by default as the non-root `nms` user inside the `nms` group, both of which are created during installation. - -3. Restart the NGINX web server: - - ```bash - sudo systemctl restart nginx - ``` - -4. If running Security Monitoring v1.7.0 or higher, start the module: - - ```bash - sudo systemctl start nms-sm - ``` - - ---- - -### Access the web interface - -{{< include "installation/access-web-ui.md" >}} - - ---- - -### Add license - -A valid license is required to make full use of all the features in Security Monitoring module. - -Refer to the [Add a License]({{< relref "/nim/admin-guide/license/add-license.md" >}}) topic for instructions on how to download and apply a trial license, subscription license, or Flexible Consumption Program license. - ---- - -## Upgrade Security Monitoring - -{{}}The upgrade process for Security Monitoring **does not** automatically upgrade Instance Manager, which is a package dependency. To ensure compatibility with Security Monitoring, you will need to manually [upgrade Instance Manager]({{< relref "/nim/deploy/vm-bare-metal/install.md#upgrade-nim" >}}) to a version supported by Security Monitoring. For specific version dependencies between Security Monitoring and Instance Manager, refer to the [Security Monitoring release notes]({{< relref "/nim/monitoring/security-monitoring/releases/release-notes.md" >}}).{{}} - -
- -{{}} -{{%tab name="CentOS, RHEL, RPM-Based"%}} - -1. To upgrade to the latest version of Security Monitoring, run the following command: - - ```bash - sudo yum update -y nms-sm - ``` - -{{%/tab%}} - -{{%tab name="Debian, Ubuntu, Deb-Based"%}} - -1. To upgrade to the latest version of the Security Monitoring, run the following command: - - ```bash - sudo apt-get update - sudo apt-get install -y --only-upgrade nms-sm - ``` - -{{%/tab%}} -{{}} - -2. Restart the NGINX Instance Manager platform services: - - ```bash - sudo systemctl restart nms - ``` - - NGINX Instance Manager components started this way run by default as the non-root `nms` user inside the `nms` group, both of which are created during installation. - -3. Restart the NGINX web server: - - ```bash - sudo systemctl restart nginx - ``` - -4. If running Security Monitoring v1.7.0 or higher, start the module: - - ```bash - sudo systemctl start nms-sm - ``` - -5. (Optional) If you use SELinux, follow the steps in the [Configure SELinux]({{< relref "/nim/system-configuration/configure-selinux.md" >}}) guide to restore the default SELinux labels (`restorecon`) for the files and directories related to NGINX Instance Manager. - ---- - -## See also - -To set up your NGINX App Protect WAF data plane instances for use with Security Monitoring, refer to the following instructions: - -- [Create App Protect WAF instances for Security Monitoring]({{< relref "/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances" >}}) diff --git a/content/nim/monitoring/security-monitoring/releases/_index.md b/content/nim/monitoring/security-monitoring/releases/_index.md deleted file mode 100644 index 65ec4e6d0..000000000 --- a/content/nim/monitoring/security-monitoring/releases/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: Releases -description: "Stay up-to-date with the latest F5 NGINX Security Monitoring releases." -weight: 300 ---- diff --git a/content/nim/monitoring/security-monitoring/releases/known-issues.md b/content/nim/monitoring/security-monitoring/releases/known-issues.md deleted file mode 100644 index 898f1a037..000000000 --- a/content/nim/monitoring/security-monitoring/releases/known-issues.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: Known issues -description: This document lists and describes the known issues and possible workarounds - in the F5 NGINX Security Monitoring module. Fixed issues are removed - after **45 days**. -toc: true -weight: 200 -doctype: reference -product: NIM -docs: DOCS-1077 ---- - -{{< tip >}}We recommend you upgrade to the latest version of the Security Monitoring module to take advantage of new features, improvements, and bug fixes.{{< /tip >}} - ---- - -## 1.7.0 -October 18, 2023 - -### {{% icon-bug %}} Web interface fails to load after restarting NGINX Instance Manager {#44587} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 44587 | Open | - -{{}} -#### Description -The NGINX Instance Manager web interface can fail to load with a "Page not found" error after restarting its service. The security monitoring module will fail to appear on the launchpad until the page is manually reloaded. - -#### Workaround - -Reload the page in the browser to resolve this issue. - ---- - -## 1.5.0 -June 12, 2023 - -### {{% icon-resolved %}} Using empty values as filters returns inaccurate results {#42941} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 42941 | Fixed in Security Monitoring -1.6.0 | - -{{}} -#### Description -Using an empty string as a key or value results in an empty dataset. - ---- - -## 1.0.0 -November 17, 2022 - -### {{% icon-resolved %}} The API Connectivity Manager module won't load if the Security Monitoring module is enabled {#44433} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 44433 | Fixed in Instance Manager 2.8.0 | - -{{}} -#### Description -If you have Instance Manager 2.7 or earlier installed and attempt to enable both the API Connectivity Manager and Security Monitoring modules on the same NGINX Instance Manager management plane, the API Connectivity Manager module will not load because of incompatibility issues with the Security Monitoring module. - -#### Workaround - -Before enabling the API Connectivity Manager and Security Monitoring modules, ensure that your Instance Manager is upgraded to version 2.8 or later. Be sure to read the release notes for each module carefully, as they may contain important information about version dependencies. - -To see which version of Instance Manager you have installed, run the following command: - -- CentOS, RHEL, RPM-based: - - ```bash - yum info nms-instance-manager - ``` - -- Debian, Ubuntu, Deb-based: - - ```bash - dpkg -s nms-instance-manager - ``` - ---- - -### {{% icon-bug %}} Filtering data by Instance Group in the Security Monitoring module does not show any results. {#38790} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 38790 | Open | - -{{}} -#### Description -The Security Monitoring plugin on NGINX Agent does not automatically pick up changes made to agent-dynamic.conf, causing the Instance Group association to be missing in the Security Violations generated. - -#### Workaround - -Restart the NGINX Agent, and the subsequent Violations should be associated with the Instance Group: - -`systemctl restart nginx-agent` - ---- - -### {{% icon-resolved %}} The field retrieving URIs is incorrectly listed as URL {#38377} - -{{}} - -| Issue ID | Status | -|----------------|--------| -| 38377 | Fixed in Security Monitoring -1.2.0 | - -{{}} -#### Description -The field with URI data was mapped to the heading URL. The name of the field has been corrected. diff --git a/content/nim/monitoring/security-monitoring/releases/release-notes.md b/content/nim/monitoring/security-monitoring/releases/release-notes.md deleted file mode 100644 index 1d73b2fbc..000000000 --- a/content/nim/monitoring/security-monitoring/releases/release-notes.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: Release notes -description: These release notes list and describe the new features, enhancements, - and resolved issues in the F5 NGINX Security Monitoring module. -toc: true -weight: 100 -doctype: reference -product: NIM -docs: DOCS-1078 ---- - ---- - -## 1.7.1 - -October 23, 2023 - -### Upgrade Paths {#1-7-1-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.4.0 - 1.7.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-7-1-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Stability and performance improvements** - - This release includes stability and performance improvements. - - -### Known Issues{#1-7-1-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.7.0 - -October 18, 2023 - -### Upgrade Paths {#1-7-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.4.0 - 1.6.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### Changes in Default Behavior{#1-7-0-changes-in-behavior} -This release has the following changes in default behavior: - -- {{% icon-feature %}} **Security Monitoring backend service** - - The backend for Security Monitoring is now served by the `nms-sm` process instead of `nms-core`. The `nms-sm` process must be started after installation of the `nms-sm` package. - - -### Known Issues{#1-7-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.6.0 - -July 20, 2023 - -### Upgrade Paths {#1-6-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.3.0 - 1.5.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### Resolved Issues{#1-6-0-resolved-issues} -This release fixes the following issues. Select an issue's ID link to view its details. - -- {{% icon-resolved %}} Using empty values as filters returns inaccurate results [(42941)]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md#42941" >}}) - -### Known Issues{#1-6-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.5.0 - -June 12, 2023 - -### Upgrade Paths {#1-5-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.2.0 - 1.4.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-5-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Improved security monitoring with violation and signature details** - - This release adds violation and signature details to Security Monitoring. This information helps you identify false positives and gain a more comprehensive understanding of violations, allowing you to fine-tune your security policies and optimize your threat detection. - - -### Known Issues{#1-5-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.4.0 - -April 26, 2023 - -### Upgrade Paths {#1-4-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.1.0 - 1.3.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-4-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **View violation context for requests in Event logs** - - You can now view the request entity and its associated details that triggered a WAF violation from the event logs. - - -### Changes in Default Behavior{#1-4-0-changes-in-behavior} -This release has the following changes in default behavior: - -- {{% icon-feature %}} **Update to the Signature context pie chart** - - The Signature context pie chart now shows information related to signature-based violations in requests and URIs, in addition to the already available header, parameter, and cookie information. - - -### Known Issues{#1-4-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.3.0 - -March 21, 2023 - -### Upgrade Paths {#1-3-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.0.0 - 1.2.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-3-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Top Signatures section added to the Main tab** - - The "Top Signatures" section is now available in the "Main" tab of the Security Monitoring module dashboard. - - -### Security Updates{#1-3-0-security-updates} - -{{< important >}} -For the protection of our customers, NGINX doesn’t disclose security issues until an investigation has occurred and a fix is available. -{{< /important >}} - -This release includes the following security updates: - -- {{% icon-resolved %}} **Instance Manager vulnerability CVE-2023-1550** - - NGINX Agent inserts sensitive information into a log file ([CVE-2023-1550](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-1550)). An authenticated attacker with local access to read NGINX Agent log files may gain access to private keys. This issue is exposed only when the non-default trace-level logging is enabled. - - NGINX Agent is included with NGINX Instance Manager, and used in conjunction with API Connectivity Manager and the Security Monitoring module. - - This issue has been classified as [CWE-532: Insertion of Sensitive Information into Log File](https://cwe.mitre.org/data/definitions/532.html). - -#### Mitigation - -- Avoid configuring trace-level logging in the NGINX Agent configuration file. For more information, refer to the [Configuring the NGINX Agent]({{< relref "/nms/nginx-agent/install-nginx-agent.md#configuring-the-nginx-agent ">}}) section of NGINX Instance Manager documentation. If trace-level logging is required, ensure only trusted users have access to the log files. - -#### Fixed in - -- NGINX Agent 2.23.3 -- Instance Manager 2.9.0 - -For more information, refer to the MyF5 article [K000133135](https://my.f5.com/manage/s/article/K000133135). - - -### Changes in Default Behavior{#1-3-0-changes-in-behavior} -This release has the following changes in default behavior: - -- {{% icon-feature %}} **Improved error message when NGNIX Management Suite server is not running** - - The Security Monitoring module now displays the message "Upstream unavailable" when the NGINX Instance Manager server is not running, instead of the previous message "Oops something went wrong." - -- {{% icon-feature %}} **Single quotes are automatically escaped in filtered values** - - Single quotes in filtered values are automatically escaped to ensure that the data is parsed correctly. - - -### Known Issues{#1-3-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.2.0 - -January 30, 2023 - -### Upgrade Paths {#1-2-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.0.0 - 1.1.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### What's New{#1-2-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Get the latest Signature and Geolocation Databases** - - [Update the Signature database]({{< relref "/nim/monitoring/security-monitoring/configure/update-signatures" >}}) to get the latest attack signature details. - - [Update the Geolocation Database]({{< relref "/nim/monitoring/security-monitoring/configure/update-geo-db" >}}) to get the most accurate mapping of IP address to Geolocation. - - -### Resolved Issues{#1-2-0-resolved-issues} -This release fixes the following issues. Select an issue's ID link to view its details. - -- {{% icon-resolved %}} The field retrieving URIs is incorrectly listed as URL [(38377)]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md#38377" >}}) - -### Known Issues{#1-2-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.1.0 - -December 20, 2022 - -### Upgrade Paths {#1-1-0-upgrade-paths} - -Security Monitoring supports upgrades from these previous versions: - -- 1.0.0 - -If your Security Monitoring version is older, you may need to upgrade to an intermediate version before upgrading to the target version. - - - -### Changes in Default Behavior{#1-1-0-changes-in-behavior} -This release has the following changes in default behavior: - -- {{% icon-feature %}} **Removal of Total Requests count** - - The Total Requests count was removed from the Security Monitoring dashboards, to avoid customer confusion, as the value didn't convey different configuration scenarios for NGINX App Protect on NGINX instances. - -- {{% icon-feature %}} **Removal of WAF PASSED requests count** - - The count of WAF `PASSED` requests was removed from the Security Monitoring dashboards to avoid customer confusion, as it counted only requests with violations and not all requests filtered by NGINX App Protect WAF. - - -### Known Issues{#1-1-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - ---- - -## 1.0.0 - -November 17, 2022 - - -### What's New{#1-0-0-whats-new} -This release includes the following updates: - -- {{% icon-feature %}} **Introducing the NGINX Security Monitoring module** - - Use the NGINX Security Monitoring module to monitor the NGINX App Protect WAF protection of your apps and APIs. View protection insights for analyzing possible threats and tuning policies. - - The Security Monitoring module includes the following: - - - Informative dashboards that provide valuable protection insights - - In-depth security log details to help with analyzing possible threats and making policy decisions - - Refer to the [Installation Guide]({{< relref "/nim/deploy/_index.md" >}}) to get started. - - -### Known Issues{#1-0-0-known-issues} - -You can find information about known issues in the [Known Issues]({{< relref "/nim/monitoring/security-monitoring/releases/known-issues.md" >}}) topic. - diff --git a/content/nim/monitoring/security-monitoring/set-up-app-protect-instances.md b/content/nim/monitoring/security-monitoring/set-up-app-protect-instances.md new file mode 100644 index 000000000..e92b98034 --- /dev/null +++ b/content/nim/monitoring/security-monitoring/set-up-app-protect-instances.md @@ -0,0 +1,192 @@ +--- +title: Set up App Protect WAF instances for Security Monitoring +weight: 100 +toc: true +type: how-to +product: NIM +docs: DOCS-1107 +--- + +## Overview + +F5 NGINX Security Monitoring supports two main use cases: + +- **Security Monitoring only**: Monitor data from NGINX App Protect WAF instances. You can view security dashboards to identify threats and adjust policies. WAF configurations are managed outside NGINX Instance Manager. +- **Security Monitoring and Instance Manager**: Monitor security data and manage WAF configurations and policies in one place. Push pre-compiled updates to individual instances or groups. + +--- + +## Before you begin + +Complete these steps before starting: + +1. If you’re new to NGINX App Protect WAF, follow these guides: + + - [Install NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/admin-guide/install/) on each data plane instance. Ensure connectivity to the NGINX Instance Manager host. + - [Configure NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/configuration-guide/configuration/#policy-configuration-overview) as needed for each instance. + +2. Review NGINX App Protect WAF dependencies: + + {{< include "nim/tech-specs/security-data-plane-dependencies.md" >}} + +3. Determine your use case: **Security Monitoring only** or **Security Monitoring and Configuration Management**. + +--- + +## Install NGINX Agent + +NGINX Agent collects metrics, manages configurations, and sends events. Install and configure it on each WAF data plane host. + +1. Connect to the host via SSH. +2. Install the NGINX Agent package from the NGINX Instance Manager host: + + {{< include "agent/installation/install-agent-api.md" >}} + +3. Edit `/etc/nginx-agent/nginx-agent.conf` to enable `nap_monitoring`. Add this configuration: + + ```yaml + dataplane: + status: + poll_interval: 30s + report_interval: 24h + events: + enable: true + metrics: + bulk_size: 20 + report_interval: 1m + collection_interval: 15s + mode: aggregated + config_dirs: "/etc/nginx:/usr/local/etc/nginx:/usr/share/nginx/modules:/etc/nms:/etc/app_protect" + extensions: + - nginx-app-protect + - nap-monitoring + nginx_app_protect: + report_interval: 15s + precompiled_publication: true + nap_monitoring: + collector_buffer_size: 50000 + processor_buffer_size: 50000 + syslog_ip: "127.0.0.1" + syslog_port: 514 + ``` + +4. If `location /api` isn’t configured in `nginx.conf`, add this directive: + + ```nginx + server { + location /api { + api write=on; + allow 127.0.0.1; + deny all; + } + } + ``` + + Restart NGINX: + + ```bash + sudo systemctl restart nginx + ``` + +5. **Important:** The `syslog:server=:` must match the `syslog_ip` and `syslog_port` values in the NGINX Agent configuration file. The dashboards won’t display data if these settings don’t match. + + - For NGINX App Protect Version 5, networking changes prevent using `127.0.0.1` as a syslog server address. Instead, use the `docker0` interface address (typically `192.0.10.1`) or the IP address of the data plane host. + +6. Use the NGINX Agent installation script to add `nginx_app_protect` and `nap_monitoring` fields to the configuration. Follow these steps: + + ```bash + # Download the installation script via API + curl https:///install/nginx-agent > install.sh + + # Use the --nap-monitoring flag to set the child fields for nap_monitoring. + # The values will match the example configuration above. + # Use -m | --nginx-app-protect-mode to set up NGINX App Protect management. + # Example: Specify 'precompiled-publication' for precompiled policy publication, + # which sets 'precompiled_publication' to 'true'. To set it to 'false', use 'none'. + + sudo sh ./install.sh --nap-monitoring true --nginx-app-protect-mode precompiled-publication + ``` + + {{}}The `--nap-monitoring` flag adds fields under `nap_monitoring`. The `--nginx-app-protect-mode` flag sets up management of NGINX App Protect with the following options: + - Use `precompiled-publication` to enable precompiled policy publication (`precompiled_publication: true`). + - Use `none` if you don’t want to enable precompiled publication (`precompiled_publication: false`).{{}} + +7. Restart the NGINX Agent: + + ```bash + sudo systemctl restart nginx-agent + ``` + +--- + +## Create instances for Security Monitoring only + +Use these steps if you’re only monitoring security data without managing configurations in NGINX Instance Manager. + +1. Connect to the data plane host via SSH. +2. Create a log format file at `/etc/app_protect/conf/log_sm.json`: + + ```json + { + "filter": { + "request_type": "illegal" + }, + "content": { + "format": "user-defined", + "format_string": "%blocking_exception_reason%,%dest_port%,%ip_client%,%severity%,%uri%", + "escaping_characters": [ + { + "from": ",", + "to": "%2C" + } + ], + "max_request_size": "2048", + "max_message_size": "5k" + } + } + ``` + +3. In the NGINX configuration, add: + + ```nginx + app_protect_security_log_enable on; + app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; + ``` + +4. Restart NGINX Agent and NGINX: + + ```bash + sudo systemctl restart nginx-agent + sudo systemctl restart nginx + ``` + +--- + +## Create instances for Security Monitoring with Instance Manager + +Follow these steps to use Security Monitoring and Instance Manager together. + +1. Log in to the NGINX Instance Manager interface. +2. Navigate to **Modules** > **Instance Manager**. +3. Select **Edit Config** for the desired instance or group. +4. Add the following to the configuration file: + + ```nginx + app_protect_enable on; + app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz"; + app_protect_security_log_enable on; + app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; + ``` + +5. **Important:** Add the `app_protect_policy_file` directive with a reference to a security policy. Use the `.tgz` file extension for precompiled publication or `.json` for non-precompiled configurations. Ensure the policy file exists at the specified location. If using custom policies, update them in NGINX Instance Manager. + +6. Add the `app_protect_security_log_enable` and `app_protect_security_log` directives to log attack data. Ensure the configuration references the correct `syslog:server` values. + +7. Select **Publish** to push updates to instances. + +--- + +## See also + +- [Add user access to Security Monitoring dashboards]({{< relref "/nim/monitoring/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}}) +- [Manage your app protect WAF configs]({{< relref "/nim/nginx-app-protect/setup-waf-config-management" >}}) diff --git a/content/nim/monitoring/security-monitoring/troubleshooting.md b/content/nim/monitoring/security-monitoring/troubleshooting.md index 75230b7b2..983405844 100644 --- a/content/nim/monitoring/security-monitoring/troubleshooting.md +++ b/content/nim/monitoring/security-monitoring/troubleshooting.md @@ -1,6 +1,4 @@ --- -description: This topic describes possible issues users might encounter when using - the Security Monitoring module. When possible, suggested workarounds are provided. docs: DOCS-1226 doctypes: - reference @@ -11,39 +9,38 @@ toc: true weight: 1000 --- -## Security Event log backup with Security Monitoring +## Security event log backup with Security Monitoring ### Description -If a Security Violation event is not received by the Security Monitoring module, the data representing the attack is lost. +If a Security Violation event is not received by the Security Monitoring module, the attack data is lost. ### Resolution -F5 NGINX App Protect supports logging to multiple destinations, enabling the user to send a log to NGINX agent and a copy to be stored as a backup. In the event of a failure to receive Security Events in Security Monitoring, the backup log can be checked to verify attack details. Change the settings below to enable backup logging: +F5 NGINX App Protect supports logging to multiple destinations. This allows users to send logs to the NGINX agent and store a backup. If Security Monitoring fails to receive Security Events, you can check the backup log to verify attack details. Use the following settings to enable backup logging: -1. Instance with Security Monitoring only +1. **For an instance with Security Monitoring only:** -```nginx -app_protect_policy_file "/etc/app_protect/conf/NginxDefaultPolicy.json"; -app_protect_security_log_enable on; -app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; -app_protect_security_log "/etc/app_protect/conf/log_sm.json" ; -# Example: app_protect_security_log "/etc/app_protect/conf/log_sm.json" /var/log/app_protect/security.log; -``` + ```nginx + app_protect_policy_file "/etc/app_protect/conf/NginxDefaultPolicy.json"; + app_protect_security_log_enable on; + app_protect_security_log "/etc/app_protect/conf/log_sm.json" syslog:server=127.0.0.1:514; + app_protect_security_log "/etc/app_protect/conf/log_sm.json" ; + # Example: app_protect_security_log "/etc/app_protect/conf/log_sm.json" /var/log/app_protect/security.log; + ``` -1. Instance with Security Monitoring and NGINX Instance Manager +2. **For an instance with Security Monitoring and NGINX Instance Manager:** -```nginx -app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz"; -app_protect_security_log_enable on; -app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; -app_protect_security_log "/etc/nms/secops_dashboard.tgz" ; -# Example: app_protect_security_log "/etc/nms/secops_dashboard.tgz" /var/log/app_protect/security.log; -``` + ```nginx + app_protect_policy_file "/etc/nms/NginxDefaultPolicy.tgz"; + app_protect_security_log_enable on; + app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; + app_protect_security_log "/etc/nms/secops_dashboard.tgz" ; + # Example: app_protect_security_log "/etc/nms/secops_dashboard.tgz" /var/log/app_protect/security.log; + ``` --- -## How to Get Support +## How to get support {{< include "support/how-to-get-support.md" >}} - diff --git a/content/nim/monitoring/security-monitoring/update-geo-db.md b/content/nim/monitoring/security-monitoring/update-geo-db.md new file mode 100644 index 000000000..7d5a2495f --- /dev/null +++ b/content/nim/monitoring/security-monitoring/update-geo-db.md @@ -0,0 +1,42 @@ +--- +title: Update the geolocation database used in dashboards +weight: 400 +toc: true +type: how-to +product: NIM +docs: DOCS-1108 +--- + +## Overview + +The F5 NGINX Security Monitoring module tracks security violations on NGINX App Protect WAF instances. It uses MaxMind's GeoLite2 Free Database to provide geolocation data in analytics dashboards. + +Follow these steps to update the Security Monitoring module with the latest geolocation database, ensuring dashboards display accurate geolocation data. + +--- + +## Before you begin + +Ensure the following prerequisites are met: + +- NGINX App Protect is configured, and the Security Monitoring dashboard is collecting security violations. + +--- + +## Update the geolocation database + +1. Create a [MaxMind](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data/) account and subscribe to receive updates for the GeoLite2 database. +2. Download the GeoLite2 Country database (Edition ID: GeoLite2-Country) in GeoIP2 Binary `.mmdb` format from the [MaxMind](https://www.maxmind.com/en/accounts/current/geoip/downloads) website. The database is included in a `.gzip` file. +3. Extract the `.gzip` file to access the GeoLite2 Country database file, named `GeoLite2-Country.mmdb`. +4. Replace the existing `GeoLite2-Country.mmdb` file on the NGINX Instance Manager control plane at `/usr/share/nms/geolite2/GeoLite2-Country.mmdb` with the new database: + + ```bash + sudo scp /path/to/GeoLite2-Country.mmdb {user}@{host}:/usr/share/nms/geolite2/GeoLite2-Country.mmdb + ``` + +5. Restart the NGINX Instance Manager services to apply the update: + + ```bash + sudo systemctl restart nms-ingestion + sudo systemctl restart nms-core + ``` diff --git a/content/nim/monitoring/security-monitoring/update-signatures.md b/content/nim/monitoring/security-monitoring/update-signatures.md new file mode 100644 index 000000000..374a75076 --- /dev/null +++ b/content/nim/monitoring/security-monitoring/update-signatures.md @@ -0,0 +1,49 @@ +--- +title: Update the Attack Signature Database +weight: 300 +toc: true +type: how-to +product: NIM +docs: DOCS-1109 +--- + +## Overview + +The F5 NGINX Security Monitoring module tracks security violations on NGINX App Protect WAF instances. Its analytics dashboards use a Signature Database to provide details about Attack Signatures, including their name, accuracy, and risk. + +If the Signature Database is outdated and doesn’t match the version used in App Protect WAF, new signatures may appear without attributes like a name, risk, or accuracy. + +Follow these steps to update the Security Monitoring module with the latest Attack Signature data, ensuring the dashboards display complete and accurate information. + +--- + +## Before you begin + +Ensure the following prerequisites are met: + +- NGINX App Protect is configured, and the Security Monitoring dashboard is collecting security violations. + +--- + +## Update the Signature Database + +1. Open an SSH connection to the data plane host and log in. +2. Generate a Signature Report file using the [Attack Signature Report Tool]({{< relref "/nap-waf/v4/configuration-guide/configuration.md#attack-signature-report-tool" >}}). Save the file as `signature-report.json`: + + ```bash + sudo /opt/app_protect/bin/get-signatures -o ./signature-report.json + ``` + +3. Open an SSH connection to the management plane host and log in. +4. Copy the `signature-report.json` file to the NGINX Instance Manager control plane at `/usr/share/nms/sigdb/`: + + ```bash + sudo scp /path/to/signature-report.json {user}@{host}:/usr/share/nms/sigdb/signature-report.json + ``` + +5. Restart the NGINX Instance Manager services to apply the update: + + ```bash + sudo systemctl restart nms-ingestion + sudo systemctl restart nms-core + ``` diff --git a/content/nim/nginx-app-protect/setup-waf-config-management.md b/content/nim/nginx-app-protect/setup-waf-config-management.md index 71bbe7256..738ae9739 100644 --- a/content/nim/nginx-app-protect/setup-waf-config-management.md +++ b/content/nim/nginx-app-protect/setup-waf-config-management.md @@ -23,7 +23,7 @@ Complete the following prerequisites before proceeding with this guide. - You have one or more instances of [NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/admin-guide/install/) installed and running. See [Support for NGINX App Protect WAF]({{< relref "tech-specs#support-for-nginx-app-protect-waf" >}}) for a list of supported versions. - {{}}If you are using configuration management and the NGINX Management Suite Security Monitoring module, follow the instructions in the [setup guide]({{}}) to set up your NGINX App Protect instances before proceeding with this guide.{{}} + {{}}If you are using configuration management and the NGINX Management Suite Security Monitoring module, follow the instructions in the [setup guide]({{}}) to set up your NGINX App Protect instances before proceeding with this guide.{{}} - You have Instance Manager v2.6.0 or later [installed]({{< relref "/nim/deploy/vm-bare-metal/_index.md" >}}), licensed, and running. If you have a subscription to NGINX App Protect WAF, you can find your Instance Manager license in the subscription details section of [MyF5](https://my.f5.com). @@ -398,7 +398,7 @@ curl -X POST 'https://{{NMS_FQDN}}//api/platform/v1/security/threat-campaigns' \ The Security Monitoring module's analytics dashboards make use of a Signature Database to provide more information on Attack Signatures that have triggered Security Violations, such as the Signature's name, accuracy, and risk level. -To ensure that the dashboards show the most up-to-date information, you need to [update the Security Monitoring Signature Database]({{< relref "/nim/monitoring/security-monitoring/configure/update-signatures" >}}) +To ensure that the dashboards show the most up-to-date information, you need to [update the Security Monitoring Signature Database]({{< relref "/nim/monitoring/security-monitoring/update-signatures" >}}) --- @@ -922,7 +922,7 @@ server { app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; ``` -Refer to the [Security Monitoring setup guide]({{< relref "/nim/monitoring/security-monitoring/configure/set-up-app-protect-instances" >}}) to learn more. {{}} +Refer to the [Security Monitoring setup guide]({{< relref "/nim/monitoring/security-monitoring/set-up-app-protect-instances" >}}) to learn more. {{}} {{}} NGINX configuration for NGINX App Protect Version 5 requires the following changes: diff --git a/content/nms/acm/how-to/install-acm.md b/content/nms/acm/how-to/install-acm.md index 9a83bd09c..04b9b9e84 100644 --- a/content/nms/acm/how-to/install-acm.md +++ b/content/nms/acm/how-to/install-acm.md @@ -155,10 +155,6 @@ Complete the following steps for each data plane instance you want to use with A - [Install the Developer Portal]({{< relref "/nms/acm/how-to/devportals/installation/install-dev-portal.md" >}}) -### Install Other NGINX Management Suite Modules - -- [Install Security Monitoring]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) - ### Get Started with API Connectivity Manager - [Create Workspaces and Environments for your API Infrastructure]({{< relref "/nms/acm/how-to/infrastructure/manage-api-infrastructure.md" >}}) diff --git a/content/nms/acm/how-to/policies/advanced-security.md b/content/nms/acm/how-to/policies/advanced-security.md index f87ac5445..06ef4784c 100644 --- a/content/nms/acm/how-to/policies/advanced-security.md +++ b/content/nms/acm/how-to/policies/advanced-security.md @@ -40,7 +40,7 @@ To complete the steps in this guide, you need the following: - You have one or more [Environments with an API Gateway]({{< relref "/nms/acm/getting-started/add-api-gateway" >}}). - You have [published one or more API Gateways]({{< relref "/nms/acm/getting-started/publish-api-proxy" >}}). - You have [installed and set up NGINX App Protect]({{< relref "/nap-waf/v4/admin-guide/install-nms" >}}). -- NGINX Management Suite Security Monitoring is [installed]({{< relref "/nim/monitoring/security-monitoring/install-security-monitoring.md" >}}) and running. + --- From fd3c4635f65a426ab3151f7133c5377939bf0cef Mon Sep 17 00:00:00 2001 From: Travis Martin Date: Wed, 29 Jan 2025 10:56:48 -0800 Subject: [PATCH 2/2] moved sec mon docs to nap dir --- content/nap-waf/v4/admin-guide/install-nms.md | 2 +- .../security-monitoring/_index.md | 0 .../give-access-to-security-monitoring-dashboards.md | 0 .../security-monitoring/set-up-app-protect-instances.md | 2 +- .../security-monitoring/troubleshooting.md | 0 .../security-monitoring/update-geo-db.md | 0 .../security-monitoring/update-signatures.md | 0 .../nim/nginx-app-protect/setup-waf-config-management.md | 6 +++--- 8 files changed, 5 insertions(+), 5 deletions(-) rename content/nim/{monitoring => nginx-app-protect}/security-monitoring/_index.md (100%) rename content/nim/{monitoring => nginx-app-protect}/security-monitoring/give-access-to-security-monitoring-dashboards.md (100%) rename content/nim/{monitoring => nginx-app-protect}/security-monitoring/set-up-app-protect-instances.md (98%) rename content/nim/{monitoring => nginx-app-protect}/security-monitoring/troubleshooting.md (100%) rename content/nim/{monitoring => nginx-app-protect}/security-monitoring/update-geo-db.md (100%) rename content/nim/{monitoring => nginx-app-protect}/security-monitoring/update-signatures.md (100%) diff --git a/content/nap-waf/v4/admin-guide/install-nms.md b/content/nap-waf/v4/admin-guide/install-nms.md index ac94a2a68..9020cba28 100644 --- a/content/nap-waf/v4/admin-guide/install-nms.md +++ b/content/nap-waf/v4/admin-guide/install-nms.md @@ -21,7 +21,7 @@ weight: 100 [NGINX Management Suite Security Monitoring]({{< relref "/nms/about.md#security-monitoring" >}}) provides a centralized visualization tool that lets you analyze threats, view protection insights, and identify areas for policy tuning. -- For more information on how to configure Security Monitoring, see [Set Up App Protect Instances for Security Monitoring]({{< relref "/nim/monitoring/security-monitoring/set-up-app-protect-instances.md" >}}). +- For more information on how to configure Security Monitoring, see [Set Up App Protect Instances for Security Monitoring]({{< relref "/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md" >}}). --- diff --git a/content/nim/monitoring/security-monitoring/_index.md b/content/nim/nginx-app-protect/security-monitoring/_index.md similarity index 100% rename from content/nim/monitoring/security-monitoring/_index.md rename to content/nim/nginx-app-protect/security-monitoring/_index.md diff --git a/content/nim/monitoring/security-monitoring/give-access-to-security-monitoring-dashboards.md b/content/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md similarity index 100% rename from content/nim/monitoring/security-monitoring/give-access-to-security-monitoring-dashboards.md rename to content/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md diff --git a/content/nim/monitoring/security-monitoring/set-up-app-protect-instances.md b/content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md similarity index 98% rename from content/nim/monitoring/security-monitoring/set-up-app-protect-instances.md rename to content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md index e92b98034..9e58b4f51 100644 --- a/content/nim/monitoring/security-monitoring/set-up-app-protect-instances.md +++ b/content/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances.md @@ -188,5 +188,5 @@ Follow these steps to use Security Monitoring and Instance Manager together. ## See also -- [Add user access to Security Monitoring dashboards]({{< relref "/nim/monitoring/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}}) +- [Add user access to Security Monitoring dashboards]({{< relref "/nim/nginx-app-protect/security-monitoring/give-access-to-security-monitoring-dashboards.md" >}}) - [Manage your app protect WAF configs]({{< relref "/nim/nginx-app-protect/setup-waf-config-management" >}}) diff --git a/content/nim/monitoring/security-monitoring/troubleshooting.md b/content/nim/nginx-app-protect/security-monitoring/troubleshooting.md similarity index 100% rename from content/nim/monitoring/security-monitoring/troubleshooting.md rename to content/nim/nginx-app-protect/security-monitoring/troubleshooting.md diff --git a/content/nim/monitoring/security-monitoring/update-geo-db.md b/content/nim/nginx-app-protect/security-monitoring/update-geo-db.md similarity index 100% rename from content/nim/monitoring/security-monitoring/update-geo-db.md rename to content/nim/nginx-app-protect/security-monitoring/update-geo-db.md diff --git a/content/nim/monitoring/security-monitoring/update-signatures.md b/content/nim/nginx-app-protect/security-monitoring/update-signatures.md similarity index 100% rename from content/nim/monitoring/security-monitoring/update-signatures.md rename to content/nim/nginx-app-protect/security-monitoring/update-signatures.md diff --git a/content/nim/nginx-app-protect/setup-waf-config-management.md b/content/nim/nginx-app-protect/setup-waf-config-management.md index 738ae9739..7a1e73f0f 100644 --- a/content/nim/nginx-app-protect/setup-waf-config-management.md +++ b/content/nim/nginx-app-protect/setup-waf-config-management.md @@ -23,7 +23,7 @@ Complete the following prerequisites before proceeding with this guide. - You have one or more instances of [NGINX App Protect WAF](https://docs.nginx.com/nginx-app-protect/admin-guide/install/) installed and running. See [Support for NGINX App Protect WAF]({{< relref "tech-specs#support-for-nginx-app-protect-waf" >}}) for a list of supported versions. - {{}}If you are using configuration management and the NGINX Management Suite Security Monitoring module, follow the instructions in the [setup guide]({{}}) to set up your NGINX App Protect instances before proceeding with this guide.{{}} + {{}}If you are using configuration management and the NGINX Management Suite Security Monitoring module, follow the instructions in the [setup guide]({{}}) to set up your NGINX App Protect instances before proceeding with this guide.{{}} - You have Instance Manager v2.6.0 or later [installed]({{< relref "/nim/deploy/vm-bare-metal/_index.md" >}}), licensed, and running. If you have a subscription to NGINX App Protect WAF, you can find your Instance Manager license in the subscription details section of [MyF5](https://my.f5.com). @@ -398,7 +398,7 @@ curl -X POST 'https://{{NMS_FQDN}}//api/platform/v1/security/threat-campaigns' \ The Security Monitoring module's analytics dashboards make use of a Signature Database to provide more information on Attack Signatures that have triggered Security Violations, such as the Signature's name, accuracy, and risk level. -To ensure that the dashboards show the most up-to-date information, you need to [update the Security Monitoring Signature Database]({{< relref "/nim/monitoring/security-monitoring/update-signatures" >}}) +To ensure that the dashboards show the most up-to-date information, you need to [update the Security Monitoring Signature Database]({{< relref "/nim/nginx-app-protect/security-monitoring/update-signatures" >}}) --- @@ -922,7 +922,7 @@ server { app_protect_security_log "/etc/nms/secops_dashboard.tgz" syslog:server=127.0.0.1:514; ``` -Refer to the [Security Monitoring setup guide]({{< relref "/nim/monitoring/security-monitoring/set-up-app-protect-instances" >}}) to learn more. {{}} +Refer to the [Security Monitoring setup guide]({{< relref "/nim/nginx-app-protect/security-monitoring/set-up-app-protect-instances" >}}) to learn more. {{}} {{}} NGINX configuration for NGINX App Protect Version 5 requires the following changes: