Merge pull request #2359 from paperless-ngx/feature-log-failed-auth

Feature: Log failed login attempts

Pipfile

@@ -16,6 +16,7 @@ django-compression-middleware = "*"
 django-extensions = "*"
 django-filter = "~=22.1"
 djangorestframework = "~=3.14"
+django-ipware = "*"
 filelock = "*"
 gunicorn = "*"
 imap-tools = "*"
@@ -69,6 +70,7 @@ djangorestframework-guardian = "*"
 channels-redis = "==3.4.1"
 
 
+
 [dev-packages]
 coveralls = "*"
 factory-boy = "*"

Pipfile.lock

@@ -1,7 +1,7 @@
 {
     "_meta": {
         "hash": {
-            "sha256": "99f415c5ce96020dc3fcb137dc15d47cc5431686bdce1ca42e6254a2719060a8"
+            "sha256": "0e1a26c5e9acb1d745f951f92d00d60272f83406467d90551e558972697b53cd"
         },
         "pipfile-spec": 6,
         "requires": {},
@@ -480,6 +480,14 @@
             "index": "pypi",
             "version": "==2.4.0"
         },
+        "django-ipware": {
+            "hashes": [
+                "sha256:602a58325a4808bd19197fef2676a0b2da2df40d0ecf21be414b2ff48c72ad05",
+                "sha256:878dbb06a87e25550798e9ef3204ed70a200dd8b15e47dcef848cf08244f04c9"
+            ],
+            "index": "pypi",
+            "version": "==4.0.2"
+        },
         "djangorestframework": {
             "hashes": [
                 "sha256:579a333e6256b09489cbe0a067e66abe55c6595d8926be6b99423786334350c8",

docs/configuration.md

@@ -262,6 +262,14 @@ do CORS calls. Set this to your public domain name.
 
     Defaults to "<http://localhost:8000>".
 
+`PAPERLESS_TRUSTED_PROXIES=<comma-separated-list>`
+
+: This may be needed to prevent IP address spoofing if you are using e.g.
+fail2ban with log entries for failed authorization attempts. Value should be
+IP address(es).
+
+    Defaults to empty string.
+
 `PAPERLESS_FORCE_SCRIPT_NAME=<path>`
 
 : To host paperless under a subpath url like example.com/paperless you

src/paperless/apps.py

@@ -0,0 +1,15 @@
+from django.apps import AppConfig
+from django.utils.translation import gettext_lazy as _
+from paperless.signals import handle_failed_login
+
+
+class PaperlessConfig(AppConfig):
+    name = "paperless"
+
+    verbose_name = _("Paperless")
+
+    def ready(self):
+        from django.contrib.auth.signals import user_login_failed
+
+        user_login_failed.connect(handle_failed_login)
+        AppConfig.ready(self)

src/paperless/settings.py

@@ -416,6 +416,13 @@ if _paperless_url:
         # always allow localhost. Necessary e.g. for healthcheck in docker.
         ALLOWED_HOSTS = [_paperless_uri.hostname] + ["localhost"]
 
+# For use with trusted proxies
+_trusted_proxies = os.getenv("PAPERLESS_TRUSTED_PROXIES")
+if _trusted_proxies:
+    TRUSTED_PROXIES = _trusted_proxies.split(",")
+else:
+    TRUSTED_PROXIES = []
+
 # The secret key has a default that should be fine so long as you're hosting
 # Paperless on a closed network.  However, if you're putting this anywhere
 # public, you should change the key to something unique and verbose.

src/paperless/signals.py

@@ -0,0 +1,32 @@
+import logging
+
+from django.conf import settings
+from ipware import get_client_ip
+
+logger = logging.getLogger("paperless.auth")
+
+
+# https://docs.djangoproject.com/en/4.1/ref/contrib/auth/#django.contrib.auth.signals.user_login_failed
+def handle_failed_login(sender, credentials, request, **kwargs):
+    client_ip, is_routable = get_client_ip(
+        request,
+        proxy_trusted_ips=settings.TRUSTED_PROXIES,
+    )
+    if client_ip is None:
+        logger.info(
+            f"Login failed for user `{credentials['username']}`."
+            + " Unable to determine IP address.",
+        )
+    else:
+        if is_routable:
+            # We got the client's IP address
+            logger.info(
+                f"Login failed for user `{credentials['username']}`"
+                + f" from IP `{client_ip}.`",
+            )
+        else:
+            # The client's IP address is private
+            logger.info(
+                f"Login failed for user `{credentials['username']}`"
+                + f" from private IP `{client_ip}.`",
+            )

src/paperless/tests/test_signals.py

@@ -0,0 +1,80 @@
+from django.http import HttpRequest
+from django.test import TestCase
+from paperless.signals import handle_failed_login
+
+
+class TestFailedLoginLogging(TestCase):
+    def setUp(self):
+        super().setUp()
+
+        self.creds = {
+            "username": "john lennon",
+        }
+
+    def test_none(self):
+        """
+        GIVEN:
+            - Request with no IP possible
+        WHEN:
+            - Request provided to signal handler
+        THEN:
+            - Unable to determine logged
+        """
+        request = HttpRequest()
+        request.META = {}
+        with self.assertLogs("paperless.auth") as logs:
+            handle_failed_login(None, self.creds, request)
+
+            self.assertEqual(
+                logs.output,
+                [
+                    "INFO:paperless.auth:Login failed for user `john lennon`. Unable to determine IP address.",
+                ],
+            )
+
+    def test_public(self):
+        """
+        GIVEN:
+            - Request with publicly routeable IP
+        WHEN:
+            - Request provided to signal handler
+        THEN:
+            - Expected IP is logged
+        """
+        request = HttpRequest()
+        request.META = {
+            "HTTP_X_FORWARDED_FOR": "177.139.233.139",
+        }
+        with self.assertLogs("paperless.auth") as logs:
+            handle_failed_login(None, self.creds, request)
+
+            self.assertEqual(
+                logs.output,
+                [
+                    "INFO:paperless.auth:Login failed for user `john lennon` from IP `177.139.233.139.`",
+                ],
+            )
+
+    def test_private(self):
+        """
+        GIVEN:
+            - Request with private range IP
+        WHEN:
+            - Request provided to signal handler
+        THEN:
+            - Expected IP is logged
+            - IP is noted to be a private IP
+        """
+        request = HttpRequest()
+        request.META = {
+            "HTTP_X_FORWARDED_FOR": "10.0.0.1",
+        }
+        with self.assertLogs("paperless.auth") as logs:
+            handle_failed_login(None, self.creds, request)
+
+            self.assertEqual(
+                logs.output,
+                [
+                    "INFO:paperless.auth:Login failed for user `john lennon` from private IP `10.0.0.1.`",
+                ],
+            )