update doc for web UI account, add ISO format to country core and update version of plugins

This commit is contained in:
florian 2024-01-08 17:24:57 +01:00
parent 80983f3fed
commit 34ce47079e
No known key found for this signature in database
GPG key ID: 93EE47CC3D061500
8 changed files with 190 additions and 287 deletions

View file

@ -343,13 +343,13 @@ Here is the list of "official" plugins that we maintain (see the [bunkerweb-plug
| Name | Version | Description | Link |
| :------------: | :-----: | :------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------: |
| **ClamAV** | 1.2 | Automatically scans uploaded files with the ClamAV antivirus engine and denies the request when a file is detected as malicious. | [bunkerweb-plugins/clamav](https://github.com/bunkerity/bunkerweb-plugins/tree/main/clamav) |
| **Coraza** | 1.2 | Inspect requests using a the Coraza WAF (alternative of ModSecurity). | [bunkerweb-plugins/coraza](https://github.com/bunkerity/bunkerweb-plugins/tree/main/coraza) |
| **CrowdSec** | 1.2 | CrowdSec bouncer for BunkerWeb. | [bunkerweb-plugins/crowdsec](https://github.com/bunkerity/bunkerweb-plugins/tree/main/crowdsec) |
| **Discord** | 1.2 | Send security notifications to a Discord channel using a Webhook. | [bunkerweb-plugins/discord](https://github.com/bunkerity/bunkerweb-plugins/tree/main/discord) |
| **Slack** | 1.2 | Send security notifications to a Slack channel using a Webhook. | [bunkerweb-plugins/slack](https://github.com/bunkerity/bunkerweb-plugins/tree/main/slack) |
| **VirusTotal** | 1.2 | Automatically scans uploaded files with the VirusTotal API and denies the request when a file is detected as malicious. | [bunkerweb-plugins/virustotal](https://github.com/bunkerity/bunkerweb-plugins/tree/main/virustotal) |
| **WebHook** | 1.2 | Send security notifications to a custom HTTP endpoint using a Webhook. | [bunkerweb-plugins/slack](https://github.com/bunkerity/bunkerweb-plugins/tree/main/webhook) |
| **ClamAV** | 1.3 | Automatically scans uploaded files with the ClamAV antivirus engine and denies the request when a file is detected as malicious. | [bunkerweb-plugins/clamav](https://github.com/bunkerity/bunkerweb-plugins/tree/main/clamav) |
| **Coraza** | 1.3 | Inspect requests using a the Coraza WAF (alternative of ModSecurity). | [bunkerweb-plugins/coraza](https://github.com/bunkerity/bunkerweb-plugins/tree/main/coraza) |
| **CrowdSec** | 1.3 | CrowdSec bouncer for BunkerWeb. | [bunkerweb-plugins/crowdsec](https://github.com/bunkerity/bunkerweb-plugins/tree/main/crowdsec) |
| **Discord** | 1.3 | Send security notifications to a Discord channel using a Webhook. | [bunkerweb-plugins/discord](https://github.com/bunkerity/bunkerweb-plugins/tree/main/discord) |
| **Slack** | 1.3 | Send security notifications to a Slack channel using a Webhook. | [bunkerweb-plugins/slack](https://github.com/bunkerity/bunkerweb-plugins/tree/main/slack) |
| **VirusTotal** | 1.3 | Automatically scans uploaded files with the VirusTotal API and denies the request when a file is detected as malicious. | [bunkerweb-plugins/virustotal](https://github.com/bunkerity/bunkerweb-plugins/tree/main/virustotal) |
| **WebHook** | 1.3 | Send security notifications to a custom HTTP endpoint using a Webhook. | [bunkerweb-plugins/slack](https://github.com/bunkerity/bunkerweb-plugins/tree/main/webhook) |
You will find more information in the [plugins section](https://docs.bunkerweb.io/1.5.5/plugins/?utm_campaign=self&utm_source=github) of the documentation.

View file

@ -8,13 +8,13 @@ Here is the list of "official" plugins that we maintain (see the [bunkerweb-plug
| Name | Version | Description | Link |
| :------------: | :-----: | :------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------: |
| **ClamAV** | 1.2 | Automatically scans uploaded files with the ClamAV antivirus engine and denies the request when a file is detected as malicious. | [bunkerweb-plugins/clamav](https://github.com/bunkerity/bunkerweb-plugins/tree/main/clamav) |
| **Coraza** | 1.2 | Inspect requests using a the Coraza WAF (alternative of ModSecurity). | [bunkerweb-plugins/coraza](https://github.com/bunkerity/bunkerweb-plugins/tree/main/coraza) |
| **CrowdSec** | 1.2 | CrowdSec bouncer for BunkerWeb. | [bunkerweb-plugins/crowdsec](https://github.com/bunkerity/bunkerweb-plugins/tree/main/crowdsec) |
| **Discord** | 1.2 | Send security notifications to a Discord channel using a Webhook. | [bunkerweb-plugins/discord](https://github.com/bunkerity/bunkerweb-plugins/tree/main/discord) |
| **Slack** | 1.2 | Send security notifications to a Slack channel using a Webhook. | [bunkerweb-plugins/slack](https://github.com/bunkerity/bunkerweb-plugins/tree/main/slack) |
| **VirusTotal** | 1.2 | Automatically scans uploaded files with the VirusTotal API and denies the request when a file is detected as malicious. | [bunkerweb-plugins/virustotal](https://github.com/bunkerity/bunkerweb-plugins/tree/main/virustotal) |
| **WebHook** | 1.2 | Send security notifications to a custom HTTP endpoint using a Webhook. | [bunkerweb-plugins/webhook](https://github.com/bunkerity/bunkerweb-plugins/tree/main/webhook) |
| **ClamAV** | 1.3 | Automatically scans uploaded files with the ClamAV antivirus engine and denies the request when a file is detected as malicious. | [bunkerweb-plugins/clamav](https://github.com/bunkerity/bunkerweb-plugins/tree/main/clamav) |
| **Coraza** | 1.3 | Inspect requests using a the Coraza WAF (alternative of ModSecurity). | [bunkerweb-plugins/coraza](https://github.com/bunkerity/bunkerweb-plugins/tree/main/coraza) |
| **CrowdSec** | 1.3 | CrowdSec bouncer for BunkerWeb. | [bunkerweb-plugins/crowdsec](https://github.com/bunkerity/bunkerweb-plugins/tree/main/crowdsec) |
| **Discord** | 1.3 | Send security notifications to a Discord channel using a Webhook. | [bunkerweb-plugins/discord](https://github.com/bunkerity/bunkerweb-plugins/tree/main/discord) |
| **Slack** | 1.3 | Send security notifications to a Slack channel using a Webhook. | [bunkerweb-plugins/slack](https://github.com/bunkerity/bunkerweb-plugins/tree/main/slack) |
| **VirusTotal** | 1.3 | Automatically scans uploaded files with the VirusTotal API and denies the request when a file is detected as malicious. | [bunkerweb-plugins/virustotal](https://github.com/bunkerity/bunkerweb-plugins/tree/main/virustotal) |
| **WebHook** | 1.3 | Send security notifications to a custom HTTP endpoint using a Webhook. | [bunkerweb-plugins/webhook](https://github.com/bunkerity/bunkerweb-plugins/tree/main/webhook) |
## How to use a plugin

View file

@ -459,10 +459,10 @@ The country security feature allows you to apply policy based on the country of
Here is the list of related settings :
| Setting | Default | Description |
| :-----------------: | :-----: | :------------------------------------------- |
| `BLACKLIST_COUNTRY` | | List of 2 letters country code to blacklist. |
| `WHITELIST_COUNTRY` | | List of 2 letters country code to whitelist. |
| Setting |Default| Context |Multiple| Description |
|-------------------|-------|---------|--------|--------------------------------------------------------------------------------------------------------------|
|`BLACKLIST_COUNTRY`| |multisite|no |Deny access if the country of the client is in the list (ISO 3166-1 alpha-2 format separated with spaces). |
|`WHITELIST_COUNTRY`| |multisite|no |Deny access if the country of the client is not in the list (ISO 3166-1 alpha-2 format separated with spaces).|
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.

View file

@ -194,10 +194,10 @@ STREAM support :white_check_mark:
Deny access based on the country of the client IP.
| Setting |Default| Context |Multiple| Description |
|-------------------|-------|---------|--------|-----------------------------------------------------------------------------|
|`BLACKLIST_COUNTRY`| |multisite|no |Deny access if the country of the client is in the list (2 letters code). |
|`WHITELIST_COUNTRY`| |multisite|no |Deny access if the country of the client is not in the list (2 letters code).|
| Setting |Default| Context |Multiple| Description |
|-------------------|-------|---------|--------|--------------------------------------------------------------------------------------------------------------|
|`BLACKLIST_COUNTRY`| |multisite|no |Deny access if the country of the client is in the list (ISO 3166-1 alpha-2 format separated with spaces). |
|`WHITELIST_COUNTRY`| |multisite|no |Deny access if the country of the client is not in the list (ISO 3166-1 alpha-2 format separated with spaces).|
### Custom HTTPS certificate
@ -550,3 +550,4 @@ Allow access based on internal and external IP/network/rDNS/ASN whitelists.
|`WHITELIST_USER_AGENT_URLS`| |global |no |List of URLs, separated with spaces, containing good User-Agent to whitelist. |
|`WHITELIST_URI` | |multisite|no |List of URI (PCRE regex), separated with spaces, to whitelist. |
|`WHITELIST_URI_URLS` | |global |no |List of URLs, separated with spaces, containing bad URI to whitelist. |

View file

@ -289,26 +289,23 @@ If you have bots that need to access your website, the recommended way to avoid
When using container-based integrations, the timezone of the container may not match the one of the host machine. To resolve that, you can set the `TZ` environment variable to the timezone of your choice on your containers (e.g. `TZ=Europe/Paris`). You will find the list of timezone identifiers [here](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List).
## Recover profile
## Web UI
In case you lost your UI logs, you can get them by accessing your database and checking `bw_ui_users` table.
### Access database
In case you lost your UI credentials or have 2FA issues, you can connect to the database to retrieve access.
**Access database**
=== "SQLite"
=== "Debian and Ubuntu"
=== "Linux"
Install SQLite:
Install SQLite (Debian/Ubuntu) :
```shell
sudo apt install sqlite3
```
=== "Fedora and RedHat"
Install SQLite:
Install SQLite (Fedora/RedHat) :
```shell
sudo dnf install sqlite
@ -316,76 +313,79 @@ In case you lost your UI logs, you can get them by accessing your database and c
=== "Docker"
1. Access you scheduler container
Get a shell into your scheduler container :
!!! note "Docker arguments"
- the `-u 0` option is to run the command as root (mandatory)
- the `-it` options are to run the command interactively (mandatory)
- `<bunkerweb_scheduler_container>`: the name or ID of your scheduler container
!!! note "Docker arguments"
- the `-u 0` option is to run the command as root (mandatory)
- the `-it` options are to run the command interactively (mandatory)
- `<bunkerweb_scheduler_container>` : the name or ID of your scheduler container
```shell
docker exec -u 0 -it <bunkerweb_scheduler_container> bash
```
```shell
docker exec -u 0 -it <bunkerweb_scheduler_container> bash
```
2. Install SQLite
```bash
apk add sqlite
```
1. Access your database
!!! note "Database path"
We assume that you are using the default database path. If you are using a custom path, you will need to adapt the command.
Install SQLite :
```bash
sqlite3 /data/lib/db.sqlite3
apk add sqlite
```
You should see something like this:
Access your database :
```text
SQLite version <VER> <DATE>
Enter ".help" for usage hints.
sqlite>
```
!!! note "Database path"
We assume that you are using the default database path. If you are using a custom path, you will need to adapt the command.
```bash
sqlite3 /var/lib/bunkerweb/db.sqlite3
```
You should see something like this :
```text
SQLite version <VER> <DATE>
Enter ".help" for usage hints.
sqlite>
```
=== "MariaDB / MySQL"
!!! warning "MariaDB / MySQL only"
!!! note "MariaDB / MySQL only"
The following steps are only valid for MariaDB / MySQL databases. If you are using another database, please refer to the documentation of your database.
!!! note "Credentials and database name"
You will need to use the same credentials and database named used in the `DATABASE_URI` setting.
=== "Linux"
1. Access your local database
Access your local database :
```bash
mysql -u root -p bunkerweb
```
```bash
mysql -u <user> -p <database>
```
Then enter your password of the database user and you should be able to access your database.
Then enter your password of the database user and you should be able to access your database.
=== "Docker"
1. Access you database container
Access your database container :
!!! note "Docker arguments"
- the `-u 0` option is to run the command as root (mandatory)
- the `-it` options are to run the command interactively (mandatory)
- `<bunkerweb_db_container>`: the name or ID of your database container
- `<user>`: the database user
- `<database>`: the database name
!!! note "Docker arguments"
- the `-u 0` option is to run the command as root (mandatory)
- the `-it` options are to run the command interactively (mandatory)
- `<bunkerweb_db_container>` : the name or ID of your database container
- `<user>` : the database user
- `<database>` : the database name
```shell
docker exec -u 0 -it <bunkerweb_db_container> mysql -u <user> -p <database>
```
```shell
docker exec -u 0 -it <bunkerweb_db_container> mysql -u <user> -p <database>
```
Then enter your password of the database user and you should be able to access your database.
Then enter your password of the database user and you should be able to access your database.
### Check user table
**Troubleshooting actions**
!!! info "Database schema"
The database schema is the following:
!!! info "Table schema"
The schema of the `bw_ui_users` table is the following :
```sql
id INTEGER PRIMARY KEY AUTOINCREMENT
@ -396,182 +396,73 @@ In case you lost your UI logs, you can get them by accessing your database and c
method ("manual" or "ui") NOT NULL DEFAULT 'manual'
```
By default, database table is `bw_ui_users`.
=== "Retrieve username"
Execute the following command:
```sql
SELECT * FROM bw_ui_users;
```
You should see something like this:
```text
1|<username>|<password_hash>|1|<secret_totp_token>|(manual or ui)
```
### Update profile
!!! warning "Update password"
Contrary to username, password is hashed, you need to update it using the same hash algorithms and token from UI.
You can update your username / password executing this command:
```sql
UPDATE bw_ui_users SET username = <username>, password = <password_hash> WHERE id = 1;
```
If you check again your `bw_ui_users` table following this command:
```sql
SELECT * FROM bw_ui_users;
```
You should see something like this:
```text
1|<username>|<password_hash>|0||(manual or ui)
```
And that's it ! Now use your logs on UI !
## Lost 2FA authentication
If you lost your 2FA authentication, you can reset it by following these steps :
### Access database
=== "SQLite"
=== "Debian and Ubuntu"
Install SQLite:
```shell
sudo apt install sqlite3
```
=== "Fedora and RedHat"
Install SQLite:
```shell
sudo dnf install sqlite
```
=== "Docker"
1. Access you scheduler container
!!! note "Docker arguments"
- the `-u 0` option is to run the command as root (mandatory)
- the `-it` options are to run the command interactively (mandatory)
- `<bunkerweb_scheduler_container>`: the name or ID of your scheduler container
```shell
docker exec -u 0 -it <bunkerweb_scheduler_container> bash
```
2. Install SQLite
```bash
apk add sqlite
```
1. Access your database
!!! note "Database path"
We assume that you are using the default database path. If you are using a custom path, you will need to adapt the command.
```bash
sqlite3 /data/lib/db.sqlite3
```
You should see something like this:
```text
SQLite version <VER> <DATE>
Enter ".help" for usage hints.
sqlite>
```
=== "MariaDB / MySQL"
!!! warning "MariaDB / MySQL only"
The following steps are only valid for MariaDB / MySQL databases. If you are using another database, please refer to the documentation of your database.
=== "Linux"
1. Access your local database
```bash
mysql -u root -p bunkerweb
```
Then enter your password of the database user and you should be able to access your database.
=== "Docker"
1. Access you database container
!!! note "Docker arguments"
- the `-u 0` option is to run the command as root (mandatory)
- the `-it` options are to run the command interactively (mandatory)
- `<bunkerweb_db_container>`: the name or ID of your database container
- `<user>`: the database user
- `<database>`: the database name
```shell
docker exec -u 0 -it <bunkerweb_db_container> mysql -u <user> -p <database>
```
Then enter your password of the database user and you should be able to access your database.
### Check user table
!!! info "Database schema"
The database schema is the following:
Execute the following command to extract data from the `bw_ui_users` table :
```sql
id INTEGER PRIMARY KEY AUTOINCREMENT
username VARCHAR(256) NOT NULL UNIQUE
password VARCHAR(60) NOT NULL
is_two_factor_enabled BOOLEAN NOT NULL DEFAULT 0
secret_token VARCHAR(32) DEFAULT NULL
method ("manual" or "ui") NOT NULL DEFAULT 'manual'
SELECT * FROM bw_ui_users;
```
By default, database table is `bw_ui_users`.
You should see something like this :
```text
1|<username>|<password_hash>|1|<secret_totp_token>|(manual or ui)
```
Execute the following command:
=== "Update password"
```sql
SELECT * FROM bw_ui_users;
```
You first need to hash the new password using the bcrypt algorithm.
You should see something like this:
```text
1|<username>|<password_hash>|1|<secret_totp_token>|(manual or ui)
```
Install the Python bcrypt library :
### Deactivate 2FA
```shell
pip install bcrypt
```
You can deactivate 2FA executing this command:
Generate your hash (replace `mypassword` with your own password) :
```sql
UPDATE bw_ui_users SET is_two_factor_enabled = 0, secret_token = NULL WHERE id = 1;
```
```shell
python -c 'from bcrypt import hashpw, gensalt ; print(hashpw("mypassword".encode("utf-8"), gensalt(rounds=13)).decode())'
```
If you check again your `bw_ui_users` table following this command:
You can update your username / password executing this command :
```sql
SELECT * FROM bw_ui_users;
```
```sql
UPDATE bw_ui_users SET username = <username>, password = <password_hash> WHERE id = 1;
```
You should see something like this:
If you check again your `bw_ui_users` table following this command :
```text
1|<username>|<password_hash>|0||(manual or ui)
```
```sql
SELECT * FROM bw_ui_users;
```
And that's it ! You just have to try to log in once again and the 2FA will not be prompted !
You should see something like this :
```text
1|<username>|<password_hash>|0||(manual or ui)
```
You should now be able to use the new credentials to log into the web UI.
=== "Disable 2FA authentication"
You can deactivate 2FA by executing this command :
```sql
UPDATE bw_ui_users SET is_two_factor_enabled = 0, secret_token = NULL WHERE id = 1;
```
If you check again your `bw_ui_users` table by following this command :
```sql
SELECT * FROM bw_ui_users;
```
You should see something like this :
```text
1|<username>|<password_hash>|0||(manual or ui)
```
You should now be able to log into the web UI only using your username and password.

View file

@ -727,6 +727,62 @@ Review your final BunkerWeb UI URL and then click on the `Setup` button. Once th
systemctl restart bunkerweb-ui
```
## Account management
You can change the username, password needed and manage two-factor authentication by **accessing the account page** of the web UI from the menu.
TODO : insert menu image
### Username / Password
!!! warning "Lost password/username"
In case you forgot your UI credentials, you can reset them from the CLI following [the steps described in the troubleshooting section](troubleshooting.md#web-ui).
You can update your username or password by filling the dedicated forms. For security reason, you need to enter your current password even if you are connected.
Please note that when your username or password is updated, you will be logout from the web UI to log in again.
<figure markdown>
![Overview](assets/img/profile-username-password.webp){ align=center, width="800" }
<figcaption>Username / Password forms</figcaption>
</figure>
### Two-Factor Authentication
!!! warning "Lost secret key"
In case you lost your secret key, you can disable 2FA from the CLI following [the steps described in the troubleshooting section](troubleshooting.md#web-ui).
You can power-up your login security by adding **Two-Factor Authentication (2FA)** to your account. By doing so, an extra code will be needed in addition to your password.
The web UI uses [Time based One Time Password (TOTP)](https://en.wikipedia.org/wiki/Time-based_one-time_password) as 2FA implementation : using a **secret key**, the algorithm will generate **one time passwords only valid for a short period of time**.
Any TOTP client such as Google Authenticator, Authy, FreeOTP, ... can be used to store the secret key and generate the codes. Please note that once TOTP is enabled, **you won't be able to retrieve it from the web UI**.
The following steps are needed to enable the TOTP feature from the web UI :
- Copy the secret key or use the QR code on your authenticator app
- Enter the current TOTP code in the 2FA input
- Enter your current password
!!! info "Secret key refresh"
A new secret key is **generated each time** you visit the page or submit the form. In case something went wrong (e.g. : expired TOTP code), you will need to copy the new secret key to your authenticator app until 2FA is successfuly enabled.
Once enabled, 2FA authentication can be disabled at the same place.
<figure markdown>
![Overview](assets/img/profile-totp.webp){ align=center, width="800" }
<figcaption>TOTP enable / disable forms</figcaption>
</figure>
After a successful login/password combination, you will be prompted to enter your TOTP code :
<figure markdown>
![Overview](assets/img/profile-2fa.webp){ align=center, width="400" }
<figcaption>Additional TOTP page</figcaption>
</figure>
## Advanced installation
=== "Docker"
@ -1642,48 +1698,3 @@ Review your final BunkerWeb UI URL and then click on the `Setup` button. Once th
```shell
systemctl restart bunkerweb
```
## Manage profile
You can manage some profile settings within the web UI. You do so by **accessing the profile page**.
You can change the username and password needed to login, and you can add double factor authentication.
### Username / Password
!!! warning "Recover profile"
In case you forgot your UI logs, you can [access them from the CLI following these steps](troubleshooting.md#recover-profile).
You can update your username or password by filling the dedicated forms (for security reason, you need to give your password even if you are connected).
When updating username or password, you'll be logout from UI and you'll need to login again.
<figure markdown>
![Overview](assets/img/profile-username-password.webp){ align=center, width="800" }
<figcaption>Username / Password forms</figcaption>
</figure>
### 2FA
!!! warning "Secret key loss"
In case you lost your secret key, you can [disable 2FA from the CLI following these steps](troubleshooting.md#lost-2fa-authentication).
You can power-up your login security by adding 2FA inside your account.
You need to store the secret key or scan code QR in a compatible auth manager (like Google Authenticator) and put the given code in the related input field when filling the form.
In case you enable TOTP, you'll be able to disable it in the same place.
<figure markdown>
![Overview](assets/img/profile-totp.webp){ align=center, width="800" }
<figcaption>TOTP enable / disabled forms</figcaption>
</figure>
When it's enable, you get an additionnal page to login.
<figure markdown>
![Overview](assets/img/profile-2fa.webp){ align=center, width="400" }
<figcaption>Additionnal TOTP page</figcaption>
</figure>

View file

@ -8,7 +8,7 @@
"BLACKLIST_COUNTRY": {
"context": "multisite",
"default": "",
"help": "Deny access if the country of the client is in the list (2 letters code).",
"help": "Deny access if the country of the client is in the list (ISO 3166-1 alpha-2 format separated with spaces).",
"id": "country-blacklist",
"label": "Country blacklist",
"regex": "^(?! )( *([A-Z]{2})(?!.*\\2) *)*$",
@ -17,7 +17,7 @@
"WHITELIST_COUNTRY": {
"context": "multisite",
"default": "",
"help": "Deny access if the country of the client is not in the list (2 letters code).",
"help": "Deny access if the country of the client is not in the list (ISO 3166-1 alpha-2 format separated with spaces).",
"id": "country-whitelist",
"label": "Country whitelist",
"regex": "^(?! )( *([A-Z]{2})(?!.*\\2) *)*$",

View file

@ -22,7 +22,7 @@
href="https://www.bunkerweb.io/?utm_campaign=self&utm_source=ui"
class="hover:italic hover:brightness-90 block sm:px-4 pt-1 pb-0 lg:pb-1 text-xs tracking-wide font-normal transition duration-300 ease-in-out text-white dark:text-white"
target="_blank"
>Bunkerweb</a
>BunkerWeb</a
>
</li>
<li class="nav-item">