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

• 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;

Kong Gateway

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

• 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

Kong Gateway

• 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:

Using the Advanced Machine Learning Model

Now you might want to have a look at our interactive CLI tool:

pageUsing the open-appsec-ctl Tool