djcheckup 0.1.0__tar.gz

djcheckup-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.3
+Name: djcheckup
+Version: 0.1.0
+Summary: DJ Checkup is a security scanner for Django sites.
+Author: Stuart Maxwell
+Author-email: Stuart Maxwell <stuart@amanzi.nz>
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: rich>=14.1.0
+Requires-Dist: typer>=0.17.4
+Requires-Python: >=3.13
+Project-URL: Homepage, https://github.com/stuartmaxwell/djcheckup
+Project-URL: Repository, https://github.com/stuartmaxwell/djcheckup
+Description-Content-Type: text/markdown
+
+# DJ Checkup
+
+## Overview
+
+DJ Checkup is a security scanner for Django sites. This package provides a command-line interface to run the security
+checks against your Django site. These are the same checks that are used by the DJ Checkup website at
+<https://djcheckup.com>.
+
+## Installation
+
+This works best when installed with `uv tool` or `pipx`.
+
+```bash
+# With uv:
+uv tool install djcheckup
+
+# Or with pipx:
+pipx install djcheckup
+```
+
+You can also run the tool without installing it:
+
+```bash
+# With uvx:
+uvx djcheckup https://yourdjangosite.com
+```
+
+## Usage
+
+Run the `djcheckup` command-line utility with the URL of your Django site.
+
+You'll see a nicely formatted report in your terminal:
+
+```text
+╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│                                     DJ Checkup Results for https://djcheckup.com                                     │
+│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
+│ ┃ Check                                            ┃ Result     ┃ Message                                          ┃ │
+│ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │
+│ │ Can I connect to your site?                      │ 🟢 Success │ Connected to your site successfully.             │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is your Django admin site exposed at the default │ 🟢 Success │ Your Django admin site is not exposed at the     │ │
+│ │ URL?                                             │            │ default URL. This reduces the risk of automated  │ │
+│ │                                                  │            │ attacks.                                         │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is a CSRF cookie set?                            │ 🟢 Success │ CSRF cookie detected. Your site is protected     │ │
+│ │                                                  │            │ against cross-site request forgery attacks.      │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the CSRF cookie HttpOnly?                     │ 🟢 Success │ Your CSRF cookie is marked as HttpOnly, which    │ │
+│ │                                                  │            │ helps prevent some XSS attacks.                  │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the CSRF cookie SameSite=Lax?                 │ 🟢 Success │ CSRF cookie is marked as SameSite=Lax, which     │ │
+│ │                                                  │            │ helps prevent CSRF attacks via cross-site        │ │
+│ │                                                  │            │ requests.                                        │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the CSRF cookie Secure?                       │ 🟢 Success │ CSRF cookie is marked as Secure. It will only be │ │
+│ │                                                  │            │ sent over HTTPS.                                 │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Does your site return a 404 for non-existent     │ 🟢 Success │ Your site correctly returns a 404 error for      │ │
+│ │ pages?                                           │            │ non-existent pages.                              │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is Django DEBUG mode disabled?                   │ 🟢 Success │ Django DEBUG mode is disabled. This is essential │ │
+│ │                                                  │            │ for production security.                         │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the Strict-Transport-Security (HSTS) header   │ 🟢 Success │ Strict-Transport-Security header is set. Your    │ │
+│ │ set?                                             │            │ site enforces HTTPS for all visitors.            │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Does your site redirect all HTTP traffic to      │ 🟢 Success │ All HTTP traffic is redirected to HTTPS. This is │ │
+│ │ HTTPS?                                           │            │ essential for security.                          │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is your site accessible via HTTPS?               │ 🟢 Success │ Your site is accessible via HTTPS. All sensitive │ │
+│ │                                                  │            │ data is encrypted in transit.                    │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is your login page exposed at a default or       │ 🟢 Success │ Login page is not exposed at the default URL.    │ │
+│ │ guessable URL?                                   │            │ This reduces the risk of automated attacks.      │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the sessionid cookie set?                     │ 🔴 Failure │ No sessionid cookie was found. This is normal if │ │
+│ │                                                  │            │ your site does not use sessions on this page. If │ │
+│ │                                                  │            │ your application relies on sessions for          │ │
+│ │                                                  │            │ authentication or user data, ensure Django's     │ │
+│ │                                                  │            │ session middleware is enabled and configured     │ │
+│ │                                                  │            │ correctly.                                       │ │
+│ │                                                  │            │                                                  │ │
+│ │                                                  │            │ Reference:                                       │ │
+│ │                                                  │            │                                                  │ │
+│ │                                                  │            │  • Django Sessions                               │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the sessionid cookie HttpOnly?                │ 🟡 Skipped │ Check skipped due to failed or missing           │ │
+│ │                                                  │            │ dependency: sessionid_cookie_check               │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the sessionid cookie Secure?                  │ 🟡 Skipped │ Check skipped due to failed or missing           │ │
+│ │                                                  │            │ dependency: sessionid_cookie_check               │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the sessionid cookie SameSite=Lax?            │ 🟡 Skipped │ Check skipped due to failed or missing           │ │
+│ │                                                  │            │ dependency: sessionid_cookie_check               │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the X-Frame-Options header set?               │ 🟢 Success │ X-Frame-Options header is set. Your site is      │ │
+│ │                                                  │            │ protected against clickjacking attacks.          │ │
+│ └──────────────────────────────────────────────────┴────────────┴──────────────────────────────────────────────────┘ │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```

djcheckup-0.1.0/README.md

@@ -0,0 +1,101 @@
+# DJ Checkup
+
+## Overview
+
+DJ Checkup is a security scanner for Django sites. This package provides a command-line interface to run the security
+checks against your Django site. These are the same checks that are used by the DJ Checkup website at
+<https://djcheckup.com>.
+
+## Installation
+
+This works best when installed with `uv tool` or `pipx`.
+
+```bash
+# With uv:
+uv tool install djcheckup
+
+# Or with pipx:
+pipx install djcheckup
+```
+
+You can also run the tool without installing it:
+
+```bash
+# With uvx:
+uvx djcheckup https://yourdjangosite.com
+```
+
+## Usage
+
+Run the `djcheckup` command-line utility with the URL of your Django site.
+
+You'll see a nicely formatted report in your terminal:
+
+```text
+╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
+│                                     DJ Checkup Results for https://djcheckup.com                                     │
+│ ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ │
+│ ┃ Check                                            ┃ Result     ┃ Message                                          ┃ │
+│ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │
+│ │ Can I connect to your site?                      │ 🟢 Success │ Connected to your site successfully.             │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is your Django admin site exposed at the default │ 🟢 Success │ Your Django admin site is not exposed at the     │ │
+│ │ URL?                                             │            │ default URL. This reduces the risk of automated  │ │
+│ │                                                  │            │ attacks.                                         │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is a CSRF cookie set?                            │ 🟢 Success │ CSRF cookie detected. Your site is protected     │ │
+│ │                                                  │            │ against cross-site request forgery attacks.      │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the CSRF cookie HttpOnly?                     │ 🟢 Success │ Your CSRF cookie is marked as HttpOnly, which    │ │
+│ │                                                  │            │ helps prevent some XSS attacks.                  │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the CSRF cookie SameSite=Lax?                 │ 🟢 Success │ CSRF cookie is marked as SameSite=Lax, which     │ │
+│ │                                                  │            │ helps prevent CSRF attacks via cross-site        │ │
+│ │                                                  │            │ requests.                                        │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the CSRF cookie Secure?                       │ 🟢 Success │ CSRF cookie is marked as Secure. It will only be │ │
+│ │                                                  │            │ sent over HTTPS.                                 │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Does your site return a 404 for non-existent     │ 🟢 Success │ Your site correctly returns a 404 error for      │ │
+│ │ pages?                                           │            │ non-existent pages.                              │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is Django DEBUG mode disabled?                   │ 🟢 Success │ Django DEBUG mode is disabled. This is essential │ │
+│ │                                                  │            │ for production security.                         │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the Strict-Transport-Security (HSTS) header   │ 🟢 Success │ Strict-Transport-Security header is set. Your    │ │
+│ │ set?                                             │            │ site enforces HTTPS for all visitors.            │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Does your site redirect all HTTP traffic to      │ 🟢 Success │ All HTTP traffic is redirected to HTTPS. This is │ │
+│ │ HTTPS?                                           │            │ essential for security.                          │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is your site accessible via HTTPS?               │ 🟢 Success │ Your site is accessible via HTTPS. All sensitive │ │
+│ │                                                  │            │ data is encrypted in transit.                    │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is your login page exposed at a default or       │ 🟢 Success │ Login page is not exposed at the default URL.    │ │
+│ │ guessable URL?                                   │            │ This reduces the risk of automated attacks.      │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the sessionid cookie set?                     │ 🔴 Failure │ No sessionid cookie was found. This is normal if │ │
+│ │                                                  │            │ your site does not use sessions on this page. If │ │
+│ │                                                  │            │ your application relies on sessions for          │ │
+│ │                                                  │            │ authentication or user data, ensure Django's     │ │
+│ │                                                  │            │ session middleware is enabled and configured     │ │
+│ │                                                  │            │ correctly.                                       │ │
+│ │                                                  │            │                                                  │ │
+│ │                                                  │            │ Reference:                                       │ │
+│ │                                                  │            │                                                  │ │
+│ │                                                  │            │  • Django Sessions                               │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the sessionid cookie HttpOnly?                │ 🟡 Skipped │ Check skipped due to failed or missing           │ │
+│ │                                                  │            │ dependency: sessionid_cookie_check               │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the sessionid cookie Secure?                  │ 🟡 Skipped │ Check skipped due to failed or missing           │ │
+│ │                                                  │            │ dependency: sessionid_cookie_check               │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the sessionid cookie SameSite=Lax?            │ 🟡 Skipped │ Check skipped due to failed or missing           │ │
+│ │                                                  │            │ dependency: sessionid_cookie_check               │ │
+│ ├──────────────────────────────────────────────────┼────────────┼──────────────────────────────────────────────────┤ │
+│ │ Is the X-Frame-Options header set?               │ 🟢 Success │ X-Frame-Options header is set. Your site is      │ │
+│ │                                                  │            │ protected against clickjacking attacks.          │ │
+│ └──────────────────────────────────────────────────┴────────────┴──────────────────────────────────────────────────┘ │
+╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```

djcheckup-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "djcheckup"
+version = "0.1.0"
+description = "DJ Checkup is a security scanner for Django sites."
+readme = "README.md"
+authors = [{ name = "Stuart Maxwell", email = "stuart@amanzi.nz" }]
+requires-python = ">=3.13"
+dependencies = ["httpx>=0.28.1", "rich>=14.1.0", "typer>=0.17.4"]
+
+[project.scripts]
+djcheckup = "djcheckup.run:app"
+
+[project.urls]
+Homepage = "https://github.com/stuartmaxwell/djcheckup"
+Repository = "https://github.com/stuartmaxwell/djcheckup"
+
+[build-system]
+requires = ["uv_build>=0.8.13,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["ALL"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google" # Accepts: "google", "numpy", or "pep257".

djcheckup-0.1.0/src/djcheckup/__init__.py

@@ -0,0 +1,12 @@
+"""DJ Checkup CLI package."""
+
+import logging
+
+from rich.logging import RichHandler
+
+FORMAT = "%(message)s"
+logging.basicConfig(level=logging.WARNING, format=FORMAT, datefmt="[%X]", handlers=[RichHandler()])
+
+logger = logging.getLogger("rich")
+
+__version__ = "0.1.0"

djcheckup-0.1.0/src/djcheckup/check_defs.py

@@ -0,0 +1,337 @@
+"""Check definitions."""
+
+from djcheckup.checks import (
+    ContentCheck,
+    CookieCheck,
+    CookieHttpOnlyCheck,
+    CookieSameSiteCheck,
+    CookieSecureCheck,
+    HeaderCheck,
+    PathCheck,
+    SchemeCheck,
+    SeverityWeight,
+)
+
+admin_check = PathCheck(
+    check_id="admin_check",
+    name="Is your Django admin site exposed at the default URL?",
+    path="/admin",
+    success=False,
+    severity=SeverityWeight.HIGH,
+    success_message="""
+Your Django admin site is not exposed at the default URL. This reduces the risk of automated attacks.
+""",
+    failure_message="""
+Your Django admin site is accessible at the default URL (`/admin`).
+
+Best practice is to restrict admin access to trusted IPs, use strong authentication, and change the admin URL to a
+non-default, unguessable value. Never expose the admin over HTTP; always use HTTPS.
+
+Reference:
+- [Django Admin Docs](https://docs.djangoproject.com/en/stable/ref/contrib/admin/#adminsite-objects)
+""",
+)
+
+
+csrf_check = CookieCheck(
+    check_id="csrf_check",
+    name="Is a CSRF cookie set?",
+    cookie_name="csrftoken",
+    success=True,
+    severity=SeverityWeight.LOW,
+    success_message="CSRF cookie detected. Your site is protected against cross-site request forgery attacks.",
+    failure_message="""
+No CSRF cookie was found. This is expected if your site does not render any forms that require CSRF protection on this
+page. If you have forms that perform POST, PUT, or DELETE requests, ensure Django's CSRF middleware is enabled and not
+bypassed.
+
+Reference:
+- [Django CSRF Protection](https://docs.djangoproject.com/en/stable/ref/csrf/)
+""",
+)
+
+
+csrf_httponly_check = CookieHttpOnlyCheck(
+    check_id="csrf_httponly_check",
+    depends_on="csrf_check",
+    name="Is the CSRF cookie HttpOnly?",
+    cookie_name="csrftoken",
+    success=False,
+    severity=SeverityWeight.MEDIUM,
+    success_message="Your CSRF cookie is marked as HttpOnly, which helps prevent some XSS attacks.",
+    failure_message="""
+Your CSRF cookie is not marked as HttpOnly. While Django does not set this by default
+(to allow JavaScript access for some use cases), setting HttpOnly can help mitigate certain XSS risks.
+Consider your application's needs before enabling this.
+
+**Note:** This check will be skipped if the `csrf_check` check fails.
+
+Reference:
+- [Django CSRF Cookie Settings](https://docs.djangoproject.com/en/stable/ref/settings/#csrf-cookie-httponly)
+""",
+)
+
+
+csrf_samesite_check = CookieSameSiteCheck(
+    check_id="csrf_samesite_check",
+    depends_on="csrf_check",
+    name="Is the CSRF cookie SameSite=Lax?",
+    cookie_name="csrftoken",
+    samesite_value="Lax",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="CSRF cookie is marked as SameSite=Lax, which helps prevent CSRF attacks via cross-site requests.",
+    failure_message="""
+Your CSRF cookie is not marked as SameSite=Lax. This increases the risk of CSRF attacks.
+Set `CSRF_COOKIE_SAMESITE = 'Lax'` in your Django settings.
+
+**Note:** This check will be skipped if the `csrf_check` check fails.
+
+Reference:
+- [Django CSRF Settings](https://docs.djangoproject.com/en/stable/ref/settings/#csrf-cookie-samesite)
+""",
+)
+
+
+csrf_secure_check = CookieSecureCheck(
+    check_id="csrf_secure_check",
+    depends_on="csrf_check",
+    name="Is the CSRF cookie Secure?",
+    cookie_name="csrftoken",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="CSRF cookie is marked as Secure. It will only be sent over HTTPS.",
+    failure_message="""
+Your CSRF cookie is not marked as Secure. This means it could be sent over unencrypted HTTP,
+exposing it to interception. Set `CSRF_COOKIE_SECURE = True` in your Django settings.
+
+**Note:** This check will be skipped if the `csrf_check` check fails.
+
+Reference:
+- [Django CSRF Settings](https://docs.djangoproject.com/en/stable/ref/settings/#csrf-cookie-secure)
+""",
+)
+
+
+debug_404_check = PathCheck(
+    check_id="debug_404_check",
+    name="Does your site return a 404 for non-existent pages?",
+    path="/a/b/c/d/e/f/g/h/i/j/xyz/",
+    status_code=404,
+    success=True,
+    severity=SeverityWeight.MEDIUM,
+    success_message="Your site correctly returns a 404 error for non-existent pages.",
+    failure_message="""
+Your site does not return a 404 error for non-existent pages. This may indicate a misconfiguration or a custom error
+handler that does not set the correct status code.
+Ensure your web server and Django app return 404 for missing resources.
+
+Reference:
+- [Django Custom Error Views](https://docs.djangoproject.com/en/stable/topics/http/views/#customizing-error-views)
+""",
+)
+
+
+debug_check = ContentCheck(
+    check_id="debug_check",
+    depends_on="debug_404_check",
+    name="Is Django DEBUG mode disabled?",
+    path="/a/b/c/d/e/f/g/h/i/j/xyz/",
+    content="DEBUG = True",
+    success=False,
+    severity=SeverityWeight.CRITICAL,
+    success_message="Django DEBUG mode is disabled. This is essential for production security.",
+    failure_message="""
+Your site appears to have Django's DEBUG mode enabled. This exposes sensitive information and should never be used in
+production. Set `DEBUG = False` in your settings.
+
+Reference:
+- [Django Deployment Checklist](https://docs.djangoproject.com/en/stable/howto/deployment/checklist/#debug)
+""",
+)
+
+
+hsts_header_check = HeaderCheck(
+    check_id="hsts_header_check",
+    name="Is the Strict-Transport-Security (HSTS) header set?",
+    header_name="Strict-Transport-Security",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="Strict-Transport-Security header is set. Your site enforces HTTPS for all visitors.",
+    failure_message="""
+Your site does not send the Strict-Transport-Security (HSTS) header. This means browsers may allow users to visit your
+site over HTTP, exposing them to downgrade attacks.
+Set this header in your web server or via Django's `SECURE_HSTS_SECONDS` setting.
+
+Reference:
+- [Django Security Settings](https://docs.djangoproject.com/en/stable/ref/settings/#secure-hsts-seconds)
+- [MDN: Strict-Transport-Security](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security)
+""",
+)
+
+
+http_check = SchemeCheck(
+    check_id="http_check",
+    name="Does your site redirect all HTTP traffic to HTTPS?",
+    start_scheme="http",
+    end_scheme="https",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="All HTTP traffic is redirected to HTTPS. This is essential for security.",
+    failure_message="""
+Your site does not redirect HTTP traffic to HTTPS. This exposes users to man-in-the-middle attacks. Ensure your web
+server or CDN is configured to redirect all HTTP requests to HTTPS.
+
+Reference:
+- [Django Security Settings](https://docs.djangoproject.com/en/stable/ref/settings/#secure-ssl-redirect)
+- [Google Web Fundamentals](https://developers.google.com/web/fundamentals/security/encrypt-in-transit/enable-https)
+""",
+)
+
+
+https_check = SchemeCheck(
+    check_id="https_check",
+    name="Is your site accessible via HTTPS?",
+    start_scheme="https",
+    end_scheme="https",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="Your site is accessible via HTTPS. All sensitive data is encrypted in transit.",
+    failure_message="""
+Your site is not accessible via HTTPS. This exposes all traffic to interception and tampering. Obtain and install a
+valid TLS certificate and configure your web server to serve HTTPS.
+
+Reference:
+- [Django Security Settings](https://docs.djangoproject.com/en/stable/ref/settings/#secure-proxy-ssl-header)
+- [Cloudflare SSL](https://support.cloudflare.com/hc/en-us/articles/360023792171-Getting-Started-with-Cloudflare-SSL)
+""",
+)
+
+
+login_check = PathCheck(
+    check_id="login_check",
+    name="Is your login page exposed at a default or guessable URL?",
+    path="/accounts/login/",
+    success=False,
+    severity=SeverityWeight.MEDIUM,
+    success_message="Login page is not exposed at the default URL. This reduces the risk of automated attacks.",
+    failure_message="""
+Your login page is accessible at the default URL (`/accounts/login/`). Consider changing it to a non-default path and
+always require HTTPS for login forms. Use strong authentication and rate limiting to prevent brute-force attacks.
+""",
+)
+
+
+sessionid_cookie_check = CookieCheck(
+    check_id="sessionid_cookie_check",
+    name="Is the sessionid cookie set?",
+    cookie_name="sessionid",
+    success=True,
+    severity=SeverityWeight.LOW,
+    success_message="Session cookie is set. User sessions are being managed securely.",
+    failure_message="""
+No sessionid cookie was found. This is normal if your site does not use sessions on this page. If your application
+relies on sessions for authentication or user data, ensure Django's session middleware is enabled and configured
+correctly.
+
+Reference:
+- [Django Sessions](https://docs.djangoproject.com/en/stable/topics/http/sessions/)
+""",
+)
+
+
+sessionid_httponly_check = CookieHttpOnlyCheck(
+    check_id="sessionid_httponly_check",
+    depends_on="sessionid_cookie_check",
+    name="Is the sessionid cookie HttpOnly?",
+    cookie_name="sessionid",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="Sessionid cookie is marked as HttpOnly. This helps prevent access from JavaScript.",
+    failure_message="""
+Your sessionid cookie is not marked as HttpOnly. This increases the risk of session theft via XSS.
+Set `SESSION_COOKIE_HTTPONLY = True` in your Django settings.
+
+**Note:** This check will be skipped if the `sessionid_cookie_check` check fails.
+
+Reference:
+- [Django Session Security](https://docs.djangoproject.com/en/stable/ref/settings/#session-cookie-httponly)
+""",
+)
+
+
+sessionid_samesite_check = CookieSameSiteCheck(
+    check_id="sessionid_samesite_check",
+    depends_on="sessionid_cookie_check",
+    name="Is the sessionid cookie SameSite=Lax?",
+    cookie_name="sessionid",
+    samesite_value="Lax",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="Sessionid cookie is marked as SameSite=Lax. This helps prevent CSRF attacks.",
+    failure_message="""
+Your sessionid cookie is not marked as SameSite=Lax. This increases the risk of CSRF attacks.
+Set `SESSION_COOKIE_SAMESITE = 'Lax'` in your Django settings.
+
+Reference:
+- [Django Session Security](https://docs.djangoproject.com/en/stable/ref/settings/#session-cookie-samesite)
+""",
+)
+
+
+sessionid_secure_check = CookieSecureCheck(
+    check_id="sessionid_secure_check",
+    depends_on="sessionid_cookie_check",
+    name="Is the sessionid cookie Secure?",
+    cookie_name="sessionid",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="Sessionid cookie is marked as Secure. It will only be sent over HTTPS.",
+    failure_message="""
+Your sessionid cookie is not marked as Secure. This means it could be sent over unencrypted HTTP, exposing it to
+interception. Set `SESSION_COOKIE_SECURE = True` in your Django settings.
+
+**Note:** This check will be skipped if the `sessionid_cookie_check` check fails.
+
+Reference:
+- [Django Session Security](https://docs.djangoproject.com/en/stable/ref/settings/#session-cookie-secure)
+""",
+)
+
+
+xframe_header_check = HeaderCheck(
+    check_id="xframe_header_check",
+    name="Is the X-Frame-Options header set?",
+    header_name="X-Frame-Options",
+    success=True,
+    severity=SeverityWeight.HIGH,
+    success_message="X-Frame-Options header is set. Your site is protected against clickjacking attacks.",
+    failure_message="""
+Your site does not send the X-Frame-Options header. This allows your site to be embedded in iframes,
+making it vulnerable to clickjacking. Set this header in your web server or via Django's `XFrameOptionsMiddleware`.
+
+Reference:
+- [Django Clickjacking Protection](https://docs.djangoproject.com/en/stable/ref/clickjacking/)
+- [MDN: X-Frame-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options)
+""",
+)
+
+
+all_checks = [
+    admin_check,
+    csrf_check,
+    csrf_httponly_check,
+    csrf_samesite_check,
+    csrf_secure_check,
+    debug_404_check,
+    debug_check,
+    hsts_header_check,
+    http_check,
+    https_check,
+    login_check,
+    sessionid_cookie_check,
+    sessionid_httponly_check,
+    sessionid_secure_check,
+    sessionid_samesite_check,
+    xframe_header_check,
+]

djcheckup-0.1.0/src/djcheckup/checks.py

@@ -0,0 +1,420 @@
+"""Check types."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from enum import Enum
+from http.cookiejar import CookieJar
+from typing import Literal
+
+import httpx
+
+from djcheckup import logger
+
+
+class SeverityWeight(Enum):
+    """Severity weight for the security score."""
+
+    NONE = 0
+    LOW = 5
+    MEDIUM = 15
+    HIGH = 30
+    CRITICAL = 50
+
+
+class CheckResult(Enum):
+    """Possible results of a check."""
+
+    SUCCESS = "success"
+    FAILURE = "failure"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class SiteCheckContext:
+    """Context object passed to all checks."""
+
+    url: httpx.URL
+    client: httpx.Client
+    headers: httpx.Headers
+    cookies: CookieJar
+    content: str
+    response_url: httpx.URL
+
+
+@dataclass
+class CheckResponse:
+    """The response from an individual check."""
+
+    name: str
+    result: CheckResult
+    severity_score: SeverityWeight
+    message: str
+
+
+@dataclass
+class SiteCheckResult:
+    """The result of a site check."""
+
+    url: httpx.URL
+    check_results: list[CheckResponse]
+
+
+@dataclass(kw_only=True)
+class _BaseCheck(ABC):
+    """Base class for all checks."""
+
+    check_id: str
+    name: str
+    success: bool
+    severity: SeverityWeight
+    success_message: str
+    failure_message: str
+    depends_on: str | None = None
+
+    @abstractmethod
+    def check(self, context: SiteCheckContext) -> bool:
+        """Run the check and return the result."""
+        ...
+
+    def run(self, context: SiteCheckContext, previous_results: dict[str, CheckResponse]) -> CheckResponse:
+        """Run the header check."""
+        if self.depends_on:
+            dependent_result = previous_results.get(self.depends_on)
+
+            if not dependent_result or dependent_result.result == CheckResult.FAILURE:
+                logger.info(f"Skipping check '{self.name}' because it depends on failed check '{self.depends_on}'.")
+
+                return CheckResponse(
+                    name=self.name,
+                    result=CheckResult.SKIPPED,
+                    severity_score=SeverityWeight.NONE,
+                    message=f"Check skipped due to failed or missing dependency: {self.depends_on}",
+                )
+
+        check_result = self.check(context)
+
+        result = CheckResult.SUCCESS if check_result == self.success else CheckResult.FAILURE
+
+        return CheckResponse(
+            name=self.name,
+            result=result,
+            severity_score=self.severity,
+            message=self.success_message if result == CheckResult.SUCCESS else self.failure_message,
+        )
+
+
+@dataclass
+class HeaderCheck(_BaseCheck):
+    """A header check."""
+
+    header_name: str
+    header_value: str = ""
+
+    def check(self, context: SiteCheckContext) -> bool:
+        """Check if a specific header is present and optionally if it matches a given value."""
+        # Normalize header names to lowercase for case-insensitive comparison
+        headers = {k.lower(): v for k, v in context.headers.items()}
+        actual_value = headers.get(self.header_name.lower())
+        if actual_value is None:
+            logger.info(f"Header '{self.header_name}' not found: {context.headers}")
+            return False
+
+        # Compare header values case-insensitively if header_value is provided
+        if self.header_value and actual_value.lower() != self.header_value.lower():
+            logger.info(f"Header '{self.header_name}' value '{actual_value}' doesn't match '{self.header_value}'.")
+            return False
+
+        logger.debug(f"Header '{self.header_name}' is present with value '{actual_value}'.")
+        return True
+
+
+@dataclass
+class ContentCheck(_BaseCheck):
+    """A content check.
+
+    Checks for specific content in the response.
+    Takes an optional path to check a different URL.
+    """
+
+    content: str
+    path: str = ""
+
+    def check(self, context: SiteCheckContext) -> bool:
+        """Check if the response body contains the expected content."""
+        response_content: str = ""
+
+        if self.path:
+            # Append the path to the url
+            new_url = httpx.URL(context.url).join(self.path)
+            logger.info(f"Making request to {new_url}")
+
+            response = context.client.get(new_url)
+            response_content = response.text
+
+        else:
+            response_content = context.content
+
+        if response_content == "":
+            logger.warning("No response content to check.")
+            return False
+
+        if self.content not in response_content:
+            logger.debug("Response body does not contain expected content.")
+            return False
+
+        logger.debug("Response body contains expected content.")
+        return True
+
+
+@dataclass
+class CookieCheck(_BaseCheck):
+    """A cookie check."""
+
+    cookie_name: str
+    cookie_value: str = ""
+
+    def check(self, context: SiteCheckContext) -> bool:
+        """Check if a specific cookie is present and optionally if it matches a given value."""
+        if not context.cookies:
+            logger.warning("No response cookies to check.")
+            return False
+
+        for cookie in context.cookies:
+            if cookie.name == self.cookie_name:
+                if self.cookie_value and cookie.value == self.cookie_value:
+                    logger.info(
+                        f"Cookie '{self.cookie_name}' value '{cookie.value}' doesn't match '{self.cookie_value}'.",
+                    )
+                    return True
+
+                if not self.cookie_value:
+                    logger.debug(f"Cookie '{self.cookie_name}' is present.")
+                    return True
+
+        logger.debug(f"Cookie '{self.cookie_name}' is not present.")
+        return False
+
+
+@dataclass
+class CookieHttpOnlyCheck(_BaseCheck):
+    """A cookie HttpOnly check."""
+
+    cookie_name: str
+
+    def check(self, context: SiteCheckContext) -> bool:
+        """Check if a specific cookie is marked as HttpOnly."""
+        if not context.cookies:
+            logger.warning("No response cookies to check.")
+            return False
+
+        for cookie in context.cookies:
+            if cookie.name == self.cookie_name:
+                return cookie.has_nonstandard_attr("HttpOnly")
+
+        logger.info(f"Cookie '{self.cookie_name}' was not found.")
+        return False
+
+
+@dataclass
+class CookieSameSiteCheck(_BaseCheck):
+    """A cookie SameSite check."""
+
+    cookie_name: str
+    samesite_value: Literal["Strict", "Lax", "None"]
+
+    def check(self, context: SiteCheckContext) -> bool:
+        """Check if a specific cookie has a SameSite attribute."""
+        if not context.cookies:
+            logger.warning("No response cookies to check.")
+            return False
+
+        for cookie in context.cookies:
+            if cookie.name == self.cookie_name:
+                return cookie.get_nonstandard_attr("SameSite") == self.samesite_value
+
+        logger.info(f"Cookie '{self.cookie_name}' was not found.")
+        return False
+
+
+@dataclass
+class CookieSecureCheck(_BaseCheck):
+    """A cookie secure check.
+
+    Checks if the specified cookie is marked as Secure.
+    """
+
+    cookie_name: str
+
+    def check(self, context: SiteCheckContext) -> bool:
+        """Check if a specific cookie is marked as Secure."""
+        if not context.cookies:
+            logger.warning("No response cookies to check.")
+            return False
+
+        for cookie in context.cookies:
+            if cookie.name == self.cookie_name:
+                logger.debug(f"Found cookie '{self.cookie_name}': {cookie}, with attributes {cookie.__dict__}")
+                return cookie.secure
+
+        logger.info(f"Cookie '{self.cookie_name}' was not found.")
+        return False
+
+
+@dataclass
+class PathCheck(_BaseCheck):
+    """A path check.
+
+    Checks if the specified path returns a successful response.
+
+    Takes an optional status code to check against if you want to test for a specific status code.
+
+    Returns True if the path is accessible or the status code matches.
+    Returns False if the path is not accessible or the status code does not match.
+    """
+
+    path: str
+    status_code: int | None = None
+
+    def check(self, context: SiteCheckContext) -> bool:
+        """Makes a request to the specified path and checks the response."""
+        # Append the path to the url using the urlib module
+        new_url = httpx.URL(context.url).join(self.path)
+        logger.info(f"Making request to {new_url}")
+
+        response = context.client.get(new_url)
+        logger.info(f"Response status code: {response.status_code}")
+
+        if self.status_code:
+            if response.status_code == self.status_code:
+                logger.debug(f"Request to {new_url} returned expected status code {self.status_code}.")
+                return True
+            logger.debug(f"Request to {new_url} returned unexpected status code {response.status_code}.")
+            return False
+
+        if httpx.codes.is_success(response.status_code):
+            logger.debug(f"Request to {new_url} succeeded.")
+            return True
+
+        logger.debug(f"Request to {new_url} failed with status code {response.status_code}.")
+        return False
+
+
+@dataclass
+class SchemeCheck(_BaseCheck):
+    """A scheme check.
+
+    Checks if the URL scheme (http or https) that the request starts with matches the final scheme.
+
+    `start_scheme` is the scheme to start with.
+    `end_scheme` is the expected scheme after any redirects.
+    """
+
+    start_scheme: Literal["http", "https"]
+    end_scheme: Literal["http", "https"]
+
+    def check(self, context: SiteCheckContext) -> bool:
+        """Check if the scheme of the URL in the request matches the final scheme."""
+        # If the start scheme matches the original URL scheme, then we don't need a new request.
+        if context.url.scheme == self.start_scheme and context.response_url.scheme == self.end_scheme:
+            logger.debug(f"URL '{context.url}' scheme matches expected scheme '{self.end_scheme}'.")
+            return True
+
+        # Need to create a new URL with the specified start scheme
+        new_url = context.url.copy_with(scheme=self.start_scheme)
+        logger.debug(f"Created new URL '{new_url}' with scheme '{self.end_scheme}'.")
+
+        # And make a request to the new URL
+        response = context.client.get(new_url)
+
+        if response.url.scheme == self.end_scheme:
+            logger.debug(f"Request to {new_url} succeeded.")
+            return True
+
+        logger.debug(f"URL '{context.url}' matches scheme '{self.start_scheme}' to '{self.end_scheme}'.")
+        return False
+
+
+class SiteChecker:
+    """Run all the checks for a given site."""
+
+    def __init__(self, url: str) -> None:
+        """Initialize the SiteChecker with a URL."""
+        self.url: httpx.URL = httpx.URL(url)
+        self.user_agent: str = "DJCheckupBot/1.0 (+https://djcheckup.com/bot-info)"
+        self.timeout: float = 10.0
+        self.client: httpx.Client = httpx.Client(
+            headers={"User-Agent": self.user_agent},
+            timeout=self.timeout,
+            follow_redirects=True,
+        )
+
+    def close(self) -> None:
+        """Close the HTTP client and release resources."""
+        self.client.close()
+
+    def run_first_check(self) -> CheckResponse:
+        """Run the first check.
+
+        This connects to the URL using httpx to check connectivity and then saves the page content, headers, and cookies
+        into a context object for the remaining checks.
+        """
+        logger.info(f"Running first check for {self.url}")
+
+        check_name = "Can I connect to your site?"
+        severity_weight = SeverityWeight.HIGH
+        success_message = "Connected to your site successfully."
+        error_message = "Unable to connect to your site and no further checks can be performed."
+
+        try:
+            response = self.client.get(self.url)
+            response.raise_for_status()
+            logger.debug(f"Successfully connected to {self.url}")
+
+        except httpx.RequestError:
+            logger.exception(f"Error connecting to {self.url}")
+            return CheckResponse(
+                name=check_name,
+                result=CheckResult.FAILURE,
+                severity_score=severity_weight,
+                message=error_message,
+            )
+
+        self.context = SiteCheckContext(
+            url=self.url,
+            client=self.client,
+            headers=response.headers,
+            cookies=response.cookies.jar,
+            content=response.text,
+            response_url=response.url,
+        )
+
+        logger.info(f"Finished first check for {self.url}")
+
+        return CheckResponse(
+            name=check_name,
+            result=CheckResult.SUCCESS,
+            severity_score=severity_weight,
+            message=success_message,
+        )
+
+    def run_checks(self, checks: list[_BaseCheck]) -> SiteCheckResult:
+        """Run all checks."""
+        # First, run the first check
+        first_check = self.run_first_check()
+        site_check_results = SiteCheckResult(url=self.url, check_results=[first_check])
+
+        if first_check.result == CheckResult.FAILURE:
+            return site_check_results
+
+        # If the first check passes, run all other checks
+        previous_results: dict[str, CheckResponse] = {"first_check": first_check}
+
+        for check in checks:
+            result = check.run(self.context, previous_results)
+            site_check_results.check_results.append(result)
+            previous_results[check.check_id] = result
+            logger.debug(f"Finished running check: {check.name}")
+
+        # Close the HTTP client
+        self.client.close()
+        return site_check_results

djcheckup-0.1.0/src/djcheckup/output_json.py

@@ -0,0 +1,28 @@
+"""Output the results as JSON."""
+
+import json
+from dataclasses import asdict
+
+import httpx
+
+from djcheckup.checks import CheckResult, SeverityWeight, SiteCheckResult
+
+
+def custom_encoder(obj: object) -> str | int:
+    """Custom JSON encoder for non-serializable types."""
+    if isinstance(obj, SeverityWeight):
+        return obj.value
+
+    if isinstance(obj, CheckResult):
+        return obj.value
+
+    if isinstance(obj, httpx.URL):
+        return str(obj)
+
+    msg = f"Object of type {type(obj).__name__} is not JSON serializable"
+    raise TypeError(msg)
+
+
+def output_results_as_json(results: SiteCheckResult) -> str:
+    """Convert the results to JSON format."""
+    return json.dumps(asdict(results), default=custom_encoder)

djcheckup-0.1.0/src/djcheckup/output_rich.py

@@ -0,0 +1,32 @@
+"""Use Rich to display output."""
+
+from rich.console import Console
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.table import Table
+
+from djcheckup.checks import CheckResult, SiteCheckResult
+
+
+def rich_output(check_results: SiteCheckResult) -> None:
+    """Display results using Rich."""
+    console = Console()
+
+    table = Table(title=f"DJ Checkup Results for {check_results.url}", show_lines=True)
+
+    table.add_column("Check", justify="left")
+    table.add_column("Result", justify="left")
+    table.add_column("Message", justify="left")
+
+    for result in check_results.check_results:
+        emoji = ""
+        if result.result == CheckResult.SUCCESS:
+            emoji = "🟢 "
+        elif result.result == CheckResult.FAILURE:
+            emoji = "🔴 "
+        elif result.result == CheckResult.SKIPPED:
+            emoji = "🟡 "
+        display_result = emoji + result.result.value.capitalize()
+        table.add_row(result.name, display_result, Markdown(result.message))
+
+    console.print(Panel(table))

djcheckup-0.1.0/src/djcheckup/run.py

@@ -0,0 +1,36 @@
+"""Command line interface."""
+
+from typing import Annotated
+
+import rich
+import typer
+
+from djcheckup.check_defs import all_checks
+from djcheckup.checks import SiteChecker
+from djcheckup.output_json import output_results_as_json
+from djcheckup.output_rich import rich_output
+
+app = typer.Typer()
+
+
+@app.command()
+def run_checks(
+    url: Annotated[str, typer.Argument(help="The URL to check.")],
+    *,
+    output_json: Annotated[
+        bool,
+        typer.Option(help="Prints the results in JSON format."),
+    ] = False,
+) -> None:
+    """Run the DJ Checkup tool against a specific URL."""
+    checker = SiteChecker(url)
+    results = checker.run_checks(all_checks)
+
+    if output_json:
+        rich.print_json(output_results_as_json(results))
+    else:
+        rich_output(results)
+
+
+if __name__ == "__main__":
+    app()