def is_user_attempt_whitelisted(request: AxesHttpRequest, credentials: dict = None) -> bool:
"""
Check if the given request or credentials refer to a whitelisted username.
A whitelisted user has the magic ``nolockout`` property set.
If the property is unknown or False or the user can not be found,
this implementation fails gracefully and returns True.
"""
username_field = getattr(get_user_model(), 'USERNAME_FIELD', 'username')
username_value = get_client_username(request, credentials)
kwargs = {
username_field: username_value
}
user_model = get_user_model()
try:
user = user_model.objects.get(**kwargs)
return user.nolockout
except (user_model.DoesNotExist, AttributeError):
pass
return False
def generate_axes_lockout_response(request, credentials):
enqueue(
"authentication.tasks:force_password_reset", get_client_username(request, credentials)
)
error_message = (
f"Too many failed login attempts, check your email to choose a new password."
)
return make_response(data={api_settings.NON_FIELD_ERRORS_KEY: error_message}, status=403)
def user_login_failed(
self,
sender,
credentials: dict,
request: AxesHttpRequest = None,
**kwargs
): # pylint: disable=too-many-locals
"""
When user login fails, save attempt record in cache and lock user out if necessary.
:raises AxesSignalPermissionDenied: if user should be locked out.
"""
if request is None:
log.error('AXES: AxesCacheHandler.user_login_failed does not function without a request.')
return
if not hasattr(request, 'axes_attempt_time'):
log.error('AXES: AxesCacheHandler.user_login_failed needs a valid AxesHttpRequest object.')
return
username = get_client_username(request, credentials)
client_str = get_client_str(username, request.axes_ip_address, request.axes_user_agent, request.axes_path_info)
if self.is_whitelisted(request, credentials):
log.info('AXES: Login failed from whitelisted client %s.', client_str)
return
failures_since_start = 1 + self.get_failures(request, credentials)
if failures_since_start > 1:
log.warning(
'AXES: Repeated login failure by %s. Count = %d of %d. Updating existing record in the cache.',
client_str,
failures_since_start,
settings.AXES_FAILURE_LIMIT,
)
else:
log.warning(
'AXES: New login failure by %s. Creating new record in the cache.',
client_str,
)
cache_key = get_client_cache_key(request, credentials)
self.cache.set(cache_key, failures_since_start, self.cache_timeout)
if failures_since_start >= settings.AXES_FAILURE_LIMIT:
log.warning('AXES: Locking out %s after repeated login failures.', client_str)
user_locked_out.send(
'axes',
request=request,
username=username,
ip_address=request.axes_ip_address,
)
raise AxesSignalPermissionDenied('Locked out due to repeated login failures.')
def test_default_get_client_username(self):
expected = "test-username"
request = HttpRequest()
request.POST["username"] = expected
actual = get_client_username(request)
self.assertEqual(expected, actual)
def test_default_get_client_username(self):
expected = 'test-username'
request = AxesHttpRequest()
request.POST['username'] = expected
actual = get_client_username(request)
self.assertEqual(expected, actual)
def test_default_get_client_username(self):
expected = 'test-username'
request = AxesHttpRequest()
request.POST['username'] = expected
actual = get_client_username(request)
self.assertEqual(expected, actual)
def user_login_failed(self, sender, credentials, request=None, **kwargs): # pylint: disable=too-many-locals
"""
When user login fails, save attempt record in cache and lock user out if necessary.
:raises AxesSignalPermissionDenied: if user should be locked out.
"""
if request is None:
log.error(
'AXES: AxesCacheHandler.user_login_failed does not function without a request.'
)
return
username = get_client_username(request, credentials)
ip_address = get_client_ip_address(request)
user_agent = get_client_user_agent(request)
path_info = get_client_path_info(request)
client_str = get_client_str(username, ip_address, user_agent,
path_info)
if self.is_whitelisted(request, credentials):
log.info('AXES: Login failed from whitelisted client %s.',
client_str)
return
failures_since_start = 1 + self.get_failures(request, credentials)
if failures_since_start > 1:
log.warning(
'AXES: Repeated login failure by %s. Count = %d of %d. Updating existing record in the cache.',
client_str,
failures_since_start,
settings.AXES_FAILURE_LIMIT,
)
else:
log.warning(
'AXES: New login failure by %s. Creating new record in the cache.',
client_str,
)
cache_key = get_client_cache_key(request, credentials)
self.cache.set(cache_key, failures_since_start, self.cache_timeout)
if failures_since_start >= settings.AXES_FAILURE_LIMIT:
log.warning('AXES: Locking out %s after repeated login failures.',
client_str)
user_locked_out.send(
'axes',
request=request,
username=username,
ip_address=ip_address,
)
raise AxesSignalPermissionDenied(
'Locked out due to repeated login failures.')
def filter_user_attempts(request: AxesHttpRequest, credentials: dict = None) -> QuerySet:
"""
Return a queryset of AccessAttempts that match the given request and credentials.
"""
username = get_client_username(request, credentials)
filter_kwargs = get_client_parameters(username, request.axes_ip_address, request.axes_user_agent)
return AccessAttempt.objects.filter(**filter_kwargs)
def test_default_get_client_username_credentials(self):
expected = "test-username"
expected_in_credentials = "test-credentials-username"
request = HttpRequest()
request.POST["username"] = expected
credentials = {"username": expected_in_credentials}
actual = get_client_username(request, credentials)
self.assertEqual(expected_in_credentials, actual)
def filter_user_attempts(request, credentials: dict = None) -> QuerySet:
"""
Return a queryset of AccessAttempts that match the given request and credentials.
"""
username = get_client_username(request, credentials)
filter_kwargs = get_client_parameters(username, request.axes_ip_address,
request.axes_user_agent)
return AccessAttempt.objects.filter(**filter_kwargs)
def test_default_get_client_username_credentials(self):
expected = 'test-username'
expected_in_credentials = 'test-credentials-username'
request = HttpRequest()
request.POST['username'] = expected
credentials = {'username': expected_in_credentials}
actual = get_client_username(request, credentials)
self.assertEqual(expected_in_credentials, actual)
def test_custom_get_client_username_from_credentials(self):
provided = "test-username"
provided_in_credentials = "test-credentials-username"
expected_in_credentials = "prefixed-" + provided_in_credentials
request = HttpRequest()
request.POST["username"] = provided
credentials = {"username": provided_in_credentials}
actual = get_client_username(request, credentials)
self.assertEqual(expected_in_credentials, actual)
def test_custom_get_client_username_from_credentials(self):
provided = 'test-username'
provided_in_credentials = 'test-credentials-username'
expected_in_credentials = 'prefixed-' + provided_in_credentials
request = AxesHttpRequest()
request.POST['username'] = provided
credentials = {'username': provided_in_credentials}
actual = get_client_username(request, credentials)
self.assertEqual(expected_in_credentials, actual)
def test_custom_get_client_username_from_credentials(self):
provided = 'test-username'
provided_in_credentials = 'test-credentials-username'
expected_in_credentials = 'prefixed-' + provided_in_credentials
request = HttpRequest()
request.POST['username'] = provided
credentials = {'username': provided_in_credentials}
actual = get_client_username(request, credentials)
self.assertEqual(expected_in_credentials, actual)
def test_default_get_client_username_drf(self):
class DRFRequest:
def __init__(self):
self.data = {}
expected = "test-username"
request = DRFRequest()
request.data["username"] = expected
actual = get_client_username(request)
self.assertEqual(expected, actual)
def test_default_get_client_username_credentials(self):
expected = 'test-username'
expected_in_credentials = 'test-credentials-username'
request = AxesHttpRequest()
request.POST['username'] = expected
credentials = {
'username': expected_in_credentials
}
actual = get_client_username(request, credentials)
self.assertEqual(expected_in_credentials, actual)
def filter_user_attempts(request, credentials: dict = None) -> List[QuerySet]:
"""
Return a list querysets of AccessAttempts that match the given request and credentials.
"""
username = get_client_username(request, credentials)
filter_kwargs_list = get_client_parameters(username,
request.axes_ip_address,
request.axes_user_agent)
attempts_list = [
AccessAttempt.objects.filter(**filter_kwargs)
for filter_kwargs in filter_kwargs_list
]
return attempts_list
def __call__(self, request):
response = self.get_response(request)
if "rest_framework" in settings.INSTALLED_APPS:
AxesProxyHandler.update_request(request)
username = get_client_username(request)
credentials = get_credentials(username)
failures_since_start = AxesProxyHandler.get_failures(
request, credentials)
if (settings.AXES_LOCK_OUT_AT_FAILURE
and failures_since_start >= get_failure_limit(
request, credentials)):
request.axes_locked_out = True
if getattr(request, "axes_locked_out", None):
response = get_lockout_response(request) # type: ignore
return response
def is_user_attempt_whitelisted(request, credentials: dict = None) -> bool:
"""
Check if the given request or credentials refer to a whitelisted username.
A whitelisted user has the magic ``nolockout`` property set.
If the property is unknown or False or the user can not be found,
this implementation fails gracefully and returns True.
"""
username_field = getattr(get_user_model(), 'USERNAME_FIELD', 'username')
username_value = get_client_username(request, credentials)
kwargs = {username_field: username_value}
user_model = get_user_model()
try:
user = user_model.objects.get(**kwargs)
return user.nolockout
except (user_model.DoesNotExist, AttributeError):
pass
return False
def test_get_client_username_str(self):
self.assertEqual(
get_client_username(AxesHttpRequest(), {}),
'username',
)
def user_login_failed(self,
sender,
credentials: dict,
request=None,
**kwargs): # pylint: disable=too-many-locals
"""
When user login fails, save AccessAttempt record in database, mark request with lockout attribute and emit lockout signal.
"""
log.info(
"AXES: User login failed, running database handler for failure.")
if request is None:
log.error(
"AXES: AxesDatabaseHandler.user_login_failed does not function without a request."
)
return
# 1. database query: Clean up expired user attempts from the database before logging new attempts
clean_expired_user_attempts(request.axes_attempt_time)
username = get_client_username(request, credentials)
client_str = get_client_str(
username,
request.axes_ip_address,
request.axes_user_agent,
request.axes_path_info,
request,
)
# This replaces null byte chars that crash saving failures.
get_data = get_query_str(request.GET).replace("\0", "0x00")
post_data = get_query_str(request.POST).replace("\0", "0x00")
if self.is_whitelisted(request, credentials):
log.info("AXES: Login failed from whitelisted client %s.",
client_str)
return
# 2. database query: Get or create access record with the new failure data
if settings.AXES_ONLY_USER_FAILURES and username is None:
log.warning(
"AXES: Username is None and AXES_ONLY_USER_FAILURES is enabled, new record will NOT be created."
)
else:
with transaction.atomic():
(
attempt,
created,
) = AccessAttempt.objects.select_for_update().get_or_create(
username=username,
ip_address=request.axes_ip_address,
user_agent=request.axes_user_agent,
defaults={
"get_data": get_data,
"post_data": post_data,
"http_accept": request.axes_http_accept,
"path_info": request.axes_path_info,
"failures_since_start": 1,
"attempt_time": request.axes_attempt_time,
},
)
# Record failed attempt with all the relevant information.
# Filtering based on username, IP address and user agent handled elsewhere,
# and this handler just records the available information for further use.
if created:
log.warning(
"AXES: New login failure by %s. Created new record in the database.",
client_str,
)
# 3. database query if there were previous attempts in the database
# Update failed attempt information but do not touch the username, IP address, or user agent fields,
# because attackers can request the site with multiple different configurations
# in order to bypass the defense mechanisms that are used by the site.
else:
separator = "\n---------\n"
attempt.get_data = Concat("get_data",
Value(separator + get_data))
attempt.post_data = Concat("post_data",
Value(separator + post_data))
attempt.http_accept = request.axes_http_accept
attempt.path_info = request.axes_path_info
attempt.failures_since_start = F(
"failures_since_start") + 1
attempt.attempt_time = request.axes_attempt_time
attempt.save()
log.warning(
"AXES: Repeated login failure by %s. Updated existing record in the database.",
client_str,
)
# 3. or 4. database query: Calculate the current maximum failure number from the existing attempts
failures_since_start = self.get_failures(request, credentials)
request.axes_failures_since_start = failures_since_start
if (settings.AXES_LOCK_OUT_AT_FAILURE
and failures_since_start >= get_failure_limit(
request, credentials)):
log.warning("AXES: Locking out %s after repeated login failures.",
client_str)
request.axes_locked_out = True
user_locked_out.send(
"axes",
request=request,
username=username,
ip_address=request.axes_ip_address,
)
def test_get_client_username(self):
self.assertEqual(get_client_username(AxesHttpRequest(), {}), 'example')
def test_get_client_username_str(self):
self.assertEqual(get_client_username(HttpRequest(), {}), "username")
def test_get_client_username_not_callable(self):
with self.assertRaises(TypeError):
get_client_username(HttpRequest(), {})
def test_get_client_username_invalid_callable_too_many_arguments(self):
with self.assertRaises(TypeError):
get_client_username(HttpRequest(), {})
def test_get_client_username(self):
self.assertEqual(get_client_username(HttpRequest(), {}), "example")
def test_get_client_username_invalid_callable_too_many_arguments(self):
with self.assertRaises(TypeError):
get_client_username(AxesHttpRequest(), {})
def test_get_client_username_not_callable(self):
with self.assertRaises(TypeError):
get_client_username(AxesHttpRequest(), {})
def test_get_client_username_str(self):
self.assertEqual(
get_client_username(AxesHttpRequest(), {}),
'username',
)
def user_login_failed(self, sender, credentials, request=None, **kwargs): # pylint: disable=too-many-locals
"""
When user login fails, save AccessAttempt record in database and lock user out if necessary.
:raises AxesSignalPermissionDenied: if user should be locked out.
"""
attempt_time = now()
# 1. database query: Clean up expired user attempts from the database before logging new attempts
clean_expired_user_attempts(attempt_time)
if request is None:
log.error(
'AXES: AxesDatabaseHandler.user_login_failed does not function without a request.'
)
return
username = get_client_username(request, credentials)
ip_address = get_client_ip_address(request)
user_agent = get_client_user_agent(request)
path_info = get_client_path_info(request)
http_accept = get_client_http_accept(request)
client_str = get_client_str(username, ip_address, user_agent,
path_info)
get_data = get_query_str(request.GET)
post_data = get_query_str(request.POST)
if self.is_whitelisted(request, credentials):
log.info('AXES: Login failed from whitelisted client %s.',
client_str)
return
# 2. database query: Calculate the current maximum failure number from the existing attempts
failures_since_start = 1 + self.get_failures(request, credentials,
attempt_time)
# 3. database query: Insert or update access records with the new failure data
if failures_since_start > 1:
# Update failed attempt information but do not touch the username, IP address, or user agent fields,
# because attackers can request the site with multiple different configurations
# in order to bypass the defense mechanisms that are used by the site.
log.warning(
'AXES: Repeated login failure by %s. Count = %d of %d. Updating existing record in the database.',
client_str,
failures_since_start,
settings.AXES_FAILURE_LIMIT,
)
separator = '\n---------\n'
attempts = get_user_attempts(request, credentials, attempt_time)
attempts.update(
get_data=Concat('get_data', Value(separator + get_data)),
post_data=Concat('post_data', Value(separator + post_data)),
http_accept=http_accept,
path_info=path_info,
failures_since_start=failures_since_start,
attempt_time=attempt_time,
)
else:
# Record failed attempt with all the relevant information.
# Filtering based on username, IP address and user agent handled elsewhere,
# and this handler just records the available information for further use.
log.warning(
'AXES: New login failure by %s. Creating new record in the database.',
client_str,
)
AccessAttempt.objects.create(
username=username,
ip_address=ip_address,
user_agent=user_agent,
get_data=get_data,
post_data=post_data,
http_accept=http_accept,
path_info=path_info,
failures_since_start=failures_since_start,
attempt_time=attempt_time,
)
if failures_since_start >= settings.AXES_FAILURE_LIMIT:
log.warning('AXES: Locking out %s after repeated login failures.',
client_str)
user_locked_out.send(
'axes',
request=request,
username=username,
ip_address=ip_address,
)
raise AxesSignalPermissionDenied(
'Locked out due to repeated login failures.')
def test_get_client_username(self):
self.assertEqual(get_client_username(AxesHttpRequest(), {}), 'example')
def user_login_failed(self,
sender,
credentials: dict,
request=None,
**kwargs): # pylint: disable=too-many-locals
"""
When user login fails, save attempt record in cache and lock user out if necessary.
:raises AxesSignalPermissionDenied: if user should be locked out.
"""
if request is None:
log.error(
"AXES: AxesCacheHandler.user_login_failed does not function without a request."
)
return
username = get_client_username(request, credentials)
if settings.AXES_ONLY_USER_FAILURES and username is None:
log.warning(
"AXES: Username is None and AXES_ONLY_USER_FAILURES is enabled, new record will NOT be created."
)
return
client_str = get_client_str(
username,
request.axes_ip_address,
request.axes_user_agent,
request.axes_path_info,
request,
)
if self.is_whitelisted(request, credentials):
log.info("AXES: Login failed from whitelisted client %s.",
client_str)
return
failures_since_start = 1 + self.get_failures(request, credentials)
request.axes_failures_since_start = failures_since_start
if failures_since_start > 1:
log.warning(
"AXES: Repeated login failure by %s. Count = %d of %d. Updating existing record in the cache.",
client_str,
failures_since_start,
get_failure_limit(request, credentials),
)
else:
log.warning(
"AXES: New login failure by %s. Creating new record in the cache.",
client_str,
)
cache_keys = get_client_cache_key(request, credentials)
for cache_key in cache_keys:
failures = self.cache.get(cache_key, default=0)
self.cache.set(cache_key, failures + 1, self.cache_timeout)
if (settings.AXES_LOCK_OUT_AT_FAILURE
and failures_since_start >= get_failure_limit(
request, credentials)):
log.warning("AXES: Locking out %s after repeated login failures.",
client_str)
request.axes_locked_out = True
user_locked_out.send(
"axes",
request=request,
username=username,
ip_address=request.axes_ip_address,
)
def user_login_failed(self,
sender,
credentials: dict,
request=None,
**kwargs): # pylint: disable=too-many-locals
"""
When user login fails, save AccessAttempt record in database and lock user out if necessary.
:raises AxesSignalPermissionDenied: if user should be locked out.
"""
if request is None:
log.error(
"AXES: AxesDatabaseHandler.user_login_failed does not function without a request."
)
return
# 1. database query: Clean up expired user attempts from the database before logging new attempts
clean_expired_user_attempts(request.axes_attempt_time)
username = get_client_username(request, credentials)
client_str = get_client_str(
username,
request.axes_ip_address,
request.axes_user_agent,
request.axes_path_info,
)
# This replaces null byte chars that crash saving failures, meaning an attacker doesn't get locked out.
get_data = get_query_str(request.GET).replace("\0", "0x00")
post_data = get_query_str(request.POST).replace("\0", "0x00")
if self.is_whitelisted(request, credentials):
log.info("AXES: Login failed from whitelisted client %s.",
client_str)
return
# 2. database query: Calculate the current maximum failure number from the existing attempts
failures_since_start = 1 + self.get_failures(request, credentials)
# 3. database query: Insert or update access records with the new failure data
try:
attempt = AccessAttempt.objects.get(
username=username,
ip_address=request.axes_ip_address,
user_agent=request.axes_user_agent,
)
# Update failed attempt information but do not touch the username, IP address, or user agent fields,
# because attackers can request the site with multiple different configurations
# in order to bypass the defense mechanisms that are used by the site.
log.warning(
"AXES: Repeated login failure by %s. Count = %d of %d. Updating existing record in the database.",
client_str,
attempt.failures_since_start,
get_failure_limit(request, credentials),
)
separator = "\n---------\n"
attempt.get_data = Concat("get_data", Value(separator + get_data))
attempt.post_data = Concat("post_data",
Value(separator + post_data))
attempt.http_accept = request.axes_http_accept
attempt.path_info = request.axes_path_info
attempt.failures_since_start += 1
attempt.attempt_time = request.axes_attempt_time
attempt.save()
except AccessAttempt.DoesNotExist:
# Record failed attempt with all the relevant information.
# Filtering based on username, IP address and user agent handled elsewhere,
# and this handler just records the available information for further use.
if not (settings.AXES_ONLY_USER_FAILURES and username is None):
log.warning(
"AXES: New login failure by %s. Creating new record in the database.",
client_str,
)
AccessAttempt.objects.create(
username=username,
ip_address=request.axes_ip_address,
user_agent=request.axes_user_agent,
get_data=get_data,
post_data=post_data,
http_accept=request.axes_http_accept,
path_info=request.axes_path_info,
failures_since_start=1,
attempt_time=request.axes_attempt_time,
)
else:
log.warning(
"AXES: Username is None and AXES_ONLY_USER_FAILURES is enable, New record won't be created."
)
if (settings.AXES_LOCK_OUT_AT_FAILURE
and failures_since_start >= get_failure_limit(
request, credentials)):
log.warning("AXES: Locking out %s after repeated login failures.",
client_str)
request.axes_locked_out = True
user_locked_out.send(
"axes",
request=request,
username=username,
ip_address=request.axes_ip_address,
)
def user_login_failed(
self,
sender,
credentials: dict,
request: AxesHttpRequest = None,
**kwargs
): # pylint: disable=too-many-locals
"""
When user login fails, save AccessAttempt record in database and lock user out if necessary.
:raises AxesSignalPermissionDenied: if user should be locked out.
"""
if request is None:
log.error('AXES: AxesDatabaseHandler.user_login_failed does not function without a request.')
return
if not hasattr(request, 'axes_attempt_time'):
log.error('AXES: AxesDatabaseHandler.user_login_failed needs a valid AxesHttpRequest object.')
return
# 1. database query: Clean up expired user attempts from the database before logging new attempts
clean_expired_user_attempts(request.axes_attempt_time)
username = get_client_username(request, credentials)
client_str = get_client_str(username, request.axes_ip_address, request.axes_user_agent, request.axes_path_info)
get_data = get_query_str(request.GET)
post_data = get_query_str(request.POST)
if self.is_whitelisted(request, credentials):
log.info('AXES: Login failed from whitelisted client %s.', client_str)
return
# 2. database query: Calculate the current maximum failure number from the existing attempts
failures_since_start = 1 + self.get_failures(request, credentials)
# 3. database query: Insert or update access records with the new failure data
if failures_since_start > 1:
# Update failed attempt information but do not touch the username, IP address, or user agent fields,
# because attackers can request the site with multiple different configurations
# in order to bypass the defense mechanisms that are used by the site.
log.warning(
'AXES: Repeated login failure by %s. Count = %d of %d. Updating existing record in the database.',
client_str,
failures_since_start,
settings.AXES_FAILURE_LIMIT,
)
separator = '\n---------\n'
attempts = get_user_attempts(request, credentials)
attempts.update(
get_data=Concat('get_data', Value(separator + get_data)),
post_data=Concat('post_data', Value(separator + post_data)),
http_accept=request.axes_http_accept,
path_info=request.axes_path_info,
failures_since_start=failures_since_start,
attempt_time=request.axes_attempt_time,
)
else:
# Record failed attempt with all the relevant information.
# Filtering based on username, IP address and user agent handled elsewhere,
# and this handler just records the available information for further use.
log.warning(
'AXES: New login failure by %s. Creating new record in the database.',
client_str,
)
AccessAttempt.objects.create(
username=username,
ip_address=request.axes_ip_address,
user_agent=request.axes_user_agent,
get_data=get_data,
post_data=post_data,
http_accept=request.axes_http_accept,
path_info=request.axes_path_info,
failures_since_start=failures_since_start,
attempt_time=request.axes_attempt_time,
)
if failures_since_start >= settings.AXES_FAILURE_LIMIT:
log.warning('AXES: Locking out %s after repeated login failures.', client_str)
user_locked_out.send(
'axes',
request=request,
username=username,
ip_address=request.axes_ip_address,
)
raise AxesSignalPermissionDenied('Locked out due to repeated login failures.')
