Install With Docker (Locally Managed)

Prerequisites

• Linux machine with:

  • Docker installed (or similar, compatible container runtime)

  • Root permissions

The following prerequisites are optional and only relevant if you want to connect your open-appsec agent directly to a WebUI (SaaS) management tenant:

• Access to a SaaS tenant on my.openappsec.io (WebUI for SaaS management) Follow the instructions available here:

Sign-Up and Login to Portal

• Agent profile created for open-appsec Docker deployment in SaaS tenant Follow the instructions available here, make sure to choose the "Declarative configuration" management mode. Once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below:

Create a Profile

Installation

NGINX

Follow these steps to deploy open-appsec and NGINX reverse proxy (including open-appsec attachment) with separate containers (e.g. on Docker) or implement this using your deployment CI pipeline: (This is the standard deployment, an alternative option to deploy with a single, unified container is available as well, see "NGINX - Unified" tab.)

Step 1: Pull the open-appsec agent image or add/use it as part of the deployment CI’s container management system:

docker pull ghcr.io/openappsec/agent:latest

Step 2: Create a valid local_policy.yaml file which contains the desired declarative configuration for the agent container and put it in a local directory of your choice to be used in the docker run command for the agent as <path-to-persistent-location-for-local-configuration-file> (see also Step 4 for the docker run command).

You can also download and use the example default local_policy.yaml from the open-appsec GitHub repository.

Full details regarding the declarative local policy file structure are available here:

Configuration Using Local Policy File (Docker)

Step 3: Create the following empty directories to be used later for volume mounts in the docker run command for the agent.

<path-to-persistent-location-for-agent-config>
<path-to-persistent-location-for-agent-data-files>
<path-to-persistent-location-for-agent-debugs-and-logs>

Creation of the folders above and the volume mounts shown in the next step with -v is optional but strongly recommended for having persistence of the important agent information (data, config, logs). Mounting a folder <path-to-local-configuration-file>, which must contain a valid local configuration file for the open-appsec agent, to /ext/appsec directory inside the agent container on the other hand is mandatory for standalone deployments.

Step 4: Run the open-appsec agent container with this command:

docker run --name=open-appsec-agent \
--ipc=host \
-v <path-to-persistent-location-for-agent-config>:/etc/cp/conf \
-v <path-to-persistent-location-for-agent-data-files>:/etc/cp/data \
-v <path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent \
-v <path-to-persistent-location-for-local-configuration-file>:/ext/appsec \
-e registered_server='NGINX Server' \
-e user_email=<add-your-email-here> \
-e https_proxy=<user:password@proxy-address:port> \
-e autoPolicyLoad=false \
-e AGENT_TOKEN= \
-it -d ghcr.io/openappsec/agent:latest /cp-nano-agent

• AGENT_TOKEN <TOKEN>(environment variable, optional), replace with the token you copied from the profile in the WebUI before (see Prerequisites section above).

• https_proxy (environment variable) : allows you to configure an HTTP(S) proxy server to be used by the agent. It is optional and can be removed if not needed.

• autoPolicyLoad (environment variable): when set to true, allows you to set the open-appsec agent to automatically apply any new changes in the local_policy.yaml file without having to restart the agent container or applying the changes with open-appsec-ctl -ap (note that this can take up to 30 seconds). This is useful, especially in DevOps/continuous deployment scenarios.

• user_email (environment variable): allows you to provide your email address.

• no-upgrade (optional) flag to the cp-nano-agent command will start the agent without an initial upgrade.

The optional user_email environment variable allows you to associate your email address with your specific deployment by replacing <your-email-address> with your own email address.

This allows the open-appsec team to provide you easy assistance in case of any issues you might have with your specific deployment in the future and also to provide you information proactively regarding open-appsec in general or regarding your specific deployment. This is an optional parameter and can be removed. If we send automatic emails there will also be an opt-out option included for receiving similar communication in the future.

Step 5: Create (or replace) the NGINX container by first pulling the open-appsec NGINX container, which already contains the open-appsec attachment. Alternatively, add/use it as part of the deployment CI’s container management system:

docker pull ghcr.io/openappsec/nginx-attachment:latest

Step 6: Run the open-appsec NGINX container, make sure to add the --ipc=host parameter, here’s an example command:

docker run --name open-appsec-nginx --ipc=host -p 80:80 -d ghcr.io/openappsec/nginx-attachment:latest

For general NGINX configuration please check the relevant NGINX documentation.

Step 7: Make sure both containers are running, use docker ps to verify.

If you've connected to SaaS Management Tenant in Step 4:

Step 8: Navigate to the Agents tab in the WebUI and ensure the new Agent is successfully connected.

Kong Gateway

Follow these steps to install Kong with open-appsec using containers (e.g. on Docker) or using your deployment CI:

Step 1: Pull the open-appsec agent image or add/use it as part of the deployment CI’s container management system:

docker pull ghcr.io/openappsec/agent:latest

Step 2: Create a valid local-policy.yaml file which contains the desired declarative configuration for the agent container (see also Step 3) and put it in a local directory to be used in the docker run command for the agent as <path-to-persistent-location-for-local-configuration-file> .

You can also download and use the example local_policy.yaml file from the open-appsec GitHub repository.

Full details regarding the declarative local policy file structure are available here:

Configuration Using Local Policy File (Docker)

Step 3: The volume mounts set in the next step with-v are optional but recommended for the persistence of the agent information (data, config, logs). If you want to use those parameters create the following empty directories to be used later for volume mounts in the docker run command for the agent.

<path-to-persistent-location-for-agent-config>
<path-to-persistent-location-for-agent-data-files>
<path-to-persistent-location-for-agent-debugs-and-logs>

Step 4: Run the open-appsec agent container with this command

docker run --name=open-appsec-agent \
--ipc=host \
-v <path-to-persistent-location-for-agent-config>:/etc/cp/conf \
-v <path-to-persistent-location-for-agent-data-files>:/etc/cp/data \
-v <path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent \
-v <path-to-persistent-location-for-local-configuration-file>:/ext/appsec \
-e registered_server='Kong Server' \
-e user_email=<add-your-email-here> \
-e autoPolicyLoad=false \
-e https_proxy=<user:password@proxy-address:port> \
-e AGENT_TOKEN= \
-it -d ghcr.io/openappsec/agent:latest /cp-nano-agent

• AGENT_TOKEN <TOKEN>(environment variable, optional), replace with the token you copied from the profile in the WebUI before (see Prerequisites section above).

• https_proxy (environment variable) : allows you to configure an HTTP(S) proxy server to be used by the agent. It is optional and can be removed if not needed.

• autoPolicyLoad (environment variable): when set to true, allows you to set the open-appsec agent to automatically apply any new changes in the local_policy.yaml file without having to restart the agent container or applying the changes with open-appsec-ctl -ap (note that this can take up to 30 seconds). This is useful, especially in DevOps/continuous deployment scenarios.

• user_email (environment variable): allows you to provide your email address.

• no-upgrade (optional) flag to the cp-nano-agent command will start the agent without an initial upgrade.

The optional user_email environment variable allows you to associate your email address with your specific deployment by replacing <your-email-address> with your own email address.

This allows us to provide you easy assistance in case of any issues you might have with your specific deployment in the future and also to provide you information proactively regarding open-appsec in general or regarding your specific deployment. This is an optional parameter and can be removed. If we send automatic emails there will also be an opt-out option included for receiving similar communication in the future.

Step 5: Create (or replace) the Kong container by pulling the enhanced open-appsec Kong container, which already contains the open-appsec attachment. Alternatively, add/use it as part of the deployment CI’s container management system:

For Kong (open-source version):

docker pull ghcr.io/openappsec/kong-attachment:latest

For Kong Gateway (enterprise version):

docker pull ghcr.io/openappsec/kong-gateway-attachment:latest

Step 6: Run the open-appsec Kong container, make sure to add the --ipc=host parameter, here’s an example command:

For Kong (open-source version):

docker run -d --name kong --ipc=host -p 8000:8000 -p 8443:8443 -p 127.0.0.1:8001:8001 -p 127.0.0.1:8444:8444 ghcr.io/openappsec/kong-attachment:latest

For Kong Gateway (enterprise version):

docker run -d --name kong-gateway --ipc=host -p 8000:8000 -p 8443:8443 -p 127.0.0.1:8001:8001 -p 127.0.0.1:8444:8444 ghcr.io/openappsec/kong-gateway-attachment:latest

Step 7: Make sure both containers are running, use docker ps to verify.

If you've connected to SaaS Management Tenant in Step 4:

Step 8: Navigate to the Agents tab in the WebUI and ensure the new Agent is successfully connected. don't forget to enforce the policy afterward. More details here:

Protect Additional Assets

For general Kong configuration details please check the Kong documentation

NGINX - Unified (beta)

This feature is currently in beta and may be subject to changes.

Make sure to meet the prerequisites on top of this page and to have the profile token available. Make sure you enforce the policy after profile creation.

Follow these steps to deploy open-appsec combined with NGINX reverse proxy (including open-appsec attachment) with a single, unified container (e.g. on Docker) or implement this using your deployment CI pipeline:

Step 1: Pull the open-appsec agent unified with the NGINX image or add/use it as part of the deployment CI’s container management system:

docker pull ghcr.io/openappsec/agent-unified:latest

Step 2: Create a valid local_policy.yaml file which contains the desired declarative configuration for the agent container and put it in a local directory of your choice to be used in the docker run command for the agent as <path-to-persistent-location-for-local-configuration-file> (see also Step 4 for the docker run command).

You can also download and use the example default local_policy.yaml from the open-appsec GitHub repository.

Full details regarding the declarative local policy file structure are available here:

Configuration Using Local Policy File (Docker)

Step 3: Create the following empty directories to be used later for volume mounts in the docker run command for the agent.

<path-to-persistent-location-for-agent-config>
<path-to-persistent-location-for-agent-data-files>
<path-to-persistent-location-for-agent-debugs-and-logs>

Creation of the folders above and the volume mounts shown in the next step with -v is optional but strongly recommended for having persistence of the important agent information (data, config, logs). Mounting a folder <path-to-local-configuration-file>, which must contain a valid local configuration file for the open-appsec agent, to /ext/appsecdirectory inside the agent container is mandatory for standalone deployments.

Step 4: Run the open-appsec agent container with this command:

docker run -d \
  --name open-appsec-agent-unified \
  --restart unless-stopped \
  -p 80:80 \
  -p 443:443 \
  -v <path-to-persistent-location-for-agent-config>:/etc/cp/conf \
  -v <path-to-persistent-location-for-agent-data-files>:/etc/cp/data \
  -v <path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent \
  -v <path-to-persistent-location-for-local-configuration-file>:/ext/appsec \
  -e user_email=<your-email-address> \
  -e https_proxy=<user:password@proxy address:port> \
  -e AGENT_TOKEN= \
  ghcr.io/openappsec/agent-unified:latest /cp-nano-agent

• AGENT_TOKEN <TOKEN>(environment variable, optional), replace with the token you copied from the profile in the WebUI before (see Prerequisites section above).

• The https_proxy environment variable allows you to configure an HTTP(S) proxy server to be used by the agent. It is optional and can be removed if not needed.

• The user_email environment variable allows you to provide your email address.

The optional user_email environment variable allows you to associate your email address with your specific deployment by replacing <your-email-address> with your own email address.

This allows the open-appsec team to provide you easy assistance in case of any issues you might have with your specific deployment in the future and also to provide you information proactively regarding open-appsec in general or regarding your specific deployment. This is an optional parameter and can be removed. If we send automatic emails there will also be an opt-out option included for receiving similar communication in the future.

For general NGINX configuration please check the relevant NGINX documentation.

Step 5: Make sure both containers are running, use docker ps to verify.

If you've connected to SaaS Management Tenant in Step 4:

Step 6: Navigate to the Agents tab in the WebUI and ensure the new Agent is successfully connected.

APISIX Gateway

Follow these steps to install APISIX with open-appsec using containers (e.g. on Docker) or using your deployment CI:

Step 1: Create a folder to hold the appsec declarative configuration file, and download the example configuration file:

mkdir ./appsec-localconfig

Step 2: Create a valid local_policy.yaml file which contains the desired declarative configuration for the agent container and add to the folder:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/examples/local_policy.yaml -O appsec-localconfig/local_policy.yaml

Full details regarding the declarative local policy file structure are available here:

Configuration Using Local Policy File (Docker)

Step 3: Download the docker-compose file, see content bellow:

wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/apisix/docker-compose.yaml

version: "3"

services:
  apisix:
    container_name: apisix
    image: "ghcr.io/openappsec/apisix-attachment:latest"
    ipc: host
    restart: always
    volumes:
      - .<apisix-conf-path>:/usr/local/apisix/conf/apisix.yaml:ro
    environment:
      - APISIX_STAND_ALONE=true
    ports:
      - "9180:9180/tcp"
      - "9080:9080/tcp"
      - "9091:9091/tcp"
      - "9443:9443/tcp"

  appsec-agent:
    container_name: appsec-agent
    image: 'ghcr.io/openappsec/agent:latest'
    ipc: host
    restart: unless-stopped
    environment:
      # adjust with your own email below
      - user_email=[e-mail]
      - registered_server="APISIX Server"
      - AGENT_TOKEN=<TOKEN>
    volumes:
      - ./appsec-config:/etc/cp/conf
      - ./appsec-data:/etc/cp/data
      - ./appsec-logs:/var/log/nano_agent
      - ./appsec-localconfig:/ext/appsec
    command: /cp-nano-agent 

Step 4: Replace <apisix-conf-path> with the path for declarative configuration file for APISIX, an example file can be found here, for general APISIX configuration details please check the APISIX Documentation.

• The volume mounts are optional but recommended for the persistence of the agent information (data, config, logs).

• The optional user_email environment variable allows you to associate your email address with your specific deployment by replacing <your-email-address> with your own email address. This allows us to provide you easy assistance in case of any issues you might have with your specific deployment in the future and also to provide you information proactively regarding open-appsec in general or regarding your specific deployment. This is an optional parameter and can be removed. If we send automatic emails there will also be an opt-out option included for receiving similar communication in the future.

• AGENT_TOKEN <TOKEN>(environment variable, optional), replace with the token you copied from the profile in the WebUI before (see Prerequisites section above).

Step 5: Run the Docker Compose

docker-compose up -d

Step 6: Make sure both containers are running, use docker ps to verify.

If you've added a Token Step 4:

Step 7: Navigate to the Agents tab and ensure the new Agent is successfully connected.

Now your open-appsec installation on Docker is completed and your configured web app or API assets are protected!