Documentation | Examples | Blog posts | Community chat | Follow us
Make security by default great again !
bunkerized-nginx is a web server based on the notorious nginx and focused on security. It integrates into existing environments (Linux, Docker, Swarm, Kubernetes, ...) to make your web services "secure by default" without any hassle. The security best practices are automatically applied for you while keeping control of every settings to meet your own use case.
Non-exhaustive list of features :
- HTTPS support with transparent Let's Encrypt automation
- State-of-the-art web security : HTTP security headers, prevent leaks, TLS hardening, ...
- Integrated ModSecurity WAF with the OWASP Core Rule Set
- Automatic ban of strange behaviors
- Antibot challenge through cookie, javascript, captcha or recaptcha v3
- Block TOR, proxies, bad user-agents, countries, ...
- Block known bad IP with DNSBL
- Prevent bruteforce attacks with rate limiting
- Plugins system for external security checks (ClamAV, CrowdSec, ...)
- Easy to configure with environment variables or web UI
- Seamless integration into existing environments : Linux, Docker, Swarm, Kubernetes, ...
Fooling automated tools/scanners :
You can find a live demo at https://demo-nginx.bunkerity.com, feel free to do some security tests.
Table of contents
Click to show
Integrations
Docker
You can get official prebuilt Docker images of bunkerized-nginx for x86, x64, armv7 and aarch64/arm64 architectures on Docker Hub :
$ docker pull bunkerity/bunkerized-nginxOr you can build it from source if you wish :
$ git clone https://github.com/bunkerity/bunkerized-nginx.git
$ cd bunkerized-nginx
$ docker build -t bunkerized-nginx .To use bunkerized-nginx as a Docker container you have to pass specific environment variables, mount volumes and redirect ports to make it accessible from the outside.
You will find more information about Docker integration in the documentation.
Docker autoconf
The downside of using environment variables is that the container needs to be recreated each time there is an update which is not very convenient. To counter that issue, you can use another image called bunkerized-nginx-autoconf which will listen for Docker events and automatically configure bunkerized-nginx instance in real time without recreating the container. Instead of defining environment variables for the bunkerized-nginx container, you simply add labels to your web services and bunkerized-nginx-autoconf will "automagically" take care of the rest.
You will find more information about Docker autoconf feature in the documentation.
Swarm
Using bunkerized-nginx in a Docker Swarm cluster requires a shared folder accessible from both managers and workers (anything like NFS, GlusterFS, CephFS or even SSHFS will work). The deployment and configuration is very similar to the "Docker autoconf" one but with services instead of containers. A service based on the bunkerized-nginx-autoconf image needs to be scheduled on a manager node (don't worry it doesn't expose any network port for obvious security reasons). This service will listen for Docker Swarm events like service creation or deletion and generate the configuration according to the labels of each service. Once configuration generation is done, the bunkerized-nginx-autoconf service will send a reload order to all the bunkerized-nginx tasks so they can load the new configuration.
You will find more information about Docker Swarm integration in the documentation.
Kubernetes
This integration is still in beta, please fill an issue if you find a bug or have an idea on how to improve it.
Using bunkerized-nginx in a Kubernetes cluster requires a shared folder accessible from the nodes (anything like NFS, GlusterFS, CephFS or even SSHFS will work). The bunkerized-nginx-autoconf acts as an Ingress Controller and connects to the k8s API to get cluster events and generate a new configuration when it's needed. Once the configuration is generated, the Ingress Controller sends a reload order to the bunkerized-nginx instances running in the cluster.
You will find more information about Kubernetes integration in the documentation.
Linux
This integration is still in beta, please fill an issue if you find a bug or have an idea on how to improve it.
List of supported Linux distributions :
- Debian buster (10)
- Ubuntu focal (20.04)
- CentOS 7
- Fedora 34
Unlike containers, Linux integration can be tedious because bunkerized-nginx has a bunch of dependencies that need to be installed before we can use it. Fortunately, we provide a helper script to make the process easier and automatic. Once installed, the configuration is really simple, all you have to do is to edit the /opt/bunkerized-nginx/variables.env configuration file and run the bunkerized-nginx command to apply it.
You will find more information about Linux integration in the documentation.
Configuration
The configuration is made through what we call "environment variables" as a form of key/value pairs. You will find the quickstart guide and the complete list of environment variables in the documentation.
Singlesite
By default, bunkerized-nginx will only create one server block in the nginx configuration. This cover the simplest use-case where you want to protect one service easily and quickly.
Here is a dummy configuration as an example :
SERVER_NAME=example.com www.example.com
AUTO_LETS_ENCRYPT=yes
DISABLE_DEFAULT_SERVER=yes
USE_REVERSE_PROXY=yes
REVERSE_PROXY_URL=/
REVERSE_PROXY_HOST=http://internal-service.example.local:8080
# Uncomment the HTTP_PORT and HTTPS_PORTS variables when using Linux configuration
#HTTP_PORT=80
#HTTPS_PORT=443
Multisite
If you have multiple services to protect, the easiest way to do it is by enabling the "multisite" mode. When using multisite, bunkerized-nginx will create one server block per server defined in the SERVER_NAME environment variable. You can configure each servers independently by adding the server name as a prefix.
Here is a dummy configuration as an example :
SERVER_NAME=app1.example.com app2.example.com
# Without prefix the variables are applied globally but can still be overriden
AUTO_LETS_ENCRYPT=yes
DISABLE_DEFAULT_SERVER=yes
# Specific configurations for first service
app1.example.com_USE_REVERSE_PROXY=yes
app1.example.com_REVERSE_PROXY_URL=/
app1.example.com_REVERSE_PROXY_HOST=http://internal-service.example.local:8080
# Specific configuration for second service
app2.example.com_REMOTE_PHP=my-fpm
app2.example.com_REMOTE_PHP_PATH=/var/www/html
# Uncomment the HTTP_PORT and HTTPS_PORTS variables when using Linux configuration
#HTTP_PORT=80
#HTTPS_PORT=443
Special folders
| Name | Location | Purpose | Multisite |
|---|---|---|---|
| www | /www (container) /opt/bunkerized-nginx/www (Linux) |
Static files that need to be delivered by bunkerized-nginx. | Yes |
| http-confs | /http-confs (container) /opt/bunkerized-nginx/http-confs (Linux) |
Custom nginx configuration files loaded at http context. | No |
| server-confs | /server-confs (container) /opt/bunkerized-nginx/server-confs (Linux) |
Custom nginx configuration files loaded at server context. | Yes |
| modsec-confs | /modsec-confs (container) /opt/bunkerized-nginx/modsec-confs (Linux) |
Custom ModSecurity configuration files loaded before the Core Rule Set. | Yes |
| modsec-crs-confs | /modsec-crs-confs (container) /opt/bunkerized-nginx/modsec-crs-confs (Linux) |
Custom ModSecurity configuration files loaded after the Core Rule Set. | Yes |
| plugins | /plugins (container) /opt/bunkerized-nginx/plugins (Linux) |
Location of bunkerized-nginx plugins. | No |
| cache | /cache (container) /opt/bunkerized-nginx/plugins (Linux) |
Placeholder for caching data like external blacklists. | No |
| acme-challenge | /acme-challenge (container) /opt/bunkerized-nginx/acme-challenge (Linux) |
Placeholder for Let's Encrypt challenges. | No |
You will find more information about the special folders in the documentation.
Web UI
You will find more information about the web UI in the documentation.
Security tuning
bunkerized-nginx comes with a set of predefined security settings that you can (and you should) tune to meet your own use case. We recommend you to read the security tuning section of the documentation.
Going further
License
This project is licensed under the terms of the GNU Affero General Public License (AGPL) version 3.
Contributing
If you would like to contribute to the project you can read the contributing guidelines to get started.
Security policy
We take security bugs as serious issues and encourage responsible disclosure, see our security policy for more information.