librewolf
/
bunkerized-nginx
mirror of https://github.com/bunkerity/bunkerized-nginx
4
0
Fork 1
Code Issues Projects Releases Wiki Activity

Fix typos in the docs

This commit is contained in:
TheophileDiot 2022-09-28 15:13:17 +02:00
parent 94ce249d74
commit de0954fac3
9 changed files with 139 additions and 121 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/about.md
View File

@ -2,11 +2,11 @@
## Who maintains BunkerWeb ?
BunkerWeb is maintained by [Bunkerity](https://www.bunkerity.com), a French 🇫🇷 company specialised in Cybersecurity 🛡️.
BunkerWeb is maintained by [Bunkerity](https://www.bunkerity.com), a French 🇫🇷 company specialized in Cybersecurity 🛡️.
## Do you offer professional services ?
Yes, we offer professional services related to BunkerWeb like :
Yes, we offer professional services related to BunkerWeb such as :
- Consulting
- Support
@ -17,7 +17,7 @@ Please contact us at [contact@bunkerity.com](mailto:contact@bunkerity.com) if yo
## Where to get community support ?
To get free community support you can use the following medias :
To get free community support, you can use the following medias :
- The #help channel of BunkerWeb in the [Discord server](https://discord.com/invite/fTf46FmtyD)
- The help category of [GitHub dicussions](https://github.com/bunkerity/bunkerweb/discussions)

12
docs/concepts.md
View File

@ -28,7 +28,7 @@ If you think that a new integration should be supported, do not hesitate to open
Once BunkerWeb is integrated into your environment, you will need to configure it to serve and protect your web applications.
Configuration of BunkerWeb is done using what we called the "settings" or "variables". Each setting is identified by a name like `AUTO_LETS_ENCRYPT` or `USE_ANTIBOT` for example. You can assign values to the settings to configure BunkerWeb.
The configuration of BunkerWeb is done by using what we call the "settings" or "variables". Each setting is identified by a name such as `AUTO_LETS_ENCRYPT` or `USE_ANTIBOT`. You can assign values to the settings to configure BunkerWeb.
Here is a dummy example of a BunkerWeb configuration :
@ -48,19 +48,19 @@ USE_BROTLI=no
!!! info "Settings generator tool"
To help you tuning BunkerWeb we have made an easy to use settings generator tool available at [config.bunkerweb.io](https://config.bunkerweb.io).
To help you tune BunkerWeb, we offer an easy-to-use settings generator tool available at [config.bunkerweb.io](https://config.bunkerweb.io).
## Multisite mode
The multisite mode is a crucial concept to understand when using BunkerWeb. Because the goal is to protect web applications, we intrinsically inherit the concept of "virtual host" or "vhost" (more info [here](https://en.wikipedia.org/wiki/Virtual_hosting)) which makes it possible to serve multiple web applications from a single (or a cluster of) instance.
The multisite mode is a crucial concept to understand when using BunkerWeb. Because the goal is to protect web applications, our solution is intrinsically linked to the concept of "virtual host" or "vhost" (more info [here](https://en.wikipedia.org/wiki/Virtual_hosting)) which makes it possible to serve multiple web applications from a single (or a cluster of) instance.
By default, the multisite mode of BunkerWeb is disabled which means that only one web application will be served and all the settings will be applied to it. The typical use case is when you have a single application to protect : you don't have to worry about the multisite and the default behavior should be the right one for you.
By default, the multisite mode of BunkerWeb is disabled which means that only one web application will be served and all the settings will be applied to it. The typical use case is having a single application to protect : you don't have to worry about the multisite and the default behavior should be the right one for you.
When multisite mode is enabled, BunkerWeb will serve and protect multiple web applications. Each web application is identified by a unique server name and have its own set of settings. The typical use case is when you have multiple applications to protect and you want to use a single (or a cluster depending of the integration) instance of BunkerWeb.
When multisite mode is enabled, BunkerWeb serves and protects multiple web applications. Each web application is identified by a unique server name and have its own set of settings. The typical use case is having multiple applications to protect and you want to use a single (or a cluster depending of the integration) instance of BunkerWeb.
The multisite mode is controlled by the `MULTISITE` setting which can be set to `yes` (enabled) or `no` (disabled, which is the default).
Each setting has a context which defines "where" it can be applied. If the context is global then the setting can't be set per server (or "per site", "per app") but only to the whole configuration. Otherwise, if the context is multisite, the setting can be set globally and per server. Defining a multisite setting to a specific server is done by adding the server name as a prefix of the setting name like `app1.example.com_AUTO_LETS_ENCRYPT` or `app2.example.com_USE_ANTIBOT` for example. When a multisite setting is defined globally (without any server prefix), all the servers will inherit that setting (but can still be overriden if we set the same setting with the server name prefix).
Each setting has a context that defines "where" it can be applied. If the context is global then the setting can't be set per server (or "per site", "per app") but only to the whole configuration. Otherwise, if the context is multisite, the setting can be set globally and per server. Defining a multisite setting to a specific server is done by adding the server name as a prefix of the setting name like `app1.example.com_AUTO_LETS_ENCRYPT` or `app2.example.com_USE_ANTIBOT` for example. When a multisite setting is defined globally (without any server prefix), all the servers will inherit that setting (but can still be overriden if we set the same setting with the server name prefix).
Here is a dummy example of a multisite BunkerWeb configuration :

40
docs/integrations.md
View File

@ -9,13 +9,13 @@
Using BunkerWeb as a [Docker](https://www.docker.com/) container is a quick and easy way to test and use it as long as you are familiar with the Docker technology.
We provide ready to use prebuilt images for x64, x86 armv8 and armv7 architectures on [Docker Hub](https://hub.docker.com/r/bunkerity/bunkerweb) :
We provide ready-to-use prebuilt images for x64, x86 armv8 and armv7 architectures on [Docker Hub](https://hub.docker.com/r/bunkerity/bunkerweb) :
```shell
docker pull bunkerity/bunkerweb:1.4.3
```
Alternatively, you can build the Docker images directly from the [source](https://github.com/bunkerity/bunkerweb) (and take a coffee ☕ because it may be long depending on your hardware) :
Alternatively, you can build the Docker images directly from the [source](https://github.com/bunkerity/bunkerweb) (and get a coffee ☕ because it may take a long time depending on your hardware) :
```shell
git clone https://github.com/bunkerity/bunkerweb.git && \
@ -23,7 +23,7 @@ cd bunkerweb && \
docker build -t my-bunkerweb .
```
Usage and configuration of the BunkerWeb container are based on :
BunkerWeb container's usage and configuration are based on :
- **Environment variables** to configure BunkerWeb and meet your use cases
- **Volume** to cache important data and mount custom configuration files
@ -66,7 +66,7 @@ The easiest way of managing the volume is by using a named one. You will first n
docker volume create bw_data
```
Once it's created, you can mount it on `/data` when running the container :
Once it's created, you will be able to mount it on `/data` when running the container :
```shell
docker run \
@ -92,7 +92,7 @@ volumes:
!!! warning "Using local folder for persistent data"
BunkerWeb runs as an **unprivileged user with UID 101 and GID 101** inside the container. The reason behind this is the security : in case a vulnerability is exploited, the attacker won't have full root (UID/GID 0) privileges.
BunkerWeb runs as an **unprivileged user with UID 101 and GID 101** inside the container. The reason behind this is security : in case a vulnerability is exploited, the attacker won't have full root (UID/GID 0) privileges.
But there is a downside : if you use a **local folder for the persistent data**, you will need to **set the correct permissions** so the unprivileged user can write data to it. Something like that should do the trick :
```shell
mkdir bw-data && \
@ -282,7 +282,7 @@ networks:
name: bw-services
```
Once the stack is setup, you can now create the web application container and add the settings as labels using the "bunkerweb." prefix in order to automatically setup BunkerWeb :
Once the stack is set up, you will be able to create the web application container and add the settings as labels using the "bunkerweb." prefix in order to automatically set up BunkerWeb :
```shell
docker run \
@ -330,11 +330,11 @@ networks:
</figure>
!!! info "Docker autoconf"
The Docker autoconf integration is similar of the Docker autoconf one (but with services instead of containers). Please read the [Docker autoconf integration section](#docker-autoconf) first if needed.
The Docker autoconf integration is similar to the Docker autoconf one (but with services instead of containers). Please read the [Docker autoconf integration section](#docker-autoconf) first if needed.
To automatically configure BunkerWeb instances, a special service, called **autoconf**, will be scheduled on a manager node. That service will listen for Docker Swarm events like service creation or deletion and automatically configure the **BunkerWeb instances** in real-time without downtime.
To automatically configure BunkerWeb instances, a special service called **autoconf**, will be scheduled on a manager node. That service will listen for Docker Swarm events like service creation or deletion and automatically configure the **BunkerWeb instances** in real-time without downtime.
Like the [Docker autoconf integration](#docker-autoconf), configuration for web services is defined using labels starting with the special **bunkerweb.** prefix.
Like the [Docker autoconf integration](#docker-autoconf), configuration for web services is defined by using labels starting with the special **bunkerweb.** prefix.
The recommended setup is to schedule the **BunkerWeb service** as a **global service** on all worker nodes and the **autoconf service** as a **single replicated service** on a manager node.
@ -447,7 +447,7 @@ volumes:
bw-data:
```
Once the BunkerWeb Swarm stack is set up and running (see autoconf logs for more information), you can now deploy web applications in the cluster and use labels to dynamically configure BunkerWeb :
Once the BunkerWeb Swarm stack is set up and running (see autoconf logs for more information), you will be able to deploy web applications in the cluster and use labels to dynamically configure BunkerWeb :
```shell
docker service \
@ -655,7 +655,7 @@ spec:
mountPath: /data
```
Once the BunkerWeb Kubernetes stack is setup and running (see autoconf logs for more information), you can now deploy web applications in the cluster and declare your Ingress resource. Please note that [settings](/1.4/settings) need to be set as annotations for the Ingress resource with the special value **bunkerweb.io** for the domain part :
Once the BunkerWeb Kubernetes stack is set up and running (see autoconf logs for more information), you will be able to deploy web applications in the cluster and declare your Ingress resource. Please note that [settings](/1.4/settings) need to be set as annotations for the Ingress resource with the special value **bunkerweb.io** for the domain part :
```yaml
apiVersion: networking.k8s.io/v1
@ -684,9 +684,9 @@ List of supported Linux distros :
- Fedora 36
- CentOS Stream 8
Please note that you will need to **install NGINX 1.20.2 before BunkerWeb**. For all distros, except Fedora, using prebuilt packages from [official NGINX repository](https://nginx.org/en/linux_packages.html) is mandatory. Compiling NGINX from source or using packages from different repositories won't work with the official prebuild packages of BunkerWeb but you can build it from source.
Please note that you will need to **install NGINX 1.20.2 before BunkerWeb**. For all distros, except Fedora, using prebuilt packages from [official NGINX repository](https://nginx.org/en/linux_packages.html) is mandatory. Compiling NGINX from source or using packages from different repositories won't work with the official prebuilt packages of BunkerWeb but you can build it from source.
Repositories of Linux packages for BunkerWeb are available on [PackageCloud](https://packagecloud.io/bunkerity/bunkerweb), they provide a bash script to automatically add and trust the repository (but you can also follow the [manual installation](https://packagecloud.io/bunkerity/bunkerweb/install) instructions if you prefer).
Repositories of Linux packages for BunkerWeb are available on [PackageCloud](https://packagecloud.io/bunkerity/bunkerweb). They provide a bash script to add and trust the repository automatically (but you can also follow the [manual installation](https://packagecloud.io/bunkerity/bunkerweb/install) instructions if you prefer).
=== "Debian"
@ -769,7 +769,7 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt
=== "CentOS Stream"
The first step is to add NGINX official repository, create the following file at `/etc/yum.repos.d/nginx.repo` :
The first step is to add NGINX official repository. Create the following file at `/etc/yum.repos.d/nginx.repo` :
```conf
[nginx-stable]
name=nginx stable repo
@ -813,7 +813,7 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt
https://github.com/bunkerity/bunkerweb.git /tmp/bunkerweb
```
BunkerWeb needs some dependencies to be compiled and install to `/opt/bunkerweb/deps`, the easiest way to it is by executing the [install.sh helper script](https://github.com/bunkerity/bunkerweb/blob/master/deps/install.sh) (please note that you will need to install additional packages which is not covered in this procedure and depends on your own system) :
BunkerWeb needs some dependencies to be compiled and installed to `/opt/bunkerweb/deps`, the easiest way to do it is by executing the [install.sh helper script](https://github.com/bunkerity/bunkerweb/blob/master/deps/install.sh) (please note that you will need to install additional packages which is not covered in this procedure and depends on your own system) :
```
mkdir /opt/bunkerweb/deps && \
/tmp/bunkerweb/deps/install.sh
@ -826,7 +826,7 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt
pip install --no-cache-dir --target /opt/bunkerweb/deps/python -r /tmp/bunkerweb/ui/requirements.txt
```
Once dependencies had been installed, you can now copy the BunkerWeb sources to the target `/opt/bunkerweb` folder :
Once dependencies are installed, you will be able to copy the BunkerWeb sources to the target `/opt/bunkerweb` folder :
```shell
for src in api cli confs core gen helpers job lua misc utils ui settings.json VERSION linux/variables.env linux/ui.env linux/scripts ; do
cp -r /tmp/bunkerweb/${src} /opt/bunkerweb
@ -849,7 +849,7 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt
chown -R root:nginx /opt/bunkerweb
```
Last but not least, you will need to setup systemd unit files :
Last but not least, you will need to set up system unit files :
```shell
cp /tmp/bunkerweb/linux/*.service /etc/systemd/system && \
systemctl daemon-reload && \
@ -859,7 +859,7 @@ Repositories of Linux packages for BunkerWeb are available on [PackageCloud](htt
systemctl enable bunkerweb-ui
```
Configuration of BunkerWeb is done by editing the `/opt/bunkerweb/variables.env` file :
The configuration of BunkerWeb is done by editing the `/opt/bunkerweb/variables.env` file :
```conf
MY_SETTING_1=value1
@ -892,12 +892,12 @@ List of supported Linux distros :
A specific BunkerWeb Ansible role is available on [Ansible Galaxy](https://galaxy.ansible.com/fl0ppy_d1sk/bunkerweb) (source code is available [here](https://github.com/bunkerity/bunkerweb-ansible)).
First of all download the role from ansible-galaxy :
First of all, download the role from ansible-galaxy :
```shell
ansible-galaxy install fl0ppy_d1sk.bunkerweb
```
Next create an inventory by adding the IP adress or FQDN of one or more remote systems, either in `/etc/ansible/hosts` or in your own playbook `inventory.yml` :
Next, create an inventory by adding the IP adress or FQDN of one or more remote systems, either in `/etc/ansible/hosts` or in your own playbook `inventory.yml` :
```toml
[mybunkers]
192.0.2.50

12
docs/migrating.md
View File

@ -2,11 +2,11 @@
!!! warning "Read this if you were a bunkerized user"
A lot of things have changed since the last bunkerized release. If you want to do an upgrade, which we recommend you to do because BunkerWeb is by far better than bunkerized, please read carefully this section and also the whole documentation.
A lot of things changed since the last bunkerized release. If you want to do an upgrade, which we recommend you do because BunkerWeb is by far, better than bunkerized. Please read carefully this section as well as the whole documentation.
## Volumes
When using container-based integrations like [Docker](/1.4/integrations/#docker), [Docker autoconf](/1.4/integrations/#docker-autoconf), [Swarm](/1.4/integrations/#swarm) or [Kubernetes](/1.4/integrations/#kubernetes), volumes for storing data like certificates, cache or custom configurations has changed. We now have a single "bw-data" volume which contains everything and should be easier to manage than bunkerized.
When using container-based integrations like [Docker](/1.4/integrations/#docker), [Docker autoconf](/1.4/integrations/#docker-autoconf), [Swarm](/1.4/integrations/#swarm) or [Kubernetes](/1.4/integrations/#kubernetes), volumes for storing data like certificates, cache or custom configurations have changed. We now have a single "bw-data" volume which contains everything and should be easier to manage than bunkerized.
## Removed features
@ -21,16 +21,16 @@ Instead of supporting only Authelia, we decided to support generic auth request
## Replaced BLOCK_\*, WHITELIST_\* and BLACKLIST_\* settings
The blocking mechanisms has been completely redesigned. We have detected that a lot of false positives came from the default blacklists hardcoded into bunkerized. That's why we decided to give the users the choice of their blacklists (and also whitelists) for IP address, reverse DNS, user-agent, URI and ASN, see the [Blacklisting and whitelisting](/1.4/security-tuning/#blacklisting-and-whitelisting) section of the [security tuning](/1.4/security-tuning).
The blocking mechanisms have been completely redesigned. We have detected that a lot of false positives came from the default blacklists hardcoded into bunkerized. That's why we now give users the possibility of choosing their own blacklists (and also whitelists). For IP address, reverse DNS, user-agent, URI and ASN, see the [Blacklisting and whitelisting](/1.4/security-tuning/#blacklisting-and-whitelisting) section of the [security tuning](/1.4/security-tuning).
## Changed WHITELIST_USER_AGENT setting behavior
The new behavior of the WHITELIST_USER_AGENT setting is to **disable completely security checks** if the User-Agent value of a client match any of the patterns. In bunkerized it was used to ignore specific User-Agent values when `BLOCK_USER_AGENT` was set to `yes` to avoid false positives. You can choose the blacklist of your choice to avoid FP (see previous section).
The new behavior of the WHITELIST_USER_AGENT setting is to **disable completely security checks** if the User-Agent value of a client matches any of the patterns. In bunkerized it was used to ignore specific User-Agent values when `BLOCK_USER_AGENT` was set to `yes` to avoid false positives. You can select the blacklist of your choice to avoid FP (see previous section).
## Changed PROXY_REAL_IP_* settings
To avoid any confusion between reverse proxy and real IP, we decided to renamed the `PROXY_REAL_IP_*` settings, you will find more information on the subject [here](/1.4/quickstart-guide/#behind-load-balancer-or-reverse-proxy).
To avoid any confusion between reverse proxy and real IP, we decided to rename the `PROXY_REAL_IP_*` settings, you will find more information on the subject [here](/1.4/quickstart-guide/#behind-load-balancer-or-reverse-proxy).
## Default values and new settings
The default value of settings may have changed and we have added many other settings, we recommend you to read the [security tuning](/1.4/security-tuning) and [settings](/1.4/settings) sections of the documentation.
The default value of some settings have changed and we have added many other settings, we recommend you read the [security tuning](/1.4/security-tuning) and [settings](/1.4/settings) sections of the documentation.

22
docs/plugins.md
View File

@ -1,6 +1,6 @@
# Plugins
BunkerWeb comes with a plugin system to make it possible to easily add new features. Once a plugin is installed, you can manage it using additional settings defined by the plugin.
BunkerWeb comes with a plugin system making it possible to easily add new features. Once a plugin is installed, you can manage it using additional settings defined by the plugin.
## Official plugins
@ -35,7 +35,7 @@ The first step is to install the plugin by putting the plugin files inside the c
mkdir -p ./bw-data/plugins
```
Then you can drop the plugins of your choice into that folder :
Then, you can drop the plugins of your choice into that folder :
```shell
git clone https://github.com/bunkerity/bunkerweb-plugins && \
cp -rp ./bunkerweb-plugins/* ./bw-data/plugins
@ -90,7 +90,7 @@ The first step is to install the plugin by putting the plugin files inside the c
docker exec -it myautoconf /bin/bash
```
Once you have a shell inside the container, you can drop the plugins of your choice inside the `/data/plugins` folder :
Once you have a shell inside the container, you will be able to drop the plugins of your choice inside the `/data/plugins` folder :
```shell
git clone https://github.com/bunkerity/bunkerweb-plugins && \
cp -rp ./bunkerweb-plugins/* /data/plugins
@ -105,7 +105,7 @@ The first step is to install the plugin by putting the plugin files inside the c
kubectl exec -it myautoconf -- /bin/bash
```
Once you have a shell inside the container, you can drop the plugins of your choice inside the `/data/plugins` folder :
Once you have a shell inside the container, you will be able to drop the plugins of your choice inside the `/data/plugins` folder :
```shell
git clone https://github.com/bunkerity/bunkerweb-plugins && \
cp -rp ./bunkerweb-plugins/* /data/plugins
@ -152,7 +152,7 @@ The first step is to install the plugin by putting the plugin files inside the c
!!! tip "Existing plugins"
If the documentation is not enough you can have a look at the existing source code of [official plugins](https://github.com/bunkerity/bunkerweb-plugins) and the [core plugins](https://github.com/bunkerity/bunkerweb/tree/master/core) (already included in BunkerWeb but they are plugins technically speaking).
If the documentation is not enough, you can have a look at the existing source code of [official plugins](https://github.com/bunkerity/bunkerweb-plugins) and the [core plugins](https://github.com/bunkerity/bunkerweb/tree/master/core) (already included in BunkerWeb but they are plugins, technically speaking).
The first step is to create a folder that will contain the plugin :
@ -291,10 +291,10 @@ The declared functions are automatically called during specific contexts. Here a
| Function | Context | Description | Return value |
| :------: | :--------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `init` | [init_by_lua](https://github.com/openresty/lua-nginx-module#init_by_lua) | Called when NGINX just started or received a reload order. the typical use case is to prepare any data that will be used by your plugin. | `ret`, `err`<ul><li>`ret` (boolean) : true if no error else false</li><li>`err` (string) : success or error message</li></ul> |
| `access` | [access_by_lua](https://github.com/openresty/lua-nginx-module#access_by_lua) | Called on each request received by the server. The typical use case is to do the security checks here and deny the request if needed. | `ret`, `err`, `return`, `status`<ul><li>`ret` (boolean) : true if no error else false</li><li>`err` (string) : success or error message</li><li>`return` (boolean) : true if you want to stop the access phase and send a status to the client</li><li>`status` (number) : the return value to set if `return` is set to true</li></ul> |
| `log` | [log_by_lua](https://github.com/openresty/lua-nginx-module#log_by_lua) | Called when a request has finished (and before it gets logged to the access logs). The typical use case is to make stats or compute counters for example. | `ret`, `err`<ul><li>`ret` (boolean) : true if no error else false</li><li>`err` (string) : success or error message</li></ul> |
| `log_default` | [log_by_lua](https://github.com/openresty/lua-nginx-module#log_by_lua) | Same as `log` but only called on the default server. | `ret`, `err`<ul><li>`ret` (boolean) : true if no error else false</li><li>`err` (string) : success or error message</li></ul> |
| `init` | [init_by_lua](https://github.com/openresty/lua-nginx-module#init_by_lua) | Called when NGINX just started or received a reload order. the typical use case is to prepare any data that will be used by your plugin. | `ret`, `err`<ul><li>`ret` (boolean) : true if no error or else false</li><li>`err` (string) : success or error message</li></ul> |
| `access` | [access_by_lua](https://github.com/openresty/lua-nginx-module#access_by_lua) | Called on each request received by the server. The typical use case is to do the security checks here and deny the request if needed. | `ret`, `err`, `return`, `status`<ul><li>`ret` (boolean) : true if no error or else false</li><li>`err` (string) : success or error message</li><li>`return` (boolean) : true if you want to stop the access phase and send a status to the client</li><li>`status` (number) : the return value to set if `return` is set to true</li></ul> |
| `log` | [log_by_lua](https://github.com/openresty/lua-nginx-module#log_by_lua) | Called when a request has finished (and before it gets logged to the access logs). The typical use case is to make stats or compute counters for example. | `ret`, `err`<ul><li>`ret` (boolean) : true if no error or else false</li><li>`err` (string) : success or error message</li></ul> |
| `log_default` | [log_by_lua](https://github.com/openresty/lua-nginx-module#log_by_lua) | Same as `log` but only called on the default server. | `ret`, `err`<ul><li>`ret` (boolean) : true if no error or else false</li><li>`err` (string) : success or error message</li></ul> |
#### Libraries
@ -412,12 +412,12 @@ Content of foo is : {{ foo }}.
{% endif %}
```
Please note that every form submission is protected via a CSRF token, you will need to include the follow snippet into your forms :
Please note that every form submission is protected via a CSRF token, you will need to include the following snippet into your forms :
```html
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}" />
```
Retrieving user submitted data is pretty simple thanks to the request module provided by Flask :
Retrieving user submitted data is pretty simple, thank to the request module provided by Flask :
```python
from flask import request

66
docs/quickstart-guide.md
View File

@ -29,7 +29,7 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s
docker network create bw-net
```
Then instantiate your app :
Then, instantiate your app :
```shell
docker run -d \
--name myapp \
@ -263,7 +263,7 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s
systemctl status bunkerweb
```
If it's already running we can restart it :
If it's already running, we can restart it :
```shell
systemctl restart bunkerweb
```
@ -275,7 +275,7 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s
=== "Ansible"
We will assume that you already have a service running and you want to use bunkerweb as a reverse-proxy.
We will assume that you already have a service running and you want to use Bunkerweb as a reverse-proxy.
The following command will run a basic HTTP server on the port 8000 and deliver the files in the current directory :
```shell
@ -871,7 +871,7 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s
systemctl status bunkerweb
```
If it's already running we can restart it :
If it's already running, we can restart it :
```shell
systemctl restart bunkerweb
```
@ -940,7 +940,7 @@ You will find more settings about reverse proxy in the [settings section](/1.4/s
## Behind load balancer or reverse proxy
When BunkerWeb is itself behind a load balancer or a reverse proxy, you will need to configure it so it can get the real IP address of the clients. If you don't do it, the security features will block the IP address of the load balancer or reverse proxy instead of the client one.
When BunkerWeb is itself behind a load balancer or a reverse proxy, you need to configure it so it can get the real IP address of the clients. If you don't, the security features will block the IP address of the load balancer or reverse proxy instead of the client's one.
BunkerWeb actually supports two methods to retrieve the real IP address of the client :
@ -1048,7 +1048,7 @@ REAL_IP_HEADER=X-Forwarded-For
=== "Kubernetes"
You will need to add the settings to the environment variables of the bunkerweb containers (doing it using the ingress is not supported because you will get into trouble when using things like Let's Encrypt) :
You will need to add the settings to the environment variables of the Bunkerweb containers (doing it using the ingress is not supported because you will get into trouble when using things like Let's Encrypt) :
```yaml
apiVersion: apps/v1
kind: DaemonSet
@ -1085,7 +1085,7 @@ REAL_IP_HEADER=X-Forwarded-For
...
```
Don't forget to restart the bunkerweb service once it's done.
Don't forget to restart the Bunkerweb service once it's done.
=== "Ansible"
@ -1218,7 +1218,7 @@ REAL_IP_HEADER=proxy_protocol
=== "Kubernetes"
You will need to add the settings to the environment variables of the bunkerweb containers (doing it using the ingress is not supported because you will get into trouble when using things like Let's Encrypt) :
You will need to add the settings to the environment variables of the Bunkerweb containers (doing it using the ingress is not supported because you will get into trouble when using things like Let's Encrypt) :
```yaml
apiVersion: apps/v1
kind: DaemonSet
@ -1258,7 +1258,7 @@ REAL_IP_HEADER=proxy_protocol
...
```
Don't forget to restart the bunkerweb service once it's done.
Don't forget to restart the Bunkerweb service once it's done.
=== "Ansible"
@ -1303,15 +1303,15 @@ Because BunkerWeb is based on the NGINX web server, you can add custom NGINX con
- **modsec-crs** : before the OWASP Core Rule Set is loaded
- **modsec** : after the OWASP Core Rule Set is loaded (also used if CRS is not loaded)
Custom configurations can be applied globally or only for a specific server when applicable and if multisite mode is enabled.
Custom configurations can be applied globally or only for a specific server when applicable and if the multisite mode is enabled.
The howto depends on the integration used but under the hood, applying custom configurations is done by adding files ending with the .conf suffix in their name to specific folders. To apply a custom configuration for a specific server, the file is written to a subfolder which is named as the primary server name.
Some integrations offer a more convenient way of applying configurations for example using [Configs](https://docs.docker.com/engine/swarm/configs/) with Swarm or [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with Kubernetes.
Some integrations offer a more convenient way of applying configurations such as using [Configs](https://docs.docker.com/engine/swarm/configs/) with Swarm or [ConfigMap](https://kubernetes.io/docs/concepts/configuration/configmap/) with Kubernetes.
=== "Docker"
When using the [Docker integration](/1.4/integrations/#docker), you have two choices for adding custom configurations :
When using the [Docker integration](/1.4/integrations/#docker), you have two choices for the addition of custom configurations :
- Using specific settings `*_CUSTOM_CONF_*` as environment variables (easiest)
- Writing .conf files to the volume mounted on /data
@ -1454,7 +1454,7 @@ Some integrations offer a more convenient way of applying configurations for exa
To keep it simple, you don't even need to attach the Config to a service : the autoconf service is listening for Config events and will update the custom configurations when needed.
When creating a Config you will need to add special labels :
When creating a Config, you will need to add special labels :
* **bunkerweb.CONFIG_TYPE** : must be set to a valid custom configuration type (http, server-http, default-server-http, modsec or modsec-crs)
* **bunkerweb.CONFIG_SITE** : set to a server name to apply configuration to that specific server (optional, will be applied globally if unset)
@ -1477,7 +1477,7 @@ Some integrations offer a more convenient way of applying configurations for exa
To keep it simple, you don't even need to use the ConfigMap with a Pod (e.g. as environment variable or volume) : the autoconf Pod is listening for ConfigMap events and will update the custom configurations when needed.
When creating a ConfigMap you will need to add special labels :
When creating a ConfigMap, you will need to add special labels :
* **bunkerweb.io/CONFIG_TYPE** : must be set to a valid custom configuration type (http, server-http, default-server-http, modsec or modsec-crs)
* **bunkerweb.io/CONFIG_SITE** : set to a server name to apply configuration to that specific server (optional, will be applied globally if unset)
@ -1520,7 +1520,7 @@ Some integrations offer a more convenient way of applying configurations for exa
chmod -R 770 /opt/bunkerweb/configs
```
Don't forget to restart the bunkerweb service once it's done.
Don't forget to restart the Bunkerweb service once it's done.
=== "Ansible"
@ -1562,7 +1562,7 @@ Some integrations offer a more convenient way of applying configurations for exa
## PHP
!!! warning "Support is in beta"
At the moment, PHP support with BunkerWeb is still in beta and we recommend you to use a reverse-proxy architecture if you can. By the way, PHP is not supported at all for some integrations like Kubernetes.
At the moment, PHP support with BunkerWeb is still in beta and we recommend you use a reverse-proxy architecture if you can. By the way, PHP is not supported at all for some integrations like Kubernetes.
BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/manual/en/install.fpm.php) instances. We will assume that you are already familiar with managing that kind of services.
@ -1580,7 +1580,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
When using the [Docker integration](/1.4/integrations/#docker), to support PHP applications, you will need to :
- Copy your application files into the `www` subfolder of the `bw-data` volume of BunkerWeb
- Setup a PHP-FPM container for your application and mount the `bw-data/www` folder
- Set up a PHP-FPM container for your application and mount the `bw-data/www` folder
- Use the specific settings `REMOTE_PHP` and `REMOTE_PHP_PATH` as environment variables when starting BunkerWeb
Create the `bw-data/www` folder :
@ -1661,7 +1661,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
When using the [Docker autoconf integration](/integrations/#docker-autoconf), your PHP files must not be mounted into the `bw-data/www` folder. Instead, you will need to create a specific folder containing your PHP application and mount it both on the BunkerWeb container (outside the `/data` endpoint) and your PHP-FPM container.
First of all create the application folder (e.g. `myapp`), copy your files and fix the permissions so BunkerWeb (UID/GID 101) can at least read files and list folders and PHP-FPM (UID/GID 33) is the owner of the files and folders :
First of all, create the application folder (e.g. `myapp`), copy your files and fix the permissions so BunkerWeb (UID/GID 101) can at least read files and list folders and PHP-FPM (UID/GID 33) is the owner of the files and folders :
```shell
chown -R 33:101 ./myapp && \
find ./myapp -type f -exec chmod 0640 {} \; && \
@ -1677,7 +1677,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
bunkerity/bunkerweb:1.4.3
```
Once BunkerWeb and autoconf are ready, you can now create the PHP-FPM container, mount the application folder inside the container and configure it using specific labels :
Once BunkerWeb and autoconf are ready, you will be able to create the PHP-FPM container, mount the application folder inside the container and configure it using specific labels :
```shell
docker run -d \
--name myphp \
@ -1725,7 +1725,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
When using the [Docker Swarm integration](/integrations/#swarm), your PHP files must not be mounted into the `bw-data/www` folder. Instead, you will need to create a specific folder containing your PHP application and mount it both on the BunkerWeb container (outside the `/data` endpoint) and your PHP-FPM container. As an example, we will consider that you have a shared folder mounted on your worker nodes on the `/shared` endpoint.
First of all create the application folder (e.g. `/shared/myapp`), copy your files and fix the permissions so BunkerWeb (UID/GID 101) can at least read files and list folders and PHP-FPM (UID/GID 33) is the owner of the files and folders :
First of all, create the application folder (e.g. `/shared/myapp`), copy your files and fix the permissions so BunkerWeb (UID/GID 101) can at least read files and list folders and PHP-FPM (UID/GID 33) is the owner of the files and folders :
```shell
chown -R 33:101 /shared/myapp && \
find /shared/myapp -type f -exec chmod 0640 {} \; && \
@ -1741,7 +1741,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
bunkerity/bunkerweb:1.4.3
```
Once BunkerWeb and autoconf are ready, you can now create the PHP-FPM service, mount the application folder inside the container and configure it using specific labels :
Once BunkerWeb and autoconf are ready, you will be able to create the PHP-FPM service, mount the application folder inside the container and configure it using specific labels :
```shell
docker service create \
--name myphp \
@ -1793,7 +1793,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
We will assume that you already have the [Linux integration](/1.4/integrations/#linux) stack running on your machine.
By default, BunkerWeb will search for web files inside the `/opt/bunkerweb/www` folder. You can use it for storing your PHP application. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb.
By default, BunkerWeb will search for web files inside the `/opt/bunkerweb/www` folder. You can use it to store your PHP application. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb.
First of all, you will need to make sure that your PHP-FPM instance can access the files inside the `/opt/bunkerweb/www` folder and also that BunkerWeb can access the UNIX socket file in order to communicate with PHP-FPM. We recommend to set a different user like `www-data` for the PHP-FPM service and to give the nginx group access to the UNIX socket file. Here is corresponding PHP-FPM configuration :
```ini
@ -1847,7 +1847,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
=== "Ansible"
By default, BunkerWeb will search for web files inside the `/opt/bunkerweb/www` folder. You can use it for storing your PHP application. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb.
By default, BunkerWeb will search for web files inside the `/opt/bunkerweb/www` folder. You can use it to store your PHP application. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb.
First of all, you will need to make sure that your PHP-FPM instance can access the files inside the `/opt/bunkerweb/www` folder and also that BunkerWeb can access the UNIX socket file in order to communicate with PHP-FPM. We recommend to set a different user like `www-data` for the PHP-FPM service and to give the nginx group access to the UNIX socket file. Here is corresponding PHP-FPM configuration :
```ini
@ -1863,7 +1863,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
```
!!! info "PHP-FPM with Ansible"
The PHP-FPM configuration part using Ansible is out-of-scope of this documentation.
The PHP-FPM configuration part using Ansible is out of the scope of this documentation.
Content of the `my_variables.env` configuration file :
```env
@ -1876,7 +1876,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
LOCAL_PHP_PATH=/opt/bunkerweb/www/
```
The `custom_site` variable can be used to specificy a directory containing your application files (e.g : `my_app`) that will be copied to `/opt/bunkerweb/www` and the `custom_www_owner` variable contains the owner that should be set for the files and folders. Here is an example using the Ansible inventory :
The `custom_site` variable can be used to specify a directory containing your application files (e.g : `my_app`) that will be copied to `/opt/bunkerweb/www` and the `custom_www_owner` variable contains the owner that should be set for the files and folders. Here is an example using the Ansible inventory :
```ini
[mybunkers]
192.168.0.42 variables_env="{{ playbook_dir }}/my_variables.env" custom_www="{{ playbook_dir }}/my_app" custom_www_owner="www-data"
@ -2040,7 +2040,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
=== "Docker autoconf"
When using the [Docker autoconf integration](/integrations/#docker-autoconf), your PHP files must not be mounted into the `bw-data/www` folder. Instead, you will need to create a specific folders containing your PHP applications and mount them both on the BunkerWeb container (outside the `/data` endpoint) and your PHP-FPM containers.
When using the [Docker autoconf integration](/integrations/#docker-autoconf), your PHP files must not be mounted into the `bw-data/www` folder. Instead, you will need to create a specific folder containing your PHP applications and mount it both on the BunkerWeb container (outside the `/data` endpoint) and your PHP-FPM containers.
First of all create the applications folder (e.g. `myapp`), the subfolders for each application (e.g, `app1`, `app2` and `app3`), copy your web files and fix the permissions so BunkerWeb (UID/GID 101) can at least read files and list folders and PHP-FPM (UID/GID 33) is the owner of the files and folders :
```shell
@ -2058,7 +2058,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
bunkerity/bunkerweb:1.4.3
```
Once BunkerWeb and autoconf are ready, you can now create the PHP-FPM containers, mount the right application folder inside each container and configure them using specific labels :
Once BunkerWeb and autoconf are ready, you will be able to create the PHP-FPM containers, mount the right application folder inside each container and configure them using specific labels :
=== "App #1"
```shell
@ -2166,7 +2166,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
When using the [Docker Swarm integration](/integrations/#swarm), your PHP files must not be mounted into the `bw-data/www` folder. Instead, you will need to create a specific folder containing your PHP applications and mount it both on the BunkerWeb container (outside the `/data` endpoint) and your PHP-FPM containers. As an example, we will consider that you have a shared folder mounted on your worker nodes on the `/shared` endpoint.
FFirst of all create the applications folder (e.g. `myapp`), the subfolders for each application (e.g, `app1`, `app2` and `app3`), copy your files and fix the permissions so BunkerWeb (UID/GID 101) can at least read files and list folders and PHP-FPM (UID/GID 33) is the owner of the files and folders :
First of all, create the applications folder (e.g. `myapp`), the subfolders for each application (e.g, `app1`, `app2` and `app3`), copy your files and fix the permissions so BunkerWeb (UID/GID 101) can at least read files and list folders and PHP-FPM (UID/GID 33) is the owner of the files and folders :
```shell
chown -R 33:101 /shared/myapps && \
find /shared/myapps -type f -exec chmod 0640 {} \; && \
@ -2182,7 +2182,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
bunkerity/bunkerweb:1.4.3
```
Once BunkerWeb and autoconf are ready, you can now create the PHP-FPM service, mount the application folder inside the container and configure it using specific labels :
Once BunkerWeb and autoconf are ready, you will be able to create the PHP-FPM service, mount the application folder inside the container and configure it using specific labels :
=== "App #1"
```shell
@ -2298,7 +2298,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
We will assume that you already have the [Linux integration](/1.4/integrations/#linux) stack running on your machine.
By default, BunkerWeb will search for web files inside the `/opt/bunkerweb/www` folder. You can use it for storing your PHP applications : each application will be in its own subfolder named the same as the primary server name. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb.
By default, BunkerWeb will search for web files inside the `/opt/bunkerweb/www` folder. You can use it to store your PHP applications : each application will be in its own subfolder named the same as the primary server name. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb.
First of all, you will need to make sure that your PHP-FPM instance can access the files inside the `/opt/bunkerweb/www` folder and also that BunkerWeb can access the UNIX socket file in order to communicate with PHP-FPM. We recommend to set a different user like `www-data` for the PHP-FPM service and to give the nginx group access to the UNIX socket file. Here is corresponding PHP-FPM configuration :
```ini
@ -2357,7 +2357,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
=== "Ansible"
By default, BunkerWeb will search for web files inside the `/opt/bunkerweb/www` folder. You can use it for storing your PHP application : each application will be in its own subfolder named the same as the primary server name. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb.
By default, BunkerWeb will search for web files inside the `/opt/bunkerweb/www` folder. You can use it to store your PHP application : each application will be in its own subfolder named the same as the primary server name. Please note that you will need to configure your PHP-FPM service to get or set the user/group of the running processes and the UNIX socket file used to communicate with BunkerWeb.
First of all, you will need to make sure that your PHP-FPM instance can access the files inside the `/opt/bunkerweb/www` folder and also that BunkerWeb can access the UNIX socket file in order to communicate with PHP-FPM. We recommend to set a different user like `www-data` for the PHP-FPM service and to give the nginx group access to the UNIX socket file. Here is corresponding PHP-FPM configuration :
```ini
@ -2373,7 +2373,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
```
!!! info "PHP-FPM with Ansible"
The PHP-FPM configuration part using Ansible is out-of-scope of this documentation.
The PHP-FPM configuration part using Ansible is out of the scope of this documentation.
Content of the `my_variables.env` configuration file :
```env
@ -2391,7 +2391,7 @@ BunkerWeb supports PHP using external or remote [PHP-FPM](https://www.php.net/ma
app3.example.com_LOCAL_PHP_PATH=/opt/bunkerweb/www/app3.example.com
```
The `custom_site` variable can be used to specificy a directory containing your application files (e.g : `my_app`) that will be copied to `/opt/bunkerweb/www` and the `custom_www_owner` variable contains the owner that should be set for the files and folders. Here is an example using the Ansible inventory :
The `custom_site` variable can be used to specify a directory containing your application files (e.g : `my_app`) that will be copied to `/opt/bunkerweb/www` and the `custom_www_owner` variable contains the owner that should be set for the files and folders. Here is an example using the Ansible inventory :
```ini
[mybunkers]
192.168.0.42 variables_env="{{ playbook_dir }}/my_variables.env" custom_www="{{ playbook_dir }}/my_app" custom_www_owner="www-data"

58
docs/security-tuning.md
View File

@ -1,6 +1,6 @@
# Security tuning
BunkerWeb offers many security features that you can configure with [settings](/1.4/settings). Even if the default values of settings ensure a minimal "security by default", we strongly recommend you to tune them. By doing so you will be able to ensure a security level of your choice but also manage false positives.
BunkerWeb offers many security features that you can configure with [settings](/1.4/settings). Even if the default values of settings ensure a minimal "security by default", we strongly recommend you tune them. By doing so you will be able to ensure the security level of your choice but also manage false positives.
!!! tip "Other settings"
This section only focuses on security tuning, see the [settings section](/1.4/settings) of the documentation for other settings.
@ -14,7 +14,7 @@ The first thing to define is the kind of action to do when a client access is de
- `403` : send a "classical" Forbidden HTTP status code (a web page or custom content will be displayed)
- `444` : close the connection (no web page or custom content will be displayed)
The default value is `403` and we suggest you to set it to `444` only if you already fixed a lot of false positive, you are familiar with BunkerWeb and want a higher level of security.
The default value is `403` and we suggest you set it to `444` only if you already fixed a lot of false positive, you are familiar with BunkerWeb and want a higher level of security.
### Default server
@ -36,7 +36,7 @@ To disable serving files from the www folder, you can set `SERVE_FILES` to `no`
### Headers
Headers are very important when it comes to HTTP security. Not only some of them are too verbose but others can add some security, especially on the client-side.
Headers are very important when it comes to HTTP security. While some of them might be too verbose, others' verbosity will need to be increased, especially on the client-side.
#### Remove headers
@ -121,7 +121,7 @@ When `USE_CUSTOM_HTTPS` is set to `yes`, BunkerWeb will check every day if the c
### Self-signed
If you want to quickly test HTTPS for staging/dev environment you can configure BunkerWeb to generate self-signed certificates, here is the list of related
If you want to quickly test HTTPS for staging/dev environment you can configure BunkerWeb to generate self-signed certificates, here is the list of related settings :
| Setting | Default | Description |
| :------------------------: | :--------------------: | :------------------------------------------------------------------------------------------------------------------------- |
@ -177,13 +177,13 @@ That kind of security measure is implemented and enabled by default in BunkerWeb
| `BAD_BEHAVIOR_STATUS_CODES` | `400 401 403 404 405 429 444` | List of HTTP status codes considered as "suspicious". |
| `BAD_BEHAVIOR_BAN_TIME` | `86400` | The duration time (in seconds) of a ban when a client reached the threshold. |
| `BAD_BEHAVIOR_THRESHOLD` | `10` | Maximum number of "suspicious" HTTP status codes within the time period. |
| `BAD_BEHAVIOR_COUNT_TIME` | `60` | Period of time where we count "suspicious" HTTP status codes. |
| `BAD_BEHAVIOR_COUNT_TIME` | `60` | Period of time during which we count "suspicious" HTTP status codes. |
In other words, with the default values, if a client generates more than `10` status codes from the list `400 401 403 404 405 429 444` within `60` seconds his IP address will be banned for `86400` seconds.
In other words, with the default values, if a client generates more than `10` status codes from the list `400 401 403 404 405 429 444` within `60` seconds their IP address will be banned for `86400` seconds.
## Antibot
Attackers will certainly use automated tools to exploit/find some vulnerabilities in your web applications. One countermeasure is to challenge the users to detect if they look like a bot. If the challenge is solved, we consider the client as "legitimate" and he can access the web application.
Attackers will certainly use automated tools to exploit/find some vulnerabilities in your web applications. One countermeasure is to challenge the users to detect if they look like a bot. If the challenge is solved, we consider the client as "legitimate" and they can access the web application.
That kind of security is implemented but not enabled by default in BunkerWeb and is called "Antibot". Here is the list of supported challenges :
@ -204,15 +204,15 @@ Here is the list of related settings :
| `ANTIBOT_HCAPTCHA_SECRET` and `ANTIBOT_RECAPTCHA_SECRET` | | The Secret value to use when `USE_ANTIBOT` is set to `hcaptcha` or `recaptcha`. |
| `ANTIBOT_RECAPTCHA_SCORE` | `0.7` | The minimum score that clients must have when `USE_ANTIBOT` is set to `recaptcha`. |
## Blacklisting and whitelisting
## Blacklisting, whitelisting and greylisting
The blacklisting security feature is very easy to understand : if a specific criteria is met, the client will be banned. As for the whitelisting, it's the exact opposite : if a specific criteria is met, the client will be allowed and no additional security check will be done.
The blacklisting security feature is very easy to understand : if a specific criteria is met, the client will be banned. As for the whitelisting, it's the exact opposite : if a specific criteria is met, the client will be allowed and no additional security check will be done. Whereas for the greylisting : if a specific criteria is met, the client will be allowed but additional security checks will be done.
You can configure blacklisting and whitelisting at the same time. If that's the case, note that whitelisting is executed before blacklisting : if a criteria is true for both, the client will be whitelisted.
You can configure blacklisting, whitelisting and greylisting at the same time. If that's the case, note that whitelisting is executed before blacklisting and greylisting : even if a criteria is true for all of them, the client will be whitelisted.
### Blacklisting
You can use the following settings to setup blacklisting :
You can use the following settings to set up blacklisting :
| Setting | Default | Description |
| :-------------------------: | :----------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------- |
@ -228,13 +228,31 @@ You can use the following settings to setup blacklisting :
| `BLACKLIST_URI` | | List of requests URI to blacklist. |
| `BLACKLIST_URI_URLS` | | List of URLs containing request URI to blacklist. |
### Greylisting
You can use the following settings to set up greylisting :
| Setting | Default | Description |
| :-------------------------: | :----------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------- |
| `USE_GREYLIST` | `no` | When set to `yes`, will enable greylisting based on various criteria. |
| `GREYLIST_IP` | | List of IPs and networks to greylist. |
| `GREYLIST_IP_URLS` | | List of URL containing IP and network to greylist. |
| `GREYLIST_RDNS` | | List of reverse DNS to greylist. |
| `GREYLIST_RDNS_URLS` | | List of URLs containing reverse DNS to greylist. |
| `GREYLIST_ASN` | | List of ASN to greylist. |
| `GREYLIST_ASN_URLS` | | List of URLs containing ASN to greylist. |
| `GREYLIST_USER_AGENT` | | List of User-Agents to greylist. |
| `GREYLIST_USER_AGENT_URLS` | | List of URLs containing User-Agent(s) to greylist. |
| `GREYLIST_URI` | | List of requests URI to greylist. |
| `GREYLIST_URI_URLS` | | List of URLs containing request URI to greylist. |
### Whitelisting
You can use the following settings to setup whitelisting :
You can use the following settings to set up whitelisting :
| Setting | Default | Description |
| :-------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------- |
| `USE_WHITELIST` | `yes` | When set to `yes`, will enable blacklisting based on various criteria. |
| `USE_WHITELIST` | `yes` | When set to `yes`, will enable whitelisting based on various criteria. |
| `WHITELIST_IP` | `20.191.45.212 40.88.21.235 40.76.173.151 40.76.163.7 20.185.79.47 52.142.26.175 20.185.79.15 52.142.24.149 40.76.162.208 40.76.163.23 40.76.162.191 40.76.162.247 54.208.102.37 107.21.1.8` | List of IP and network to whitelist. The default list contains IP from DuckDuckGo crawler. |
| `WHITELIST_IP_URLS` | `` | List of URLs containing IP and network to whitelist. |
| `WHITELIST_RDNS` | `.google.com .googlebot.com .yandex.ru .yandex.net .yandex.com .search.msn.com .baidu.com .baidu.jp .crawl.yahoo.net .fwd.linkedin.com .twitter.com .twttr.com .discord.com` | List of reverse DNS to whitelist. Default list contains various reverse DNS of search engines and social media crawlers. |
@ -274,7 +292,7 @@ BunkerWeb supports applying a limit policy to :
- Number of connections per IP
- Number of requests per IP and URL within a time period
Please note that it should not be considered as an effective solution against DoS or DDoS but rather an anti-bruteforce measure or rate limit policy for API.
Please note that it should not be considered as an effective solution against DoS or DDoS but rather as an anti-bruteforce measure or rate limit policy for API.
In both cases (connections or requests) if the limit is reached, the client will receive the HTTP status "429 - Too Many Requests".
@ -294,11 +312,11 @@ The following settings are related to the Limiting requests feature :
| Setting | Default | Description |
| :--------------: | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `USE_LIMIT_REQ` | `yes` | When set to `yes`, will limit the number of requests for a given IP on each URL with a period of time. |
| `USE_LIMIT_REQ` | `yes` | When set to `yes`, will limit the number of requests for a given IP on each URL within a period of time. |
| `LIMIT_REQ_URL` | `/` | The URL that will be limited. The special URL `/` will define a default limit for all URLs. |
| `LIMIT_REQ_RATE` | `2r/s` | The limit to apply to the corresponding URL. Syntax is `Xr/Y` where **X** is the number of request(s) and **Y** the period of time (s for second, m for minute, h for hour and d for day). |
Please note that you can add different rate for different URLs by adding a number to suffix to the settings for example : `LIMIT_REQ_URL_1=/url1`, `LIMIT_REQ_RATE_1=5r/d`, `LIMIT_REQ_URL_2=/url2`, `LIMIT_REQ_RATE_2=1r/m`, ...
Please note that you can add different rates for different URLs by adding a number as a suffix to the settings for example : `LIMIT_REQ_URL_1=/url1`, `LIMIT_REQ_RATE_1=5r/d`, `LIMIT_REQ_URL_2=/url2`, `LIMIT_REQ_RATE_2=1r/m`, ...
Another important thing to note is that `LIMIT_REQ_URL` accepts LUA patterns.
@ -316,12 +334,12 @@ Here is the list of related settings :
| `BLACKLIST_COUNTRY` | | List of 2 letters country code to blacklist. |
| `WHITELIST_COUNTRY` | | List of 2 letters country code to whitelist. |
Using both country blacklist and whitelist at the same time makes no sense. If you do please note that only the whitelist will be executed.
Using both country blacklist and whitelist at the same time makes no sense. If you do, please note that only the whitelist will be executed.
## Authentication
### Auth basic
You can quickly protect sensitive resources like the admin area for example by requiring HTTP basic authentication. Here is the list of related settings :
You can quickly protect sensitive resources like the admin area for example, by requiring HTTP basic authentication. Here is the list of related settings :
| Setting | Default | Description |
| :-----------------------: | :---------------: | :------------------------------------------------------------------------------------------- |
@ -332,12 +350,12 @@ You can quickly protect sensitive resources like the admin area for example by r
| `AUTH_BASIC_TEXT` | `Restricted area` | Text to display in the auth prompt. |
### Auth request
You can deploy complex authentification (e.g. SSO), by using the auth request settings (see [here](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/) for more information on the feature). Please note that you will find [Authelia](https://www.authelia.com/) and [Authentik](https://goauthentik.io/) examples in the [repository](https://github.com/bunkerity/bunkerweb/tree/master/examples).
You can deploy complex authentication (e.g. SSO), by using the auth request settings (see [here](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/) for more information on the feature). Please note that you will find [Authelia](https://www.authelia.com/) and [Authentik](https://goauthentik.io/) examples in the [repository](https://github.com/bunkerity/bunkerweb/tree/master/examples).
**Auth request settings are related to reverse proxy rules.**
| Setting | Default | Context |Multiple| Description |
|---------------------------------------|----------------------------------|---------|--------|--------------------------------------------------------------------------------------------------------------------|
|`REVERSE_PROXY_AUTH_REQUEST` | |multisite|yes |Enable authentication using an external provider (value of auth_request directive). |
|`REVERSE_PROXY_AUTH_REQUEST_SIGNIN_URL`| |multisite|yes |Redirect clients to signin URL when using REVERSE_PROXY_AUTH_REQUEST (used when auth_request call returned 401). |
|`REVERSE_PROXY_AUTH_REQUEST_SIGNIN_URL`| |multisite|yes |Redirect clients to sign-in URL when using REVERSE_PROXY_AUTH_REQUEST (used when auth_request call returned 401). |
|`REVERSE_PROXY_AUTH_REQUEST_SET` | |multisite|yes |List of variables to set from the authentication provider, separated with ; (values of auth_request_set directives).|

16
docs/settings.md
View File

@ -2,11 +2,11 @@
!!! info "Settings generator tool"
To help you tuning BunkerWeb we have made an easy to use settings generator tool available at [config.bunkerweb.io](https://config.bunkerweb.io).
To help you tune BunkerWeb, we have made an easy-to-use settings generator tool available at [config.bunkerweb.io](https://config.bunkerweb.io).
This section contains the full list of settings supported by BunkerWeb. If you are not familiar with BunkerWeb, you should first read the [concepts](/1.4/concepts) section of the documentation. Please follow the instructions for your own [integration](/1.4/integrations) on how to apply the settings.
This section contains the full list of settings supported by BunkerWeb. If you are not yet familiar with BunkerWeb, you should first read the [concepts](/1.4/concepts) section of the documentation. Please follow the instructions for your own [integration](/1.4/integrations) on how to apply the settings.
As a general rule when multisite mode is enabled, if you want to apply settings with multisite context to a specific server you will need to add the primary (first) server name as a prefix like `www.example.com_USE_ANTIBOT=captcha` or `myapp.example.com_USE_GZIP=yes` for example.
As a general rule when multisite mode is enabled, if you want to apply settings with multisite context to a specific server, you will need to add the primary (first) server name as a prefix like `www.example.com_USE_ANTIBOT=captcha` or `myapp.example.com_USE_GZIP=yes` for example.
When settings are considered as "multiple", it means that you can have multiple groups of settings for the same feature by adding numbers as suffix like `REVERSE_PROXY_URL_1=/subdir`, `REVERSE_PROXY_HOST_1=http://myhost1`, `REVERSE_PROXY_URL_2=/anotherdir`, `REVERSE_PROXY_HOST_2=http://myhost2`, ... for example.
@ -42,7 +42,7 @@ When settings are considered as "multiple", it means that you can have multiple
| Setting | Default | Context |Multiple| Description |
|---------------------------|------------|---------|--------|---------------------------------------------------------------------------------|
|`USE_ANTIBOT` |`no` |multisite|no |Activate antibot feature. |
|`ANTIBOT_URI` |`/challenge`|multisite|no |Unused URI that clients will be redirected to solve the challenge. |
|`ANTIBOT_URI` |`/challenge`|multisite|no |Unused URI that clients will be redirected to to solve the challenge. |
|`ANTIBOT_SESSION_SECRET` |`random` |global |no |Secret used to encrypt sessions variables for storing data related to challenges.|
|`ANTIBOT_SESSION_NAME` |`random` |global |no |Name of the cookie used by the antibot feature. |
|`ANTIBOT_RECAPTCHA_SCORE` |`0.7` |multisite|no |Minimum score required for reCAPTCHA challenge. |
@ -69,7 +69,7 @@ When settings are considered as "multiple", it means that you can have multiple
|`BAD_BEHAVIOR_STATUS_CODES`|`400 401 403 404 405 429 444`|multisite|no |List of HTTP status codes considered as 'bad'. |
|`BAD_BEHAVIOR_BAN_TIME` |`86400` |multisite|no |The duration time (in seconds) of a ban when the corresponding IP has reached the threshold.|
|`BAD_BEHAVIOR_THRESHOLD` |`10` |multisite|no |Maximum number of 'bad' HTTP status codes within the period of time before IP is banned. |
|`BAD_BEHAVIOR_COUNT_TIME` |`60` |multisite|no |Period of time where we count 'bad' HTTP status codes. |
|`BAD_BEHAVIOR_COUNT_TIME` |`60` |multisite|no |Period of time during which we count 'bad' HTTP status codes. |
### Blacklist
@ -275,16 +275,16 @@ When settings are considered as "multiple", it means that you can have multiple
|`REVERSE_PROXY_BUFFERING` |`yes` |multisite|yes |Enable or disable buffering of responses from proxied resource. |
|`REVERSE_PROXY_KEEPALIVE` |`no` |multisite|yes |Enable or disable keepalive connections with the proxied resource. |
|`REVERSE_PROXY_AUTH_REQUEST` | |multisite|yes |Enable authentication using an external provider (value of auth_request directive). |
|`REVERSE_PROXY_AUTH_REQUEST_SIGNIN_URL`| |multisite|yes |Redirect clients to signin URL when using REVERSE_PROXY_AUTH_REQUEST (used when auth_request call returned 401). |
|`REVERSE_PROXY_AUTH_REQUEST_SIGNIN_URL`| |multisite|yes |Redirect clients to sign-in URL when using REVERSE_PROXY_AUTH_REQUEST (used when auth_request call returned 401). |
|`REVERSE_PROXY_AUTH_REQUEST_SET` | |multisite|yes |List of variables to set from the authentication provider, separated with ; (values of auth_request_set directives).|
|`USE_PROXY_CACHE` |`no` |multisite|no |Enable or disable caching of the proxied resources. |
|`PROXY_CACHE_PATH_LEVELS` |`1:2` |global |no |Hierarchy levels of the cache. |
|`PROXY_CACHE_PATH_ZONE_SIZE` |`10m` |global |no |Maximum size of cached metadata when caching proxied resources. |
|`PROXY_CACHE_PATH_PARAMS` |`max_size=100m` |global |no |Additional parameters to add to the proxy_cache directive. |
|`PROXY_CACHE_METHODS` |`GET HEAD` |multisite|no |HTTP methods that should trigger a cache operation. |
|`PROXY_CACHE_MIN_USES` |`2` |multisite|no |The minimimum number of requests before a response is cached. |
|`PROXY_CACHE_MIN_USES` |`2` |multisite|no |The minimum number of requests before a response is cached. |
|`PROXY_CACHE_KEY` |`$scheme$host$request_uri` |multisite|no |The key used to uniquely identify a cached response. |
|`PROXY_CACHE_VALID` |`200=24h 301=1h 302=24h` |multisite|no |Define the caching time dependending on the HTTP status code (list of status=time). |
|`PROXY_CACHE_VALID` |`200=24h 301=1h 302=24h` |multisite|no |Define the caching time depending on the HTTP status code (list of status=time). |
|`PROXY_NO_CACHE` |`$http_pragma $http_authorization`|multisite|no |Conditions to disable caching of responses. |
|`PROXY_CACHE_BYPASS` |`0` |multisite|no |Conditions to bypass caching of responses. |
|`REVERSE_PROXY_CONNECT_TIMEOUT` |`60s` |multisite|yes |Timeout when connecting to the proxied resource. |

28
docs/troubleshooting.md
View File

@ -2,16 +2,16 @@
## Logs
When troubleshooting, the logs are your best friends. We try our best to provide user-friendly logs to help you understand what's happening.
When troubleshooting, logs are your best friends. We try our best to provide user-friendly logs to help you understand what's happening.
Please note that you can set `LOG_LEVEL` setting to `info` (default : `notice`) to increase the verbosity of BunkerWeb.
Here is how you can access the logs depending on your integration :
Here is how you can access the logs, depending on your integration :
=== "Docker"
!!! tip "List containers"
To list the running containers you can use the following command :
To list the running containers, you can use the following command :
```shell
docker ps
```
@ -29,7 +29,7 @@ Here is how you can access the logs depending on your integration :
=== "Docker autoconf"
!!! tip "List containers"
To list the running containers you can use the following command :
To list the running containers, you can use the following command :
```shell
docker ps
```
@ -49,12 +49,12 @@ Here is how you can access the logs depending on your integration :
=== "Swarm"
!!! tip "List services"
To list the services you can use the following command :
To list the services, you can use the following command :
```shell
docker service ls
```
You can use the `docker service logs` command (replace `mybunker` and `myautoconf` my with the name of your services) :
You can use the `docker service logs` command (replace `mybunker` and `myautoconf` with the name of your services) :
```shell
docker service logs mybunker
docker service logs myautoconf
@ -63,11 +63,11 @@ Here is how you can access the logs depending on your integration :
=== "Kubernetes"
!!! tip "List pods"
To list the pods you can use the following command :
To list the pods, you can use the following command :
```shell
kubectl get pods
```
You can use the `kubectl logs` command (replace `mybunker` and `myautoconf` my with the name of your pods) :
You can use the `kubectl logs` command (replace `mybunker` and `myautoconf` with the name of your pods) :
```shell
kubectl logs mybunker
kubectl logs myautoconf
@ -101,14 +101,14 @@ Here is how you can access the logs depending on your integration :
## Permissions
Don't forget that BunkerWeb runs as an unprivileged user for obvious security reasons. Double-check the permissions of files and folders used by BunkerWeb especially if you use custom configurations (more info [here](/1.4/quickstart-guide/#custom-configurations)). You will need to set at least **RW** rights on files and **_RWX_** on folders.
Don't forget that BunkerWeb runs as an unprivileged user for obvious security reasons. Double-check the permissions of files and folders used by BunkerWeb, especially if you use custom configurations (more info [here](/1.4/quickstart-guide/#custom-configurations)). You will need to set at least **RW** rights on files and **_RWX_** on folders.
## ModSecurity
The default BunkerWeb configuration of ModSecurity is to load the Core Rule Set in anomaly scoring mode with a paranoia level (PL) of 1 :
- Each matched rule will increase an anomaly score (so many rules can match a single request)
- PL1 include rules with fewer chances of false positives (but less security than PL4)
- PL1 includes rules with fewer chances of false positives (but less security than PL4)
- the default threshold for anomaly score is 5 for requests and 4 for responses
Let's take the following logs as an example of ModSecurity detection using default configuration (formatted for better readability) :
@ -184,7 +184,7 @@ Let's take the following logs as an example of ModSecurity detection using defau
client: 172.17.0.1, server: localhost, request: "GET /?id=/etc/passwd HTTP/1.1", host: "localhost"
```
As we can see there are 3 different logs :
As we can see, there are 3 different logs :
1. Rule **930120** matched
2. Rule **932160** matched
@ -192,11 +192,11 @@ As we can see there are 3 different logs :
One important thing to understand is that rule **949110** is not a "real" one : it's the one that will deny the request because the anomaly threshold is reached (which is **10** in this example). You should never remove the **949110** rule !
If it's a false-positive you should then focus on both **930120** and **932160** rules. ModSecurity and/or CRS tuning is out of the scope of this documentation but don't forget that you can apply custom configurations before and after the CRS is loaded (more info [here](/1.4/quickstart-guide/#custom-configurations)).
If it's a false-positive, you should then focus on both **930120** and **932160** rules. ModSecurity and/or CRS tuning is out of the scope of this documentation but don't forget that you can apply custom configurations before and after the CRS is loaded (more info [here](/1.4/quickstart-guide/#custom-configurations)).
## Bad Behavior
A common false-positive case is that the client is banned because of the "bad behavior" feature which means that too many suspicious HTTP status codes were generated within a time period (more info [here](/1.4/security-tuning/#bad-behavior)). You should start by reviewing the settings and edit them according to your web application(s) like removing a suspicious HTTP code, decreasing the count time, increasing the threshold, ...
A common false-positive case is when the client is banned because of the "bad behavior" feature which means that too many suspicious HTTP status codes were generated within a time period (more info [here](/1.4/security-tuning/#bad-behavior)). You should start by reviewing the settings and then edit them according to your web application(s) like removing a suspicious HTTP code, decreasing the count time, increasing the threshold, ...
## IP unban
@ -256,7 +256,7 @@ You can manually unban an IP which can be useful when doing some tests but it ne
## Whitelisting
If you have bots that need to access your website, the recommended way to avoid any false positive is to whitelist it using the [whitelisting feature](/1.4/security-tuning/#blacklisting-and-whitelisting). We don't recommend using the `WHITELIST_URI*` or `WHITELIST_USER_AGENT*` settings unless they are set to secret and unpredictable values. Common use cases are :
If you have bots that need to access your website, the recommended way to avoid any false positive is to whitelist them using the [whitelisting feature](/1.4/security-tuning/#blacklisting-and-whitelisting). We don't recommend using the `WHITELIST_URI*` or `WHITELIST_USER_AGENT*` settings unless they are set to secret and unpredictable values. Common use cases are :
- Healthcheck / status bot
- Callback like IPN or webhook