Links
Comment on page

Install open-appsec for Linux

The fastest and easiest way to deploy and configure open-appsec is using an interactive CLI tool which will guide you through the most commonly required customizations.

Prerequisites

  • Linux machine with:
    • A supported OS and NGINX or Kong version. A list of all supported/pre-compiled attachments for NGINX and Kong per supported OS versions is available here. In case your versions are not supported yet, you can also build the code yourself, see here.
    • Root permissions
  • wget command-line tool installed on your linux machine

Installation

Download the installer for Linux using these commands:
wget https://downloads.openappsec.io/open-appsec-install && chmod +x open-appsec-install
You can show the installer version and available options by running the following command to show the help info:
./open-appsec-install -h
This interactive installer provides 2 alternative modes for automatic vs. manual installation:

Mode 1: Automatic installation of open-appsec and adding attachment (plugin) to NGINX/Kong

In this mode open-appsec will automatically installed with all required components and the attachment will be added and activated in the existing configuration for NGINX/Kong.
./open-appsec-install --auto
The steps shown below for Mode 2 are the exact steps which are also performed when running the automatic installation.

Optional open-appsec installer parameters

  • --token allows connecting directly to SaaS management, to get the token please follow the instructions here.
  • --prevent will set the default rule in the default policy file to prevent-learn instead of detect-learn, but the recommendation is to keep detect-learn as the default rule.

Mode 2: Download of software components and presenting manual installation instructions

In this mode all required components based on your NGINX/Kong version, OS version, Platform will be downloaded to your machine and instructions are presented for manual installation.
./open-appsec-install --download
Optionally you can add a --tmpdir <path> option to specify an alternative path for the downloaded software components (default path is /tmp/openappsec/ )
Once the download has finished, follow these steps for manual installation:

Step 1: Deploying the attachment on an existing alpine NGINX/Kong server

NGINX
Kong Gateway
  • Copy the associated libraries as shown in the output for Step 1 with commands similar to this:
cp /tmp/open-appsec/[version specific dir]/libshmem_ipc /usr/lib/
cp /tmp/open-appsec/[version specific dir]/libcompression_utils /usr/lib/
cp /tmp/open-appsec/[version specific dir]/libnginx_attachment_util /usr/lib/
  • Copy the nginx attachment file as shown in the output for Step 1 with command similar to this:
cp /tmp/open-appsec/[version specific dir]/libngx_module.so /usr/lib/nginx/modules/
  • Load the attachment on your NGINX by adding the following line to your nginx.conf, usually located here: /etc/nginx/ load_module /usr/lib/nginx/modules/libngx_module.so;
Please note that Kong is built on top of OpenResty, which again is based on NGINX. The open-appsec attachment is technically integrating in the OpenResty-layer of a Kong installation as a module (very similar to the NGINX integration).
Copy the associated libraries as shown in the output for Step 1 with commands similar to this:
cp /tmp/open-appsec/[version specific dir]/libshmem_ipc /usr/lib/
cp /tmp/open-appsec/[version specific dir]/libcompression_utils /usr/lib/
cp /tmp/open-appsec/[version specific dir]/libnginx_attachment_util /usr/lib/
  • Copy the OpenResty attachment file as shown in the output for Step 1 with command similar to this:
cp /tmp/open-appsec/[version specific dir]/libngx_module.so /usr/lib/nginx/modules/
  • Load the attachment on your Kong OpenResty by adding two lines to nginx.lua, usually located here: /usr/local/share/lua/[version specific dir]/kong/templates/
    • In the return section add following line: load_module /usr/lib/nginx/modules/ngx_cp_attachment_module.so;
    • In the http sub-section add following line: cp_worker_processes ${{nginx_worker_processes}};

Step 2: Installing open-appsec agent

  • Run the following commands:
/tmp/open-appsec/openappsec/install-cp-nano-agent.sh --install --hybrid_mode
/tmp/open-appsec/openappsec/install-cp-nano-service-http-transaction-handler.sh --install
/tmp/open-appsec/openappsec/install-cp-nano-attachment-registration-manager.sh --install

Step 3 Validate configuration

NGINX
Kong Gateway
  • Run the following command to validate the nginx configuration:
nginx -t
You should see an output confirming that the syntax is "ok" similar to this: nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful
  • Restart the NGINX service so that the updated nginx configuration is applied and the open-appsec attachment module is loaded:
service nginx restart
  • Run the following command to validate the OpenResty configuration:
/usr/local/openresty/nginx/sbin/nginx -t
You should see an output confirming that the syntax is "ok" similar to this: nginx: the configuration file /usr/local/openresty/nginx/conf/nginx.conf syntax is ok
nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful
Restart the Kong service so that the updated OpenResty configuration in OpenResty's nginx.conf is applied and the open-appsec attachment module is loaded:
kong restart

Congratulations, you successfully installed and activated open-appsec to your existing NGINX/Kong installation.

For Production usage you might want to switch from using the Basic to the more accurate Advanced Machine Learning model, as described here:
Now you might want to have a look at our interactive CLI tool: