Administration Guide
Welcome to NGINX App Protect.
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
- User Permissions
- CentOS 7.4+ Installation
- RHEL 7.4+ Installation
- Debian 9 Installation
- Debian 10 Installation
- Ubuntu 18.04 Installation
- Alpine 3.10 Installation
- Docker Deployment
- Converter Tool Docker Image
- 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 21 and later supports NGINX App Protect.
NGINX App Protect supports the following operating systems:
- CentOS/RHEL 7.4.x and above
- Debian 9
- Debian 10
- Ubuntu 18.04
- Alpine 3.10
The NGINX App Protect package has 4 dependencies:
- nginx-plus-module-appprotect - NGINX Plus dynamic module for App Protect
- app-protect-engine - The App Protect enforcement engine
- app-protect-plugin - The App Protect connector API between the engine and the NGINX Plus dynamic module
- 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.
User Permissions
If a user other than nginx is to be used, note the following:
If nginx user creation is disallowed on the platform, the following warning may be seen during installation:
warning: user nginx does not exist - using root
After first installation, upgrade, or security update installation, perform the following steps before starting/restarting/reloading NGINX:
Modify user permissions on all installed NGINX App Protect files:
chown -R <user>:<group> /usr/share/ts /var/log/app_protect /opt/app_protect /etc/app_protect
Modify user of NGINX App Protect processes:
For service startup modify the User in the following files on your platform:
nginx-app-protect-compiler.service
nginx-app-protect.service
For docker deployment, modify the
entrypoint.sh
script to use the correct user instead of nginx when starting up thebd_agent
andbd-socket-plugin
processes.
CentOS 7.4+ Installation
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
Create the
/etc/ssl/nginx/
directory:sudo mkdir -p /etc/ssl/nginx
Log in to the Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
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.Install prerequisite packages:
sudo yum install ca-certificates epel-release wget
Add NGINX Plus repository:
sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/nginx-plus-7.repo
Install the most recent version of the NGINX 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
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
Load the NGINX App Protect module on the main context in the nginx.conf:
load_module modules/ngx_http_app_protect_module.so;
Enable NGINX App Protect on an
http/server/location
context in thenginx.conf
file:app_protect_enable on;
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.
Start the NGINX service:
sudo systemctl start nginx
RHEL 7.4+ Installation
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
Create the
/etc/ssl/nginx/
directory:sudo mkdir -p /etc/ssl/nginx
Log in to the Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
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.Install prerequisite packages:
sudo yum install ca-certificates wget
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
Enable Yum repositories to pull App Protect dependencies:
Download the file
dependencies.repo
to/etc/yum.repos.d
:sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/dependencies.repo
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
Install the most recent version of the NGINX 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
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
Load the NGINX App Protect module on the main context in the
nginx.conf
:load_module modules/ngx_http_app_protect_module.so;
Enable NGINX App Protect on an
http/server/location
context in thenginx.conf
file:app_protect_enable on;
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.
Start the NGINX service:
sudo systemctl start nginx
Debian 9 Installation
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
Create the
/etc/ssl/nginx/
directory:sudo mkdir -p /etc/ssl/nginx
Log in to the Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
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.Install apt utils:
sudo apt-get install apt-transport-https lsb-release ca-certificates wget
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
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
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
Update the repository and install the most recent version of the NGINX 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
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
Load the NGINX App Protect module on the main context in the
nginx.conf
file:load_module modules/ngx_http_app_protect_module.so;
Enable NGINX App Protect on an
http/server/location
context in thenginx.conf
via:app_protect_enable on;
Start the NGINX service:
sudo service nginx start
Debian 10 Installation
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
Create the
/etc/ssl/nginx/
directory:sudo mkdir -p /etc/ssl/nginx
Log in to the Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
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.Install apt utils:
sudo apt-get install apt-transport-https lsb-release ca-certificates wget
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
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
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
Update the repository and install the most recent version of the NGINX 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 23 make sure of the following:
cat /etc/apt/sources.list.d/nginx-plus.list deb https://plus-pkgs.nginx.com/R23/debian buster 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=23+3.263.0-1~buster
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
Load the NGINX App Protect module on the main context in the
nginx.conf
file:load_module modules/ngx_http_app_protect_module.so;
Enable NGINX App Protect on an
http/server/location
context in thenginx.conf
via:app_protect_enable on;
Start the NGINX service:
sudo service nginx start
Note: Debian 10 activates AppArmor by default, but App Protect will run in unconfined mode after being installed as it is shipped with no AppArmor profile. To benefit from AppArmor access control capabilities for NGINX App Protect, you will have to write your own AppArmor profile for NGINX App Protect executables found in /opt/app_protect/bin
such that it best suits your environment.
Ubuntu 18.04 Installation
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
Create the
/etc/ssl/nginx/
directory:sudo mkdir -p /etc/ssl/nginx
Log in to the Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
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.Install apt utils:
sudo apt-get install apt-transport-https lsb-release ca-certificates wget
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
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
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
Update the repository and install the most recent version of the NGINX App Protect package (which includes NGINX Plus):
sudo apt-get update sudo apt-get install app-protect
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
Load the NGINX App Protect module on the main context in the
nginx.conf
file:load_module modules/ngx_http_app_protect_module.so;
Enable NGINX App Protect on an
http/server/location
context in thenginx.conf
via:app_protect_enable on;
Start the NGINX service:
sudo service nginx start
Alpine 3.10 Installation
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
Create the
/etc/ssl/nginx/
directory:sudo mkdir -p /etc/ssl/nginx cd /etc/ssl/nginx
Log in to the Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
Upload
nginx-repo.key
to/etc/apk/cert.key
andnginx-repo.crt
to/etc/apk/cert.pem
. Make sure that files do not contain other certificates and keys, as Alpine Linux does not support mixing client certificates for different repositories.Add the NGINX public signing key to the directory
/etc/apk/keys
:sudo wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub
Add NGINX Plus repository to
/etc/apk/repositories
file:printf "https://plus-pkgs.nginx.com/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | tee -a /etc/apk/repositories
It is recommended to remove all community-supported NGINX packages. Note that all NGINX modules will be removed as well.
sudo apk del -r nginx
Update the repository and install the most recent version of the NGINX App Protect package (which includes NGINX Plus):
sudo apk update sudo apk add app-protect
Alternatively, to install a specific version you should modify the repository URL in the
/etc/apk/repositories
file in the following way:https://plus-pkgs.nginx.com/Rxx/alpine/v3.10/main
where xx is a release number.
For example, to install app-protect version 23 make sure of the following:
cat /etc/apk/repositories https://plus-pkgs.nginx.com/R23/alpine/v3.10/main
Then, use the following commands to update and list available versions:
sudo apk update sudo apk search app-protect
Finally, install a specific version from the output of command above. For example:
sudo apk add app-protect=23.3.281.0-r1
Check the NGINX binary version to ensure that you have NGINX Plus installed correctly:
sudo nginx -v
Load the NGINX App Protect module on the main context in the
nginx.conf
file:load_module modules/ngx_http_app_protect_module.so;
Enable NGINX App Protect on an
http/server/location
context in thenginx.conf
via:app_protect_enable on;
Docker Deployment
Centos 7.4 Docker Deployment Example
# For CentOS 7:
FROM centos:7.4.1708
# Download certificate and key from the customer portal (https://my.f5.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"]
RHEL UBI7 Docker Deployment Example
# 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://my.f5.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"]
Debian 9 Docker Deployment Example
# For Debian 9:
FROM debian:stretch
# Download certificate and key from the customer portal (https://my.f5.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 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"]
Debian 10 Docker Deployment Example
# For Debian 10:
FROM debian:buster
# Download certificate and key from the customer portal (https://my.f5.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 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"]
Ubuntu 18.04 Docker Deployment Example
# For Ubuntu 18.04:
FROM ubuntu:bionic
# Download certificate and key from the customer portal (https://my.f5.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 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"]
Alpine 3.10 Docker Deployment Example
# For Alpine 3.10:
FROM alpine:3.10
# Download certificate and key from the customer portal (https://my.f5.com)
# and copy to the build context:
COPY nginx-repo.key /etc/apk/cert.key
COPY nginx-repo.crt /etc/apk/cert.pem
# Download and add the NGINX signing key:
RUN wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub
# Add NGINX Plus repository:
RUN printf "https://plus-pkgs.nginx.com/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | tee -a /etc/apk/repositories
# Update the repository and install the most recent version of the NGINX App Protect package (which includes NGINX Plus):
RUN apk update && apk add app-protect
# Remove nginx repository key/cert from docker
RUN rm -rf /etc/apk/cert.*
# 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"]
Docker Deployment Instructions
You need root permissions to execute the following steps.
Create a Dockerfile (see examples above) which copies the following files into the docker image:
nginx-repo.crt
: Certificate for NGINX repository accessnginx-repo.key
: Private key for NGINX repository accessnginx.conf
: User defined nginx.conf with app-protect enabledentrypoint.sh
: Docker startup script which spins up all App Protect processes, must have executable permissionscustom_log_format.json
: Optional user defined app-protect security log format file
Log in to the Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
Copy the files to the directory where the Dockerfile is located.
Optionally, create
custom_log_format.json
in the same directory, for example:{ "filter": { "request_type": "all" }, "content": { "format": "splunk", "max_request_size": "any", "max_message_size": "10k" } }
In the same directory create an nginx.conf file with the following contents:
user nginx; worker_processes auto; load_module modules/ngx_http_app_protect_module.so; error_log /var/log/nginx/error.log debug; events { worker_connections 10240; } http { include /etc/nginx/mime.types; default_type application/octet-stream; sendfile on; keepalive_timeout 65; upstream app_backend_com { server 192.168.0.1:8000; server 192.168.0.1:8001; } server { listen 80; server_name app.example.com; proxy_http_version 1.1; app_protect_enable on; app_protect_security_log_enable on; app_protect_security_log "/etc/nginx/custom_log_format.json" syslog:server=127.0.0.1:515; location / { client_max_body_size 0; default_type text/html; # set your backend here proxy_pass http://app_backend_com; proxy_set_header Host $host; } } }
Important: Make sure to replace upstream and proxy pass directives in this example with relevant application backend settings.
In the same directory create an
entrypoint.sh
file with executable permissions, and the following content (replacebash
withsh
for Alpine):#!/usr/bin/env bash /bin/su -s /bin/bash -c '/opt/app_protect/bin/bd_agent &' nginx /bin/su -s /bin/bash -c "/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 2>&1 > /var/log/app_protect/bd-socket-plugin.log &" nginx /usr/sbin/nginx -g 'daemon off;'
Create a Docker image:
# For CentOS/Debian/Ubuntu: docker build --no-cache -t app-protect .
# For RHEL: docker build --build-arg RHEL_ORGANIZATION=${RHEL_ORGANIZATION} --build-arg RHEL_ACTIVATION_KEY=${RHEL_ACTIVATION_KEY} --no-cache -t app-protect .
The
--no-cache
option tells Docker to build the image from scratch and ensures the installation of the latest version of NGINX Plus and NGINX App Protect. If the Dockerfile was previously used to build an image without the--no-cache
option, the new image uses versions from the previously built image from the Docker cache.Verify that the app-protect image was created successfully with the docker images command:
docker images app-protect
Create a container based on this image, for example, my-app-protect container:
docker run --name my-app-protect -p 80:80 -d app-protect
Verify that the my-app-protect container is up and running with the
docker ps
command:docker ps
Converter Tool Docker Image
This section explains how to build a Docker image for the purpose of converting policy files from other F5 WAF products to NGINX App Protect JSON declarative format. For more details regarding this feature refer to Converter Tools
Centos 7.4 Converter Docker Deployment Example
# For CentOS 7:
FROM centos:7.4.1708
# Download certificate and key from the customer portal (https://my.f5.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
# Update the repository and install the most recent version of the NGINX App Protect Compiler package:
RUN yum -y install app-protect-compiler \
&& yum clean all \
&& rm -rf /var/cache/yum \
&& rm -rf /etc/ssl/nginx
CMD ["sh"]
RHEL UBI7 Converter Docker Deployment Example
# 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://my.f5.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
# Update the repository and install the most recent version of the NGINX App Protect Compiler package:
RUN yum -y install app-protect-compiler \
&& yum clean all \
&& rm -rf /var/cache/yum \
&& rm -rf /etc/ssl/nginx \
&& subscription-manager unregister
CMD ["sh"]
Debian 9 Converter Docker Deployment Example
# For Debian 9:
FROM debian:stretch
# Download certificate and key from the customer portal (https://my.f5.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 App Protect Compiler package:
RUN apt-get update && apt-get install -y app-protect-compiler
# Remove nginx repository key/cert from docker
RUN rm -rf /etc/ssl/nginx
CMD ["sh"]
Debian 10 Converter Docker Deployment Example
# For Debian 10:
FROM debian:buster
# Download certificate and key from the customer portal (https://my.f5.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 App Protect Compiler package:
RUN apt-get update && apt-get install -y app-protect-compiler
# Remove nginx repository key/cert from docker
RUN rm -rf /etc/ssl/nginx
CMD ["sh"]
Ubuntu 18.04 Converter Docker Deployment Example
# For Ubuntu 18.04:
FROM ubuntu:bionic
# Download certificate and key from the customer portal (https://my.f5.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 App Protect Compiler package:
RUN apt-get update && apt-get install -y app-protect-compiler
# Remove nginx repository key/cert from docker
RUN rm -rf /etc/ssl/nginx
CMD ["sh"]
Alpine 3.10 Converter Docker Deployment Example
# For Alpine 3.10:
FROM alpine:3.10
# Download certificate and key from the customer portal (https://my.f5.com)
# and copy to the build context:
COPY nginx-repo.key /etc/apk/cert.key
COPY nginx-repo.crt /etc/apk/cert.pem
# Download and add the NGINX signing key:
RUN wget -O /etc/apk/keys/nginx_signing.rsa.pub https://cs.nginx.com/static/keys/nginx_signing.rsa.pub
# Add NGINX Plus repository:
RUN printf "https://plus-pkgs.nginx.com/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | tee -a /etc/apk/repositories
# Update the repository and install the most recent version of the NGINX App Protect Compiler package:
RUN apk update && apk add app-protect-compiler
# Remove nginx repository key/cert from docker
RUN rm -rf /etc/apk/cert.*
CMD ["sh"]
Converter Docker Deployment Instructions
You need root permissions to execute the following steps.
Create a Dockerfile (see examples above) which copies the following files into the docker image:
nginx-repo.crt
: Certificate for NGINX repository accessnginx-repo.key
: Private key for NGINX repository access
Log in to the Customer Portal and download the following two files:
nginx-repo.key nginx-repo.crt
Create a temporary folder and copy your XML policy file(s) to it:
mkdir /tmp/converter cp policy.xml /tmp/converter/
Run the docker image with the temporary folder as a mounted volume on the container, and run the policy converter script:
docker run -v /tmp/convert:/tmp/convert ubuntu-converter:latest /opt/app_protect/bin/convert-policy -i /tmp/convert/policy.xml -o /tmp/convert/policy.json | jq
Output:
{ "completed_successfully": true, "file_size": 20604, "warnings": [ "Default header '*-bin' cannot be deleted.", "Traffic Learning, Policy Building, and staging are unsupported", "/general/enableEventCorrelation must be '0' (was '1').", "Element '/websocket-urls' is unsupported.", "/signature-sets/learn value 1 is unsupported", "Element '/redirection-protection' is unsupported.", "/protocolIndependent must be '1' (was '0').", "Element '/gwt-profiles' is unsupported.", "/blocking-settings/violations/name value 'VIOL_ASM_COOKIE_HIJACKING' is unsupported.", "/blocking-settings/violations/name value 'VIOL_BLOCKING_CONDITION' is unsupported.", "/blocking-settings/violations/name value 'VIOL_BRUTE_FORCE' is unsupported.", "/blocking-settings/violations/name value 'VIOL_CONVICTION' is unsupported.", "/blocking-settings/violations/name value 'VIOL_CROSS_ORIGIN_REQUEST' is unsupported.", "/blocking-settings/violations/name value 'VIOL_CSRF' is unsupported.", "/blocking-settings/violations/name value 'VIOL_CSRF_EXPIRED' is unsupported.", "/blocking-settings/violations/name value 'VIOL_DYNAMIC_SESSION' is unsupported.", "/blocking-settings/violations/name value 'VIOL_FLOW' is unsupported.", "/blocking-settings/violations/name value 'VIOL_FLOW_DISALLOWED_INPUT' is unsupported.", "/blocking-settings/violations/name value 'VIOL_FLOW_ENTRY_POINT' is unsupported.", "/blocking-settings/violations/name value 'VIOL_FLOW_MANDATORY_PARAMS' is unsupported.", "/blocking-settings/violations/name value 'VIOL_GEOLOCATION' is unsupported.", "/blocking-settings/violations/name value 'VIOL_GWT_FORMAT' is unsupported.", "/blocking-settings/violations/name value 'VIOL_GWT_MALFORMED' is unsupported.", "/blocking-settings/violations/name value 'VIOL_HOSTNAME_MISMATCH' is unsupported.", "/blocking-settings/violations/name value 'VIOL_LOGIN_URL_BYPASSED' is unsupported.", "/blocking-settings/violations/name value 'VIOL_LOGIN_URL_EXPIRED' is unsupported.", "/blocking-settings/violations/name value 'VIOL_MALICIOUS_DEVICE' is unsupported.", "/blocking-settings/violations/name value 'VIOL_MALICIOUS_IP' is unsupported.", "/blocking-settings/violations/name value 'VIOL_PARAMETER_DYNAMIC_VALUE' is unsupported.", "/blocking-settings/violations/name value 'VIOL_PLAINTEXT_FORMAT' is unsupported.", "/blocking-settings/violations/name value 'VIOL_REDIRECT' is unsupported.", "/blocking-settings/violations/name value 'VIOL_SESSION_AWARENESS' is unsupported.", "/blocking-settings/violations/name value 'VIOL_VIRUS' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_BAD_REQUEST' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_BINARY_MESSAGE_LENGTH' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_BINARY_MESSAGE_NOT_ALLOWED' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_EXTENSION' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_FRAMES_PER_MESSAGE_COUNT' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_FRAME_LENGTH' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_FRAME_MASKING' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_FRAMING_PROTOCOL' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_TEXT_MESSAGE_NOT_ALLOWED' is unsupported.", "/blocking-settings/violations/name value 'VIOL_WEBSOCKET_TEXT_NULL_VALUE' is unsupported.", "/blocking-settings/violations/name value 'VIOL_XML_SCHEMA' is unsupported.", "/blocking-settings/violations/name value 'VIOL_XML_SOAP_ATTACHMENT' is unsupported.", "/blocking-settings/violations/name value 'VIOL_XML_SOAP_METHOD' is unsupported.", "/blocking-settings/violations/name value 'VIOL_XML_WEB_SERVICES_SECURITY' is unsupported.", "/blocking-settings/http-protocols/description value 'Unparsable request content' is unsupported.", "Element '/plain-text-profiles' is unsupported." ], "filename": "/tmp/convert/policy-ubuntu.json" }
Once completed, the newly exported JSON policy file should reside in the same folder as the source XML policy file:
ls -l /tmp/convert/ total 848 -rw-r--r-- 1 root root 20604 Dec 20 12:33 policy.json # Exported JSON policy file -rw-r--r-- 1 root root 841818 Dec 20 11:10 policy.xml # Original XML policy file
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.
Example Deployment for CentOS/RHEL
Add the NGINX App Protect Packages to an Internal Repository
On a host with access to the NGINX App Protect repository:
Install the
downloadonly
plugin for Yum:yum -y install yum-plugin-downloadonly
Download all NGINX App Protect packages, including all dependencies:
mkdir -p /etc/packages/ yum install --downloadonly --downloaddir=/etc/packages/ app-protect
Download the
epel-release
dependency package:For CentOS:
yum install --downloadonly --downloaddir=/etc/packages/ epel-release
For RHEL:
wget -P /etc/packages https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
Add the packages in
/etc/packages
to your local repository.
Example Deployment for Debian/Ubuntu
Add the NGINX App Protect Packages to an Internal Repository
On a host with access to the NGINX App Protect repository:
Download all NGINX App Protect packages, including all dependencies:
mkdir -p /etc/packages/ cd /etc/packages/ apt-get update for i in $(apt-cache depends --recurse --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances app-protect | grep "^\w" | sort -u); do apt-get download $i 2>>errors.txt; done
Add the packages in
/etc/packages
to your local repository.
Post-Installation Checks
You can run the following commands to ensure that NGINX App Protect enforcement is operational.
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
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
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]
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 variabletotal_xml_memory
in thestartup.sh
script or in thenginx-app-protect.service
file. The number471859200
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.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.
Attack Signatures Package
The attack signature package is named: app-protect-attack-signatures. 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
Compatibility with NGINX Plus Releases
A signature update package is compatible with the NGINX Plus release supported during the time the signature package was released and with all future releases from that point in time on. In other words, it is not compatible with earlier App Protect releases. Those older releases are not supported at this point in time so you will have to upgrade App Protect to benefit from the support which includes Attack Signature updates.
Installing Attack Signature Update
The App Protect installation comes with a built-in Attack Signature package that is not necessarily the most recent one and even if you have the most up to date Attack Signatures installed, updates are released every month or two, so you might want to update your Signatures from time to time. You can upgrade the signatures by updating the package any time after installing App Protect. We recommend you upgrade to the latest signature version right after installing App Protect.
After having updated the Attack Signature package you have to reload the configuration in order for the new version of the Signatures to take effect. Until then App Protect will run with the old version. That is useful when creating an environment with a specific tested version of the Attack Signatures.
CentOS / RHEL 7.4+
To add NGINX App Protect Security Updates repository, download the file
app-protect-security-updates-7.repo
to/etc/yum.repos.d
:sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-security-updates-7.repo
Update attack signatures:
sudo yum install app-protect-attack-signatures
To install a specific version, list the available versions:
sudo yum --showduplicates list app-protect-attack-signatures
To upgrade to a specific version:
sudo yum install app-protect-attack-signatures-2020.04.30
To downgrade to a specific version:
sudo yum downgrade app-protect-attack-signatures-2019.07.16
Debian 9
Add NGINX App Protect Security Updates repository:
printf "deb https://app-protect-security-updates.nginx.com/debian/ `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/app-protect-security-updates.list
Download and add the NGINX App Protect signatures signing key:
sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key
Download the apt configuration to
/etc/apt/apt.conf.d
:sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90app-protect-security-updates
Update attack signatures:
sudo apt-get update && sudo apt-get install app-protect-attack-signatures
To install a specific version, list the available versions:
sudo apt-cache policy app-protect-attack-signatures
Install a specific version:
sudo apt-get install app-protect-attack-signatures=2020.04.30-1~stretch
Debian 10
Add NGINX App Protect Security Updates repository:
printf "deb https://app-protect-security-updates.nginx.com/debian/ `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/app-protect-security-updates.list
Download and add the NGINX App Protect signatures signing key:
sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key
Download the apt configuration to
/etc/apt/apt.conf.d
:sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90app-protect-security-updates
Update attack signatures:
sudo apt-get update && sudo apt-get install app-protect-attack-signatures
To install a specific version, list the available versions:
sudo apt-cache policy app-protect-attack-signatures
Install a specific version:
sudo apt-get install app-protect-attack-signatures=2020.04.30-1~buster
Ubuntu 18.04
Add NGINX App Protect Security Updates repository:
printf "deb https://app-protect-security-updates.nginx.com/ubuntu/ `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/app-protect-security-updates.list
Download and add the NGINX App Protect signatures signing key:
sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key
Download the apt configuration to
/etc/apt/apt.conf.d
:sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90app-protect-security-updates
Update attack signatures:
sudo apt-get update && sudo apt-get install app-protect-attack-signatures
To install a specific version, list the available versions:
sudo apt-cache policy app-protect-attack-signatures
Install a specific version:
sudo apt-get install app-protect-attack-signatures=2020.07.16-1~bionic
Alpine 3.10
Add NGINX App Protect Security Updates repository:
printf "https://app-protect-security-updates.nginx.com/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | tee -a /etc/apk/repositories
Download and add the NGINX App Protect signatures signing key:
sudo wget -O /etc/apk/keys/app-protect-security-updates.rsa.pub https://cs.nginx.com/static/keys/app-protect-security-updates.rsa.pub
Update attack signatures:
sudo apk update && sudo apk add app-protect-attack-signatures
To install a specific version, list the available versions:
sudo apk search app-protect-attack-signatures
Install a specific version:
sudo apk add app-protect-attack-signatures=2020.12.28-r1
Attack Signatures when Upgrading App Protect
Upgrading App Protect does not install new Attack Signatures. You will get the same Attack Signature release after upgrading App Protect. If you want to also upgrade the Attack Signatures, you will have to explicitly update them by the respective command above.
Updating App Protect Threat Campaigns
The Threat Campaigns feature is described here.
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
Compatibility with NGINX Plus Releases
A threat campaign package is compatible with the NGINX Plus release supported during the time the threat campaign package was released and with all future releases from that point in time on. In other words, it is not compatible with earlier App Protect releases. Those older releases are not supported at this point in time so you will have to upgrade App Protect to benefit from the support which includes Threat campaigns updates.
Installing Threat Campaigns Update
The App Protect installation does not come with a built-in Threat campaigns package like Attack Signatures. Threat campaigns Updates are released periodically whenever new campaigns and vectors are discovered, so you might want to update your Threat campaigns from time to time. You can upgrade the Threat campaigns by updating the package any time after installing App Protect. We recommend you upgrade to the latest Threat campaigns version right after installing App Protect.
After having updated the Threat campaigns package you have to reload the configuration in order for the new version of the Threat campaigns to take effect. Until then App Protect will run with the old version, if exists. This is useful when creating an environment with a specific tested version of the Threat campaigns.
CentOS / RHEL 7.4+
If not already configured, add NGINX App Protect Security Updates repository by downloading the file
app-protect-security-updates-7.repo
to/etc/yum.repos.d
:sudo wget -P /etc/yum.repos.d https://cs.nginx.com/static/files/app-protect-security-updates-7.repo
Update Threat campaigns:
sudo yum install app-protect-threat-campaigns
To install a specific version, list the available versions:
sudo yum --showduplicates list app-protect-threat-campaigns
To upgrade to a specific version:
sudo yum install app-protect-threat-campaigns-2020.06.25
Debian 9
If not already configured, add NGINX App Protect Security Updates repository:
printf "deb https://app-protect-security-updates.nginx.com/debian/ `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/app-protect-security-updates.list
Download and add the NGINX App Protect Threat Campaigns signing key:
sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key
Download the apt configuration to
/etc/apt/apt.conf.d
:sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90app-protect-security-updates
Update Threat campaigns:
sudo apt-get update && sudo apt-get install app-protect-threat-campaigns
To install a specific version, list the available versions:
sudo apt-cache policy app-protect-threat-campaigns
Install a specific version:
sudo apt-get install app-protect-threat-campaigns=2020.06.25-1~stretch
Debian 10
If not already configured, add NGINX App Protect Security Updates repository:
printf "deb https://app-protect-security-updates.nginx.com/debian/ `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/app-protect-security-updates.list
Download and add the NGINX App Protect Threat Campaigns signing key:
sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key
Download the apt configuration to
/etc/apt/apt.conf.d
:sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90app-protect-security-updates
Update Threat campaigns:
sudo apt-get update && sudo apt-get install app-protect-threat-campaigns
To install a specific version, list the available versions:
sudo apt-cache policy app-protect-threat-campaigns
Install a specific version:
sudo apt-get install app-protect-threat-campaigns=2020.06.25-1~buster
Ubuntu 18.04
If not already configured, add NGINX App Protect Security Updates repository:
printf "deb https://app-protect-security-updates.nginx.com/ubuntu/ `lsb_release -cs` nginx-plus\n" | sudo tee /etc/apt/sources.list.d/app-protect-security-updates.list
Download and add the NGINX App Protect Threat Campaigns signing key:
sudo wget https://cs.nginx.com/static/keys/app-protect-security-updates.key && sudo apt-key add app-protect-security-updates.key
Download the apt configuration to
/etc/apt/apt.conf.d
:sudo wget -P /etc/apt/apt.conf.d https://cs.nginx.com/static/files/90app-protect-security-updates
Update Threat campaigns:
sudo apt-get update && sudo apt-get install app-protect-threat-campaigns
To install a specific version, list the available versions:
sudo apt-cache policy app-protect-threat-campaigns
Install a specific version:
sudo apt-get install app-protect-threat-campaigns=2020.08.05-1~bionic
Alpine 3.10
If not already configured, add NGINX App Protect Security Updates repository:
printf "https://app-protect-security-updates.nginx.com/alpine/v`egrep -o '^[0-9]+\.[0-9]+' /etc/alpine-release`/main\n" | tee -a /etc/apk/repositories
Download and add the NGINX App Protect Threat Campaigns signing key:
sudo wget -O /etc/apk/keys/app-protect-security-updates.rsa.pub https://cs.nginx.com/static/keys/app-protect-security-updates.rsa.pub
Update Threat Campaigns:
sudo apk update && sudo apk add app-protect-threat-campaigns
To install a specific version, list the available versions:
sudo apk search app-protect-threat-campaigns
Install a specific version:
sudo apk add app-protect-threat-campaigns=2020.12.24-r1
Threat Campaigns when Upgrading App Protect
Upgrading App Protect does not install new Threat Campaigns since they do not come as part of the App Protect package. You will get the same Threat Campaigns release as before the upgrade, after upgrading App Protect. If you want to also upgrade Threat Campaigns to the latest version, you will have to explicitly update them by using the command above.
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.
Modifying File Labels
For example, if you plan to store your policy or log configuration files in /etc/policy
- you should change the default SELinux file context for this directory:
semanage fcontext -a -t httpd_config_t /etc/policy
restorecon -Rv /etc/policy
Syslog to Custom Port
If you want to send logs to some unreserved port, you can use semanage
to add the desired port (here, 35514) to the syslogd_port_t type:
semanage port -a -t syslogd_port_t -p tcp 35514
Review the syslog ports by entering the following command:
semanage port -l | grep syslog
If there are additional problems, refer to the Troubleshooting Guide.