open-appsec
WebsiteManagement PortalPlaygroundGitHub
  • open-appsec Documentation
  • What is open-appsec?
  • open-appsec Video Tutorials
  • Release Notes
  • Getting started
    • Getting Started
    • Start With Kubernetes
      • Install Using Interactive CLI Tool (Ingress NGINX)
      • Configuration Using Interactive CLI Tool
      • Install Using Helm
      • Install Using Helm - new flow (beta)
      • Configuration Using CRDs
      • Configuration Using CRDs - v1beta2
      • Configuration using CRDs - special options for Large Scale Deployments
        • Using appsec class for assigning separate custom resources to specific deployments
        • Using namespace-scoped custom resources
      • Monitor Events
    • Start With Linux
      • Install open-appsec for Linux
      • Using the open-appsec-ctl Tool
      • Configuration Using Local Policy File (Linux)
      • Local Policy File (Advanced)
      • Local Policy File v1beta2 (beta)
      • Monitor Events
    • Start with Docker
      • Install With Docker (Centrally Managed)
      • Install With Docker (Locally Managed)
      • Deploy With Docker-Compose (Beta)
      • Configuration Using Local Policy File (Docker)
      • Local Policy File (Advanced)
    • Using the Web UI (SaaS)
      • Sign-Up and Login to Portal
      • Agents Deployment
      • Connect Deployed Agents to SaaS Management Using Tool (K8s & Linux)
      • Connect Deployed Agents to SaaS Management Using Helm (K8s)
      • Connect Deployed Agents to SaaS Management (Docker)
      • Create a Profile
      • Protect Additional Assets
      • Monitor Events
    • Using the Advanced Machine Learning Model
  • Concepts
    • Agents
    • Management & Automation
    • Security Practices
    • Contextual Machine Learning
  • SETUP INSTRUCTIONS
    • Setup Web Application Settings
    • Setup Custom Rules and Exceptions
    • Setup Web User Response Pages
    • Setup Log Triggers
    • Setup Behavior Upon Failure
    • Setup Agent Upgrade Schedule
  • Additional Security Engines
    • Anti-Bot
    • API Schema Enforcement
    • Data Loss Prevention (DLP) Rules
    • File Security
    • Intrusion Prevention System (IPS)
    • Rate Limit
  • Snort Rules
    • Import Snort Rules
    • Write Snort Signatures
  • HOW TO
    • Configuration and Learning
      • Track Learning and Move From Learn/Detect to Prevent
      • Configure Contextual Machine Learning for Best Accuracy
      • Track Learning and Local Tuning in Standalone Deployments
      • Move From Detect to Prevent in K8s With Many Ingress Rules
  • Deployment and Upgrade
    • Load the Attachment in Proxy Configuration
    • Upgrade Your Reverse Proxy/API Gateway When an Agent is Installed
    • Integration in GitOps CD (K8s)
    • Build open-appsec Based on Source Code
  • Management Web UI
    • Track Agent Status
    • Delete or Reset Management Tenant (SaaS)
    • Disconnect an open-appsec agent from Central Management
  • Integrations
    • About Integrations With 3rd Party Solutions
    • CrowdSec
      • CrowdSec Bouncer Support
      • CrowdSec Intelligence Sharing Using open-appsec Parser/Scenario
    • NGINX Proxy Manager
      • Install NGINX Proxy Manager with open-appsec managed from NPM WebUI
      • Install NGINX Proxy Manager with open-appsec managed from central WebUI (SaaS)
      • Frequently Asked Questions
      • How to Migrate from an Existing NGINX Proxy Manager Deployment and Keep Configuration
    • NPMplus
    • Docker SWAG
      • Install Docker SWAG with open-appsec (locally managed)
      • How to connect locally managed Docker SWAG with open-appsec to WebUI
      • Install Docker SWAG with open-appsec (centrally managed)
      • Deploy Docker SWAG with docker-compose (beta)
      • Frequently Asked Questions
  • Troubleshooting
    • Troubleshooting
    • Troubleshooting Guides
      • Configuration contains ingress/asset with URL which already has asset attached to it in your tenant
      • HTTP Request to Port 80 Not Returning as Expected
      • Agent Fails to Recognize HTTP Transactions with NGINX
      • Agent Not Recognizing Initial HTTP Requests
      • Handling Large Requests (413 Responses)
      • open-appsec on Docker HTTP Transaction Handler Is Set To Ready
      • Traffic Recognition Issue on Single-Core Machine/Connection Timed Out
      • Installing open-appsec on CentOS 7
      • SELinux: checking status and disabling
      • Deploy open-appsec directly on the web server hosting the application to protect
      • object is locked or remote, and therefore cannot be modified
      • Failed to Register to Fog
  • references
    • Agent CLI
    • Event Query Language
    • Events/Logs Schema
    • WAF Comparison Project
Powered by GitBook
On this page
  • Prerequisites
  • Installation
  • Mode 1: Automatic installation of open-appsec and adding attachment (plugin) to NGINX/Kong/APISIX
  • Mode 2: Download of software components and presenting manual installation instructions
  • Congratulations, you successfully installed and activated open-appsec integrated with your existing NGINX, Kong or APISIX installation.

Was this helpful?

  1. Getting started
  2. Start With Linux

Install open-appsec for Linux

PreviousStart With LinuxNextUsing the open-appsec-ctl Tool

Last updated 2 months ago

Was this helpful?

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, Kong, or APISIX version. Here you find lists of all supported/pre-compiled attachments per supported OS versions for each available integration: - - - In case your versions are not supported yet, you can also build the code yourself, see .

    • Root permissions

  • wget command-line tool installed on your linux machine

  • Execution permissions on the /tmp directory.

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/APISIX

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.

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/APISIX. The resulting configuration will be locally, declaratively managed using local_policy.yaml configuration file.

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)

Run this command to start the installation:

./open-appsec-install --auto

The steps shown below for "Mode 2" are the exact steps which are also performed when running the automatic installation described here as "Mode 1".

As part of the installation, a default configuration file for local, declarative management of open-appsec will be created in the following path:

/etc/cp/conf/local_policy.yaml

Optional open-appsec installer parameters

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

  • 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

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

  • Deploy the attachment by following the commands in the script's output

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

  • Deploy the attachment by following the commands in the script's output

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

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

Congratulations, you successfully installed and activated open-appsec integrated with your existing NGINX, Kong or APISIX 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:

This default local configuration file created by the open-appsec installer uses configuration file schema version . You can also replace it with a newer version of the configuration file schema, e.g. to use .

--token allows connecting directly to SaaS management, to get the token please follow the instructions .

NGINX attachment compatibility
Kong attachment compatibility
APISIX attachment compatibility
here
v1beta1
v1beta2
here
Using the open-appsec-ctl Tool