| 1 |
import re |
| 2 |
from abc import ABC, abstractmethod |
| 3 |
from typing import Optional |
| 4 |
|
| 5 |
from django.urls import reverse |
| 6 |
from django.urls.exceptions import NoReverseMatch |
| 7 |
|
| 8 |
from axes.conf import settings |
| 9 |
from axes.helpers import ( |
| 10 |
get_failure_limit, |
| 11 |
is_client_ip_address_blacklisted, |
| 12 |
is_client_ip_address_whitelisted, |
| 13 |
is_client_method_whitelisted, |
| 14 |
is_user_attempt_whitelisted, |
| 15 |
) |
| 16 |
|
| 17 |
|
| 18 |
class AbstractAxesHandler(ABC): |
| 19 |
""" |
| 20 |
Contract that all handlers need to follow |
| 21 |
""" |
| 22 |
|
| 23 |
@abstractmethod |
| 24 |
def user_login_failed(self, sender, credentials: dict, request=None, **kwargs): |
| 25 |
""" |
| 26 |
Handles the Django ``django.contrib.auth.signals.user_login_failed`` authentication signal. |
| 27 |
""" |
| 28 |
raise NotImplementedError("user_login_failed should be implemented") |
| 29 |
|
| 30 |
@abstractmethod |
| 31 |
def user_logged_in(self, sender, request, user, **kwargs): |
| 32 |
""" |
| 33 |
Handles the Django ``django.contrib.auth.signals.user_logged_in`` authentication signal. |
| 34 |
""" |
| 35 |
raise NotImplementedError("user_logged_in should be implemented") |
| 36 |
|
| 37 |
@abstractmethod |
| 38 |
def user_logged_out(self, sender, request, user, **kwargs): |
| 39 |
""" |
| 40 |
Handles the Django ``django.contrib.auth.signals.user_logged_out`` authentication signal. |
| 41 |
""" |
| 42 |
raise NotImplementedError("user_logged_out should be implemented") |
| 43 |
|
| 44 |
@abstractmethod |
| 45 |
def get_failures(self, request, credentials: Optional[dict] = None) -> int: |
| 46 |
""" |
| 47 |
Checks the number of failures associated to the given request and credentials. |
| 48 |
|
| 49 |
This is a virtual method that needs an implementation in the handler subclass |
| 50 |
if the ``settings.AXES_LOCK_OUT_AT_FAILURE`` flag is set to ``True``. |
| 51 |
""" |
| 52 |
raise NotImplementedError("get_failures should be implemented") |
| 53 |
|
| 54 |
|
| 55 |
class AxesBaseHandler: # pylint: disable=unused-argument |
| 56 |
""" |
| 57 |
Handler API definition for implementations that are used by the ``AxesProxyHandler``. |
| 58 |
|
| 59 |
If you wish to specialize your own handler class, override the necessary methods |
| 60 |
and configure the class for use by setting ``settings.AXES_HANDLER = 'module.path.to.YourClass'``. |
| 61 |
Make sure that new the handler is compliant with AbstractAxesHandler and make sure it extends from this mixin. |
| 62 |
Refer to `AxesHandler` for an example. |
| 63 |
|
| 64 |
The default implementation that is actually used by Axes is ``axes.handlers.database.AxesDatabaseHandler``. |
| 65 |
|
| 66 |
.. note:: This is a virtual class and **can not be used without specialization**. |
| 67 |
""" |
| 68 |
|
| 69 |
def is_allowed(self, request, credentials: Optional[dict] = None) -> bool: |
| 70 |
""" |
| 71 |
Checks if the user is allowed to access or use given functionality such as a login view or authentication. |
| 72 |
|
| 73 |
This method is abstract and other backends can specialize it as needed, but the default implementation |
| 74 |
checks if the user has attempted to authenticate into the site too many times through the |
| 75 |
Django authentication backends and returns ``False`` if user exceeds the configured Axes thresholds. |
| 76 |
|
| 77 |
This checker can implement arbitrary checks such as IP whitelisting or blacklisting, |
| 78 |
request frequency checking, failed attempt monitoring or similar functions. |
| 79 |
|
| 80 |
Please refer to the ``axes.handlers.database.AxesDatabaseHandler`` for the default implementation |
| 81 |
and inspiration on some common checks and access restrictions before writing your own implementation. |
| 82 |
""" |
| 83 |
|
| 84 |
if self.is_admin_site(request): |
| 85 |
return True |
| 86 |
|
| 87 |
if self.is_blacklisted(request, credentials): |
| 88 |
return False |
| 89 |
|
| 90 |
if self.is_whitelisted(request, credentials): |
| 91 |
return True |
| 92 |
|
| 93 |
if self.is_locked(request, credentials): |
| 94 |
return False |
| 95 |
|
| 96 |
return True |
| 97 |
|
| 98 |
def is_blacklisted(self, request, credentials: Optional[dict] = None) -> bool: |
| 99 |
""" |
| 100 |
Checks if the request or given credentials are blacklisted from access. |
| 101 |
""" |
| 102 |
|
| 103 |
if is_client_ip_address_blacklisted(request): |
| 104 |
return True |
| 105 |
|
| 106 |
return False |
| 107 |
|
| 108 |
def is_whitelisted(self, request, credentials: Optional[dict] = None) -> bool: |
| 109 |
""" |
| 110 |
Checks if the request or given credentials are whitelisted for access. |
| 111 |
""" |
| 112 |
|
| 113 |
if is_user_attempt_whitelisted(request, credentials): |
| 114 |
return True |
| 115 |
|
| 116 |
if is_client_ip_address_whitelisted(request): |
| 117 |
return True |
| 118 |
|
| 119 |
if is_client_method_whitelisted(request): |
| 120 |
return True |
| 121 |
|
| 122 |
return False |
| 123 |
|
| 124 |
def is_locked(self, request, credentials: Optional[dict] = None) -> bool: |
| 125 |
""" |
| 126 |
Checks if the request or given credentials are locked. |
| 127 |
""" |
| 128 |
|
| 129 |
if settings.AXES_LOCK_OUT_AT_FAILURE: |
| 130 |
# get_failures will have to be implemented by each specialized handler |
| 131 |
return self.get_failures( # type: ignore |
| 132 |
request, credentials |
| 133 |
) >= get_failure_limit(request, credentials) |
| 134 |
|
| 135 |
return False |
| 136 |
|
| 137 |
def is_admin_site(self, request) -> bool: |
| 138 |
""" |
| 139 |
Checks if the request is for admin site. |
| 140 |
""" |
| 141 |
if settings.AXES_ONLY_ADMIN_SITE and hasattr(request, "path"): |
| 142 |
try: |
| 143 |
admin_url = reverse("admin:index") |
| 144 |
except NoReverseMatch: |
| 145 |
return True |
| 146 |
return not re.match(f"^{admin_url}", request.path) |
| 147 |
|
| 148 |
return False |
| 149 |
|
| 150 |
def reset_attempts( |
| 151 |
self, |
| 152 |
*, |
| 153 |
ip_address: Optional[str] = None, |
| 154 |
username: Optional[str] = None, |
| 155 |
ip_or_username: bool = False, |
| 156 |
) -> int: |
| 157 |
""" |
| 158 |
Resets access attempts that match the given IP address or username. |
| 159 |
|
| 160 |
This method makes more sense for the DB backend, but as it is used by the ProxyHandler |
| 161 |
(via inherent), it needs to be defined here, so we get compliant with all proxy methods. |
| 162 |
|
| 163 |
Please overwrite it on each specialized handler as needed. |
| 164 |
""" |
| 165 |
return 0 |
| 166 |
|
| 167 |
def reset_logs(self, *, age_days: Optional[int] = None) -> int: |
| 168 |
""" |
| 169 |
Resets access logs that are older than given number of days. |
| 170 |
|
| 171 |
This method makes more sense for the DB backend, but as it is used by the ProxyHandler |
| 172 |
(via inherent), it needs to be defined here, so we get compliant with all proxy methods. |
| 173 |
|
| 174 |
Please overwrite it on each specialized handler as needed. |
| 175 |
""" |
| 176 |
return 0 |
| 177 |
|
| 178 |
def reset_failure_logs(self, *, age_days: Optional[int] = None) -> int: |
| 179 |
""" |
| 180 |
Resets access failure logs that are older than given number of days. |
| 181 |
|
| 182 |
This method makes more sense for the DB backend, but as it is used by the ProxyHandler |
| 183 |
(via inherent), it needs to be defined here, so we get compliant with all proxy methods. |
| 184 |
|
| 185 |
Please overwrite it on each specialized handler as needed. |
| 186 |
""" |
| 187 |
return 0 |
| 188 |
|
| 189 |
def remove_out_of_limit_failure_logs( |
| 190 |
self, *, username: str, limit: Optional[int] = None |
| 191 |
) -> int: |
| 192 |
"""Remove access failure logs that are over |
| 193 |
AXES_ACCESS_FAILURE_LOG_PER_USER_LIMIT for user username. |
| 194 |
|
| 195 |
This method makes more sense for the DB backend, but as it is used by the ProxyHandler |
| 196 |
(via inherent), it needs to be defined here, so we get compliant with all proxy methods. |
| 197 |
|
| 198 |
Please overwrite it on each specialized handler as needed. |
| 199 |
|
| 200 |
""" |
| 201 |
return 0 |
| 202 |
|
| 203 |
|
| 204 |
class AxesHandler(AbstractAxesHandler, AxesBaseHandler): |
| 205 |
""" |
| 206 |
Signal bare handler implementation without any storage backend. |
| 207 |
""" |
| 208 |
|
| 209 |
def user_login_failed(self, sender, credentials: dict, request=None, **kwargs): |
| 210 |
pass |
| 211 |
|
| 212 |
def user_logged_in(self, sender, request, user, **kwargs): |
| 213 |
pass |
| 214 |
|
| 215 |
def user_logged_out(self, sender, request, user, **kwargs): |
| 216 |
pass |
| 217 |
|
| 218 |
def get_failures(self, request, credentials: Optional[dict] = None) -> int: |
| 219 |
return 0 |