LinuxServer.io’s SWAG docker image (Secure Web Application Gateway) provides users an easy way to deploy an NGINX web server and reverse proxy with PHP support and a built-in certbot client that automates free SSL server certificate generation and renewal processes (“Let's Encrypt” and “ZeroSSL”). Further it contains “fail2ban”, which can block IP addresses with too many failed authentication attempts.
open-appsec WAF is an open-source Web Application & API Security solution, which provides automatic and preemptive threat prevention using machine learning.
A free Community Edition of open-appsec is available and supported for integrating with Docker SWAG.
Adding open-appsec WAF to your SWAG-based web server/reverse proxy will help you to make sure that your web application is protected from zero-day attacks and other attacks like those from OWASP-TOP-10.
Zero-day attacks pose a significant threat to web applications, encompassing potential dangers that demand urgent attention. These attacks exploit vulnerabilities unknown to developers and security professionals, leaving organizations susceptible to malicious activities. The peril arises from the absence of available patches or security measures, granting attackers an advantage to infiltrate systems undetected. Zero-day attacks can compromise sensitive data, compromise user privacy, or even lead to financial loss and reputational damage.
As signatures for new attacks by design can only be created after new attacks have been published, a traditional WAF solution that relies solely on signatures will never protect preemptively against zero-day attacks. open-appsec WAF was designed to not rely on signatures at all, so that it can provide true preemptive zero-day protection. This adds a strong and comprehensive threat prevention to the SWAG solution.
open-appsec reduces the administrative effort as well as the number of false positives significantly while providing stronger protection, even for unknown attacks.
open-appsec can be deployed on various platforms like Linux, Docker and K8s and more, and also integrates with different Proxy solutions like NGINX, NGINX Proxy Manager, Kong API Gateway, and others.
In this blog you will find instructions how you can deploy the “Secure Web Application Gateway” (SWAG) integrated with open-appsec WAF on Docker using docker-compose tool as well as how to optionally connect it to the central open-appsec WebUI (SaaS) service.
Deployment and Management Options
There are two main ways to manage and monitor open-appsec WAF when integrated with SWAG on Docker:
Locally manage open-appsec using a declarative configuration file and monitor logs locally using CLI or e.g. a syslog compatible server. (Note that even when managing open-appsec locally you can still connect the deployment to the central WebUI for monitoring, security log analysis as well as viewing the local configuration in read-only mode, more info on this later.)
Centrally manage open-appsec configuration and monitor security logs and agent status using the free, easy-to-use WebUI (SaaS) available at https://my.openappsec.io
Below you will first find the steps to deploy SWAG with open-appsec WAF and manage it locally using a declarative configuration file. Afterwards it will be explained how to connect the existing deployment to the central WebUI.
Here’s an example view from the central WebUI monitoring section:
How to Deploy SWAG Integrated with open-appsec WAF (Locally, Declaratively Managed)
Prerequisites
Linux machine with Docker (or similar compatible Container runtime) and docker-compose tool
Deploy SWAG with open-appsec WAF on Docker Using docker-compose
Follow the steps below to deploy Docker SWAG container integrated with open-appsec Agent container, the resulting architecture will look like this:
1. From within the directory which you want to use for the deployment:Download the initial declarative configuration file for open-appsec into new subfolder ./appsec-localconfig:
mkdir ./appsec-localconfig && wget raw.githubusercontent.com/openappsec/openappsec/main/config/linux/v1beta1/prevent/local_policy.yaml -O ./appsec-localconfig/local_policy.yaml2. Create a docker-compose.yaml file with the content below, it can be downloaded as follows:
Here's the content of the docker-compose.yaml file:
services:
swag-attachment:
image: ghcr.io/openappsec/swag-attachment:latest
ipc: service:appsec-agent
restart: unless-stopped
container_name: swag-attachment
cap_add:
- NET_ADMIN
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
- URL=yourdomain.url # replace yourdomain.url with your own domain
# make sure your domain's public IP resolves to
# the docker host for Let's Encrypt cert generation to succeed
- VALIDATION=http
# see https://docs.linuxserver.io/images/docker-swag/ for
# more cert generation/validation options
- STAGING=true # switch to 'false' after successful testing
volumes:
- ./swag-config:/config
ports:
- 443:443
- 80:80 #optional
appsec-agent:
container_name: appsec-agent
image: ghcr.io/openappsec/agent:latest
ipc: shareable
restart: unless-stopped
environment:
- user_email=user@email.com # adjust with your own email
- registered_server='SWAG Server'
# if autoPolicyLoad is set to true, open-appsec will apply
# changes in local_policy.yaml automatically
- autoPolicyLoad=true
# To connect to open-appsec central management WebUI
## create your WebUI profile at https://my.openappsec.io,
## enforce policy, copy the profile token from WebUI and add it below
- AGENT_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
3. Run the docker compose
docker compose up -dYou will see output similar to the below:
4. Verify that “appsec-agent” and “swag-attachment” containers are both up and running by verifying their status in docker ps output:
docker psYou will see output similar to the below:
5. Configure SWAG’s NGINX reverse proxy to forward traffic to your backend webserver(s). (if you don’t have experience with this, see official SWAG docs: SWAG - LinuxServer.io)
6. To verify if certificate was successfully issued use following command to show logs of the swag-attachment container:
docker logs swag-attachment7. If certificate was successfully generated in Let’s Encrypt staging mode (recommended for testing) you should now change the following line in the docker-compose.yaml file (in the swag-attachment container specification) to disable staging mode and receive a valid, trusted certificate from Let’s Encrypt:
Old value:
- STAGING=trueSet to new value:
- STAGING=falseRedeploy to apply the changes:
docker compose down && docker compose up -d8. As SWAG also contains fail2ban as an additional security layer, you can check the fail2ban status and enabled “jails” as follows:
docker exec -it swag-attachment fail2ban-client statusOutput should be similar to the following, showing the fail2ban is setup with 5 jails by default:
You can read more about fail2ban here:
Congratulations, you have successfully deployed SWAG Secure Web Application Gateway integrated with:
open-appsec WAF for automatic, machine learning-based threat prevention
Let’s Encrypt SSL certificate
fail2ban preventing different types of brute-force attacks
Now all HTTP(S) requests that SWAG’s integrated NGINX proxy will forward to your backend web server(s) will be automatically analyzed and protected by the open-appsec WAF.
Suggested Next Steps
You can check open-appsec agent status by running:
docker exec appsec-agent open-appsec-ctl -sYou will see output similar to the below:
Verify that open-appsec is preventing attacks:
Make sure the SWAG NGINX reverse proxy is properly set-up to point to some web application backend (see more details here). The NGINX configuration for the SWAG container is located here (on docker host): ./swag-config/nginx/site-confs/default.conf (and in SWAG container it’s here: /config/nginx/site-confs/default.conf) Note that for the following simulated attack you can also just run it against the default webpage SWAG returns after deployment and skip this step.
Run following curl request to simulate an attack (replace with your SWAG container DNS name and Port)
curl -v -k https://<SWAG-CONTAINER-PUBLIC-DNS-NAME>:<PORT>/?shell_cmd=cat/etc/passwdNote: “-k” was added above so this would work even when still using the non-valid Let’s Encrypt “staging” certificate.
You can alternatively use your web browser, just open the following URL: (Make sure to replace <SWAG-CONTAINER-PUBLIC-DNS-NAME> with the DNS name of your SWAG container)
https://<SWAG-CONTAINER-PUBLIC-DNS-NAME>:<PORT>/?shell_cmd=cat/etc/passwd If your policy is set to prevent in the local configuration file (default in the file used when following this guide), the request will be blocked with error 403 shown, otherwise it will be detected and you will only see it in the security logs.
You can view the resulting open-appsec security logs by running:
docker exec appsec-agent open-appsec-ctl -vlIf required you can further configure open-appsec WAF’s settings using open-appsec’s local declarative policy, see docs for the local policy file configuration options here: Local Policy File (Advanced) | open-appsec (openappsec.io)
How to Connect Your Deployment of SWAG to the Central open-appsec WebUI (SaaS)
Connecting your integrated open-appsec deployment to the open-appsec central WebUI available at: https://my.openappsec.io provides many benefits. Using the WebUI (SaaS) is optional and included in all editions, including open-appsec free community edition.
Central WebUI for viewing/managing all open-appsec configuration and functionality
Store and view your open-appsec security logs
Monitor your open-appsec deployments
Monitor learning status of each of your protected assets
See learning progress and status
Receive and manage tuning suggestions
Get cloud-based shared learning between multiple agents (e.g. in HA deployment scenario)
In the following it will be explained how you can connect your existing locally-managed Docker SWAG deployment with open-appsec to the open-appsec WebUI
Prerequisites
Existing SWAG with open-appsec WAF deployment (see above)
Connect Your SWAG with open-appsec WAF Deployment to Central WebUI
1. Sign up for a free open-appsec WebUI tenant at https://my.openappsec.io
2. Login to the open-appsec WebUI at https://my.openappsec.io
3. Create a new Docker Deployment Profile and copy the “Token” from that Profile (you will need it later!).
4. As subtype select: SWAG + open-appsec
5. Pick your desired management mode in the new WebUI Profile:
You have two options:
“Declarative configuration”: In this mode after connecting the deployment to WebUI you will still configure everything in the local declarative configuration file, but the WebUI will show you all settings (in read-only) and you can monitoring logs and security events comfortably.
“This management”: In this mode after connecting the deployment to WebUI you will be able to manage all open-appsec settings centrally (local configuration file will not be used by the agent anymore) and to monitor logs and security events comfortably.
6. Make sure to Enforce the policy in the WebUI (“Enforce” button in top right corner). You find full details about how to create the profile and get the Token here in our docs.
7. In your docker-compose.yaml file uncomment the following line and replace ADD-YOUR-TOKEN with your “Token” copied from your WebUI Docker Profile (see Prerequisites above).
# - AGENT_TOKEN=ADD-YOUR-TOKENIt will then look somewhat similar to this:
- AGENT_TOKEN=cp-123456-1234-678901234556773478592378645
Providing the token is critical to allow the agent to connect to the specific deployment profile in the central WebUI, which will allow you use the cloud-hosted central management for assets and policies, cloud logging, graphical dashboards, events analysis, and ability to manage multiple deployments/clusters in a scalable way. If you didn’t create a deployment profile and copy the token earlier, here is how to get it.
8. Run following commands to redeploy your docker-compose file:
docker-compose down && docker-compose up -dNote: The following step is only relevant when you picked “This management” as management mode earlier! Skip this step for the “Declarative management” management mode as in that case the configuration for open-appsec is done locally in the local_policy.yaml file!
9. 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 the configured web application in your asset(s) matches your public DNS name for the SWAG container, as configured within the docker compose file here:
URL=yourdomain.urlMake 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.
10. You can check open-appsec agent status by running:
docker exec appsec-agent open-appsec-ctl -s
11. Now let’s simulate some attack again to verify that open-appsec is preventing it as expected:
a) Make sure the SWAG NGINX reverse proxy is properly set-up to point to some web application backend (see more details here). The NGINX configuration for the SWAG container is located here (on docker host):
./swag-config/nginx/site-confs/default.conf(and in SWAG container it’s here: /config/nginx/site-confs/default.conf )
Note that for the following simulated attack you can also just run it against the default webpage SWAG returns after deployment and skip this step.
Run following curl request to simulate an attack (replace with your SWAG container DNS name and Port):
curl -v -k https://<SWAG-CONTAINER-PUBLIC-DNS-NAME>:<PORT>/?shell_cmd=cat/etc/passwdNote: “-k” was added above so this would work even when still using a Let’s Encrypt “staging” certificate.
You can alternatively use your web browser, just open the following URL:
https://<SWAG-CONTAINER-PUBLIC-DNS-NAME>:<PORT>/?shell_cmd=cat/etc/passwdIf open-appsec WAF is configured in prevent mode, you should see traffic blocked and error 403 returned. If in detect mode, you will see the security logs appear in security logs.
b) You’ll find the security events related to the request in the open-appsec portal under the “Monitoring” tab and in logs.
We hope you find this integration useful to secure your Web Services and APIs exposed via Docker SWAG. If you have any feedback or need assistance, please contact us using either the chat available on this website or by sending an email to info@openappsec.io. We look forward hearing from you!
For latest instructions make sure to check also the official documentation available here: https://docs.openappsec.io/integrations/docker-swag
-----
More information:
open-appsec:
Website: www.openappsec.io
Docs: docs.openappsec.io
SWAG integration docs: Docker SWAG
Hands-on labs: www.openappsec.io/playground
open-appsec technology whitepaper: www.openappsec.io/whitepaper Github: github.com/openappsec/openappsec
Docker SWAG:
Docs: docs.linuxserver.io/general/swag/
Github: linuxserver/docker-swag
Fail2ban
fail2ban Github: fail2ban/fail2ban
Comments