NGINX

Supported Technologies

tCell has pre-existing builds for these NGINX distributions. If your NGINX distribution does not match one on this list, see Custom agent builds for specific information on what to do.

VersionOSNotes
1.10.2CentOS 6EPEL version of NGINX for Centos 6, installed by yum
1.10.3Debian StretchBuild 1 - nginx-extras' version available for Debian Stretch. Different binary built with different build flags
Build 2 - Standard NGINX for Debian Stretch, installed by apt. Build flags from APT repo version
1.10.2Ubuntu XenialBuild 1 - nginx-extras' version available for Ubuntu Xenial. Different binary built with different build flags
Build 2 - Standard NGINX for Ubuntu Xenial, installed by apt. Build flags from APT repo version. The original version was built with -fPIE, but this won't work linking against static libraries, so this was changed to -fPIC
Build 3 - nginx.org apt repo compatible version. Build flags from nginx.org APT repo
1.11.2CentOS 7OpenResty 1.11.2. Build flags from OpenResty's yum repo version
1.12.2CentOS 7Standard NGINX build from the Centos 7 EPEL repo, installed by yum. Build flags from EPEL
1.12.2Alpine 3.7Standard NGINX version bundled with Alpine 3.7 stable version, installed by apk
1.13.6CentOS 7OpenResty 1.13.6. Build flags from OpenResty's yum repo version
1.14.0Ubuntu BionicStandard NGINX for Ubuntu Bionic, installed by apt. Build flags from APT repo version
1.14.1CentOS 7NGINX as configured by Redhat for RHEL7. Build flags from Redhat version
1.14.2Ubuntu XenialStable NGINX version from nginx.org. Build flags from nginx.org APT repo
1.14.2Alpine 3.8Standard NGINX for Alpine 3.8, installed by apk. Build flags from APK repo version
1.16.1Ubuntu BionicLaunchpad 1.16.1 release from NGINX
1.16.1Debian BusterStable nginx.org official docker image (docker pull nginx:1.16.1)
1.17.4Alpine 3.10Mainline nginx.org official docker image (docker pull nginx:1.17.4-alpine)
1.17.5Debian BusterMainline nginx.org official docker image (docker pull nginx:1.17.5)

Multi-app support

This agent supports multiple application configurations.

Some tCell features are not available

OS Commands, Account Takeover, Local FiIes, Packages & Vulns. features are not available on NGINX.

Prerequisites

Before starting, confirm you have:

  • Set up a tCell account
  • Created a tCell application (Admin > Applications)
  • Ensured NGINX is installed in the directory: $NGINX_INSTALL_DIR.
  • Allowed outbound HTTPS connections to the tCell cloud: What IPs do tCell agents connect to?
  • Downloaded the agent and the config file:
    1. Click on "tCell Admin" in top nav bar.
    2. Click "Download Agent".
    3. Click on “Web Server Agent”.
    4. Select "NGINX" agent.
    5. Select "Create New API Key" (default).
    6. Download the tar.xz file.
    7. Click "Download Config File" to download the agent's config file (which is pre-populated with the application and key information).

Installation

Modules and Configuration Paths

This section assumes nginx.conf path is at /etc/nginx/nginx.conf, and the modules directory is located at in -modules-path. Run the following to find your specific paths: nginx -V

In the output, search for -modules-path and conf-path.

  1. Ensure you have /etc/nginx/nginx.conf and the modules directory. If necessary, create them.

  2. Extract the downloaded nginx agent tar.xz file.

  3. Put the ngx_http_tcell_agent_module.so file that corresponds to your OS and NGINX version in -modules-path. (Package contains versions built for Ubuntu x-y, CentOS x-y, Amazon Linux.)

  4. Add the line load_module modules/ngx_http_tcell_agent_module.so; to nginx.conf* before the events block. Example:

    1
    user nginx
    2
    worker_processes auto;
    3
    4
    error_log logs/error.log;
    5
    error_log logs/error.log notice;
    6
    error_log logs/error.log info;
    7
    pid logs/nginx.pid;
    8
    9
    load_module /PATH TO/ngx_http_tcell_agent_module.so;
    10
    11
    events {
    12
    worker_connections 1024;
    13
    }
  5. Put the tcell_agent.config file in in the same directory as the nginx.conf.

  6. Add the line tcell_app_id APP_ID; to the events block in the /etc/nginx/nginx.conf file. For example: http {  tcell_app_id krtest-CeOCq;  ...}

  7. Restart nginx

If you encounter a logged message similar to nginx: [emerg] module "modules/ngx_http_tcell_agent_module.so" is not binary compatible in /usr/local/nginx/conf/nginx.conf:11, this could mean:

  • You selected an agent build that does not match your distribution
  • Your nginx build is a locally generated custom build. See custom agent builds below.

NGINX supports log rolling which allows the agent to continue adding new lines to a full log file. See set up log rolling.

Example: nginx -V

1
root@8a5fa88427d8:/etc/nginx# nginx -V
2
3
nginx version: nginx/1.14.0 (Ubuntu)
4
5
built with OpenSSL 1.1.1 11 Sep 2018
6
7
TLS SNI support enabled
8
9
configure arguments: --with-cc-opt='-g -O2 -fdebug-prefix-map=/build/nginx-GkiujU/nginx-1.14.0=. -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-Bsymbolic-functions -Wl,-z,relro -Wl,-z,now -fPIC' --prefix=/usr/share/nginx --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access.log --error-log-path=/var/log/nginx/error.log --lock-path=/var/lock/nginx.lock --pid-path=/run/nginx.pid --modules-path=/usr/lib/nginx/modules --http-client-body-temp-path=/var/lib/nginx/body --http-fastcgi-temp-path=/var/lib/nginx/fastcgi --http-proxy-temp-path=/var/lib/nginx/proxy --http-scgi-temp-path=/var/lib/nginx/scgi --http-uwsgi-temp-path=/var/lib/nginx/uwsgi --with-debug --with-pcre-jit --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-http_auth_request_module --with-http_v2_module --with-http_dav_module --with-http_slice_module --with-threads --with-http_addition_module --with-http_geoip_module=dynamic --with-http_gunzip_module --with-http_gzip_static_module --with-http_image_filter_module=dynamic --with-http_sub_module --with-http_xslt_module=dynamic --with-stream=dynamic --with-stream_ssl_module --with-mail=dynamic --with-mail_ssl_module

Verification

To verify that data are being sent to tCell, go to your tCell console and ensure that the number of web server agents listed for the application you just created is more than 0.

Troubleshooting

Log files can be found in the tcell/logs directory. If you don't see a tcell/logs directory, it's likely that the tCell agent has not started. If so:

  1. Verify that the tCell agent is being added to the server startup by running the following command:

    1
    ps aux | grep --color tcell
  2. Check for errors in your catalina.out log. Alternatively, running bin/catalina.sh run or bin/catalina.bat run on Windows will start tomcat in the foreground, and print any errors while starting up.

You can customize the log level in the tcell_agent.config file by adding a block such as the following:

json
1
"logging_options": {
2
"enabled": true,
3
"level": "INFO"
4
}

See tcell/tcell_agent.config.template for an example.

Valid log levels are:

  • TRACE
  • DEBUG
  • INFO (default)
  • WARN
  • ERROR

The preceding list indicates the precedence among the levels, from top to bottom. When you enable a log level, the lower log levels are also enabled. For example, if you enable DEBUG, then INFO, WARN, and ERROR are also enabled.

When a log file becomes full, logging continues in a new log file. See Log Rolling for more information.

Custom agent builds

NGINX requires that modules be built with the same feature flags as the server they run inside of, to ensure correct operation.

If you use a customized build of NGINX with your own set of flags, Rapid7 can build an agent to work with this environment for you.

  1. Let Rapid7 know this is a requirement you will have.
    • During a Proof of Concept, let your sales team contacts know.
    • If you've already purchased tCell and are now adding an NGINX environment to your protected application set, or are changing to a customized NGINX setup, please file a support case through the Rapid7 customer portal.
  2. Provide the following pieces of information in the support mechanism from above:
    • Output of your NGINX server with the -V flag (for example, /opt/nginx/sbin/nginx -V), preferably as a zipped textfile attachment.
    • Information about the operating system and distribution the NGINX server is for. On most Linux systems, this command provides detailed operating system information: cat /etc/*release If possible, attach the output from this command to the support case.
    • Information on the NGINX Build Provenance. Specifically, if NGINX was built from source, provide the build steps and tools used. If installed using a specific tool like apt-get, provide the detailed apt-get steps performed.
  3. Rapid7 will reply with an acknowledgement and estimate of completion time, and within a few days, custom modules that match your NGINX build.