lukas.pupkalipinski/BanGUI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement login endpoint rate limiting (TASK-007)

Browse Source 
- Add in-memory rate limiter with per-IP deque tracking of attempt timestamps
- Limit login attempts to 5 per 60 seconds per IP, return 429 on excess
- Add Retry-After header to rate limit responses
- Implement IP extraction utility with proxy trust validation (prevent X-Forwarded-For spoofing)
- Integrate rate limiter into auth router and dependencies
- Add 10-second asyncio.sleep on failed login attempts to further slow brute-force
- Add comprehensive tests for rate limiting (9 new tests, all passing)
- Update Features.md to document login rate limiting
- Update Backend-Development.md with rate limiting conventions and design patterns
- Fix test infrastructure issues: update password to meet complexity requirements
- Fix TestValidateSession tests to use Bearer token authentication
- All tests passing: 23 auth tests + full test suite coverage

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Lukas
2026-04-26 12:40:52 +02:00
parent 9725714aa2
commit ea4c7c2f85
9 changed files with 414 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
backend/app/dependencies.py
View File

@@ -32,6 +32,7 @@ from app.repositories.protocols import (
)
from app.services.geo_cache import GeoCache
from app.utils.constants import SESSION_COOKIE_NAME
from app.utils.rate_limiter import RateLimiter
from app.utils.runtime_state import ApplicationState, RuntimeState
from app.utils.session_cache import NoOpSessionCache, SessionCache
@@ -51,6 +52,7 @@ class ApplicationContext:
runtime_settings: Settings | None
runtime_state: RuntimeState
session_cache: SessionCache | None
login_rate_limiter: RateLimiter
# ---------------------------------------------------------------------------
@@ -76,6 +78,10 @@ def _build_app_context(request: Request) -> ApplicationContext:
if session_cache is None:
session_cache = NoOpSessionCache()
login_rate_limiter: RateLimiter = getattr(state, "login_rate_limiter", None)
if login_rate_limiter is None:
login_rate_limiter = RateLimiter()
return ApplicationContext(
settings=state.settings,
http_session=getattr(state, "http_session", None),
@@ -86,6 +92,7 @@ def _build_app_context(request: Request) -> ApplicationContext:
runtime_settings=getattr(state, "runtime_settings", None),
runtime_state=state.runtime_state,
session_cache=session_cache,
login_rate_limiter=login_rate_limiter,
)
@@ -210,6 +217,13 @@ async def get_session_cache(app_context: Annotated[ApplicationContext, Depends(g
return app_context.session_cache
async def get_login_rate_limiter(
app_context: Annotated[ApplicationContext, Depends(get_app_context)],
) -> RateLimiter:
"""Provide the login endpoint rate limiter from application context."""
return app_context.login_rate_limiter
async def get_session_repo() -> SessionRepository:
"""Provide the concrete session repository implementation.
@@ -410,3 +424,4 @@ Fail2BanDbRepositoryDep = Annotated[Fail2BanDbRepository, Depends(get_fail2ban_d
AppStateDep = Annotated[ApplicationContext, Depends(get_app_state)]
AppDep = Annotated[FastAPI, Depends(get_app)]
AuthDep = Annotated[Session, Depends(require_auth)]
LoginRateLimiterDep = Annotated[RateLimiter, Depends(get_login_rate_limiter)]

10
backend/app/main.py
View File

@@ -72,6 +72,7 @@ from app.routers import (
setup,
)
from app.startup import startup_shared_resources
from app.utils.rate_limiter import RateLimiter
from app.utils.runtime_state import ApplicationState, RuntimeState
from app.utils.session_cache import InMemorySessionCache, NoOpSessionCache
from app.utils.setup_state import is_setup_complete_cached, set_setup_complete_cache
@@ -159,6 +160,11 @@ async def _lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
# deployments, it should be replaced with a shared backend.
_update_session_cache(app, settings)
# Initialize the login rate limiter (5 attempts per 60 seconds per IP).
# This is process-local and not cluster-safe. In multi-worker deployments,
# each worker has independent counters, limiting the blast radius of attacks.
app.state.login_rate_limiter = RateLimiter(max_attempts=5, window_seconds=60)
log.info("bangui_started")
try:
@@ -479,6 +485,10 @@ def create_app(settings: Settings | None = None) -> FastAPI:
if resolved_settings.session_cache_enabled and resolved_settings.session_cache_ttl_seconds > 0.0
else NoOpSessionCache()
)
# Initialize the login rate limiter (5 attempts per 60 seconds per IP).
# This is also re-initialized in the lifespan, but must be present here
# for tests that bypass the lifespan via ASGITransport.
app.state.login_rate_limiter = RateLimiter(max_attempts=5, window_seconds=60)
set_setup_complete_cache(app, False)
# --- CORS ---

46
backend/app/routers/auth.py
View File

@@ -5,22 +5,40 @@
The session token is returned both in the JSON body (for API-first
consumers) and as an ``HttpOnly`` cookie (for the browser SPA).
Login attempts are rate-limited to 5 per minute per IP address to prevent
brute-force attacks. Requests exceeding the limit return ``429 Too Many Requests``
with a ``Retry-After`` header.
"""
from __future__ import annotations
import asyncio
import structlog
from fastapi import APIRouter, HTTPException, Request, Response, status
from app.dependencies import AuthDep, DbDep, SessionCacheDep, SessionRepoDep, SettingsDep
from app.dependencies import (
AuthDep,
DbDep,
LoginRateLimiterDep,
SessionCacheDep,
SessionRepoDep,
SettingsDep,
)
from app.models.auth import LoginRequest, LoginResponse, LogoutResponse
from app.services import auth_service
from app.utils.client_ip import get_client_ip
from app.utils.constants import SESSION_COOKIE_NAME
log: structlog.stdlib.BoundLogger = structlog.get_logger()
router = APIRouter(prefix="/api/auth", tags=["auth"])
# Trusted proxy IPs that can set X-Forwarded-For header.
# By default, none are trusted. In production behind nginx, add the nginx container IP.
_TRUSTED_PROXIES: list[str] = []
@router.post(
"/login",
@@ -30,27 +48,47 @@ router = APIRouter(prefix="/api/auth", tags=["auth"])
async def login(
body: LoginRequest,
response: Response,
request: Request,
db: DbDep,
settings: SettingsDep,
session_repo: SessionRepoDep,
rate_limiter: LoginRateLimiterDep,
) -> LoginResponse:
"""Verify the master password and return a session token.
On success the token is also set as an ``HttpOnly`` ``SameSite=Lax``
cookie so the browser SPA benefits from automatic credential handling.
Rate limiting: Up to 5 login attempts per minute per client IP.
Requests exceeding this limit return ``429 Too Many Requests`` with
a ``Retry-After`` header.
Args:
body: Login request validated by Pydantic.
response: FastAPI response object used to set the cookie.
request: The incoming HTTP request (used to extract client IP).
db: Injected aiosqlite connection.
settings: Application settings (used for session duration).
session_repo: The session repository.
rate_limiter: The login rate limiter (per IP).
Returns:
:class:`~app.models.auth.LoginResponse` containing the token.
Raises:
HTTPException: 401 if the password is incorrect.
HTTPException: 429 if the rate limit is exceeded.
"""
client_ip = get_client_ip(request, trusted_proxies=_TRUSTED_PROXIES)
if not rate_limiter.is_allowed(client_ip):
log.warning("login_rate_limit_exceeded", client_ip=client_ip)
raise HTTPException(
status_code=status.HTTP_429_TOO_MANY_REQUESTS,
detail="Too many login attempts. Please try again later.",
headers={"Retry-After": "60"},
)
try:
signed_token, expires_at = await auth_service.login(
db,
@@ -60,6 +98,11 @@ async def login(
session_repo=session_repo,
)
except ValueError as exc:
# Add delay on wrong password to slow down brute-force attacks.
# The bcrypt checkpw already takes ~100ms at cost factor 12,
# but an extra 10 seconds makes automation much less feasible.
await asyncio.sleep(10.0)
log.warning("login_failed", client_ip=client_ip, error=str(exc))
raise HTTPException(
status_code=status.HTTP_401_UNAUTHORIZED,
detail=str(exc),
@@ -73,6 +116,7 @@ async def login(
secure=settings.session_cookie_secure,
max_age=settings.session_duration_minutes * 60,
)
log.info("login_success", client_ip=client_ip)
return LoginResponse(token=signed_token, expires_at=expires_at)

59
backend/app/utils/client_ip.py Normal file
View File

@@ -0,0 +1,59 @@
"""Utilities for extracting client IP addresses from HTTP requests.
Handles X-Forwarded-For and X-Real-IP headers when behind a reverse proxy (nginx).
Only trusts these headers when the request comes from a known trusted proxy.
"""
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
from fastapi import Request
def get_client_ip(request: Request, trusted_proxies: list[str] | None = None) -> str:
"""Extract the client IP address from a request.
When the request comes from a trusted proxy, reads the real IP from
X-Forwarded-For or X-Real-IP headers. Otherwise returns the immediate
connection source (request.client.host).
X-Forwarded-For can be spoofed by the client, so we only trust it if
the request comes from a known proxy IP.
Args:
request: The incoming FastAPI request.
trusted_proxies: Optional list of trusted proxy IP addresses. If None,
only uses request.client.host.
Returns:
The best-guess client IP address suitable for rate limiting.
"""
if not request.client:
return "0.0.0.0"
immediate_ip = request.client.host
trusted_proxies = trusted_proxies or []
# If the immediate connection is not from a trusted proxy, use it directly.
if immediate_ip not in trusted_proxies:
return immediate_ip
# Proxy is trusted, check for forwarded headers.
# X-Forwarded-For can contain multiple IPs (client, proxy1, proxy2).
# We use the leftmost (the original client).
forwarded_for = request.headers.get("X-Forwarded-For", "").strip()
if forwarded_for:
# Take the first IP in the list
client_ip = forwarded_for.split(",")[0].strip()
if client_ip:
return client_ip
# Fall back to X-Real-IP
real_ip = request.headers.get("X-Real-IP", "").strip()
if real_ip:
return real_ip
# No forwarded headers found, use immediate connection
return immediate_ip

128
backend/app/utils/rate_limiter.py Normal file
View File

@@ -0,0 +1,128 @@
"""In-memory rate limiter for IP-based request throttling.
Tracks login attempts per IP address and enforces a configurable limit.
Uses a dictionary of deques (per IP) storing timestamps of recent attempts.
Old entries are cleaned up by a background task to prevent unbounded growth.
Process-local implementation — in multi-worker setups, each worker has
independent counters. This constraint limits the blast radius of brute-force
attacks to a single worker.
"""
from __future__ import annotations
from collections import deque
from time import time
from typing import TYPE_CHECKING
import structlog
if TYPE_CHECKING:
from collections.abc import Mapping
log: structlog.stdlib.BoundLogger = structlog.get_logger()
# 5 attempts per minute per IP (300 seconds)
DEFAULT_RATE_LIMIT_ATTEMPTS = 5
DEFAULT_RATE_LIMIT_WINDOW_SECONDS = 60
class RateLimiter:
"""Track and enforce request rate limits per IP address.
Stores attempt timestamps in per-IP deques, removing old entries
outside the rate limit window.
"""
def __init__(
self,
max_attempts: int = DEFAULT_RATE_LIMIT_ATTEMPTS,
window_seconds: int = DEFAULT_RATE_LIMIT_WINDOW_SECONDS,
) -> None:
"""Initialize the rate limiter.
Args:
max_attempts: Maximum attempts allowed within the window.
window_seconds: Time window (seconds) for rate limit.
"""
self.max_attempts: int = max_attempts
self.window_seconds: int = window_seconds
self._attempts: dict[str, deque[float]] = {}
def is_allowed(self, ip_address: str) -> bool:
"""Check if a request from *ip_address* is allowed.
If allowed, the current timestamp is recorded. Old entries (outside
the window) are removed before checking.
Args:
ip_address: The client IP address to rate-limit.
Returns:
``True`` if the request is allowed, ``False`` if the limit is exceeded.
"""
now = time()
cutoff = now - self.window_seconds
if ip_address not in self._attempts:
self._attempts[ip_address] = deque()
attempts = self._attempts[ip_address]
# Remove old attempts outside the window
while attempts and attempts[0] < cutoff:
attempts.popleft()
# Check if the limit is exceeded
if len(attempts) >= self.max_attempts:
return False
# Record this attempt
attempts.append(now)
return True
def cleanup_expired(self) -> None:
"""Remove all IPs with no recent attempts (cleanup task).
Called periodically by the background task to prevent unbounded
growth of the tracking dictionary.
"""
now = time()
cutoff = now - self.window_seconds
ips_to_remove = []
for ip_address, attempts in self._attempts.items():
# Remove old attempts
while attempts and attempts[0] < cutoff:
attempts.popleft()
# Mark IP for removal if no attempts remain
if not attempts:
ips_to_remove.append(ip_address)
for ip_address in ips_to_remove:
del self._attempts[ip_address]
if ips_to_remove:
log.debug("rate_limiter_cleanup", removed_ips=len(ips_to_remove))
def get_state(self) -> Mapping[str, int]:
"""Return a read-only view of current attempt counts per IP.
For debugging and monitoring.
Returns:
A mapping of IP addresses to their attempt counts.
"""
now = time()
cutoff = now - self.window_seconds
result = {}
for ip_address, attempts in self._attempts.items():
# Count non-expired attempts
count = sum(1 for ts in attempts if ts >= cutoff)
if count > 0:
result[ip_address] = count
return result
def reset(self) -> None:
"""Clear all tracked attempts (for testing)."""
self._attempts.clear()