Administration Guide

Overview

NGINX App Protect provides web application firewall (WAF) security protection for your web applications, including OWASP Top 10; response inspection; Meta characters check; HTTP protocol compliance; evasion techniques; disallowed file types; JSON & XML well-formedness; sensitive parameters & Data Guard.

This guide explains how to deploy NGINX App Protect as well as upgrade App Protect and the App Protect signature sets.

• Prerequisites
• Platform Security Considerations
• CentOS 7.4+ Installation
• RHEL 7.4+ Installation
• Debian 9 Installation
• Ubuntu 18.04 Installation
• Docker Deployment
• Offline Installation
• Post-Installation Checks
• Updating App Protect Attack Signatures
• Updating App Protect Threat Campaigns
• Upgrading App Protect
• SELinux Configuration

Prerequisites

NGINX App Protect is available to customers as a downloadable dynamic module at an additional cost. To purchase or add NGINX App Protect to an existing NGINX Plus subscription, contact the NGINX sales team.

NGINX Plus Release 19 and later supports NGINX App Protect.

NGINX App Protect supports the following operating systems:

• CentOS/RHEL 7.4.x and above
• Debian 9
• Ubuntu 18.04

The NGINX App Protect package has 4 dependencies:

1. nginx-plus-module-appprotect - NGINX Plus dynamic module for App Protect
2. app-protect-engine - The App Protect enforcement engine
3. app-protect-plugin - The App Protect connector API between the engine and the NGINX Plus dynamic module
4. app-protect-compiler - The App Protect enforcement engine compiler agent

See the NGINX Plus full list of prerequisites for more details. NGINX App Protect can be installed as a module to an existing NGINX Plus installation or as a complete NGINX Plus with App Protect installation in a clean environment.

Platform Security Considerations

When deploying App Protect on NGINX Plus take the following precautions to secure the platform. This avoids the risk of causing a Denial of Service condition or compromising the platform security.

• Restrict permissions to the files on the NGINX App Protect platform to user nginx and group nginx, especially for the sensitive areas containing the configuration.
• Remove unnecessary remote access services on the platform.
• Configure a Syslog destination on the same machine as App Protect and proxy to an external destination. This avoids eavesdropping and man-in-the-middle attacks on the Syslog channel.

CentOS 7.4+ Installation

1. If you already have NGINX packages in your system, back up your configs and logs:

   sudo cp -a /etc/nginx /etc/nginx-plus-backup
   sudo cp -a /var/log/nginx /var/log/nginx-plus-backup
   

2. Create the /etc/ssl/nginx/ directory:

   sudo mkdir -p /etc/ssl/nginx
   

3. Log in to the NGINX Customer Portal and download the following two files:

   nginx-repo.key
   nginx-repo.crt
   

4. Copy the above two files to the CentOS server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

5. Install prerequisite packages:

   sudo yum install ca-certificates epel-release wget
   

6. Add NGINX Plus repository:

   sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.repo
   

7. Install the most recent version of the NGINX Plus App Protect package (which includes NGINX Plus):

   sudo yum install app-protect
   

   Alternatively, you can use the following command to list available versions:

   sudo yum --showduplicates list app-protect
   

   Then, install a specific version from the output of command above. For example:

   sudo yum install app-protect-20+2.52.1
   

8. Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:

   sudo nginx -v
   

9. Load the NGINX App Protect module on the main context in the nginx.conf:

   load_module modules/ngx_http_app_protect_module.so;
   

10. Enable NGINX App Protect on an http/server/location context in the nginx.conf file:

    app_protect_enable on;
    

11. Configure SELinux as appropriate per your organization’s security policies. App Protect applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the Troubleshooting Guide.

12. Start the NGINX service:

    sudo systemctl start nginx
    

RHEL 7.4+ Installation

1. If you already have NGINX packages in your system, back up your configs and logs:

   sudo cp -a /etc/nginx /etc/nginx-plus-backup
   sudo cp -a /var/log/nginx /var/log/nginx-plus-backup
   

2. Create the /etc/ssl/nginx/ directory:

   sudo mkdir -p /etc/ssl/nginx
   

3. Log in to the NGINX Customer Portal and download the following two files:

   nginx-repo.key
   nginx-repo.crt
   

4. Copy the above two files to the RHEL server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

5. Install prerequisite packages:

   sudo yum install ca-certificates wget
   

6. Add NGINX Plus repository by downloading the file nginx-plus-7.repo to /etc/yum.repos.d:

   sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.repo
   

7. Enable Yum repositories to pull App Protect dependencies:

   Install epel-release:

   sudo rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
   

   If you have a RHEL subscription:

   sudo yum-config-manager --enable rhui-REGION-rhel-server-optional rhui-REGION-rhel-server-releases rhel-7-server-optional-rpms
   

   If you don’t have a RHEL subscription you can pull the dependencies from the CentOS repository: Create a new repository centos.repo in /etc/yum.repos.d/ with the content:

   [centos]
   name=CentOS-7
   baseurl=http://ftp.heanet.ie/pub/centos/7/os/x86_64/
   enabled=1
   gpgcheck=1
   gpgkey=http://ftp.heanet.ie/pub/centos/7/os/x86_64/RPM-GPG-KEY-CentOS-7
   

8. Install the most recent version of the NGINX Plus App Protect package (which includes NGINX Plus):

   sudo yum install app-protect
   

   Alternatively, you can use the following command to list available versions:

   sudo yum --showduplicates list app-protect
   

   Then, install a specific version from the output of command above. For example:

   sudo yum install app-protect-22+3.74.0
   

9. Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:

   sudo nginx -v
   

10. Load the NGINX App Protect module on the main context in the nginx.conf:

    load_module modules/ngx_http_app_protect_module.so;
    

11. Enable NGINX App Protect on an http/server/location context in the nginx.conf file:

    app_protect_enable on;
    

12. Configure SELinux as appropriate per your organization’s security policies. App Protect applies the prebuilt SELinux policy module during the installation. If you encounter any issues, check the Troubleshooting Guide.

13. Start the NGINX service:

    sudo systemctl start nginx
    

Debian 9 Installation

1. If you already have NGINX packages in your system, back up your configs and logs:

   sudo cp -a /etc/nginx /etc/nginx-plus-backup
   sudo cp -a /var/log/nginx /var/log/nginx-plus-backup
   

2. Create the /etc/ssl/nginx/ directory:

   sudo mkdir -p /etc/ssl/nginx
   

3. Log in to the NGINX Customer Portal and download the following two files:

   nginx-repo.key
   nginx-repo.crt
   

4. Copy the above two files to the Debian server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

5. Install apt utils:

   sudo apt-get install apt-transport-https lsb-release ca-certificates wget
   

6. Download and add the NGINX signing key:

   sudo wget https://cs.nginx.com/static/keys/nginx_signing.key && sudo apt-key add nginx_signing.key
   

7. Add NGINX Plus repository:

   printf "deb https://plus-pkgs.nginx.com/debian `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list
   

8. Download the apt configuration to /etc/apt/apt.conf.d:

   sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90nginx
   

9. Update the repository and install the most recent version of the NGINX Plus App Protect package (which includes NGINX Plus):

   sudo apt-get update
   sudo apt-get install app-protect
   

   Alternatively, to install a specific version you should modify the repository URL in the /etc/apt/sources.list.d/nginx-plus.list file in the following way:

   deb https://plus-pkgs.nginx.com/Rxx/debian ...
   

   where xx is a release number.

   For example, to install app-protect version 20 make sure of the following:

   cat /etc/apt/sources.list.d/nginx-plus.list
   deb https://plus-pkgs.nginx.com/R20/debian stretch nginx-plus
   

   Then, use the following commands to update and list available versions:

    sudo apt-get update
    sudo apt-cache policy app-protect
   

   Finally, install a specific version from the output of command above. For example:

   sudo apt-get install app-protect=20+2.52.1-1~stretch
   

10. Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:

    sudo nginx -v
    

11. Load the NGINX App Protect module on the main context in the nginx.conf file:

    load_module modules/ngx_http_app_protect_module.so;
    

12. Enable NGINX App Protect on an http/server/location context in the nginx.conf via:

    app_protect_enable on;
    

13. Start the NGINX service:

    sudo service nginx start
    

Ubuntu 18.04 Installation

1. If you already have NGINX packages in your system, back up your configs and logs:

   sudo cp -a /etc/nginx /etc/nginx-plus-backup
   sudo cp -a /var/log/nginx /var/log/nginx-plus-backup
   

2. Create the /etc/ssl/nginx/ directory:

   sudo mkdir -p /etc/ssl/nginx
   

3. Log in to the NGINX Customer Portal and download the following two files:

   nginx-repo.key
   nginx-repo.crt
   

4. Copy the above two files to the Ubuntu server’s /etc/ssl/nginx/ directory. Use an SCP client or another secure file transfer tool to perform this task.

5. Install apt utils:

   sudo apt-get install apt-transport-https lsb-release ca-certificates wget
   

6. Download and add the NGINX signing key:

   sudo wget https://cs.nginx.com/static/keys/nginx_signing.key && sudo apt-key add nginx_signing.key
   

7. Add NGINX Plus repository:

   printf "deb https://plus-pkgs.nginx.com/ubuntu `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/nginx-plus.list
   

8. Download the apt configuration to /etc/apt/apt.conf.d:

   sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90nginx
   

9. Update the repository and install the most recent version of the NGINX Plus App Protect package (which includes NGINX Plus):

   sudo apt-get update
   sudo apt-get install app-protect
   

10. Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:

    sudo nginx -v
    

11. Load the NGINX App Protect module on the main context in the nginx.conf file:

    load_module modules/ngx_http_app_protect_module.so;
    

12. Enable NGINX App Protect on an http/server/location context in the nginx.conf via:

    app_protect_enable on;
    

13. Start the NGINX service:

    sudo service nginx start
    

Docker Deployment

# For CentOS 7:
FROM centos:7.4.1708

# Download certificate and key from the customer portal (https://cs.nginx.com)
# and copy to the build context:
COPY nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

# Install prerequisite packages:
RUN yum -y install wget ca-certificates epel-release

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.repo

# Install NGINX App Protect:
RUN yum -y install app-protect \
    && yum clean all \
    && rm -rf /var/cache/yum \
    && rm -rf /etc/ssl/nginx

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh  /root/

CMD ["sh", "/root/entrypoint.sh"]

# For RHEL ubi7:
FROM registry.redhat.io/ubi7/ubi

ARG RHEL_ORGANIZATION
ARG RHEL_ACTIVATION_KEY

# Download certificate and key from the customer portal (https://cs.nginx.com)
# and copy to the build context:
COPY nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

# Install prerequisite packages:
RUN yum -y install wget ca-certificates

# Add NGINX Plus repo to Yum:
RUN wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.repo

# Enable Yum repositories to pull App Protect dependencies:
RUN subscription-manager register --org=${RHEL_ORGANIZATION} --activationkey=${RHEL_ACTIVATION_KEY} \
    && yum-config-manager --enable rhui-REGION-rhel-server-extras rhui-REGION-rhel-server-optional rhel-7-server-optional-rpms \
    && rpm -ivh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm \
    && yum clean all

# Install NGINX App Protect:
RUN yum -y install app-protect \
    && yum clean all \
    && rm -rf /var/cache/yum \
    && rm -rf /etc/ssl/nginx \
    && subscription-manager unregister

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh /root/

CMD ["sh", "/root/entrypoint.sh"]

# For Debian 9:
FROM debian:stretch

# Download certificate and key from the customer portal (https://cs.nginx.com)
# and copy to the build context:
COPY nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://plus-pkgs.nginx.com/debian `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90nginx

# Update the repository and install the most recent version of the NGINX Plus App Protect package (which includes NGINX Plus):
RUN apt-get update && apt-get install -y app-protect

# Remove nginx repository key/cert from docker
RUN rm -rf /etc/ssl/nginx

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh  /root/

CMD ["sh", "/root/entrypoint.sh"]

# For Ubuntu 18.04:
FROM ubuntu:bionic

# Download certificate and key from the customer portal (https://cs.nginx.com)
# and copy to the build context:
COPY nginx-repo.crt nginx-repo.key /etc/ssl/nginx/

# Install prerequisite packages:
RUN apt-get update && apt-get install -y apt-transport-https lsb-release ca-certificates wget gnupg2

# Download and add the NGINX signing key:
RUN wget https://cs.nginx.com/static/keys/nginx_signing.key && apt-key add nginx_signing.key

# Add NGINX Plus repository:
RUN printf "deb https://plus-pkgs.nginx.com/ubuntu `lsb_release -cs` nginx-plus\n" | tee /etc/apt/sources.list.d/nginx-plus.list

# Download the apt configuration to `/etc/apt/apt.conf.d`:
RUN wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90nginx

# Update the repository and install the most recent version of the NGINX Plus App Protect package (which includes NGINX Plus):
RUN apt-get update && apt-get install -y app-protect

# Remove nginx repository key/cert from docker
RUN rm -rf /etc/ssl/nginx

# Forward request logs to Docker log collector:
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
    && ln -sf /dev/stderr /var/log/nginx/error.log

# Copy configuration files:
COPY nginx.conf custom_log_format.json /etc/nginx/
COPY entrypoint.sh  /root/

CMD ["sh", "/root/entrypoint.sh"]

Offline Installation

To perform an offline installation of NGINX App Protect you can use a host with access to the NGINX repository to download all the packages (including dependencies) to your local repository.

Post-Installation Checks

You can run the following commands to ensure that NGINX App Protect enforcement is operational.

1. Check that the four processes needed for NGINX App Protect are running using ps aux:

   • bd_agent
   • bd-socket-plugin
   • nginx: master process
   • nginx: worker process

   USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
   root         7  1.2  0.3 128136 50440 ?        S    09:11   0:02 /usr/bin/perl /opt/app_protect/bin/bd_agent
   root         8  1.3  2.4 3486948 399092 ?      Sl   09:11   0:02 /usr/share/ts/bin/bd-socket-plugin tmm_count 4 proc_cpuinfo_cpu_mhz 2000000 total_xml_memory 307200000 total_umu_max_size 3129344 sys_max_account_id 1024 no_static_config
   root        14  0.0  0.1  71060 26680 ?        S    09:11   0:00 nginx: master process /usr/sbin/nginx -c /tmp/policy/test_nginx.conf -g daemon off;
   root        26  0.0  0.3  99236 52092 ?        S    09:12   0:00 nginx: worker process
   root        28  0.0  0.0  11788  2920 pts/0    Ss   09:12   0:00 bash
   root        43  0.0  0.0  47460  3412 pts/0    R+   09:14   0:00 ps aux
   

2. Verify that there are no NGINX errors in the /var/log/nginx/error.log and that the policy compiled successfully:

   2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT { "event": "configuration_load_start", "configSetFile": "/opt/f5waf/config/config_set.json" }
   2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT policy 'app_protect_default_policy' from: /etc/nginx/NginxDefaultPolicy.json compiled successfully
   2020/05/10 13:21:04 [notice] 402#402: APP_PROTECT { "event": "configuration_load_success", "software_version": "1.1.1", "attack_signatures_package":{"revision_datetime":"2019-07-16T12:21:31Z"},"completed_successfully":true}
   2020/05/10 13:21:04 [notice] 402#402: using the "epoll" event method
   2020/05/10 13:21:04 [notice] 402#402: nginx/1.17.6 (nginx-plus-r20)
   2020/05/10 13:21:04 [notice] 402#402: built by gcc 4.8.5 20150623 (Red Hat 4.8.5-36) (GCC)
   2020/05/10 13:21:04 [notice] 402#402: OS: Linux 3.10.0-957.27.2.el7.x86_64
   2020/05/10 13:21:04 [notice] 402#402: getrlimit(RLIMIT_NOFILE): 1048576:1048576
   2020/05/10 13:21:04 [notice] 406#406: start worker processes
   2020/05/10 13:21:04 [notice] 406#406: start worker process 407
   

3. Check that sending an attack signature in a request returns a response block page containing a support ID:

   Request:
   http://10.240.185.211/?a=<script>
   
   Response:
   The requested URL was rejected. Please consult with your administrator.
   
   Your support ID is: 9847191526422998597
   
   [Go Back]
   

4. In case your policy includes JSON/XML profiles, please check /var/log/app_protect/bd-socket-plugin.log and make sure there aren’t any errors by running:

   grep '|ERR' /var/log/app_protect/bd-socket-plugin.log
   

   If you see an error similar to:

   ... Cannot allocate 196744 more bytes for XML parser. current memory size 307089520 (in bytes) ...
   

   Increase the bd-socket-plugin process command line variable total_xml_memory in the startup.sh script or in the nginx-app-protect.service file. The number 471859200 should be enough for most use cases, you may need to use a bigger number if the number of profiles is large, or large json/xml schemas are used in the policy.

5. If there are additional problems, refer to the Troubleshooting Guide.

Updating App Protect Attack Signatures

Attack Signatures updates are released at higher frequency than App Protect, therefore they are released in their own package, separate from the App Protect package. You can update the attack signatures without updating the App Protect release, and conversely, you can update App Protect without changing the attack signature package, unless you move to a new NGINX Plus release.

Updating App Protect Threat Campaigns

The Threat campaigns package is named: app-protect-threat-campaigns. The version number for this package reflects the date the package was released. The format is: YYYY.MM.DD where:

• YYYY is the 4-digit year
• MM is the month
• DD is the day in the month

Example: 2020.03.31

Upgrading App Protect

You can upgrade to the latest NGINX Plus and App Protect versions by downloading and installing the latest NGINX App Protect package. When upgrading from this package, App Protect will be uninstalled and reinstalled. The old default security policy is deleted and the new default security policy is installed. If you have created a custom security policy, the policy persists and you will need to update nginx.conf and point to the custom security policy by referencing the json file (using the full path).

If you upgrade your NGINX version outside of the App Protect module, App Protect will be uninstalled and you will need to reinstall it. You need to restart NGINX after an upgrade.

SELinux Configuration

The default settings for Security-Enhanced Linux (SELinux) on modern Red Hat Enterprise Linux (RHEL) and related distros can be very strict, erring on the side of security rather than convenience.

Although the App Protect applies its SELinux policy module during installation, your specific configuration might be blocked unless you adjust the policy or modify file labels.

semanage fcontext -a -t httpd_config_t /etc/policy
restorecon -Rv /etc/policy

semanage port -a -t syslogd_port_t -p tcp 35514

semanage port -l | grep syslog