Debian Codegraph @

axes/handlers/base.py

raw
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