Install Docker SWAG with open-appsec (centrally managed)
Last updated
Last updated
open-appsec Docker SWAG integration is currently in "beta".
Access to a SaaS tenant on my.openappsec.io (WebUI for SaaS management) Follow the instructions available here:
Agent profile created for open-appsec Docker deployment in SaaS tenant Follow the instructions available here. Once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below:
Linux machine with:
Docker and Docker Compose installed
Root Permissions
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:
In your docker-compose.yaml provide your “Token” copied from your WebUI Docker Profile (see Prerequisites above) as the value for the existing AGENT_TOKEN key. It 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.
If you migrate from an existing Docker SWAG deployment to Docker SWAG with open-appsec make sure to make all adjustments you did in your existing docker-compose.yaml for SWAG also in the one above before deployment.
Also make sure to copy your existing SWAG configuration folder contents into ./swag-config
on the docker host.
Run the docker compose:
You will see output similar to the below:
Verify that “appsec-agent” and “swag-attachment” containers are both up and running by verifying their status in docker ps output:
You will see output similar to the below:
Configure SWAG’s NGINX reverse proxy to forward traffic to your backend webserver(s). (if you don’t have experience with this, see SWAG docs: SWAG - LinuxServer.io)
To verify if the SSL certificate was successfully issued by Let's Encrypt you can use following command to show logs of the swag-attachment container:
If certificate was successfully generated in Let’s Encrypt staging mode (recommended for testing, this will generate a non-trusted certificate only but allows for more failed validations before blocking for certain time) 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=true
New value: - STAGING=false
Redeploy to apply the changes:
As SWAG also contains fail2ban as an additional security layer, you can check the fail2ban status and enabled “jails” as follows:
Output should be similar to the following, showing the fail2ban is setup with 5 jails by default:
You can read more about fail2ban here: fail2ban/fail2ban: Daemon to ban hosts that cause multiple authentication errors (github.com)
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 configure in the compose file here: URL=yourdomain.url)
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!
open-appsec WAF for automatic, machine learning-based threat prevention
Let’s Encrypt SSL certificate
fail2ban preventing different types of brute-force attacks
open-appsec WebUI (SaaS) for central management
Now all HTTP(S) requests that SWAG’s integrated NGINX proxy will forward to your backend web server(s) will be first automatically analyzed and protected by the open-appsec WAF.
You can check open-appsec agent status by running:
You will see output similar to the below:
Check what's shown for "Management mode:" to verify that your agent is connected to the central open-appsec WebUI in the mode which you selected within the profile settings.
Verify that open-appsec is preventing attacks:
a) If you didn't do this yet make sure the SWAG NGINX reverse proxy is properly set-up to point to some web application backend (see more details here) for which also a matching asset in the open-appsec WebUI is defined and that policy was enforced in WebUI. 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.
b) Run following curl request to simulate an attack (replace with your SWAG container DNS name and Port)
Note: “-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:
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.
c) You’ll find the security events related to the request in the open-appsec portal under the “Monitoring” tab and in logs.