Overview
Coraza Proxy is configured entirely through environment variables. This page documents all available variables with types, defaults, and usage examples.
Server Configuration
PORT
HTTP server listening port.
Port number for the proxy server to listen on
If PORT is not set or contains invalid value, defaults to “8081”
Backend Routing
BACKENDS
JSON configuration for backend server routing.
BACKENDS
JSON
default:"{\"default\":[\"localhost:5000\"]}"
Backend routing configuration (supports host-based and path-based routing)
{
"example.com": {
"default": ["web:80", "web2:80"],
"paths": {
"/static": ["cdn:80"],
"/api": ["api:8080"]
}
}
}
{
"waf.test.local": ["web:80"],
"api.test.local": ["api:8082"],
"default": ["localhost:5000"]
}
BACKENDS='{"waf.test.local":["web:80"], "api.test.local":["api:8082"], "default":["localhost:5000"]}'
WAF Configuration
CORAZA_RULES_PATH_SITES
Colon-separated list of rule files for web sites (Paranoia Level 1).
WAF rules for regular web applications
CORAZA_RULES_PATH_SITES="coraza.conf:profiles/pl1-crs-setup.conf:coreruleset/rules/*.conf"
CORAZA_RULES_PATH_APIS
Colon-separated list of rule files for APIs (Paranoia Level 2).
WAF rules for API endpoints (stricter rules)
CORAZA_RULES_PATH_APIS="coraza.conf:profiles/pl2-crs-setup.conf:coreruleset/rules/REQUEST-901-INITIALIZATION.conf:coreruleset/rules/*.conf"
PROXY_WEB_HOSTS
Comma-separated list of hostnames to apply web site WAF rules.
Hostnames that use CORAZA_RULES_PATH_SITES rules
PROXY_WEB_HOSTS=waf.test.local
PROXY_APIS_HOSTS
Comma-separated list of hostnames to apply API WAF rules.
Hostnames that use CORAZA_RULES_PATH_APIS rules
PROXY_APIS_HOSTS=api.test.local
Rate Limiting
PROXY_RATE_LIMIT
Maximum requests per second per IP address.
Rate limit in requests per second
PROXY_RATE_BURST
Maximum burst size for rate limiting.
Burst size (maximum requests allowed in a burst)
limiter := NewIPRateLimiter(
rate.Limit(getEnvInt("PROXY_RATE_LIMIT", 5)),
getEnvInt("PROXY_RATE_BURST", 10),
)
Bot Protection
PROXY_BLOCK_BOTS
Enable or disable bot blocking.
Whether to block requests from known bots
PROXY_BOTS
Comma-separated list of bot user-agent substrings to block.
PROXY_BOTS
string
default:"python,googlebot,bingbot,yandex,baiduspider"
Bot identifiers to block (case-insensitive substring match)
PROXY_BOTS=python,Googlebot,Bingbot,Slurp,DuckDuckBot,yandex,YandexBot,Sogou,baiduspider
if blockBots {
ua := strings.ToLower(r.UserAgent())
envBots := getEnvString("PROXY_BOTS", "python,googlebot,bingbot,yandex,baiduspider")
badBots := strings.Split(envBots, ",")
for _, bot := range badBots {
if strings.Contains(ua, bot) {
log.Println("Bot blocked", clientIP)
http.Error(w, "Bot blocked", http.StatusForbidden)
return
}
}
}
GeoIP Filtering
GEO_BLOCK_ENABLED
Enable or disable geographic IP filtering.
Whether to enable GeoIP-based access control
Requires GeoLite2-Country.mmdb database at /app/GeoLite2-Country.mmdb
GEO_ALLOW_COUNTRIES
Comma-separated list of allowed country codes (ISO 3166-1 alpha-2).
Allowlist of country codes (empty = allow all except blocked)
GEO_ALLOW_COUNTRIES=US,CA,GB,DE,FR
GEO_BLOCK_COUNTRIES
Comma-separated list of blocked country codes (ISO 3166-1 alpha-2).
Blocklist of country codes (takes precedence over allowlist)
GEO_BLOCK_COUNTRIES=CN,RU,KP
Country codes are automatically converted to uppercase. Blocklist takes precedence over allowlist.
IP Reputation (Placeholder)
PROXY_VERIFY_IP_REPUTATION
Placeholder for future IP reputation verification.
PROXY_VERIFY_IP_REPUTATION
Reserved for future IP reputation checking feature
PROXY_VERIFY_IP_REPUTATION=false
Currently only logs when enabled. No actual reputation check is performed.
Helper Functions
These internal functions read environment variables:
getEnvString()
func getEnvString(key string, d string) string {
if value, ok := os.LookupEnv(key); ok {
return value
}
return d
}
getEnvInt()
func getEnvInt(key string, d int) int {
if value, err := strconv.Atoi(getEnvString(key, "")); err == nil {
return value
}
return d
}
getEnvBool()
func getEnvBool(key string, d bool) bool {
if value, err := strconv.ParseBool(getEnvString(key, "")); err == nil {
return value
}
return d
}
Complete Example Configuration
# Server
PORT=8081
# Backends
BACKENDS='{"waf.test.local":["web:80"], "api.test.local":["api:8082"], "default":["localhost:5000"]}'
# WAF Rules
CORAZA_RULES_PATH_SITES="coraza.conf:profiles/pl1-crs-setup.conf:coreruleset/rules/*.conf"
CORAZA_RULES_PATH_APIS="coraza.conf:profiles/pl2-crs-setup.conf:coreruleset/rules/REQUEST-901-INITIALIZATION.conf:coreruleset/rules/*.conf"
# Host Classification
PROXY_WEB_HOSTS=waf.test.local
PROXY_APIS_HOSTS=api.test.local
# Rate Limiting
PROXY_RATE_LIMIT=5
PROXY_RATE_BURST=10
# Bot Protection
PROXY_BLOCK_BOTS=false
PROXY_BOTS=python,Googlebot,Bingbot,Slurp,DuckDuckBot,yandex,YandexBot,Sogou,baiduspider
# GeoIP Filtering
GEO_BLOCK_ENABLED=false
GEO_ALLOW_COUNTRIES=US,CA,GB,DE,FR
GEO_BLOCK_COUNTRIES=CN,RU,KP
# IP Reputation (placeholder)
PROXY_VERIFY_IP_REPUTATION=false
Variable Summary Table
| Variable | Type | Default | Source Lines |
|---|
| PORT | string | "8081" | 177-186 |
| BACKENDS | JSON | {"default":["localhost:5000"]} | 97-161 |
| CORAZA_RULES_PATH_SITES | string | /app/coraza.conf:... | 381-384 |
| CORAZA_RULES_PATH_APIS | string | /app/coraza.conf:... | 387-390 |
| PROXY_WEB_HOSTS | string | "" | 410, 468-470 |
| PROXY_APIS_HOSTS | string | "" | 409, 464-466 |
| PROXY_RATE_LIMIT | int | 5 | 412-413 |
| PROXY_RATE_BURST | int | 10 | 412-414 |
| PROXY_BLOCK_BOTS | bool | false | 375, 447 |
| PROXY_BOTS | string | "python,googlebot,..." | 449 |
| GEO_BLOCK_ENABLED | bool | false | 370-373 |
| GEO_ALLOW_COUNTRIES | string | "" | 418 |
| GEO_BLOCK_COUNTRIES | string | "" | 419 |
| PROXY_VERIFY_IP_REPUTATION | bool | false | 51, 428-430 |
