Set up App Protect WAF instances for Security Monitoring

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:

  2. Review NGINX App Protect WAF dependencies:

    The Security Monitoring module requires the following versions of NGINX App Protect WAF and NGINX Plus for the data plane:

    Security Monitoring NGINX App Protect WAF
    1.7.1 Release 4.7.0–4.12.0, 5.1.0–5.4.0
    1.7.0 Release 4.4.0–4.7.0
    1.6.0 Release 4.3.0–4.4.0
    1.5.0 Release 4.3.0
    1.4.0 Release 4.2.0
    1.3.0 Release 3.12.2–4.2.0
    1.2.0 Release 3.12.2–4.1.0
    1.1.0 Release 3.12.2–4.0.0
    1.0.0 Release 3.12.2

  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:

    Note: To complete this step, make sure that gpg is installed on your system. You can install NGINX Agent using various command-line tools like curl or wget. If your NGINX Instance Manager host is not set up with valid TLS certificates, you can use the insecure flags provided by those tools. See the following examples:

    • Secure:

      curl https://<NMS_FQDN>/install/nginx-agent | sudo sh

    • Insecure:

      curl --insecure https://<NMS_FQDN>/install/nginx-agent | sudo sh

      You can add your NGINX instance to an existing instance group or create one using --instance-group or -g flag when installing NGINX Agent.

      The following example shows how to download and run the script with the optional --instance-group flag adding the NGINX instance to the instance group my-instance-group:

      curl https://<NMS_FQDN>/install/nginx-agent > install.sh; chmod u+x install.sh
   sudo ./install.sh --instance-group my-instance-group

      By default, the install script attempts to use a secure connection when downloading packages. If, however, the script cannot create a secure connection, it uses an insecure connection instead and logs the following warning message:

      Warning: An insecure connection will be used during this nginx-agent installation

      To require a secure connection, you can set the optional flag skip-verify to false.

      The following example shows how to download and run the script with an enforced secure connection:

      curl https://<NMS_FQDN>/install/nginx-agent > install.sh chmod u+x install.sh; chmod u+x install.sh
   sudo sh ./install.sh --skip-verify false

    • Secure:

      wget https://<NMS_FQDN>/install/nginx-agent -O - | sudo sh -s --skip-verify false

    • Insecure:

      wget --no-check-certificate https://<NMS_FQDN>/install/nginx-agent -O - | sudo sh

      When you install the NGINX Agent, you can use the --instance-group or -g flag to add your NGINX instance to an existing instance group or to a new group that you specify.

      The following example downloads and runs the NGINX Agent install script with the optional --instance-group flag, adding the NGINX instance to the instance group my-instance-group:

      wget https://gnms1.npi.f5net.com/install/nginx-agent -O install.sh ; chmod u+x install.sh
   sudo ./install.sh --instance-group my-instance-group

  3. Edit /etc/nginx-agent/nginx-agent.conf to enable nap_monitoring. Add this configuration:

    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:

    server {
   location /api {
      api write=on;
      allow 127.0.0.1;
      deny all;
   }
}

    Restart NGINX:

    sudo systemctl restart nginx

  5. Important: The syslog:server=<syslog_ip>:<syslog_port> 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:

    # Download the installation script via API
curl https://<NMS_FQDN>/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
    Note:

    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:

    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:

    {
   "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:

    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:

    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:

    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

Last modified February 6, 2025