From 9d1caaaf3fa87be0724f5044782839c895695292 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20NOBILI?= Date: Fri, 31 May 2024 10:49:46 +0200 Subject: [PATCH] doc: describe how brute-force plugin works --- doc/sources/admin/bruteforceprotection.rst | 37 +++++++++++++++++----- 1 file changed, 29 insertions(+), 8 deletions(-) diff --git a/doc/sources/admin/bruteforceprotection.rst b/doc/sources/admin/bruteforceprotection.rst index 82305d363f..0a69122c71 100644 --- a/doc/sources/admin/bruteforceprotection.rst +++ b/doc/sources/admin/bruteforceprotection.rst @@ -29,13 +29,13 @@ set to ``On``. - **Parameters**: - - **Activation**: Enable/disable brute force attack protection - - **Lock time**: Waiting time before another login attempt - - **Allowed failed login**: Number of failed login attempts allowed before account is locked - - **Incremental lock**: Enable/disable incremental lock times - - **Incremental lock times**: List of comma separated lock time values in seconds - - **Maximum lock time**: Lock time values can not be higher than max lock time - - **Maximum age**: Delta between current and last stored failed login + - **Activation**: Enable/disable brute force attack protection (``bruteForceProtection`` in config. file) + - **Lock time**: Waiting time before another login attempt (``bruteForceProtectionTempo`` in config. file) + - **Allowed failed login**: Number of failed login attempts allowed before account is locked (``bruteForceProtectionMaxFailed`` in config. file) + - **Incremental lock**: Enable/disable incremental lock times (``bruteForceProtectionIncrementalTempo`` in config. file) + - **Incremental lock times**: List of comma separated lock time values in seconds (``bruteForceProtectionLockTimes`` in config. file) + - **Maximum lock time**: Lock time values can not be higher than max lock time (``bruteForceProtectionMaxLockTime`` in config. file) + - **Maximum age**: Delta between current and last stored failed login (``bruteForceProtectionMaxAge`` in config. file) Incremental lock time enabled @@ -85,4 +85,25 @@ the lock time before trying to log in again. .. danger:: Number of failed login attempts stored in history MUST be higher than allowed failed logins for this plugin takes effect. - See :doc:`History plugin` \ No newline at end of file + See :doc:`History plugin` + +How locking works +~~~~~~~~~~~~~~~~~ + +When incremental lock time is disabled +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The plugin considers the number of failed logins in ``bruteForceProtectionMaxAge`` time span. + +If this number is higher than ``bruteForceProtectionMaxFailed``, then the account is locked for ``bruteForceProtectionTempo`` seconds. + +When incremental lock time is enabled +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The plugin considers the number of failed logins in ``bruteForceProtectionMaxAge`` time span. + +The account lock time is taken from the ``bruteForceProtectionLockTimes`` array of values. Every failed login attempt in the considered period +will increase the index used to get the lock time value inside the array. + +If the failed login attempt arises after the account lock time, then a new failure is recorded in journal unless +``bruteForceProtectionMaxLockTime`` is reached. This failure will be taken into account for next lock time selection. -- GitLab