primedefender-fastapi 0.1.0__tar.gz

primedefender_fastapi-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+venv/
+ENV/
+.env
+.env.local
+.idea/
+.vscode/
+*.swp
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml

primedefender_fastapi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PrimeDefender contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

primedefender_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: primedefender-fastapi
+Version: 0.1.0
+Summary: PrimeDefender security middleware for FastAPI: WAF-style detection, blocking, and incident reporting to the PrimeDefender bridge.
+Project-URL: Homepage, https://github.com/primedefender/primedefender-fastapi
+Project-URL: Repository, https://github.com/primedefender/primedefender-fastapi
+Project-URL: Issues, https://github.com/primedefender/primedefender-fastapi/issues
+Author: PrimeDefender contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: fastapi,intrusion-detection,middleware,primedefender,security,sqli,waf,xss
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# primedefender-fastapi
+
+**PrimeDefender** adds a security layer to [FastAPI](https://fastapi.tiangolo.com/) applications: it inspects incoming requests for common attack patterns, optionally blocks them, and sends structured incidents to your **PrimeDefender bridge** (for example for a live monitoring map).
+
+This package publishes to PyPI as **`primedefender-fastapi`**. The import name is **`primedefender_fastapi`**.
+
+## Features
+
+| Detection | Notes |
+|-----------|--------|
+| SQL injection | Signature-based |
+| XSS | Signature-based |
+| Brute force | Configurable window on auth paths |
+| Path traversal | Signature-based |
+| Command injection | Signature-based |
+| File inclusion | Signature-based |
+| DDoS / flood | Per-IP sliding window |
+| Bot activity | User-agent heuristics + rate limit |
+| Scanner | UA + path probes + rate limit |
+| Suspicious request | Method / query / body heuristics (observe by default) |
+| Auth bypass probe | Header / query patterns (observe by default) |
+
+Blocked requests return JSON with HTTP `403` or `429` as appropriate. Incidents are **POST**ed to the bridge (default path **`/ingest`** if your `PRIMEDEFENDER_BRIDGE_URL` has no path).
+
+## Requirements
+
+- Python **3.10+**
+- A running **PrimeDefender bridge** that accepts the incident JSON (see your dashboard docs).
+
+## Install
+
+```bash
+pip install primedefender-fastapi
+```
+
+For a local editable install while developing the package:
+
+```bash
+pip install -e ./primedefender-fastapi
+```
+
+## Environment variables
+
+Set these in your process environment or load them with `python-dotenv` **before** the app imports settings (see below).
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PRIMEDEFENDER_BRIDGE_URL` | Yes* | Bridge base URL, e.g. `http://localhost:3000` (path `/ingest` is added if missing) |
+| `PRIMEDEFENDER_API_KEY` | Yes* | API key sent as `X-Api-Key` / `Authorization: Bearer` |
+| `PRIMEDEFENDER_SITE_ID` | Yes* | Site identifier in payloads |
+| `PRIMEDEFENDER_SITE_LAT` | Recommended | Target latitude for map “to” pin |
+| `PRIMEDEFENDER_SITE_LON` | Recommended | Target longitude |
+| `PRIMEDEFENDER_SITE_REGION_LABEL` | Optional | Human label, e.g. `Indonesia, Bali` → `targetLabel = "{site_id} · {label}"` |
+| `PRIMEDEFENDER_PRIVATE_SOURCE_LABEL` | Optional | Label for private/loopback IPs |
+| `PRIMEDEFENDER_AUTH_BYPASS_MODE` | Optional | `observe` (default) or `block` |
+| `PRIMEDEFENDER_SUSPICIOUS_REQUEST_MODE` | Optional | `observe` (default) or `block` |
+
+\*If bridge URL, API key, or site id is missing, reporting is disabled (middleware still runs detections).
+
+See `.env.example` in this repository for tuning knobs (`PRIMEDEFENDER_BODY_CAP_BYTES`, rate limits, GeoIP TTL, etc.).
+
+## FastAPI usage
+
+**Minimal** (configuration only from environment):
+
+```python
+from fastapi import FastAPI
+from primedefender_fastapi import PrimeDefenderMiddleware
+
+app = FastAPI()
+app.add_middleware(PrimeDefenderMiddleware)
+```
+
+Load `.env` early so variables exist when settings are first read:
+
+```python
+from pathlib import Path
+from dotenv import load_dotenv
+
+load_dotenv(Path(__file__).resolve().parent / ".env")
+```
+
+**Optional constructor overrides** (other fields still come from the environment):
+
+```python
+app.add_middleware(
+    PrimeDefenderMiddleware,
+    site_label="Indonesia, Bali",
+    auth_bypass_mode="observe",
+    suspicious_request_mode="block",
+)
+```
+
+**Explicit settings object** (e.g. tests or multi-tenant):
+
+```python
+from primedefender_fastapi import PrimeDefenderMiddleware, PrimeDefenderSettings
+
+settings = PrimeDefenderSettings.from_env()
+app.add_middleware(PrimeDefenderMiddleware, settings=settings)
+```
+
+## Connect to the PrimeDefender bridge
+
+1. Run your bridge (often on port `3000` or behind HTTPS).
+2. Set `PRIMEDEFENDER_BRIDGE_URL` to that origin, e.g. `http://localhost:3000`.
+3. Ensure the bridge exposes **`POST /ingest`** (or set the full URL including path).
+4. Use a valid `PRIMEDEFENDER_API_KEY` accepted by the bridge.
+
+Health check (typical): `GET http://localhost:3000/health`.
+
+## Test SQLi / XSS locally
+
+With the API on port `8000`:
+
+**SQL injection (query)**
+
+```bash
+curl "http://127.0.0.1:8000/auth/login?next=' OR 1=1 --"
+```
+
+**XSS**
+
+```bash
+curl "http://127.0.0.1:8000/?q=%3Cscript%3Ealert(1)%3C/script%3E"
+```
+
+**Map labels (optional test headers)**
+
+```bash
+curl "http://127.0.0.1:8000/auth/login?next=' OR 1=1 --" \
+  -H "X-Prime-Source-Lat: 34.6937" \
+  -H "X-Prime-Source-Lon: 135.5023" \
+  -H "X-Prime-Source-Label: Japan, Osaka"
+```
+
+## Building and publishing
+
+Uses **hatchling** (PEP 517):
+
+```bash
+pip install build
+python -m build
+```
+
+Upload `dist/*` to PyPI with `twine` (use API tokens and trusted publishing in CI in production).
+
+## License
+
+MIT — see `LICENSE`.
+
+## Repository
+
+Placeholder links are set in `pyproject.toml` (`Homepage` / `Repository`). Replace with your real GitHub URL before publishing.

primedefender_fastapi-0.1.0/README.md

@@ -0,0 +1,154 @@
+# primedefender-fastapi
+
+**PrimeDefender** adds a security layer to [FastAPI](https://fastapi.tiangolo.com/) applications: it inspects incoming requests for common attack patterns, optionally blocks them, and sends structured incidents to your **PrimeDefender bridge** (for example for a live monitoring map).
+
+This package publishes to PyPI as **`primedefender-fastapi`**. The import name is **`primedefender_fastapi`**.
+
+## Features
+
+| Detection | Notes |
+|-----------|--------|
+| SQL injection | Signature-based |
+| XSS | Signature-based |
+| Brute force | Configurable window on auth paths |
+| Path traversal | Signature-based |
+| Command injection | Signature-based |
+| File inclusion | Signature-based |
+| DDoS / flood | Per-IP sliding window |
+| Bot activity | User-agent heuristics + rate limit |
+| Scanner | UA + path probes + rate limit |
+| Suspicious request | Method / query / body heuristics (observe by default) |
+| Auth bypass probe | Header / query patterns (observe by default) |
+
+Blocked requests return JSON with HTTP `403` or `429` as appropriate. Incidents are **POST**ed to the bridge (default path **`/ingest`** if your `PRIMEDEFENDER_BRIDGE_URL` has no path).
+
+## Requirements
+
+- Python **3.10+**
+- A running **PrimeDefender bridge** that accepts the incident JSON (see your dashboard docs).
+
+## Install
+
+```bash
+pip install primedefender-fastapi
+```
+
+For a local editable install while developing the package:
+
+```bash
+pip install -e ./primedefender-fastapi
+```
+
+## Environment variables
+
+Set these in your process environment or load them with `python-dotenv` **before** the app imports settings (see below).
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `PRIMEDEFENDER_BRIDGE_URL` | Yes* | Bridge base URL, e.g. `http://localhost:3000` (path `/ingest` is added if missing) |
+| `PRIMEDEFENDER_API_KEY` | Yes* | API key sent as `X-Api-Key` / `Authorization: Bearer` |
+| `PRIMEDEFENDER_SITE_ID` | Yes* | Site identifier in payloads |
+| `PRIMEDEFENDER_SITE_LAT` | Recommended | Target latitude for map “to” pin |
+| `PRIMEDEFENDER_SITE_LON` | Recommended | Target longitude |
+| `PRIMEDEFENDER_SITE_REGION_LABEL` | Optional | Human label, e.g. `Indonesia, Bali` → `targetLabel = "{site_id} · {label}"` |
+| `PRIMEDEFENDER_PRIVATE_SOURCE_LABEL` | Optional | Label for private/loopback IPs |
+| `PRIMEDEFENDER_AUTH_BYPASS_MODE` | Optional | `observe` (default) or `block` |
+| `PRIMEDEFENDER_SUSPICIOUS_REQUEST_MODE` | Optional | `observe` (default) or `block` |
+
+\*If bridge URL, API key, or site id is missing, reporting is disabled (middleware still runs detections).
+
+See `.env.example` in this repository for tuning knobs (`PRIMEDEFENDER_BODY_CAP_BYTES`, rate limits, GeoIP TTL, etc.).
+
+## FastAPI usage
+
+**Minimal** (configuration only from environment):
+
+```python
+from fastapi import FastAPI
+from primedefender_fastapi import PrimeDefenderMiddleware
+
+app = FastAPI()
+app.add_middleware(PrimeDefenderMiddleware)
+```
+
+Load `.env` early so variables exist when settings are first read:
+
+```python
+from pathlib import Path
+from dotenv import load_dotenv
+
+load_dotenv(Path(__file__).resolve().parent / ".env")
+```
+
+**Optional constructor overrides** (other fields still come from the environment):
+
+```python
+app.add_middleware(
+    PrimeDefenderMiddleware,
+    site_label="Indonesia, Bali",
+    auth_bypass_mode="observe",
+    suspicious_request_mode="block",
+)
+```
+
+**Explicit settings object** (e.g. tests or multi-tenant):
+
+```python
+from primedefender_fastapi import PrimeDefenderMiddleware, PrimeDefenderSettings
+
+settings = PrimeDefenderSettings.from_env()
+app.add_middleware(PrimeDefenderMiddleware, settings=settings)
+```
+
+## Connect to the PrimeDefender bridge
+
+1. Run your bridge (often on port `3000` or behind HTTPS).
+2. Set `PRIMEDEFENDER_BRIDGE_URL` to that origin, e.g. `http://localhost:3000`.
+3. Ensure the bridge exposes **`POST /ingest`** (or set the full URL including path).
+4. Use a valid `PRIMEDEFENDER_API_KEY` accepted by the bridge.
+
+Health check (typical): `GET http://localhost:3000/health`.
+
+## Test SQLi / XSS locally
+
+With the API on port `8000`:
+
+**SQL injection (query)**
+
+```bash
+curl "http://127.0.0.1:8000/auth/login?next=' OR 1=1 --"
+```
+
+**XSS**
+
+```bash
+curl "http://127.0.0.1:8000/?q=%3Cscript%3Ealert(1)%3C/script%3E"
+```
+
+**Map labels (optional test headers)**
+
+```bash
+curl "http://127.0.0.1:8000/auth/login?next=' OR 1=1 --" \
+  -H "X-Prime-Source-Lat: 34.6937" \
+  -H "X-Prime-Source-Lon: 135.5023" \
+  -H "X-Prime-Source-Label: Japan, Osaka"
+```
+
+## Building and publishing
+
+Uses **hatchling** (PEP 517):
+
+```bash
+pip install build
+python -m build
+```
+
+Upload `dist/*` to PyPI with `twine` (use API tokens and trusted publishing in CI in production).
+
+## License
+
+MIT — see `LICENSE`.
+
+## Repository
+
+Placeholder links are set in `pyproject.toml` (`Homepage` / `Repository`). Replace with your real GitHub URL before publishing.

primedefender_fastapi-0.1.0/primedefender_fastapi/__init__.py

@@ -0,0 +1,18 @@
+"""
+PrimeDefender FastAPI middleware: request inspection, blocking, and bridge reporting.
+"""
+
+from primedefender_fastapi.config import PrimeDefenderSettings, clear_settings_cache, load_settings
+from primedefender_fastapi.detectors import Detection
+from primedefender_fastapi.middleware import PrimeDefenderMiddleware
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "PrimeDefenderMiddleware",
+    "PrimeDefenderSettings",
+    "Detection",
+    "load_settings",
+    "clear_settings_cache",
+    "__version__",
+]

primedefender_fastapi-0.1.0/primedefender_fastapi/config.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from functools import lru_cache
+from typing import Any, Literal, Tuple
+from urllib.parse import urlparse
+
+Mode = Literal["observe", "block"]
+
+
+def _env_str(key: str, default: str = "") -> str:
+    raw = os.getenv(key)
+    if raw is None:
+        return default
+    return raw.strip()
+
+
+def _env_float(key: str, default: float) -> float:
+    raw = os.getenv(key)
+    if raw is None or raw == "":
+        return default
+    try:
+        return float(raw)
+    except ValueError:
+        return default
+
+
+def _env_int(key: str, default: int) -> int:
+    raw = os.getenv(key)
+    if raw is None or raw == "":
+        return default
+    try:
+        return int(raw)
+    except ValueError:
+        return default
+
+
+def _env_bool(key: str, default: bool = False) -> bool:
+    raw = os.getenv(key)
+    if raw is None or raw == "":
+        return default
+    return raw.lower() in ("1", "true", "yes", "on")
+
+
+def _env_mode(key: str, default: Mode) -> Mode:
+    raw = (os.getenv(key) or "").strip().lower()
+    if raw in ("observe", "block"):
+        return raw  # type: ignore[return-value]
+    return default
+
+
+@dataclass(frozen=True)
+class PrimeDefenderSettings:
+    """Configuration for middleware and bridge reporting. Usually built via ``from_env()``."""
+
+    bridge_url: str
+    api_key: str
+    site_id: str
+    site_lat: float
+    site_lon: float
+    site_region_label: str
+    private_source_label: str
+    body_cap_bytes: int
+    geoip_ttl_seconds: int
+    geoip_timeout_seconds: float
+    bridge_timeout_seconds: float
+    flood_window_seconds: int
+    flood_max_requests: int
+    brute_force_window_seconds: int
+    brute_force_max_attempts: int
+    bot_window_seconds: int
+    bot_max_requests: int
+    scanner_window_seconds: int
+    scanner_max_requests: int
+    auth_bypass_mode: Mode
+    suspicious_request_mode: Mode
+    debug: bool
+
+    @property
+    def observe_only_detections(self) -> Tuple[str, ...]:
+        names: list[str] = []
+        if self.auth_bypass_mode == "observe":
+            names.append("auth_bypass")
+        if self.suspicious_request_mode == "observe":
+            names.append("suspicious_request")
+        return tuple(names)
+
+    @property
+    def resolved_bridge_url(self) -> str:
+        """POST target. If env is only origin (path empty or `/`), ``/ingest`` is appended."""
+        raw = (self.bridge_url or "").strip()
+        if not raw:
+            return raw
+        parsed = urlparse(raw)
+        path = parsed.path or ""
+        if path in ("", "/"):
+            return raw.rstrip("/") + "/ingest"
+        return raw
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.bridge_url and self.api_key and self.site_id)
+
+    @classmethod
+    def from_env(cls, **overrides: Any) -> PrimeDefenderSettings:
+        """Load from environment variables, then apply ``overrides`` (non-``None`` keys win)."""
+        data: dict[str, Any] = {
+            "bridge_url": _env_str("PRIMEDEFENDER_BRIDGE_URL"),
+            "api_key": _env_str("PRIMEDEFENDER_API_KEY"),
+            "site_id": _env_str("PRIMEDEFENDER_SITE_ID", "primestudio-api"),
+            "site_lat": _env_float("PRIMEDEFENDER_SITE_LAT", -8.6705),
+            "site_lon": _env_float("PRIMEDEFENDER_SITE_LON", 115.2126),
+            "site_region_label": _env_str("PRIMEDEFENDER_SITE_REGION_LABEL", "Indonesia, Bali") or "Indonesia, Bali",
+            "private_source_label": _env_str("PRIMEDEFENDER_PRIVATE_SOURCE_LABEL", "Local / private network")
+            or "Local / private network",
+            "body_cap_bytes": _env_int("PRIMEDEFENDER_BODY_CAP_BYTES", 16_384),
+            "geoip_ttl_seconds": _env_int("PRIMEDEFENDER_GEOIP_TTL_SECONDS", 3600),
+            "geoip_timeout_seconds": _env_float("PRIMEDEFENDER_GEOIP_TIMEOUT_SECONDS", 2.5),
+            "bridge_timeout_seconds": _env_float("PRIMEDEFENDER_BRIDGE_TIMEOUT_SECONDS", 3.0),
+            "flood_window_seconds": _env_int("PRIMEDEFENDER_FLOOD_WINDOW_SECONDS", 10),
+            "flood_max_requests": _env_int("PRIMEDEFENDER_FLOOD_MAX_REQUESTS", 60),
+            "brute_force_window_seconds": _env_int("PRIMEDEFENDER_BRUTE_WINDOW_SECONDS", 300),
+            "brute_force_max_attempts": _env_int("PRIMEDEFENDER_BRUTE_MAX_ATTEMPTS", 12),
+            "bot_window_seconds": _env_int("PRIMEDEFENDER_BOT_WINDOW_SECONDS", 60),
+            "bot_max_requests": _env_int("PRIMEDEFENDER_BOT_MAX_REQUESTS", 30),
+            "scanner_window_seconds": _env_int("PRIMEDEFENDER_SCANNER_WINDOW_SECONDS", 300),
+            "scanner_max_requests": _env_int("PRIMEDEFENDER_SCANNER_MAX_REQUESTS", 12),
+            "auth_bypass_mode": _env_mode("PRIMEDEFENDER_AUTH_BYPASS_MODE", "observe"),
+            "suspicious_request_mode": _env_mode("PRIMEDEFENDER_SUSPICIOUS_REQUEST_MODE", "observe"),
+            "debug": _env_bool("PRIMEDEFENDER_DEBUG"),
+        }
+        alias_map = {
+            "site_label": "site_region_label",
+        }
+        for key, value in overrides.items():
+            if value is None:
+                continue
+            target = alias_map.get(key, key)
+            if target not in data:
+                continue
+            if target in ("auth_bypass_mode", "suspicious_request_mode"):
+                v = str(value).lower()
+                if v in ("observe", "block"):
+                    data[target] = v
+                continue
+            data[target] = value
+        return cls(**data)  # type: ignore[arg-type]
+
+
+@lru_cache(maxsize=1)
+def load_settings() -> PrimeDefenderSettings:
+    """Cached settings from environment (call after ``load_dotenv()`` in the host app)."""
+    return PrimeDefenderSettings.from_env()
+
+
+def clear_settings_cache() -> None:
+    """Mainly for tests."""
+    load_settings.cache_clear()

primedefender_fastapi-0.1.0/primedefender_fastapi/detectors.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Pattern
+
+from primedefender_fastapi.config import PrimeDefenderSettings
+from primedefender_fastapi.rate_limit import SlidingWindowLimiter
+
+
+@dataclass
+class Detection:
+    name: str
+    category: str
+    severity: str
+    blocked: bool
+    action: str
+    status_code: int
+    detail: str
+
+
+SQLI_PATTERNS = (
+    r"(?i)\bunion\b.{0,20}\bselect\b",
+    r"(?i)\bselect\b.{0,20}\bfrom\b",
+    r"(?i)\binformation_schema\b",
+    r"(?i)\bor\b\s+1=1",
+    r"(?i)'\s*or\s*'1'='1",
+    r"(?i)\bsleep\s*\(",
+    r"(?i)\bbenchmark\s*\(",
+    r"(?i)\bdrop\s+table\b",
+    r"(?i)\bwaitfor\s+delay\b",
+)
+XSS_PATTERNS = (
+    r"(?i)<script\b",
+    r"(?i)javascript:",
+    r"(?i)onerror\s*=",
+    r"(?i)onload\s*=",
+    r"(?i)<svg\b",
+    r"(?i)<img\b",
+    r"(?i)document\.cookie",
+    r"(?i)alert\s*\(",
+)
+PATH_TRAVERSAL_PATTERNS = (
+    r"\.\./",
+    r"\.\.\\",
+    r"%2e%2e%2f",
+    r"%252e%252e%252f",
+    r"/etc/passwd",
+    r"win\.ini",
+    r"/proc/self/environ",
+)
+COMMAND_INJECTION_PATTERNS = (
+    r"(?i)(?:;|\|\||&&)\s*(?:curl|wget|bash|sh|powershell|cmd\.exe|nc)\b",
+    r"`[^`]+`",
+    r"\$\([^)]+\)",
+    r"(?i)\b(?:cmd\.exe|/bin/sh|powershell)\b",
+)
+FILE_INCLUSION_PATTERNS = (
+    r"(?i)\b(?:php|file|zip|data|expect)://",
+    r"(?i)\b(?:web-inf|phpmyadmin|wp-config\.php|\.git/config)\b",
+    r"(?i)\b(?:include|require)(_once)?\b",
+)
+SCANNER_UA_MARKERS = (
+    "sqlmap",
+    "nikto",
+    "nmap",
+    "nessus",
+    "dirbuster",
+    "gobuster",
+    "feroxbuster",
+    "wafw00f",
+    "masscan",
+    "nuclei",
+    "acunetix",
+    "burp",
+    "zaproxy",
+)
+BOT_UA_MARKERS = (
+    "python-requests",
+    "curl/",
+    "wget/",
+    "aiohttp",
+    "scrapy",
+    "httpclient",
+    "okhttp",
+    "libwww",
+    "urllib",
+    "bot",
+    "crawler",
+    "spider",
+)
+SCANNER_PATH_MARKERS = (
+    "/.env",
+    "/.git",
+    "/wp-admin",
+    "/wp-login.php",
+    "/phpmyadmin",
+    "/cgi-bin",
+    "/actuator",
+    "/vendor/phpunit",
+    "/boaform",
+)
+AUTH_BYPASS_MARKERS = (
+    "x-original-url",
+    "x-rewrite-url",
+    "x-forwarded-host",
+    "x-host",
+    "x-http-method-override",
+)
+AUTH_PATHS = (
+    "/auth/login",
+    "/auth/register",
+    "/auth/forgot-password",
+    "/auth/reset-password",
+    "/auth/reset-password-with-code",
+    "/auth/verify-reset-code",
+)
+
+
+def compile_pattern_buckets() -> Dict[str, List[Pattern[str]]]:
+    return {
+        "sqli": [re.compile(p) for p in SQLI_PATTERNS],
+        "xss": [re.compile(p) for p in XSS_PATTERNS],
+        "path_traversal": [re.compile(p, re.IGNORECASE) for p in PATH_TRAVERSAL_PATTERNS],
+        "command_injection": [re.compile(p) for p in COMMAND_INJECTION_PATTERNS],
+        "file_inclusion": [re.compile(p) for p in FILE_INCLUSION_PATTERNS],
+    }
+
+
+class RequestInspector:
+    """Stateful rate limits + signature detection for one app instance."""
+
+    def __init__(self, settings: PrimeDefenderSettings) -> None:
+        self.settings = settings
+        self.flood_limiter = SlidingWindowLimiter()
+        self.brute_force_limiter = SlidingWindowLimiter()
+        self.bot_limiter = SlidingWindowLimiter()
+        self.scanner_limiter = SlidingWindowLimiter()
+        self._compiled = compile_pattern_buckets()
+
+    def inspect(self, meta: Dict[str, Any]) -> Optional[Detection]:
+        ip = meta["client_ip"]
+        method = meta["method"]
+        path = meta["decoded_path"].lower()
+        query = meta["decoded_query"].lower()
+        combined = meta["combined"]
+        ua = meta["user_agent"].lower()
+        headers = meta["headers"]
+
+        flood_count = self.flood_limiter.hit(ip, self.settings.flood_window_seconds)
+        if flood_count > self.settings.flood_max_requests:
+            return self._decision("ddos", "Application flood limit exceeded.", blocked=True)
+
+        if method == "POST" and path in AUTH_PATHS:
+            brute_count = self.brute_force_limiter.hit(
+                f"{ip}:{path}", self.settings.brute_force_window_seconds
+            )
+            if brute_count > self.settings.brute_force_max_attempts:
+                return self._decision("brute_force_login", "Brute force login pattern detected.", blocked=True)
+
+        if any(marker in ua for marker in SCANNER_UA_MARKERS) or any(
+            marker in path for marker in SCANNER_PATH_MARKERS
+        ):
+            scanner_count = self.scanner_limiter.hit(ip, self.settings.scanner_window_seconds)
+            if scanner_count >= self.settings.scanner_max_requests:
+                return self._decision("scanner_activity", "Scanner activity detected.", blocked=True)
+
+        if any(marker in ua for marker in BOT_UA_MARKERS):
+            bot_count = self.bot_limiter.hit(ip, self.settings.bot_window_seconds)
+            if bot_count > self.settings.bot_max_requests:
+                return self._decision("bot_activity", "Automated bot activity detected.", blocked=True)
+
+        if self._matches("path_traversal", combined):
+            return self._decision("path_traversal", "Path traversal signature matched.", blocked=True)
+        if self._matches("file_inclusion", combined):
+            return self._decision("file_inclusion", "File inclusion signature matched.", blocked=True)
+        if self._matches("command_injection", combined):
+            return self._decision("command_injection", "Command injection signature matched.", blocked=True)
+        if self._matches("sqli", combined):
+            return self._decision("sqli", "SQL injection signature matched.", blocked=True)
+        if self._matches("xss", combined):
+            return self._decision("xss", "XSS signature matched.", blocked=True)
+
+        if (
+            any(header in headers for header in AUTH_BYPASS_MARKERS)
+            or "admin=true" in query
+            or "role=admin" in query
+        ):
+            return self._decision("auth_bypass", "Authorization bypass probe observed.", blocked=False)
+
+        suspicious_method = method in {"TRACE", "CONNECT"}
+        suspicious_query = len(meta["query"]) > 2048 or "%25" in meta["query"]
+        suspicious_body = meta["body_size"] > self.settings.body_cap_bytes
+        if suspicious_method or suspicious_query or suspicious_body or not ua:
+            return self._decision("suspicious_request", "Suspicious request observed.", blocked=False)
+
+        return None
+
+    def _decision(self, name: str, detail: str, blocked: bool) -> Detection:
+        observe_only = name in self.settings.observe_only_detections
+        effective_blocked = blocked and not observe_only
+        action = "blocked" if effective_blocked else "observed"
+
+        if name == "ddos":
+            return Detection(name, "ddos", "critical", effective_blocked, action, 429, detail)
+        if name in {"scanner_activity", "brute_force_login"}:
+            return Detection(name, "intrusion", "high", effective_blocked, action, 429, detail)
+        if name == "bot_activity":
+            return Detection(name, "botnet", "medium", effective_blocked, action, 429, detail)
+        if name == "command_injection":
+            return Detection(name, "malware", "critical", effective_blocked, action, 403, detail)
+        if name in {"sqli", "xss", "path_traversal", "file_inclusion"}:
+            return Detection(name, "intrusion", "high", effective_blocked, action, 403, detail)
+        if name == "auth_bypass":
+            return Detection(name, "intrusion", "medium", effective_blocked, action, 403, detail)
+        return Detection(name, "unknown", "low", effective_blocked, action, 403, detail)
+
+    def _matches(self, bucket: str, content: str) -> bool:
+        return any(pattern.search(content) for pattern in self._compiled[bucket])

primedefender_fastapi-0.1.0/primedefender_fastapi/geo.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import ipaddress
+import time
+from typing import Dict, Optional, Tuple
+
+import httpx
+
+
+def is_private_ip(ip: str) -> bool:
+    try:
+        return ipaddress.ip_address(ip).is_private
+    except ValueError:
+        return True
+
+
+def format_ip_location_label(
+    country: Optional[str],
+    region_name: Optional[str],
+    city: Optional[str],
+) -> Optional[str]:
+    """Human-readable place name, e.g. 'Japan, Osaka' or 'United States, Virginia'."""
+    if not country:
+        return None
+    if country == "United States":
+        second = region_name or city
+    else:
+        second = city or region_name
+    if second:
+        return f"{country}, {second}"
+    return country
+
+
+class GeoIPCache:
+    def __init__(self, ttl_seconds: int, timeout_seconds: float) -> None:
+        self.ttl_seconds = ttl_seconds
+        self.timeout_seconds = timeout_seconds
+        self._cache: Dict[str, Tuple[float, Tuple[Optional[float], Optional[float], Optional[str]]]] = {}
+
+    async def get(self, ip: str) -> Tuple[Optional[float], Optional[float], Optional[str]]:
+        if not ip or is_private_ip(ip):
+            return (None, None, None)
+
+        now = time.time()
+        cached = self._cache.get(ip)
+        if cached and cached[0] > now:
+            return cached[1]
+
+        lat: Optional[float] = None
+        lon: Optional[float] = None
+        label: Optional[str] = None
+        url = f"http://ip-api.com/json/{ip}?fields=status,country,regionName,city,lat,lon"
+
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                response = await client.get(url)
+                response.raise_for_status()
+                data = response.json()
+                if data.get("status") == "success":
+                    lat = data.get("lat")
+                    lon = data.get("lon")
+                    label = format_ip_location_label(
+                        data.get("country"),
+                        data.get("regionName"),
+                        data.get("city"),
+                    )
+        except Exception:
+            pass
+
+        triple = (lat, lon, label)
+        self._cache[ip] = (now + self.ttl_seconds, triple)
+        return triple

primedefender_fastapi-0.1.0/primedefender_fastapi/middleware.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict, Literal, Optional
+
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.types import ASGIApp
+from urllib.parse import unquote_plus
+
+from primedefender_fastapi.config import PrimeDefenderSettings, load_settings
+from primedefender_fastapi.geo import GeoIPCache
+from primedefender_fastapi.reporter import report_incident
+from primedefender_fastapi.detectors import RequestInspector
+
+Mode = Literal["observe", "block"]
+
+
+class PrimeDefenderMiddleware(BaseHTTPMiddleware):
+    """
+    Security inspection + optional blocking + PrimeDefender bridge reporting.
+
+    Usage::
+
+        app.add_middleware(PrimeDefenderMiddleware)
+
+    With optional overrides (still reads other options from environment)::
+
+        app.add_middleware(
+            PrimeDefenderMiddleware,
+            site_label=\"Indonesia, Bali\",
+            auth_bypass_mode=\"observe\",
+            suspicious_request_mode=\"block\",
+        )
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        settings: Optional[PrimeDefenderSettings] = None,
+        site_label: Optional[str] = None,
+        auth_bypass_mode: Optional[Mode] = None,
+        suspicious_request_mode: Optional[Mode] = None,
+    ) -> None:
+        super().__init__(app)
+        if settings is not None:
+            self.settings = settings
+        else:
+            overrides: Dict[str, Any] = {}
+            if site_label is not None:
+                overrides["site_region_label"] = site_label
+            if auth_bypass_mode is not None:
+                overrides["auth_bypass_mode"] = auth_bypass_mode
+            if suspicious_request_mode is not None:
+                overrides["suspicious_request_mode"] = suspicious_request_mode
+            self.settings = (
+                PrimeDefenderSettings.from_env(**overrides) if overrides else load_settings()
+            )
+        self.geoip = GeoIPCache(
+            ttl_seconds=self.settings.geoip_ttl_seconds,
+            timeout_seconds=self.settings.geoip_timeout_seconds,
+        )
+        self._inspector = RequestInspector(self.settings)
+
+    async def dispatch(self, request: Request, call_next):
+        if request.method.upper() == "OPTIONS":
+            return await call_next(request)
+
+        raw_body = await request.body()
+        inspected_body = raw_body[: self.settings.body_cap_bytes]
+        body_text = inspected_body.decode("utf-8", errors="ignore")
+        request = self._clone_request(request, raw_body)
+
+        client_ip = self._extract_client_ip(request)
+        metadata = self._build_metadata(request, client_ip, body_text, len(raw_body))
+        detection = self._inspector.inspect(metadata)
+
+        if detection:
+            if detection.blocked:
+                await report_incident(self.settings, self.geoip, detection, metadata)
+                return JSONResponse(
+                    status_code=detection.status_code,
+                    content={
+                        "detail": "Request blocked by PrimeDefender security middleware.",
+                        "detection": detection.name,
+                        "action": detection.action,
+                    },
+                )
+            asyncio.create_task(report_incident(self.settings, self.geoip, detection, metadata))
+
+        return await call_next(request)
+
+    def _clone_request(self, request: Request, body: bytes) -> Request:
+        async def receive() -> Dict[str, Any]:
+            return {"type": "http.request", "body": body, "more_body": False}
+
+        return Request(request.scope, receive)
+
+    def _build_metadata(
+        self, request: Request, client_ip: str, body_text: str, body_size: int
+    ) -> Dict[str, Any]:
+        headers = {k.lower(): v for k, v in request.headers.items()}
+        method = request.method.upper()
+        path = request.url.path
+        query = request.url.query or ""
+        decoded_query = unquote_plus(query)
+        decoded_path = unquote_plus(path)
+        user_agent = headers.get("user-agent", "")
+        combined = "\n".join(
+            [
+                decoded_path,
+                decoded_query,
+                body_text,
+                " ".join(f"{k}:{v}" for k, v in headers.items()),
+            ]
+        )
+        return {
+            "method": method,
+            "path": path,
+            "decoded_path": decoded_path,
+            "query": query,
+            "decoded_query": decoded_query,
+            "headers": headers,
+            "user_agent": user_agent,
+            "body_text": body_text,
+            "body_size": body_size,
+            "client_ip": client_ip,
+            "combined": combined,
+        }
+
+    def _extract_client_ip(self, request: Request) -> str:
+        hdr = request.headers
+        for name in ("cf-connecting-ip", "x-real-ip"):
+            value = hdr.get(name)
+            if value:
+                return value.strip()
+
+        forwarded_for = hdr.get("x-forwarded-for")
+        if forwarded_for:
+            first = forwarded_for.split(",")[0].strip()
+            if first:
+                return first
+
+        if request.client and request.client.host:
+            return request.client.host
+        return "unknown"

primedefender_fastapi-0.1.0/primedefender_fastapi/rate_limit.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import time
+from collections import defaultdict, deque
+from typing import Deque, Dict
+
+
+class SlidingWindowLimiter:
+    def __init__(self) -> None:
+        self._events: Dict[str, Deque[float]] = defaultdict(deque)
+
+    def hit(self, key: str, window_seconds: int) -> int:
+        now = time.time()
+        bucket = self._events[key]
+        cutoff = now - window_seconds
+        while bucket and bucket[0] < cutoff:
+            bucket.popleft()
+        bucket.append(now)
+        return len(bucket)

primedefender_fastapi-0.1.0/primedefender_fastapi/reporter.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any, Dict, Optional, Tuple
+
+import httpx
+
+from primedefender_fastapi.config import PrimeDefenderSettings
+from primedefender_fastapi.detectors import Detection
+from primedefender_fastapi.geo import GeoIPCache, is_private_ip
+
+logger = logging.getLogger(__name__)
+
+
+def parse_header_float(raw: Optional[str]) -> Optional[float]:
+    if raw is None or not str(raw).strip():
+        return None
+    try:
+        return float(str(raw).strip())
+    except ValueError:
+        return None
+
+
+def prime_header_overrides(meta: Dict[str, Any]) -> Tuple[Optional[float], Optional[float], str]:
+    h = meta["headers"]
+    lat = parse_header_float(h.get("x-prime-source-lat"))
+    lon = parse_header_float(h.get("x-prime-source-lon"))
+    label = (h.get("x-prime-source-label") or "").strip()
+    return lat, lon, label
+
+
+async def report_incident(
+    settings: PrimeDefenderSettings,
+    geo: GeoIPCache,
+    detection: Detection,
+    meta: Dict[str, Any],
+) -> None:
+    if not settings.enabled:
+        logger.debug("PrimeDefender: skip bridge (set PRIMEDEFENDER_BRIDGE_URL, API_KEY, SITE_ID)")
+        return
+
+    url = settings.resolved_bridge_url
+    if settings.debug:
+        logger.debug("PrimeDefender: POST %s detection=%s", url, detection.name)
+
+    client_ip = meta["client_ip"]
+    oh_lat, oh_lon, oh_label = prime_header_overrides(meta)
+    has_coord_override = oh_lat is not None and oh_lon is not None
+    has_label_override = bool(oh_label)
+
+    geo_lat: Optional[float] = None
+    geo_lon: Optional[float] = None
+    geo_label: Optional[str] = None
+    if not has_coord_override:
+        geo_lat, geo_lon, geo_label = await geo.get(client_ip)
+
+    if has_coord_override:
+        attacker_lat, attacker_lon = oh_lat, oh_lon
+    else:
+        attacker_lat, attacker_lon = geo_lat, geo_lon
+
+    if attacker_lat is None or attacker_lon is None:
+        attacker_lat = 0.0
+        attacker_lon = 0.0
+
+    if has_label_override:
+        source_label = oh_label
+    elif has_coord_override and not has_label_override:
+        source_label = f"{float(attacker_lat):.3f}, {float(attacker_lon):.3f}"
+    elif is_private_ip(client_ip):
+        source_label = settings.private_source_label
+    elif geo_label:
+        source_label = geo_label
+    else:
+        source_label = f"Unknown location ({client_ip})"
+
+    site_region = settings.site_region_label
+    target_label = f"{settings.site_id} · {site_region}"
+
+    payload: Dict[str, Any] = {
+        "from": {
+            "lat": float(attacker_lat),
+            "lon": float(attacker_lon),
+        },
+        "to": {
+            "lat": float(settings.site_lat),
+            "lon": float(settings.site_lon),
+        },
+        "category": detection.category,
+        "severity": detection.severity,
+        "sourceLabel": source_label,
+        "targetLabel": target_label,
+        "siteId": settings.site_id,
+        "createdAt": int(time.time() * 1000),
+        "blocked": detection.blocked,
+        "action": detection.action,
+        "path": meta["path"],
+        "method": meta["method"],
+        "attackerIp": client_ip,
+        "userAgent": meta["user_agent"],
+        "detection": detection.name,
+    }
+    if detection.category == "ddos":
+        payload["ddos"] = {"vector": "application"}
+
+    headers = {
+        "Content-Type": "application/json",
+        "X-Api-Key": settings.api_key,
+        "Authorization": f"Bearer {settings.api_key}",
+    }
+
+    try:
+        async with httpx.AsyncClient(timeout=settings.bridge_timeout_seconds) as client:
+            response = await client.post(url, json=payload, headers=headers)
+    except httpx.HTTPError as exc:
+        logger.warning(
+            "PrimeDefender: bridge HTTP error posting to %s: %s",
+            url,
+            exc,
+            exc_info=settings.debug,
+        )
+        return
+    except Exception as exc:
+        logger.warning(
+            "PrimeDefender: bridge unexpected error posting to %s: %s",
+            url,
+            exc,
+            exc_info=True,
+        )
+        return
+
+    log_msg = (
+        "PrimeDefender: bridge status=%s from=%s to=%s sourceLabel=%r targetLabel=%r detection=%s blocked=%s"
+        % (
+            response.status_code,
+            payload["from"],
+            payload["to"],
+            source_label,
+            target_label,
+            detection.name,
+            detection.blocked,
+        )
+    )
+    if response.is_success:
+        logger.info(log_msg)
+    else:
+        logger.warning("%s url=%s body=%r", log_msg, url, (response.text or "")[:800])

primedefender_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling>=1.18.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "primedefender-fastapi"
+version = "0.1.0"
+description = "PrimeDefender security middleware for FastAPI: WAF-style detection, blocking, and incident reporting to the PrimeDefender bridge."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "PrimeDefender contributors" }]
+keywords = [
+  "fastapi",
+  "security",
+  "middleware",
+  "waf",
+  "primedefender",
+  "sqli",
+  "xss",
+  "intrusion-detection",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: FastAPI",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Security",
+  "Typing :: Typed",
+]
+dependencies = [
+  "fastapi>=0.100.0",
+  "httpx>=0.25.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0.0",
+  "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/primedefender/primedefender-fastapi"
+Repository = "https://github.com/primedefender/primedefender-fastapi"
+Issues = "https://github.com/primedefender/primedefender-fastapi/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["primedefender_fastapi"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/primedefender_fastapi",
+  "/README.md",
+  "/LICENSE",
+]