NGINX

Multi-app support

This agent supports multiple application configurations. See Assign tCell App IDs to NGINX File for instructions on consolidating multiple App IDs.

Some tCell features are not available

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

Supported Technologies

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

VersionOSNotes
1.12.2CentOS 7EPEL version of NGINX for CentOS 7, compatible with the Amazon Linux NGINX-1.12.2 EPEL version
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. See Openresty limitations.
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. See Openresty limitations.
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)

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).

Limitations

The NGINX Openresty variant of our module has some important limitations to be aware of when considering configuration and deployment.

  • Openresty reads request bodies in a lazy manner, preventing us from inspecting POST data in endpoints that take advantage of LUA blocks unless that endpoint calls ngx.req.read_body() or uses the lua_need_request_body on; directive.ngx.req.read_body() or uses the lua_need_request_body on; directive.
  • The agent does not support response-size events, nor response-size-based blocking rules on responses that do not include a Content-Length header. By default, LUA-generated response bodies are sent with a chunking transfer encoding and have an indeterminate Content-Length. If you wish to receive sensor events about large response sizes you will have to configure the Content-Length header manually.

Installation

Modules and Configuration Paths

This section assumes the nginx.conf path is /etc/nginx/nginx.conf, and the modules directory is specified 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 modules/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 file.

  6. Add the line tcell_app_id APP_ID; to the events block in the /etc/nginx/nginx.conf file.

    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 Build a custom agent on how to work with Rapid7 to build a custom agent.

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.