Deploy & Configure

Get

1. Get sWAF docker image:

   docker pull swafproject/swaf

Run

2. Start a sWAF container:

   docker run -d \
       --name swaf \
       --restart always \
       --net host \
       [-v <VOLUME_NGINX_CONFIG>:/etc/nginx:rw] \
       [-v <VOLUME_NGINX_LOG>:/var/log/nginx] \
       swafproject/swaf

   where:

   • <VOLUME_NGINX_CONFIG>, the NGINX configuration volume on your Docker running host.
   • <VOLUME_NGINX_LOG>, the NGINX logs volume on your Docker running host.

   Alternatively, if you want to use a bridged network with standard web ports (default use case if --net option is not specified):

   docker run -d \
       --name swaf \
       --restart always \
       --net bridge \
       -p 80:80/tcp \
       -p 443:443/tcp \
       [-v <VOLUME_NGINX_CONFIG>:/etc/nginx:rw] \
       [-v <VOLUME_NGINX_LOG>:/var/log/nginx] \
       swafproject/swaf

Configure

sWAF is basically a containerized NGINX service, and so, all the NGINX configuration can be set up and modified directly within the container through an attached terminal and using the installed file editors like vi, ed, and nano within the container. If a volume is mounted on /etc/nginx/, you have also access to the full NGINX configuration tree and are, in this case, able to customize your deployment.

Attach Container

To get an attached terminal on a launched container:

1. Check the container name (if not set) or ID:

   # docker ps
   CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS               NAMES
   1a2b3c4d5e6f        swafproject/swaf    "/usr/local/bin/star…"   8 seconds ago       Up 7 seconds                            sweet_jang

2. Attach your terminal (according to your docker ps output):

   docker attach 1a2b3c4d5e6f

   or

   docker attach sweet_jang

You can search for 'docker attach' for further details. In this case, avoid to quit with / # exit because it will stop the container :) Just close or kill your terminal. Useful tips to detach terminal from a docker container [here].

Backup Notification

DO NOT FORGET TO BACKUP your NGINX (including ModSecurity and NAXSI) configuration from mounted volume as there isn't yet any backup automation (which means that there will be :)). This is not mandatory but strongly recommended in any case of container deletion.

Valuable folders	Description	Mounting Purpose
/etc/nginx	Whole NGINX configuration including ModSecurity and NAXSI.	Configuration modification out of the container and/or backup.
/var/log	Access and error logs from NGINX. Audit logs from ModSecurity and NAXSI.	Log exploitation and/or log export.

Configuration Files

/etc/nginx/
    ├── nginx.conf
    ├── conf.d/
    │   ├── main.conf
    │   ├── events.conf
    │   ├── http.conf
    │   ├── http.srv.*.conf
    │   ├── stream.conf
    │   └── stream.srv.*.conf
    ├── modsec.d/
    │   ├── modsec_includes.conf
    │   ├── modsecurity.conf
    │   ├── owasp-modsecurity-crs/
    │   │   ├── crs-setup.conf
    │   │   ├── *.*
    │   │   ├── **/*.*
    │   │   └── rules/
    │   │       ├── REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf
    │   │       ├── *.conf
    │   │       ├── RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf
    │   │       └── *.data
    │   └── *.*
    ├── naxsi.d/
    │   ├── naxsi_core.rules
    │   └── *.*
    └── *.*

File	Description
nginx.conf	NGINX's configuration entrypoint. Defines contexts and include directives for below files. Should not be directly modified.
../conf.d/main.conf	main context directives. Preset. Can be customized.
../conf.d/events.conf	events context directives. Preset. Can be customized.
../conf.d/http.conf	http context global directives affecting all HTTP virtual servers. Preset. Can be customized.
../conf.d/stream.conf	stream context global directives affecting all stream virtual servers. Preset. Can be customized.
../conf.d/http.srv.*.conf	Configuration files to define sections for HTTP virtual servers and upstreams. Can be splitted into multiple files according to your needs. Example file provided in http.srv.service1.conf.example.
../conf.d/stream.srv.*.conf	Configuration files to define sections for stream virtual servers and upstreams. Can be splitted into multiple files according to your needs. Example file provided in stream.srv.service2.conf.example.
../modesec.d/modsec_includes.conf	ModSecurity's configuration entrypoint. Defines include directives for below files. Should not be directly modified. The order of file inclusion in the configuration should always be: 1. modsecurity.conf / 2. crs-setup.conf / 3. rules/*.conf (the CRS rule files).
../modesec.d/modsecurity.conf	First ModSecurity loaded configuration file concerning ModSecurity's global settings. Preset. Can be customized.
../owasp-modsecurity-crs/crs-setup.conf	Second ModSecurity loaded configuration file concerning CRS settings. Default settings. Can be customized.
../owasp-modsecurity-crs/rules/REQUEST-900-EXCLUSION-RULES-BEFORE-CRS.conf	To include customized request rules.
../owasp-modsecurity-crs/rules/*.conf	Core Rule Set. Should not be directly modified.
../owasp-modsecurity-crs/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf	To include customized response rules.
../owasp-modsecurity-crs/rules/*.data	Core Rule Set. Should not be directly modified.
../naxsi.d/naxsi_core.rules	NAXSI core rules. Should not be directly modified.

*.default files are set for restore needs.

Custom Web Pages

Default index page and error pages are customizable in /var/lib/nginx/html/.

Mountable as a volume for a more easy access.

Certificates

TODO to complete with acme.sh usage.

Log Files

Paths are mountable as volumes to export logs:

• /var/log/nginx/ for NGINX logs.
• /var/log/modsec/ for ModSecurity logs.

Error Logs

• Defined in NGINX main context configuration (main.conf):

error_log /var/log/nginx/error.log info;

Access Logs

• Defined in NGINX HTTP context configuration (http.conf) for default access logging:

log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for"';

access_log /var/log/nginx/access.log main;

• To define in NGINX server context configuration (http.srv.*.conf) for each virtual server:

access_log /var/log/nginx/localhost.access.log main;

ModSecurity Audit logs

• Defined in ModSecurity global configuration (modsecurity.conf):

SecAuditLog /var/log/modsec/modsec_audit.log

Control

• Test if the full NGINX configuration is valid before reloading:

  docker exec <CONTAINER> nginx -t

• Reload NGINX configuration file:

  docker exec <CONTAINER> nginx -s reload

  Needed also when TLS certificates have been created, issued or renewed.

• Shut down gracefully NGINX service:

  docker exec <CONTAINER> nginx -s stop

• Shut down immediately (fast shutdown) NGINX service:

  docker exec <CONTAINER> nginx -s stop

• Start NGINX service:

  docker exec <CONTAINER> nginx

• Reopen NGINX log files:

  docker exec <CONTAINER> nginx -s reopen