Ingress Nginx Bouncer
📚 Documentation💠 Hub💬 Discourse
A lua plugin bouncer for Ingress Nginx Controller.
How does it work ?
This bouncer leverages OpenResty lua's API, used the ingress nginx controller as a plugin.
Supported features:
- Live mode (query the local API for each request)
- Stream mode (pull the local API for new/old decisions every X seconds)
- Ban remediation (can ban an IP address by redirecting him or returning a custom HTML page)
- reCAPTCHA v2 remediation (can return a captcha)
- Works with IPv4/IPv6
- Support IP ranges (can apply a remediation on an IP range)
At the back, this bouncer uses crowdsec lua lib.
Installation
The Ingress nginx controller should be installed using the official helm chart
Using Helm
First you need to create new ingress-nginx chart values file (crowdsec-ingress-bouncer.yaml
) to upgrade the ingress controller with the crowdsec plugin.
controller:
extraVolumes:
- name: crowdsec-bouncer-plugin
emptyDir: {}
extraInitContainers:
- name: init-clone-crowdsec-bouncer
image: crowdsecurity/lua-bouncer-plugin
imagePullPolicy: IfNotPresent
env:
- name: API_URL
value: "http://crowdsec-service.crowdsec.svc.cluster.local:8080" # crowdsec lapi service-name
- name: API_KEY
value: "<API KEY>" # generated with `cscli bouncers add -n <bouncer_name>
- name: BOUNCER_CONFIG
value: "/crowdsec/crowdsec-bouncer.conf"
- name: SECRET_KEY
value: "<your-captcha-secret-key>" # If you want captcha support otherwise remove this ENV VAR
- name: SITE_KEY
value: "<your-captcha-site-key>" # If you want captcha support otherwise remove this ENV VAR
- name: BAN_TEMPLATE_PATH
value: /etc/nginx/lua/plugins/crowdsec/templates/ban.html
- name: CAPTCHA_TEMPLATE_PATH
value: /etc/nginx/lua/plugins/crowdsec/templates/captcha.html
command: ['sh', '-c', "sh /docker_start.sh; mkdir -p /lua_plugins/crowdsec/; cp -R /crowdsec/* /lua_plugins/crowdsec/"]
volumeMounts:
- name: crowdsec-bouncer-plugin
mountPath: /lua_plugins
extraVolumeMounts:
- name: crowdsec-bouncer-plugin
mountPath: /etc/nginx/lua/plugins/crowdsec
subPath: crowdsec
config:
plugins: "crowdsec"
lua-shared-dicts: "crowdsec_cache: 50m"
server-snippet : |
lua_ssl_trusted_certificate "/etc/ssl/certs/ca-certificates.crt"; # If you want captcha support otherwise remove this line
resolver local=on ipv6=off; # If you want captcha support otherwise remove this line
This values upgrade your ingress deployment to add crowdsec lua lib as a plugin and run with the ingress controller. It used this docker image to copy the crowdsec lua library.
Once you have this patch we can upgrade the ingress-nginx chart.
helm -n ingress-nginx upgrade -f ingress-nginx-values.yaml -f crowdsec-ingress-bouncer.yaml ingress-nginx ingress-nginx
And then check if the ingress controller is running well.
kubectl -n ingress-nginx get pods
In stream mode, the bouncer will launch an internal timer to pull the local API at the first request made to the ingress controller.
Ingress controller Configuration
The bouncer uses lua_shared_dict to share cache between all workers.
If you want to increase the cache size you need to change this value :
controller:
config:
lua-shared-dicts: "crowdsec_cache: 50m"
⚠️ Do not rename the crowdsec_cache
shared dict, else the bouncer will not work anymore.
When using captcha remediation
To make HTTP request in the bouncer, we need to set a resolver
in the configuration. We choose local=on
directive since we query google.com
for the captcha verification, but you can replace it with a valid one.
To make secure HTTP request in the bouncer, we need to specify a trusted certificate (lua_ssl_trusted_certificate
).
You can also change this with a valid one :
- /etc/ssl/certs/ca-certificates.crt (Debian/Ubuntu/Gentoo)
- /etc/pki/tls/certs/ca-bundle.crt (Fedora/RHEL 6)
- /etc/ssl/ca-bundle.pem (OpenSUSE)
- /etc/pki/tls/cacert.pem (OpenELEC)
- /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem (CentOS/RHEL 7)
- /etc/ssl/cert.pem (OpenBSD, Alpine)
References
API_KEY
API_KEY=<API_KEY>
CrowdSec Local API key.
Generated with sudo cscli bouncers add
command.
API_URL
API_URL=http://<ip>:<port>
CrowdSec local API URL.
BOUNCING_ON_TYPE
BOUNCING_ON_TYPE=all|ban|captcha
Type of remediation we want to bounce.
If you choose ban
only and receive a decision with captcha
as remediation, the bouncer will skip the decision.
FALLBACK_REMEDIATION
FALLBACK_REMEDIATION=ban
The fallback remediation is applied if the bouncer receives a decision with an unknown remediation.
MODE
MODE=stream|live
The bouncer mode:
- stream: The bouncer will pull new/old decisions from the local API every X seconds (
UPDATE_FREQUENCY
parameter).
Note: The timer that pull the local API will be triggered after the first request.
- live: The bouncer will query the local API for each requests (if IP is not in cache) and will store the IP in cache for X seconds (
CACHE_EXPIRATION
parameter).
REQUEST_TIMEOUT
REQUEST_TIMEOUT=1000
Timeout in milliseconds for the HTTP requests done by the bouncer to query CrowdSec local API or www.google.com (for the reCAPTCHA verification).
EXCLUDE_LOCATION
EXCLUDE_LOCATION=/<path1>,/<path2>
The locations to exclude while bouncing. It is a list of location, separated by commas.
⚠️ It is not recommended to put EXCLUDE_LOCATION=/
.
CACHE_EXPIRATION
This option is only for the
live
mode.
CACHE_EXPIRATION=1
The cache expiration, in second, for IPs that the bouncer store in cache in live
mode.
UPDATE_FREQUENCY
This option is only for the
stream
mode.
UPDATE_FREQUENCY=10
The frequency of update, in second, to pull new/old IPs from the CrowdSec local API.
REDIRECT_LOCATION
This option is only for the
ban
remediation.
REDIRECT_LOCATION=/<path>
The location to redirect the user when there is a ban.
If it is not set, the bouncer will return the page defined in the BAN_TEMPLATE_PATH
with the RET_CODE
(403 by default).
BAN_TEMPLATE_PATH
This option is only for the
ban
remediation.
BAN_TEMPLATE_PATH=<path_to_html_template>
The path to a HTML page to return to IPs that trigger ban
remediation.
By default, the HTML template is located in /etc/nginx/lua/plugins/crowdsec/templates/ban.html
.
RET_CODE
This option is only for the
ban
remediation.
RET_CODE=403
The HTTP code to return for IPs that trigger a ban
remediation.
If nothing specified, it will return a 403.
SECRET_KEY
This option is only for the
captcha
remediation.
SECRET_KEY=<recaptcha_secret_key>
The reCAPTCHA v2 secret key.
SITE_KEY
This option is only for the
captcha
remediation.
SITE_KEY=<recaptcha_site_key>
The reCAPTCHA v2 site key.
CAPTCHA_TEMPLATE_PATH
This option is only for the
captcha
remediation.
CAPTCHA_TEMPLATE_PATH=<path_to_html_template>
The path to a captcha HTML template.
The bouncer will try to replace {{recaptcha_site_key}}
in the template with SITE_KEY
parameter.
By default, the HTML template is located in /etc/nginx/lua/plugins/crowdsec/templates/captcha.html
.
CAPTCHA_EXPIRATION
This option is only for the
captcha
remediation.
CAPTCHA_EXPIRATION=3600
The time for which the captcha will be validated. After this duration, if the decision is still present in CrowdSec local API, the IPs address will get a captcha again.