doc - official document started
This commit is contained in:
bunkerity
parent
ca660b2501
commit
5bcbb38638
|
|
@ -0,0 +1,2 @@
|
|||
Common problems and how to resolve them
|
||||
=======================================
|
||||
10
docs/conf.py
10
docs/conf.py
|
|
@ -30,8 +30,7 @@ release = 'v1.2.5'
|
|||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
]
|
||||
extensions = ['myst_parser']
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
|
@ -41,15 +40,16 @@ templates_path = ['_templates']
|
|||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'alabaster'
|
||||
import sphinx_rtd_theme
|
||||
html_theme = "sphinx_rtd_theme"
|
||||
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
html_static_path = ['_static']
|
||||
|
|
|
|||
|
|
@ -0,0 +1,2 @@
|
|||
List of environment variables
|
||||
=============================
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
# bunkerized-nginx official documentation
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 2
|
||||
:caption: Contents
|
||||
introduction
|
||||
quickstart_guide
|
||||
security_tuning
|
||||
common_problems
|
||||
volumes
|
||||
environment_variables
|
||||
```
|
||||
|
|
@ -1,20 +0,0 @@
|
|||
.. bunkerized-nginx documentation master file, created by
|
||||
sphinx-quickstart on Wed May 12 12:20:48 2021.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
Welcome to bunkerized-nginx's documentation!
|
||||
============================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Contents:
|
||||
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
* :ref:`genindex`
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
# Introduction
|
||||
|
||||
<p align="center">
|
||||
<img src="https://github.com/bunkerity/bunkerized-nginx/blob/master/logo.png?raw=true" width="425" />
|
||||
</p>
|
||||
|
||||
nginx Docker image secure by default.
|
||||
|
||||
Avoid the hassle of following security best practices each time you need a web server or reverse proxy. Bunkerized-nginx provides generic security configs, settings and tools so you don't need to do it yourself.
|
||||
|
||||
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 with fail2ban
|
||||
- Antibot challenge through cookie, javascript, captcha or recaptcha v3
|
||||
- Block TOR, proxies, bad user-agents, countries, ...
|
||||
- Block known bad IP with DNSBL and CrowdSec
|
||||
- Prevent bruteforce attacks with rate limiting
|
||||
- Detect bad files with ClamAV
|
||||
- Easy to configure with environment variables or web UI
|
||||
- Automatic configuration with container labels
|
||||
- Docker Swarm support
|
||||
|
||||
Fooling automated tools/scanners :
|
||||
|
||||
<img src="https://github.com/bunkerity/bunkerized-nginx/blob/master/demo.gif?raw=true" />
|
||||
|
||||
You can find a live demo at <a href="https://demo-nginx.bunkerity.com" target="_blank">https://demo-nginx.bunkerity.com</a>, feel free to do some security tests.
|
||||
|
|
@ -0,0 +1,340 @@
|
|||
# Quickstart guide
|
||||
|
||||
## Run HTTP server with default settings
|
||||
|
||||
```shell
|
||||
docker run -p 80:8080 -v /path/to/web/files:/www:ro bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
Web files are stored in the /www directory, the container will serve files from there. Please note that *bunkerized-nginx* doesn't run as root but with an unprivileged user with UID/GID 101 therefore you should set the rights of */path/to/web/files* accordingly.
|
||||
|
||||
## In combination with PHP
|
||||
|
||||
```shell
|
||||
docker network create mynet
|
||||
docker run --network mynet \
|
||||
-p 80:8080 \
|
||||
-v /path/to/web/files:/www:ro \
|
||||
-e REMOTE_PHP=myphp \
|
||||
-e REMOTE_PHP_PATH=/app \
|
||||
bunkerity/bunkerized-nginx
|
||||
docker run --network mynet \
|
||||
--name myphp \
|
||||
-v /path/to/web/files:/app \
|
||||
php:fpm
|
||||
```
|
||||
|
||||
The `REMOTE_PHP` environment variable lets you define the address of a remote PHP-FPM instance that will execute the .php files. `REMOTE_PHP_PATH` must be set to the directory where the PHP container will find the files.
|
||||
|
||||
## Run HTTPS server with automated Let's Encrypt
|
||||
|
||||
```shell
|
||||
docker run -p 80:8080 \
|
||||
-p 443:8443 \
|
||||
-v /path/to/web/files:/www:ro \
|
||||
-v /where/to/save/certificates:/etc/letsencrypt \
|
||||
-e SERVER_NAME=www.yourdomain.com \
|
||||
-e AUTO_LETS_ENCRYPT=yes \
|
||||
-e REDIRECT_HTTP_TO_HTTPS=yes \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
Certificates are stored in the /etc/letsencrypt directory, you should save it on your local drive. Please note that *bunkerized-nginx* doesn't run as root but with an unprivileged user with UID/GID 101 therefore you should set the rights of */where/to/save/certificates* accordingly.
|
||||
|
||||
If you don't want your webserver to listen on HTTP add the environment variable `LISTEN_HTTP` with a *no* value (e.g. HTTPS only). But Let's Encrypt needs the port 80 to be opened so redirecting the port is mandatory.
|
||||
|
||||
Here you have three environment variables :
|
||||
- `SERVER_NAME` : define the FQDN of your webserver, this is mandatory for Let's Encrypt (www.yourdomain.com should point to your IP address)
|
||||
- `AUTO_LETS_ENCRYPT` : enable automatic Let's Encrypt creation and renewal of certificates
|
||||
- `REDIRECT_HTTP_TO_HTTPS` : enable HTTP to HTTPS redirection
|
||||
|
||||
## As a reverse proxy
|
||||
|
||||
```shell
|
||||
docker run -p 80:8080 \
|
||||
-e USE_REVERSE_PROXY=yes \
|
||||
-e REVERSE_PROXY_URL=/ \
|
||||
-e REVERSE_PROXY_HOST=http://myserver:8080 \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
This is a simple reverse proxy to a unique application. If you have more than one application you can add more REVERSE_PROXY_URL/REVERSE_PROXY_HOST by appending a suffix number like this :
|
||||
|
||||
```shell
|
||||
docker run -p 80:8080 \
|
||||
-e USE_REVERSE_PROXY=yes \
|
||||
-e REVERSE_PROXY_URL_1=/app1/ \
|
||||
-e REVERSE_PROXY_HOST_1=http://myapp1:3000/ \
|
||||
-e REVERSE_PROXY_URL_2=/app2/ \
|
||||
-e REVERSE_PROXY_HOST_2=http://myapp2:3000/ \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
## Behind a reverse proxy
|
||||
|
||||
```shell
|
||||
docker run -p 80:8080 \
|
||||
-v /path/to/web/files:/www \
|
||||
-e PROXY_REAL_IP=yes \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
The `PROXY_REAL_IP` environment variable, when set to *yes*, activates the [ngx_http_realip_module](https://nginx.org/en/docs/http/ngx_http_realip_module.html) to get the real client IP from the reverse proxy.
|
||||
|
||||
See [this section](#reverse-proxy) if you need to tweak some values (trusted ip/network, header, ...).
|
||||
|
||||
## Multisite
|
||||
|
||||
By default, bunkerized-nginx will only create one server block. When setting the `MULTISITE` environment variable to *yes*, one server block will be created for each host defined in the `SERVER_NAME` environment variable.
|
||||
You can set/override values for a specific server by prefixing the environment variable with one of the server name previously defined.
|
||||
|
||||
```shell
|
||||
docker run -p 80:8080 \
|
||||
-p 443:8443 \
|
||||
-v /where/to/save/certificates:/etc/letsencrypt \
|
||||
-e SERVER_NAME=app1.domain.com app2.domain.com \
|
||||
-e MULTISITE=yes \
|
||||
-e AUTO_LETS_ENCRYPT=yes \
|
||||
-e REDIRECT_HTTP_TO_HTTPS=yes \
|
||||
-e USE_REVERSE_PROXY=yes \
|
||||
-e app1.domain.com_REVERSE_PROXY_URL=/ \
|
||||
-e app1.domain.com_REVERSE_PROXY_HOST=http://myapp1:8000 \
|
||||
-e app2.domain.com_REVERSE_PROXY_URL=/ \
|
||||
-e app2.domain.com_REVERSE_PROXY_HOST=http://myapp2:8000 \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
The `USE_REVERSE_PROXY` is a *global* variable that will be applied to each server block. Whereas the `app1.domain.com_*` and `app2.domain.com_*` will only be applied to the app1.domain.com and app2.domain.com server block respectively.
|
||||
|
||||
When serving files, the web root directory should contains subdirectories named as the servers defined in the `SERVER_NAME` environment variable. Here is an example :
|
||||
|
||||
```shell
|
||||
|
||||
docker run -p 80:8080 \
|
||||
-p 443:8443 \
|
||||
-v /where/to/save/certificates:/etc/letsencrypt \
|
||||
-v /where/are/web/files:/www:ro \
|
||||
-e SERVER_NAME=app1.domain.com app2.domain.com \
|
||||
-e MULTISITE=yes \
|
||||
-e AUTO_LETS_ENCRYPT=yes \
|
||||
-e REDIRECT_HTTP_TO_HTTPS=yes \
|
||||
-e app1.domain.com_REMOTE_PHP=php1 \
|
||||
-e app1.domain.com_REMOTE_PHP_PATH=/app \
|
||||
-e app2.domain.com_REMOTE_PHP=php2 \
|
||||
-e app2.domain.com_REMOTE_PHP_PATH=/app \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
The */where/are/web/files* directory should have a structure like this :
|
||||
```shell
|
||||
/where/are/web/files
|
||||
├── app1.domain.com
|
||||
│ └── index.php
|
||||
│ └── ...
|
||||
└── app2.domain.com
|
||||
└── index.php
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Automatic configuration
|
||||
|
||||
The downside of using environment variables is that you need to recreate a new container each time you want to add or remove a web service. An alternative is to use the *bunkerized-nginx-autoconf* image which listens for Docker events and "automagically" generates the configuration.
|
||||
|
||||
First we need a volume that will store the configurations :
|
||||
|
||||
```shell
|
||||
docker volume create nginx_conf
|
||||
```
|
||||
|
||||
Then we run bunkerized-nginx with the `bunkerized-nginx.AUTOCONF` label, mount the created volume at /etc/nginx and set some default configurations for our services (e.g. : automatic Let's Encrypt and HTTP to HTTPS redirect) :
|
||||
|
||||
```shell
|
||||
docker network create mynet
|
||||
|
||||
docker run -p 80:8080 \
|
||||
-p 443:8443 \
|
||||
--network mynet \
|
||||
-v /where/to/save/certificates:/etc/letsencrypt \
|
||||
-v /where/are/web/files:/www:ro \
|
||||
-v nginx_conf:/etc/nginx \
|
||||
-e SERVER_NAME= \
|
||||
-e MULTISITE=yes \
|
||||
-e AUTO_LETS_ENCRYPT=yes \
|
||||
-e REDIRECT_HTTP_TO_HTTPS=yes \
|
||||
-l bunkerized.nginx.AUTOCONF \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
When setting `SERVER_NAME` to nothing bunkerized-nginx won't create any server block (in case we only want automatic configuration).
|
||||
|
||||
Once bunkerized-nginx is created, let's setup the autoconf container :
|
||||
|
||||
```shell
|
||||
docker run -v /var/run/docker.sock:/var/run/docker.sock:ro \
|
||||
-v nginx_conf:/etc/nginx \
|
||||
bunkerity/bunkerized-nginx-autoconf
|
||||
```
|
||||
|
||||
We can now create a new container and use labels to dynamically configure bunkerized-nginx. Labels for automatic configuration are the same as environment variables but with the "bunkerized-nginx." prefix.
|
||||
|
||||
Here is a PHP example :
|
||||
|
||||
```shell
|
||||
docker run --network mynet \
|
||||
--name myapp \
|
||||
-v /where/are/web/files/app.domain.com:/app \
|
||||
-l bunkerized-nginx.SERVER_NAME=app.domain.com \
|
||||
-l bunkerized-nginx.REMOTE_PHP=myapp \
|
||||
-l bunkerized-nginx.REMOTE_PHP_PATH=/app \
|
||||
php:fpm
|
||||
```
|
||||
|
||||
And a reverse proxy example :
|
||||
|
||||
```shell
|
||||
docker run --network mynet \
|
||||
--name anotherapp \
|
||||
-l bunkerized-nginx.SERVER_NAME=app2.domain.com \
|
||||
-l bunkerized-nginx.USE_REVERSE_PROXY=yes \
|
||||
-l bunkerized-nginx.REVERSE_PROXY_URL=/ \
|
||||
-l bunkerized-nginx.REVERSE_PROXY_HOST=http://anotherapp
|
||||
tutum/hello-world
|
||||
```
|
||||
|
||||
## Swarm mode
|
||||
|
||||
Automatic configuration through labels is also supported in swarm mode. The *bunkerized-nginx-autoconf* is used to listen for Swarm events (e.g. service create/rm) and "automagically" edit configurations files and reload nginx.
|
||||
|
||||
As a use case we will assume the following :
|
||||
- Some managers are also workers (they will only run the *autoconf* container for obvious security reasons)
|
||||
- The bunkerized-nginx service will be deployed on all workers (global mode) so clients can connect to each of them (e.g. load balancing, CDN, edge proxy, ...)
|
||||
- There is a shared folder mounted on managers and workers (e.g. NFS, GlusterFS, CephFS, ...)
|
||||
|
||||
Let's start by creating the network to allow communications between our services :
|
||||
```shell
|
||||
docker network create -d overlay mynet
|
||||
```
|
||||
|
||||
We can now create the *autoconf* service that will listen to swarm events :
|
||||
```shell
|
||||
docker service create --name autoconf \
|
||||
--network mynet \
|
||||
--mount type=bind,source=/var/run/docker.sock,destination=/var/run/docker.sock,ro \
|
||||
--mount type=bind,source=/shared/confs,destination=/etc/nginx \
|
||||
--mount type=bind,source=/shared/letsencrypt,destination=/etc/letsencrypt \
|
||||
--mount type=bind,source=/shared/acme-challenge,destination=/acme-challenge \
|
||||
-e SWARM_MODE=yes \
|
||||
-e API_URI=/ChangeMeToSomethingHardToGuess \
|
||||
--replicas 1 \
|
||||
--constraint node.role==manager \
|
||||
bunkerity/bunkerized-nginx-autoconf
|
||||
```
|
||||
|
||||
**You need to change `API_URI` to something hard to guess since there is no other security mechanism to protect the API at the moment.**
|
||||
|
||||
When *autoconf* is created, it's time for the *bunkerized-nginx* service to be up :
|
||||
|
||||
```shell
|
||||
docker service create --name nginx \
|
||||
--network mynet \
|
||||
-p published=80,target=8080,mode=host \
|
||||
-p published=443,target=8443,mode=host \
|
||||
--mount type=bind,source=/shared/confs,destination=/etc/nginx \
|
||||
--mount type=bind,source=/shared/letsencrypt,destination=/etc/letsencrypt,ro \
|
||||
--mount type=bind,source=/shared/acme-challenge,destination=/acme-challenge,ro \
|
||||
--mount type=bind,source=/shared/www,destination=/www,ro \
|
||||
-e SWARM_MODE=yes \
|
||||
-e USE_API=yes \
|
||||
-e API_URI=/ChangeMeToSomethingHardToGuess \
|
||||
-e MULTISITE=yes \
|
||||
-e SERVER_NAME= \
|
||||
-e AUTO_LETS_ENCRYPT=yes \
|
||||
-e REDIRECT_HTTP_TO_HTTPS=yes \
|
||||
-l bunkerized-nginx.AUTOCONF \
|
||||
--mode global \
|
||||
--constraint node.role==worker \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
The `API_URI` value must be the same as the one specified for the *autoconf* service.
|
||||
|
||||
We can now create a new service and use labels to dynamically configure bunkerized-nginx. Labels for automatic configuration are the same as environment variables but with the "bunkerized-nginx." prefix.
|
||||
|
||||
Here is a PHP example :
|
||||
|
||||
```shell
|
||||
docker service create --name myapp \
|
||||
--network mynet \
|
||||
--mount type=bind,source=/shared/www/app.domain.com,destination=/app \
|
||||
-l bunkerized-nginx.SERVER_NAME=app.domain.com \
|
||||
-l bunkerized-nginx.REMOTE_PHP=myapp \
|
||||
-l bunkerized-nginx.REMOTE_PHP_PATH=/app \
|
||||
--constraint node.role==worker \
|
||||
php:fpm
|
||||
```
|
||||
|
||||
And a reverse proxy example :
|
||||
|
||||
```shell
|
||||
docker service create --name anotherapp \
|
||||
--network mynet \
|
||||
-l bunkerized-nginx.SERVER_NAME=app2.domain.com \
|
||||
-l bunkerized-nginx.USE_REVERSE_PROXY=yes \
|
||||
-l bunkerized-nginx.REVERSE_PROXY_URL=/ \
|
||||
-l bunkerized-nginx.REVERSE_PROXY_HOST=http://anotherapp \
|
||||
--constraint node.role==worker \
|
||||
tutum/hello-world
|
||||
```
|
||||
|
||||
## Web UI
|
||||
|
||||
**This feature exposes, for now, a security risk because you need to mount the docker socket inside a container exposing a web application. You can test it but you should not use it in servers facing the internet.**
|
||||
|
||||
A dedicated image, *bunkerized-nginx-ui*, lets you manage bunkerized-nginx instances and services configurations through a web user interface. This feature is still in beta, feel free to open a new issue if you find a bug and/or you have an idea to improve it.
|
||||
|
||||
First we need a volume that will store the configurations :
|
||||
|
||||
```shell
|
||||
docker volume create nginx_conf
|
||||
```
|
||||
|
||||
Then, we can create the bunkerized-nginx instance with the `bunkerized-nginx.UI` label and a reverse proxy configuration for our web UI :
|
||||
|
||||
```shell
|
||||
docker network create mynet
|
||||
|
||||
docker run -p 80:8080 \
|
||||
-p 443:8443 \
|
||||
--network mynet \
|
||||
-v nginx_conf:/etc/nginx \
|
||||
-v /where/are/web/files:/www:ro \
|
||||
-v /where/to/save/certificates:/etc/letsencrypt \
|
||||
-e SERVER_NAME=admin.domain.com \
|
||||
-e MULTISITE=yes \
|
||||
-e AUTO_LETS_ENCRYPT=yes \
|
||||
-e REDIRECT_HTTP_TO_HTTPS=yes \
|
||||
-e DISABLE_DEFAULT_SERVER=yes \
|
||||
-e admin.domain.com_SERVE_FILES=no \
|
||||
-e admin.domain.com_USE_AUTH_BASIC=yes \
|
||||
-e admin.domain.com_AUTH_BASIC_USER=admin \
|
||||
-e admin.domain.com_AUTH_BASIC_PASSWORD=password \
|
||||
-e admin.domain.com_USE_REVERSE_PROXY=yes \
|
||||
-e admin.domain.com_REVERSE_PROXY_URL=/webui/ \
|
||||
-e admin.domain.com_REVERSE_PROXY_HOST=http://myui:5000/ \
|
||||
-l bunkerized-nginx.UI \
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
The `AUTH_BASIC` environment variables let you define a login/password that must be provided before accessing to the web UI. At the moment, there is no authentication mechanism integrated into bunkerized-nginx-ui.
|
||||
|
||||
We can now create the bunkerized-nginx-ui container that will host the web UI behind bunkerized-nginx :
|
||||
|
||||
```shell
|
||||
docker run --network mynet \
|
||||
-v /var/run/docker.sock:/var/run/docker.sock:ro \
|
||||
-v nginx_conf:/etc/nginx \
|
||||
-e ABSOLUTE_URI=https://admin.domain.com/webui/ \
|
||||
bunkerity/bunkerized-nginx-ui
|
||||
```
|
||||
|
||||
After that, the web UI should be accessible from https://admin.domain.com/webui/.
|
||||
|
|
@ -0,0 +1,3 @@
|
|||
sphinx
|
||||
sphinx-rtd-theme
|
||||
myst-parser
|
||||
|
|
@ -0,0 +1,128 @@
|
|||
# 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.
|
||||
|
||||
## HTTPS
|
||||
|
||||
### Settings
|
||||
|
||||
Here is a list of environment variables and the corresponding default value related to HTTPS :
|
||||
- `LISTEN_HTTP=yes` : you can set it to `no` if you want to disable HTTP access
|
||||
- `REDIRECT_HTTP_TO_HTTPS=no` : enable/disable HTTP to HTTPS redirection
|
||||
- `HTTPS_PROTOCOLS=TLSv1.2 TLSv1.3` : list of TLS versions to use
|
||||
- `HTTP2=yes` : enable/disable HTTP2 when HTTPS is enabled
|
||||
- `COOKIE_AUTO_SECURE_FLAG=yes` : enable/disable adding Secure flag when HTTPS is enabled
|
||||
- `STRICT_TRANSPORT_SECURITY=max-age=31536000` : force users to visit the website in HTTPS (more info [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy))
|
||||
|
||||
### Let's Encrypt
|
||||
|
||||
Using Let's Encrypt with the `AUTO_LETS_ENCRYPT=yes` environment variable is the easiest way to add HTTPS supports to your web services if they are connected to internet and you have public DNS A record(s).
|
||||
|
||||
You can also set the `EMAIL_LETS_ENCRYPT` environment variable if you want to receive notifications from Let's Encrypt (e.g. : expiration).
|
||||
|
||||
### Custom certificate(s)
|
||||
|
||||
If you have security constraints (e.g : local network, custom PKI, ...) you can use custom certificates of your choice and tell bunkerized-nginx to use them with the following environment variables :
|
||||
- `USE_CUSTOM_HTTPS=yes`
|
||||
- `CUSTOM_HTTPS_CERT=/path/inside/container/to/cert.pem`
|
||||
- `CUSTOM_HTTPS_KEY=/path/inside/container/to/key.pem`
|
||||
|
||||
Here is a dummy example on how to use custom certificates :
|
||||
|
||||
```shell
|
||||
$ ls /etc/ssl/my-web-app
|
||||
cert.pem key.pem
|
||||
$ docker run -p 80:8080 \
|
||||
-p 443:8443 \
|
||||
-v /etc/ssl/my-web-app:/certs:ro \
|
||||
-e USE_CUSTOM_HTTPS=yes \
|
||||
-e CUSTOM_HTTPS_CERT=/certs/cert.pem \
|
||||
-e CUSTOM_HTTPS_KEY=/certs/key.pem \
|
||||
...
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
### Self-signed certificate
|
||||
|
||||
This method is not recommended in production but can be used to quickly deploy HTTPS for testing purposes. Just use the `GENERATE_SELF_SIGNED_SSL=yes` environment variable and bunkerized-nginx will generate a self-signed certificate for you :
|
||||
```shell
|
||||
$ docker run -p 80:8080 \
|
||||
-p 443:8443 \
|
||||
-e GENERATE_SELF_SIGNED_SSL=yes \
|
||||
...
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
## Headers
|
||||
|
||||
Some important HTTP headers related to client security are sent with a default value. Sometimes it can break a web application or can be tuned to provide even more security. The complete list is available [here](#TODO).
|
||||
|
||||
## ModSecurity
|
||||
|
||||
ModSecurity is integrated and enabled by default alongside the OWASP Core Rule Set within bunkerized-nginx. To change this behaviour you can use the `USE_MODSECURITY=no` or `USE_MODSECURITY_CRS=no` environment variables.
|
||||
|
||||
We strongly recommend to keep both ModSecurity and the OWASP Core Rule Set enabled. The only downsides are the false positives that may occur. But they can be fixed easily and the CRS team maintains a list of exclusions for common application (e.g : wordpress, nextcloud, drupal, cpanel, ...).
|
||||
|
||||
Tuning the CRS with bunkerized-nginx is pretty simple : you can add configuration before (i.e. : exclusions) and after (i.e. : exceptions/tuning) the rules are loaded. You just need to mount your .conf files into the /modsec-crs-confs (before CRS is loaded) and /modsec-confs (after CRS is loaded).
|
||||
|
||||
Here is an example to illustrate it :
|
||||
|
||||
```shell
|
||||
$ cat /data/exclusions-crs/wordpress.conf
|
||||
SecAction \
|
||||
"id:900130,\
|
||||
phase:1,\
|
||||
nolog,\
|
||||
pass,\
|
||||
t:none,\
|
||||
setvar:tx.crs_exclusions_wordpress=1"
|
||||
|
||||
$ cat /data/tuning-crs/remove-false-positives.conf
|
||||
SecRule REQUEST_FILENAME "/wp-admin/admin-ajax.php" "id:1,ctl:ruleRemoveByTag=attack-xss,ctl:ruleRemoveByTag=attack-rce"
|
||||
SecRule REQUEST_FILENAME "/wp-admin/options.php" "id:2,ctl:ruleRemoveByTag=attack-xss"
|
||||
SecRule REQUEST_FILENAME "^/wp-json/yoast" "id:3,ctl:ruleRemoveById=930120"
|
||||
|
||||
$ docker run -p 80:8080 \
|
||||
-p 443:8443 \
|
||||
-v /data/exclusions-crs:/modsec-crs-confs:ro \
|
||||
-v /data/tuning-crs:/modsec-confs:ro \
|
||||
...
|
||||
bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
## Bad behaviors detection
|
||||
|
||||
TODO
|
||||
|
||||
## Antibot challenge
|
||||
|
||||
Attackers will certainly use automated tools to exploit/find some vulnerabilities on your web service. One countermeasure is to challenge the users to detect if it looks like a bot. It might be effective against script kiddies or "lazy" attackers.
|
||||
|
||||
You can use the `USE_ANTIBOT` environment variable to add that kind of checks whenever a new client is connecting. The available challenges are : `cookie`, `javascript`, `captcha` and `recaptcha`. More info [here](#TODO).
|
||||
|
||||
## External blacklists
|
||||
|
||||
## Container hardening
|
||||
|
||||
### Drop capabilities
|
||||
By default, *bunkerized-nginx* runs as non-root user inside the container and should not use any of the default [capabilities](https://docs.docker.com/engine/security/#linux-kernel-capabilities) allowed by Docker. You can safely remove all capabilities to harden the container :
|
||||
|
||||
```shell
|
||||
docker run ... --drop-cap=all ... bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
||||
### User namespace remap
|
||||
Another hardening trick is [user namespace remapping](https://docs.docker.com/engine/security/userns-remap/) : it allows you to map the UID/GID of users inside a container to another UID/GID on the host. For example, you can map the user nginx with UID/GID 101 inside the container to a non-existent user with UID/GID 100101 on the host.
|
||||
|
||||
Let's assume you have the /etc/subuid and /etc/subgid files like this :
|
||||
```
|
||||
user:100000:65536
|
||||
```
|
||||
It means that everything done inside the container will be remapped to UID/GID 100101 (100000 + 101) on the host.
|
||||
|
||||
Please note that you must set the rights on the volumes (e.g. : /etc/letsencrypt, /www, ...) according to the remapped UID/GID :
|
||||
```shell
|
||||
$ chown root:100101 /path/to/letsencrypt
|
||||
$ chmod 770 /path/to/letsencrypt
|
||||
$ docker run ... -v /path/to/letsencrypt:/etc/letsencrypt ... bunkerity/bunkerized-nginx
|
||||
```
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
Volumes list
|
||||
============
|
||||
Loading…
Reference in New Issue