zubbl-fastapi 0.1.0__tar.gz

zubbl_fastapi-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: zubbl-fastapi
+Version: 0.1.0
+Summary: Official FastAPI integration for the Zubbl Runtime Intelligence Platform
+Author-email: Zubbl <support@zubbl.com>
+License-Expression: MIT
+Project-URL: Homepage, https://zubbl.com
+Project-URL: Documentation, https://zubbl.com
+Keywords: fastapi,security,runtime,application-security,observability,telemetry,behaviour,api-security,zubbl
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: zubbl-runtime>=0.1.0
+Provides-Extra: test
+Requires-Dist: httpx>=0.27.0; extra == "test"
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+
+# Zubbl FastAPI
+
+The official FastAPI integration for the Zubbl Runtime Intelligence Platform.
+
+Zubbl provides real-time runtime visibility, behavioural security and adaptive protection from inside your application.
+
+## Features
+
+- 5 minute integration
+- Automatic endpoint discovery
+- Runtime request telemetry
+- Behavioural security signals
+- Runtime protection policies
+- Live Runtime Viewer integration
+- Runtime Guard heartbeat
+- Zero application code changes beyond initial setup
+
+## Requirements
+
+- Python 3.10+
+- FastAPI 0.110+
+
+## Installation
+
+```bash
+pip install zubbl-fastapi
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from zubbl_fastapi import Zubbl
+
+app = FastAPI()
+
+zubbl = Zubbl("YOUR_API_KEY")
+
+zubbl.attach(
+    app,
+    identify=lambda request: request.state.user.id
+)
+```
+
+Start your application.
+
+Your application will automatically appear inside the Zubbl Runtime Viewer.
+
+## Documentation
+
+https://zubbl.com
+
+## Runtime Intelligence
+
+Unlike traditional security tooling, Zubbl observes what happens after authentication.
+
+It continuously builds runtime evidence, behavioural intelligence and protection decisions directly from application behaviour.
+
+---
+
+Built by Zubbl.

zubbl_fastapi-0.1.0/README.md

@@ -0,0 +1,61 @@
+# Zubbl FastAPI
+
+The official FastAPI integration for the Zubbl Runtime Intelligence Platform.
+
+Zubbl provides real-time runtime visibility, behavioural security and adaptive protection from inside your application.
+
+## Features
+
+- 5 minute integration
+- Automatic endpoint discovery
+- Runtime request telemetry
+- Behavioural security signals
+- Runtime protection policies
+- Live Runtime Viewer integration
+- Runtime Guard heartbeat
+- Zero application code changes beyond initial setup
+
+## Requirements
+
+- Python 3.10+
+- FastAPI 0.110+
+
+## Installation
+
+```bash
+pip install zubbl-fastapi
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI
+from zubbl_fastapi import Zubbl
+
+app = FastAPI()
+
+zubbl = Zubbl("YOUR_API_KEY")
+
+zubbl.attach(
+    app,
+    identify=lambda request: request.state.user.id
+)
+```
+
+Start your application.
+
+Your application will automatically appear inside the Zubbl Runtime Viewer.
+
+## Documentation
+
+https://zubbl.com
+
+## Runtime Intelligence
+
+Unlike traditional security tooling, Zubbl observes what happens after authentication.
+
+It continuously builds runtime evidence, behavioural intelligence and protection decisions directly from application behaviour.
+
+---
+
+Built by Zubbl.

zubbl_fastapi-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zubbl-fastapi"
+version = "0.1.0"
+description = "Official FastAPI integration for the Zubbl Runtime Intelligence Platform"
+readme = "README.md"
+requires-python = ">=3.10"
+
+authors = [
+  { name = "Zubbl", email = "support@zubbl.com" }
+]
+
+license = "MIT"
+
+keywords = [
+  "fastapi",
+  "security",
+  "runtime",
+  "application-security",
+  "observability",
+  "telemetry",
+  "behaviour",
+  "api-security",
+  "zubbl"
+]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: FastAPI",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries"
+]
+
+dependencies = [
+  "fastapi>=0.110.0",
+  "zubbl-runtime>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://zubbl.com"
+Documentation = "https://zubbl.com"
+[project.optional-dependencies]
+test = [
+  "httpx>=0.27.0",
+  "pytest>=8.0.0",
+  "pytest-asyncio>=0.23.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

zubbl_fastapi-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zubbl_fastapi-0.1.0/src/zubbl_fastapi/__init__.py

@@ -0,0 +1,37 @@
+from .integration import (
+    BlockResponseHandler,
+    DEFAULT_EXCLUDED_PATHS,
+    IdentityResolver,
+    MissingIdentityMode,
+    Zubbl,
+    ZubblFastAPIError,
+)
+from .endpoints import (
+    RouteCatalogue,
+    RouteCatalogueDiff,
+    RouteDescriptor,
+)
+from .identity import (
+    IdentityResolutionError,
+    identify_from_state,
+)
+from .middleware import ZubblMiddleware
+from .observation import RuntimeResponseObservation
+
+__all__ = [
+    "BlockResponseHandler",
+    "IdentityResolutionError",
+    "identify_from_state",
+    "DEFAULT_EXCLUDED_PATHS",
+    "IdentityResolver",
+    "MissingIdentityMode",
+    "RouteDescriptor",
+    "RouteCatalogueDiff",
+    "RouteCatalogue",
+    "RuntimeResponseObservation",
+    "Zubbl",
+    "ZubblFastAPIError",
+    "ZubblMiddleware",
+]
+
+__version__ = "0.1.0"

zubbl_fastapi-0.1.0/src/zubbl_fastapi/endpoints.py

@@ -0,0 +1,296 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
+
+
+def _normalise_path(value: str) -> str:
+    cleaned = value.strip()
+
+    if not cleaned:
+        raise ValueError("endpoint path must be a non-empty string")
+
+    if not cleaned.startswith("/"):
+        cleaned = f"/{cleaned}"
+
+    if len(cleaned) > 1:
+        cleaned = cleaned.rstrip("/")
+
+    return cleaned or "/"
+
+
+def _clean_optional_string(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+
+    cleaned = value.strip()
+    return cleaned or None
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class RouteDescriptor:
+    """
+    One stable application endpoint.
+
+    A FastAPI route supporting several methods becomes one descriptor per
+    method, giving every endpoint a deterministic path/method identity.
+    """
+
+    path: str
+    method: str
+    name: str
+    operation_id: str | None = None
+    tags: tuple[str, ...] = ()
+    include_in_schema: bool = True
+
+    def __post_init__(self) -> None:
+        path = _normalise_path(self.path)
+        method = self.method.strip().upper()
+        name = self.name.strip()
+
+        if not method:
+            raise ValueError("endpoint method must be a non-empty string")
+
+        if not name:
+            raise ValueError("endpoint name must be a non-empty string")
+
+        tags = tuple(
+            dict.fromkeys(
+                str(tag).strip()
+                for tag in self.tags
+                if str(tag).strip()
+            )
+        )
+
+        object.__setattr__(self, "path", path)
+        object.__setattr__(self, "method", method)
+        object.__setattr__(self, "name", name)
+        object.__setattr__(
+            self,
+            "operation_id",
+            _clean_optional_string(self.operation_id),
+        )
+        object.__setattr__(self, "tags", tags)
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return self.path, self.method
+
+    @property
+    def identifier(self) -> str:
+        return f"{self.method} {self.path}"
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "method": self.method,
+            "name": self.name,
+            "operation_id": self.operation_id,
+            "tags": list(self.tags),
+            "include_in_schema": self.include_in_schema,
+        }
+
+    @property
+    def fingerprint(self) -> str:
+        payload = json.dumps(
+            self.as_dict(),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+
+        return hashlib.sha256(payload).hexdigest()
+
+
+@dataclass(frozen=True, slots=True)
+class RouteCatalogueDiff:
+    added: tuple[RouteDescriptor, ...]
+    removed: tuple[RouteDescriptor, ...]
+    changed: tuple[
+        tuple[RouteDescriptor, RouteDescriptor],
+        ...,
+    ]
+
+    @property
+    def has_changes(self) -> bool:
+        return bool(self.added or self.removed or self.changed)
+
+
+@dataclass(frozen=True, slots=True)
+class RouteCatalogue:
+    routes: tuple[RouteDescriptor, ...]
+
+    def __post_init__(self) -> None:
+        ordered = tuple(
+            sorted(
+                self.routes,
+                key=lambda route: (
+                    route.path,
+                    route.method,
+                    route.name,
+                ),
+            )
+        )
+
+        keys = [route.key for route in ordered]
+
+        if len(keys) != len(set(keys)):
+            raise ValueError(
+                "route catalogue contains duplicate path/method entries"
+            )
+
+        object.__setattr__(self, "routes", ordered)
+
+    @classmethod
+    def empty(cls) -> RouteCatalogue:
+        return cls(routes=())
+
+    @classmethod
+    def from_app(
+        cls,
+        app: FastAPI,
+        *,
+        include_hidden: bool = False,
+    ) -> RouteCatalogue:
+        descriptors: list[RouteDescriptor] = []
+
+        for route in app.routes:
+            if not isinstance(route, APIRoute):
+                continue
+
+            if not include_hidden and not route.include_in_schema:
+                continue
+
+            methods = sorted(route.methods or ())
+
+            for method in methods:
+                if method in {"HEAD", "OPTIONS"}:
+                    continue
+
+                operation_id = (
+                    route.operation_id
+                    or getattr(route, "unique_id", None)
+                )
+
+                descriptors.append(
+                    RouteDescriptor(
+                        path=route.path,
+                        method=method,
+                        name=route.name,
+                        operation_id=operation_id,
+                        tags=tuple(route.tags or ()),
+                        include_in_schema=route.include_in_schema,
+                    )
+                )
+
+        return cls(routes=tuple(descriptors))
+
+    def __len__(self) -> int:
+        return len(self.routes)
+
+    def __iter__(self):
+        return iter(self.routes)
+
+    def lookup(
+        self,
+        path: str,
+        method: str,
+    ) -> RouteDescriptor | None:
+        key = (
+            _normalise_path(path),
+            method.strip().upper(),
+        )
+
+        for route in self.routes:
+            if route.key == key:
+                return route
+
+        return None
+
+    def lookup_by_name(
+        self,
+        name: str,
+    ) -> tuple[RouteDescriptor, ...]:
+        cleaned = name.strip()
+
+        return tuple(
+            route
+            for route in self.routes
+            if route.name == cleaned
+        )
+
+    def lookup_by_operation_id(
+        self,
+        operation_id: str,
+    ) -> tuple[RouteDescriptor, ...]:
+        cleaned = operation_id.strip()
+
+        return tuple(
+            route
+            for route in self.routes
+            if route.operation_id == cleaned
+        )
+
+    def as_list(self) -> list[dict[str, Any]]:
+        return [route.as_dict() for route in self.routes]
+
+    @property
+    def fingerprint(self) -> str:
+        payload = json.dumps(
+            self.as_list(),
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")
+
+        return hashlib.sha256(payload).hexdigest()
+
+    def diff(
+        self,
+        previous: RouteCatalogue,
+    ) -> RouteCatalogueDiff:
+        current_by_key = {
+            route.key: route
+            for route in self.routes
+        }
+        previous_by_key = {
+            route.key: route
+            for route in previous.routes
+        }
+
+        added = tuple(
+            current_by_key[key]
+            for key in sorted(
+                current_by_key.keys() - previous_by_key.keys()
+            )
+        )
+        removed = tuple(
+            previous_by_key[key]
+            for key in sorted(
+                previous_by_key.keys() - current_by_key.keys()
+            )
+        )
+
+        changed: list[
+            tuple[RouteDescriptor, RouteDescriptor]
+        ] = []
+
+        for key in sorted(
+            current_by_key.keys() & previous_by_key.keys()
+        ):
+            old = previous_by_key[key]
+            new = current_by_key[key]
+
+            if old != new:
+                changed.append((old, new))
+
+        return RouteCatalogueDiff(
+            added=added,
+            removed=removed,
+            changed=tuple(changed),
+        )

zubbl_fastapi-0.1.0/src/zubbl_fastapi/identity.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from starlette.requests import Request
+
+
+class IdentityResolutionError(ValueError):
+    """Raised when an identity helper is configured incorrectly."""
+
+
+def _resolve_attribute_path(
+    value: Any,
+    attribute_path: str,
+) -> Any:
+    current = value
+
+    for segment in attribute_path.split("."):
+        cleaned = segment.strip()
+
+        if not cleaned:
+            raise IdentityResolutionError(
+                "attribute_path contains an empty segment"
+            )
+
+        if current is None:
+            return None
+
+        if isinstance(current, dict):
+            current = current.get(cleaned)
+        else:
+            current = getattr(current, cleaned, None)
+
+    return current
+
+
+def identify_from_state(
+    attribute_path: str,
+) -> Callable[[Request], Any]:
+    """
+    Build an identity resolver from request.state.
+
+    Examples:
+        identify_from_state("user.id")
+        identify_from_state("external_user_id")
+    """
+    if not isinstance(attribute_path, str) or not attribute_path.strip():
+        raise IdentityResolutionError(
+            "attribute_path must be a non-empty string"
+        )
+
+    cleaned_path = attribute_path.strip()
+
+    def resolver(request: Request) -> Any:
+        return _resolve_attribute_path(
+            request.state,
+            cleaned_path,
+        )
+
+    return resolver