Install Docker SWAG with open-appsec (centrally managed)

open-appsec Docker SWAG integration is currently in "beta".

Prerequisites:

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

• Linux machine with:

  • Docker and Docker Compose installed

  • Root Permissions

Deployment

To deploy SWAG with open-appsec integration and manage open-appsec centrally with the open-appsec central WebUI (available at https://my.openappsec.io) follow the steps below:

1. Create a docker-compose.yaml file with the content below, it can be downloaded as follows:

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

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=[e-mail] # 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
      # this setting is only relevant when using local, declarative management
      - 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
      # following line is only relevant when using local, declarative management
      - ./appsec-localconfig:/ext/appsec
    command: /cp-nano-agent

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

3. Run the docker compose:

 docker-compose up -d

You 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 ps

You 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 SWAG docs: SWAG - LinuxServer.io)

6. 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:

docker logs swag-attachment

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

docker-compose down && docker compose up -d

8. 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 status

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)

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

   

   

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

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

Recommended next steps:

1. You can check open-appsec agent status by running:

docker exec appsec-agent open-appsec-ctl -s

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.

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

curl -v -k https://<SWAG-CONTAINER-PUBLIC-DNS-NAME>:<PORT>/?shell_cmd=cat/etc/passwd

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:

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.

c) You’ll find the security events related to the request in the open-appsec portal under the “Monitoring” tab and in logs.