This is based on the work made by https://github.com/docker-servers/coraza-caddy

This repository contains a Docker container running Caddy with the OWASP Coraza WAF. The container is designed to be used as a WAF for a Docker service. The OWASP CRS will be used by default.

Currently, the assumption is made that this acts as an intermediate proxy between the ingress and the service to protect. There is no SSL configuration, rather than should be handled at the ingress.

• Coraza WAF with Caddy
  • Examples
  • Env Variables
    • Coraza Specific
    • Caddy Specific
  • Important Notes
  • Configuration Files/Directories
  • Build Arguments
  • Advanced Configuration
    • Supplemental Configuration
    • Replacement Configuration - Caddy
    • Replacement Configuration - Coraza

The following env variables may be set to control Caddy and Coraza.

These values control Coraza.

These values control Caddy.

• The container is configured by default to run as a non-root user. The upstream Caddy containers run using root by default. To allow binding on ports <1024 cap_net_bind_service is added on the Caddy binary. The default port still is 8080.

The following configuration files/directories exist within the container:

• /opt/coraza/config/coraza.conf: The main Coraza configuration file.
• /opt/coraza/config.d/*.conf: User defined configuration files. See the Supplemental Configuration section for more information.
• /opt/coraza/config/crs-setup.conf: The OWASP Core Rule Set configuration file.
• /opt/coraza/owasp-crs/*.conf: The OWASP Core Rule Set rule files.
• /opt/coraza/rules/*.conf: Other default rules added by this image. Currently this is not used.
• /opt/coraza/rules.d/*.conf: Any user defined rule sets.
• /config/caddy: Caddy configuration directory. The Caddyfile generated from template is located here.
• /data/caddy: Caddy data directory. Things like SSL certificates are located here.

Various arguments can be provided if building the container yourself. The available arguments are:

We require a version of buildx >= v0.9.1. Visit the official documentation for instructions on installing and upgrading buildx. You can check which version you have using:

docker buildx version
github.com/docker/buildx v0.9.1 ed00243a0ce2a0aee75311b06e32d33b44729689

If you want to see the targets of the build, use:

docker buildx bake -f ./docker-bake.hcl --print

To build for any platforms of your choosing, just use this example:

docker buildx create --use --platform linux/amd64,linux/i386,linux/arm64,linux/arm/v7
docker buildx bake -f docker-bake.hcl

To build a specific target for a single platform only (replace target and platform strings in the example with the your choices):

docker buildx bake -f docker-bake.hcl --set "*.platform=linux/amd64" caddy-alpine

If you prefer to configure Caddy and/or Coraza yourself there are multiple options.

To add Coraza configuration without overwriting any of the container default configurations, *.conf files are loaded from these directories:

• /opt/coraza/config.d
• /opt/coraza/rules.d

As an example, you may want to create your own rules for Coraza. You would create a volume and mount it in the container at /opt/coraza/rules.d; the rules will then be loaded on server start automatically.

To add CRS Plugins, download and decompress the plugin to a directory of your choice. The official plugin list is at https://github.com/coreruleset/plugin-registry.

Create a volume or bind mount a directory of your choice to /opt/coraza/plugins; the rules will then be loaded on server start automatically.

Example:

curl -sSL https://github.com/coreruleset/wordpress-rule-exclusions-plugin/archive/refs/tags/v1.0.0.tar.gz -o wordpress.tar.gz
tar xvf wordpress.tar.gz --strip-components 1 'wordpress-rule-exclusions-plugin*/plugins'
❯ docker compose run -v $(pwd)/plugins:/opt/coraza/plugins coraza-crs
[+] Creating 1/0
 ✔ Container coraza-crs-docker-whoami-1  Running                                                                                        0.0s
Generating configuration files...
  - Caddyfile
    - Generating Caddyfile from template /templates/Caddyfile
    - Done
  - Coraza configuration file
    - Generating Caddyfile from template /templates/coraza.conf
    - Done
  - User configuration files loaded from /opt/coraza/config.d
    - Done
  - Loading user plugins from /opt/coraza/plugins
    -> wordpress-rule-exclusions-before.conf
    -> wordpress-rule-exclusions-config.conf
    - Done
  - Loading user defined rule sets from /opt/coraza/rules.d
    - Done

If you prefer to use your own configuration file for Caddy, simply mount the configuration file as /config/caddy/Caddyfile or mount a volume at /config/Caddy with a Caddyfile inside. You will need to add the relevant Coraza configuration to Caddy yourself if you choose this option. The bare minimum recommended configuration is:

# Ensure Coraza WAF runs first - this must be included for Coraza to be working
{
  order coraza_waf first
}

# Create the HTTP listener
:80 {

  # Load Coraza configuration
  coraza_waf {
    # Main configuration file
    include /opt/coraza/config/coraza.conf
    # User defined configuration files
    include /opt/coraza/config.d/*.conf
    # OWASP CRS Setup
    include /opt/coraza/config/crs-setup.conf
    # OWASP CRS Plugins Setup
    include /opt/coraza/owasp-crs/plugins/*-config.conf
    include /opt/coraza/owasp-crs/plugins/*-before.conf
    # OWASP CRS
    include /opt/coraza/owasp-crs/*.conf
    # OWASP CRS Plugins After
    include /opt/coraza/owasp-crs/plugins/*-after.conf
    # Other baked in rule sets
    include /opt/coraza/rules/*.conf
    # User defined rule sets
    include /opt/coraza/rules.d/*.conf
  }

  ...

To completely replace the Coraza configuration, create a volume and mount it in the container at /opt/coraza. Check the Configuration Files/Directories section for the expected configuration files.