We are excited to announce the availability of open-appsec support for Envoy proxy (beta) on Docker!
Envoy is an open-source edge and service proxy, specifically designed for cloud-native applications. In this blog, we will provide a short overview of Envoy proxy and open-appsec WAF, explain how to deploy Envoy with open-appsec WAF on Docker using docker-compose and provide some insights on how this integration technically works.
What is Envoy?
Networking and observability are the primary challenges in distributed architectures, as managing and debugging interconnected services is far more complex than a monolithic application. Envoy is a high-performance C++ proxy, designed to support single services and applications. It’s an open source as well as CNCF graduated project. Inspired by tools like NGINX and HAProxy, Envoy runs as a dedicated reverse proxy or alongside applications, abstracting the network with platform-agnostic features. This makes it easier to visualize issues, improve performance, and manage features centrally. Envoy has a strong global user base across many different platforms. Envoy is also well-known as a key component in many different service meshes for Kubernetes like Istio.
What is open-appsec?
open-appsec is an open-source, next-generation WAF, powered by machine learning and AI. It delivers robust protection against various web threats, including OWASP Top 10 vulnerabilities, zero-day attacks, and more. open-appsec now integrates seamlessly into modern environments built with Envoy Proxy in addition to the existing compatibility with many other reverse proxy solutions like NGINX, Kong, APISIX, Ingress NGINX and more. This makes open-appsec WAF an ideal and highly flexible solution for protecting cloud-native architectures.
open-appsec integration with Istio Service Mesh (Ingress Gateway), which is also based on Envoy proxy, was also recently announced and will soon be available.
One key feature distinguishing open-appsec from traditional WAF solutions is its machine-learning-based threat detection capabilities. It continuously evolves and learns from new attacks, offering dynamic, real-time protection without requiring manual updates or rule sets (no more signatures!). This adaptability makes it particularly effective against sophisticated attacks that can evade signature-based detection.
open-appsec WAF offers flexible management options, including a central WebUI (SaaS) for easy, centralized control. Alternatively, it supports local, declarative configurations through custom resources in Kubernetes or configuration files in Docker and Linux, making it compatible with CI/CD and GitOps workflows.
Even when managing open-appsec locally, you can still connect to the central WebUI in a read-only mode for configuration visibility, deployment monitoring, and access to security logs with comprehensive reports and dashboards.
Sign up for a free open-appsec WebUI tenant here: https://my.openappsec.io
Why is the integration of open-appsec and Envoy important?
As a high-performance proxy Envoy is designed for cloud-native applications and is therefore widely used. Together, open-appsec and Envoy enable organizations to manage, secure, and observe their web traffic communications effectively.
With an ever-increasing attack surface traditional security tools struggle to keep up, especially with distributed, cloud-native architectures, necessitating solutions that are both scalable and capable of protecting the entire system effectively in real-time.
This is where open-appsec excels, offering a highly effective, robust, and preemptively protecting WAF solution tailored to protect modern, cloud-native environments by integrating with proxies like Envoy.
Learn more about how open-appsec WAF works in the whitepaper:
Check out also open-appsec’s effectiveness compared to other WAF solutions:
How to deploy open-appsec and Envoy Proxy on Docker:
Prerequisites
Linux Docker Host with root permission
docker-compose tool installed
(Optional, Recommended) Sign-Up and Login to the open-appsec WebUI Portal if you want to centrally manage your open-appsec WAF deployment via WebUI (SaaS) OR if you want to locally manage your open-appsec WAF deployment but still connect to central WebUI for viewing the local configuration (in read-only), central monitoring, logging and reporting:
Follow the instructions below to sign-up and login to the WebUI available at https://my.openappsec.io:
(Optional, Recommended) Create a deployment profile for the open-appsec deployment in the WebUI Portal. If you signed-up and logged in to the WebUI Portal (see prerequisite above), now follow the instructions below to create a new deployment profile for your open-appsec deployment. Once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below.
Deployment
Create a folder for your new open-appsec deployment and switch to that folder, e.g.
mkdir open-appsec-deployment
cd ./open-appsec-deploymentDownload the docker compose file for open-appsec/Envoy integration
Download the .env file and adjust the configuration to your requirements as described below:
wget https://raw.githubusercontent.com/openappsec/openappsec/main/deployment/docker-compose/envoy/.envIf you created a deployment profile in the WebUI and copied the Token:
Edit the .env file and add your token to the key APPSEC_AGENT_TOKEN.
If you did not create a deployment profile in the WebUI and do not want to connect your deployment to central WebUI (SaaS) at all:
Set the value standalone for the key COMPOSE_PROFILES which will activate the deployment of additional containers which are required only when not connected to the WebUI at all (resulting in standalone, locally, declaratively managed deployment).
Replace user@email.com in the .env file with your own email.
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.)
Make sure to have a valid Envoy configuration file envoy.yaml in the mounted file path ./envoy-config/envoy.yaml on the host.
For testing purposes (lab environment only!) you can activate the deployment of the vulnerable juiceshop-backend container by adjusting the COMPOSE_PROFILES key as follows: COMPOSE_PROFILES=juiceshop and then deploy the available configuration example for exposing it via the proxy, which is provided by the open-appsec team (download link is provided in the .env file).
Important: If you provide your own configuration make sure to adjust it for also loading the open-appsec attachment as a filter.
Details here: Load the Attachment in Proxy Configuration
For a description of all available parameters in the .env file please see docs:
If you decided to locally, declaratively manage open-appsec with local_policy.yaml file:
Download the initial declarative configuration file for open-appsec into new subfolder ./appsec-localconfig:
mkdir ./appsec-localconfig
wget https://raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/prevent/local_policy.yaml -O ./appsec-localconfig/local_policy.yamlThis example configuration file is already set to mode: prevent-learn so that open-appsec will prevent attacks right from the start. Here's the path for an alternative local-policy.yaml file set to detect-learn mode.
(or simply adjust the setting in the mode setting in the earlier local_policy.yaml file to detect-learn)
In production environments, it's always recommended to start in detect-learn mode to allow open-appsec to achieve a certain learning level based on traffic observed before moving to prevent-learn for better detection accuracy and strongly reduced false positives. Read more about this here:
Perform the deployment
docker-compose up -dVerify that all containers are up and running by verifying their status in docker ps output. Note that the amount of containers will vary based between deployments with and without connection to central WebUI.
docker psCongratulations, you successfully deployed Envoy integrated with open-appsec WAF!
Recommended next steps:
If you connected to central WebUI AND configured your deployment profile in the WebUI to "This management" mode for centrally managing open-appsec configuration:
Create one or more assets in the WebUI which represent web applications and/or Web APIs which you want to be protected by open-appsec WAF and allows you to adjust the open-appsec configuration specifically for each of them.
Make sure to link your assets to the specific WebUI Profile which you created earlier (General -> Profiles) and adjust the Threat Prevention mode to Detect-Learn or Prevent (Threat Prevention -> Mode), the steps are described here:
Don't forget to Enforce policy in the WebUI after you did any changes for those changes to become effective!
If you decided to locally, declaratively manage open-appsec (with or without connection to central WebUI in "Declarative configuration" mode):
Follow the steps described here to configure your open-appsec deployment using the local_policy.yaml file: Configuration Using Local Policy File (Docker)
In case you connected your locally managed deployment also to the central WebUI in "Declarative Configuration" mode, you can check security logs and view agent status and configuration also in the central WebUI at https://my.openappsec.io .
Don't forget to apply the policy using open-appsec-ctl -ap in the open-appsec-agent container or by setting APPSEC_AUTO_POLICY_LOAD in the .env file to true for automatic application of any configuration changes done in the local_policy.yaml file for the changes to become effective!
To test your new open-appsec deployment first make sure you have configured open-appsec to prevent mode, then you can send the following http request containing an example attack - this should now be successfully blocked by open-appsec WAF (replace Docker-Host-IP with the IP address of your Docker host):
curl http://[Docker Host IP]?shell_cmd=cat/etc/passwd -vThanks for checking out this new open-appsec WAF integration with Envoy on Docker!
If you have any feedback, questions or require assistance please contact us: info@openappsec.io
To learn more about how open-appsec works, see this White Paper and the in-depth Video Tutorial. You can also experiment with deployment in the free Playground.
