# 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 * Root permissions * `wget` command-line tool installed on your linux machine * Execution permissions on the `/tmp` directory. * Linux machine with: * A supported OS and NGINX, Kong, or APISIX version already installed.\ Here you find lists of all supported/pre-compiled attachments per supported OS versions for each available integration:\ \- [NGINX attachment compatibility](https://downloads.openappsec.io/packages/supported-nginx.txt)\ \- [APISIX attachment compatibility](https://downloads.openappsec.io/packages/supported-apisix.txt)\ \- [Kong attachment compatibility](https://downloads.openappsec.io/packages/supported-kong.txt) {% hint style="info" %} **For Kong a new type of attachment plugin based on Lua is now available in beta!**\ Installation is done using `luarocks` command with a `.rockspec` file.\ You find all instructions below on this page.\ When using this, the attachment compatibility list for Kong above isn't relevant anymore,\ as there's no need anymore for providing precompiled attachments. Let us know if you have any feedback regarding this beta program or require technical assistance: [mailto://info@openappsec.io](mailto:info@openappsec.io) {% endhint %} In case your version is not supported yet, you can also build the attachment yourself from source code, see [here](/deployment-and-upgrade/build-open-appsec-based-on-source-code.md). ## Installation Download the installer for Linux using these commands: ```bash 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/APISIX** {% hint style="success" %} This is the recommended deployment mode for deploying open-appsec on Linux for most deployments, as this is fully automatic and compatible with most, typically used environments. {% endhint %} In this mode open-appsec will automatically be installed with all required components and the attachment will be added and activated in the existing configuration for NGINX/Kong (traditional integration)/APISIX. {% hint style="info" %} When using the new Kong integration based on the Lua attachment plugin you are responsible for first deploying the plugin yourself and configuring Kong to load it, steps are included in the installation instructions below. {% endhint %} The resulting configuration will be locally, declaratively managed using `local_policy.yaml` configuration file. {% hint style="info" %} If you want to directly connect your deployment to the open-appsec Web UI (SaaS) for central management this is also possible by providing the optional `--token` parameter to specify a deployment profile from Web UI to associate this new deployment with. For more details see [Using the Web UI (SaaS)](/getting-started/using-the-web-ui-saas.md) {% endhint %} Run this command to start the installation: {% tabs %} {% tab title="Linux, APISIX, Kong (traditional Kong plugin)" %} The following command will automatically install the open-appsec attachment to the NGINX, APISIX or Kong proxy, configure it to be loaded and also install the open-appsec agent with default local declarative configuration. ``` ./open-appsec-install --auto ``` {% endtab %} {% tab title="Kong Lua plugin (beta)" %} {% hint style="info" %} Using the Lua-based plugin for the open-appsec attachment is the more modern approach for deployment of the attachment when using Kong, compared to the traditional attachment plugin. It is fully aligned with Kong's plugin standards and will eventually replace the current, traditional attachment plugin for Kong in the future. {% endhint %} For deployment of the open-appsec attachment using the Kong Lua-based plugin: 1. **Install dependencies:** Make sure to have all required dependencies installed on your system, as shown in the command below:\ (This command is for Ubuntu, make sure to adjust it, if you are using a different OS.) ```bash sudo apt-get install libbrotli-dev build-essential git curl zlib1g-dev ca-certificates ``` 2. **Compile and install the Kong Lua plugin:** Run the following `luarocks` command to compile and install the Kong Lua plugin for the open-appsec attachment: ```bash luarocks install https://raw.githubusercontent.com/openappsec/attachment/main/attachments/kong/plugins/open-appsec-waf-kong-plugin/open-appsec-waf-kong-plugin-1.0.0-1.rockspec ``` 3. **Install open-appsec agent:** Run the following command to automatically install the open-appsec agent with default local declarative configuration.\ Make sure to add the `--kong-plugin` flag, this will make the installer skip the installation of the traditional attachment on NGINX level, which is not required, as the Lua-based attachment plugin was already installed in the above step using the `luarocks` command. ``` ./open-appsec-install --auto --kong-plugin ``` 4. **Load the open-appsec attachment plugin** in the Kong Gateway (note there's multiple ways to do this in Kong), here are examples for some **alternative** options:\ \ Option 1 — *If you use Kong Konnect for central management of Kong:*\ Add the Kong Konnect plugin schema for the open-appsec attachment custom plugin to your Kong Konnect tenant, you can download it from here and import in Kong Konnect web UI:\ \ Then activate the plugin from the Kong Konnect web UI.\ Full instructions for using Kong Konnect for managing the open-appsec attachment plugin can be found here: [Using Kong Konnect (Kong only)](/getting-started/using-the-web-ui-saas/using-kong-konnect-kong-only.md)\ \ Option 2 — Include the following line in the `kong.conf` file (usually located in `/etc/kong/` ):\ `plugins = bundled,open-appsec-waf-kong-plugin`\ \ Option 3 — Run this command to activate the plugin using an env variable:\ (This also loads the included bundled plugins, you can remove `bundled`, if you are not using those.)\ `export KONG_PLUGINS="bundled,open-appsec-waf-kong-plugin"`\ \ Make sure to restart Kong to apply the changes: `kong restart` also make sure to actually enable the plugin, see following step: 5. **Enable the plugin in the Kong Gateway**, here are examples for some **alternative** options:\ \&#xNAN;*Note all examples below are for **globally** enabling the attachment so that the open-appsec agent can inspect all traffic, you can also enable it more specifically per consumer, per route or per service, follow the Kong documentation for further details how to configure this.*\ \ Option 1 — *If you use Kong Konnect for central management of Kong:*\ After you activated the attachment plugin in Kong Konnect, leave Service, Route and Consumer fields empty to enable it globally.\ \ Option 2 — To globally enable the attachment plugin when using Kong with database: ```bash curl -i -X POST http://localhost:8001/plugins --data "name=open-appsec-waf-kong-plugin" ``` Option 3 — To globally enable the attachment plugin when using Kong in DB-less mode:\ Load the plugin by specifying it in your `kong.yml` file: ```yaml plugins: - name: open-appsec-waf-kong-plugin ``` 6. **Reload Kong configuration** to make sure all changes are applied: ```bash kong reload ``` {% endtab %} {% endtabs %}

Example screenshot open-appsec installer (latest installer version will look different)

{% hint style="info" %} The steps shown below for "Mode 2" (manual installation) are the exact steps which are also performed when running the automatic installation described here as "Mode 1". {% endhint %} As part of the installation, a default configuration file for declarative, local management of open-appsec will be created in the following path: ```bash /etc/cp/conf/local_policy.yaml ``` {% hint style="info" %} This default local configuration file created by the open-appsec installer uses configuration file schema version [v1beta1](/getting-started/start-with-linux/local-policy-file-advanced.md). You can also replace it with a newer version of the configuration file schema, e.g. to use [v1beta2](/getting-started/start-with-linux/local-policy-file-v1beta2-beta.md). {% endhint %} #### Optional open-appsec installer parameters * `--token` allows connecting directly to SaaS management, to get the token please follow the instructions [here](/getting-started/using-the-web-ui-saas/create-a-profile.md). * `--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. * `--kong-plugin` ONLY use this when deploying open-appsec with the Lua-based open-appsec attachment, this will skip the automatic installation of the traditional attachment, which is not required in this case. ### **Mode 2: Download of software components and presenting manual installation instructions** In this mode all required components based on your NGINX, Kong or APISIX 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 ` 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 {% tabs %} {% tab title="NGINX" %} * Copy the associated libraries **as shown in the output** of the script * Copy the nginx attachment file **as shown in the output** for Step 1 * Load the attachment on your NGINX by adding the following line to your `nginx.conf` {% endtab %} {% tab title="Kong Gateway" %} {% hint style="info" %} Please note that the traditional 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). The new Kong Plugin for integrating with open-appsec is based on Lua and integrating natively with Kong. {% endhint %} * Deploy the attachment by following the commands in the script's output. {% endtab %} {% tab title="APISIX" %} {% hint style="info" %} Please note that APISIX 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 APISIX installation as a module (very similar to the NGINX integration). {% endhint %} * Deploy the attachment by following the commands in the script's output {% endtab %} {% endtabs %} #### 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 {% tabs %} {% tab title="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 ``` {% endtab %} {% tab title="Kong (traditional plugin)" %} * 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 ``` {% endtab %} {% tab title="APISIX" %} * 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 APISIX service so that the updated OpenResty configuration in OpenResty's nginx.conf is applied and the open-appsec attachment module is loaded: ``` apisix restart ``` {% endtab %} {% tab title="Kong Lua plugin (beta)" %} * Run the following command to validate the Kong Gateway configuration:\ \ \- When using Kong with database:\ `kong check` \ \ \- When using Kong in DB-less mode:\ `kong check /path/to/kong.conf`\ `kong config parse /path/to/kong.yml` {% endtab %} {% endtabs %} ### Congratulations, you successfully installed and activated open-appsec integrated with your existing NGINX, Kong or APISIX installation. {% hint style="info" %} 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](/getting-started/using-the-advanced-machine-learning-model.md) {% endhint %} Now you might want to have a look at our interactive CLI tool: {% content-ref url="/pages/AirlOPWdonj6luaItR6H" %} [Using the open-appsec-ctl Tool](/getting-started/start-with-linux/using-the-open-appsec-ctl-tool.md) {% endcontent-ref %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.openappsec.io/getting-started/start-with-linux/install-open-appsec-for-linux.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.