cybat-sdk 0.1.1__py3-none-any.whl

cybat_sdk/__init__.py

@@ -0,0 +1,5 @@
+from .collector import CybatCollector, CybatOptions, resolve_status_filter
+
+__all__ = ["CybatCollector", "CybatOptions", "resolve_status_filter"]
+
+__version__ = "0.1.0"

cybat_sdk/collector.py

@@ -0,0 +1,212 @@
+"""
+Buffers captured HTTP events and flushes them to ingest-api (behind API Gateway).
+Never raises into the host app -- a broken or unreachable ingest endpoint must
+never take down the app being instrumented. On repeated failure the batch is
+dropped rather than retried indefinitely (Pub/Sub is the durability layer on
+our side; this SDK only needs to survive transient network blips).
+
+Mirrors SDK/node/src/index.ts's CybatCollector -- same options, same defaults,
+same wire format. See SDK/README.md for the wire contract every language SDK
+implements identically.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from .redact import mask_body, snippet_around
+
+StatusFilterFn = Callable[[int], bool]
+# 'all' | 'errors' | a predicate -- see resolve_status_filter.
+StatusFilter = Union[str, StatusFilterFn]
+
+_DEFAULT_GCP_INGEST_URL = "https://gcp-ingest.cybat.co"
+_DEFAULT_AWS_INGEST_URL = "https://aws-ingest.cybat.co"
+_BODY_DEFAULT_BYTES = 2048
+_BODY_HARD_MAX_BYTES = 8192
+_CAPTURABLE_CONTENT_TYPE = re.compile(r"^(application/(json|[\w.+-]+\+json|x-www-form-urlencoded)|text/)", re.I)
+
+
+def resolve_status_filter(filt: Optional[StatusFilter]) -> StatusFilterFn:
+    """Resolves a StatusFilter option into a plain predicate, once, at construction."""
+    if callable(filt):
+        return filt
+    if filt == "errors":
+        return lambda status: status >= 400
+    return lambda status: True
+
+
+@dataclass
+class CybatOptions:
+    """
+    Python-facing options use snake_case (idiomatic here); the wire format each
+    event is serialized to is still the shared camelCase contract in
+    SDK/README.md -- that boundary is deliberate, not an inconsistency.
+    """
+
+    api_key: str
+    # The GCP project this app's traffic should be enforced against. Required for
+    # automatic blocking (VPC Firewall / Cloud Armor) -- without it, Cybat still
+    # detects and alerts on threats, but never touches infrastructure, since it has
+    # no project to act on. Also determines routing (mutually exclusive with
+    # aws_project_id -- one SDK instance targets one cloud).
+    gcp_project_id: Optional[str] = None
+    # NOT YET LIVE -- aws-ingest.cybat.co has no backend behind it yet. Setting this
+    # today means every batch fails to send until AWS-based ingestion ships.
+    aws_project_id: Optional[str] = None
+    # Optional label identifying which of the customer's services this is, shown on incidents.
+    service_name: Optional[str] = None
+    # Overrides cloud auto-detection entirely -- set this explicitly for local/staging testing.
+    ingest_url: Optional[str] = None
+    flush_interval_ms: int = 2000
+    max_batch_size: int = 100
+    # Retries on a failed send before the batch is dropped. Default: 2 (3 attempts total).
+    max_retries: int = 2
+    # Base delay in ms before the first retry; doubles on each subsequent retry
+    # (exponential backoff): 500ms then 1000ms by default.
+    retry_backoff_ms: int = 500
+    status_filter: StatusFilter = "all"
+    # Include the request body in each event. Default: off. See README's
+    # "Request bodies & privacy" -- redaction is not optional once this is on.
+    capture_body: bool = False
+    body_max_bytes: int = _BODY_DEFAULT_BYTES
+    body_status_filter: StatusFilter = "all"
+
+    def __post_init__(self) -> None:
+        if not self.api_key:
+            raise ValueError("[cybat-sdk] api_key is required")
+        self.body_max_bytes = min(_BODY_HARD_MAX_BYTES, max(256, self.body_max_bytes))
+        self.ingest_url = _resolve_ingest_url(self)
+
+
+def _resolve_ingest_url(opts: CybatOptions) -> str:
+    """
+    Picks which cloud's ingestion endpoint to send to. An explicit ingest_url
+    always wins (escape hatch for local/staging testing). Otherwise the choice
+    follows whichever project ID was configured -- gcp_project_id and
+    aws_project_id are mutually exclusive because one SDK instance represents one
+    app running in one cloud; setting both is almost certainly a copy-paste
+    mistake, not a deliberate multi-cloud single app.
+    """
+    if opts.ingest_url:
+        return opts.ingest_url
+    if opts.gcp_project_id and opts.aws_project_id:
+        raise ValueError(
+            "[cybat-sdk] Set only one of gcp_project_id or aws_project_id -- a single SDK "
+            "instance targets a single cloud. Use two instances for an app split across both."
+        )
+    if opts.aws_project_id:
+        return _DEFAULT_AWS_INGEST_URL
+    return _DEFAULT_GCP_INGEST_URL
+
+
+class CybatCollector:
+    def __init__(self, opts: CybatOptions) -> None:
+        self.opts = opts
+        self._buffer: List[Dict[str, Any]] = []
+        self._lock = threading.Lock()
+        self._should_capture = resolve_status_filter(opts.status_filter)
+        self._should_capture_body = resolve_status_filter(opts.body_status_filter)
+
+        self._stop_event = threading.Event()
+        self._timer_thread = threading.Thread(target=self._run_timer, daemon=True)
+        self._timer_thread.start()
+
+    def _run_timer(self) -> None:
+        interval_s = self.opts.flush_interval_ms / 1000
+        while not self._stop_event.wait(interval_s):
+            self.flush()
+
+    def wants(self, status: int) -> bool:
+        """Lets an adapter skip building an event that status_filter would discard anyway."""
+        return self._should_capture(status)
+
+    def capture_body_for(self, body: Any, content_type: Optional[str], status: int) -> Dict[str, Any]:
+        """
+        Redacts and caps a request body for inclusion in an event. Returns {} (never
+        the raw body) when capture is off, the response doesn't match
+        body_status_filter, the body is empty / binary / multipart, or redaction
+        fails for any reason.
+
+        Returned keys are the WIRE names (camelCase) -- this dict is merged
+        directly into the outgoing event.
+        """
+        if not self.opts.capture_body or not self._should_capture_body(status):
+            return {}
+        try:
+            if body is None or body == "" or body == {}:
+                return {}
+            if isinstance(body, (bytes, bytearray)):
+                return {}
+            if content_type and not _CAPTURABLE_CONTENT_TYPE.search(content_type):
+                return {}
+
+            masked = mask_body(body)
+            text = masked if isinstance(masked, str) else json.dumps(masked)
+            excerpt = snippet_around(text, self.opts.body_max_bytes)
+            result: Dict[str, Any] = {"body": excerpt}
+            if excerpt != text:
+                result["bodyTruncated"] = True
+            return result
+        except Exception:
+            return {}  # when in doubt, send nothing rather than something unredacted
+
+    def record(self, event: Dict[str, Any]) -> None:
+        """
+        Framework integrations call this unconditionally with every request's
+        captured event -- the status_filter check happens once, here, so every
+        integration gets identical filtering behavior for free.
+        """
+        if not self._should_capture(event.get("status", 0)):
+            return
+        should_flush = False
+        with self._lock:
+            self._buffer.append(event)
+            if len(self._buffer) >= self.opts.max_batch_size:
+                should_flush = True
+        if should_flush:
+            self.flush()
+
+    def flush(self) -> None:
+        with self._lock:
+            if not self._buffer:
+                return
+            batch, self._buffer = self._buffer, []
+        self._send(batch, 0)
+
+    def _send(self, batch: List[Dict[str, Any]], attempt: int) -> None:
+        try:
+            data = json.dumps(batch).encode("utf-8")
+            req = urllib.request.Request(
+                self.opts.ingest_url,
+                data=data,
+                method="POST",
+                headers={"Content-Type": "application/json", "x-api-key": self.opts.api_key},
+            )
+            with urllib.request.urlopen(req, timeout=10):
+                pass  # 2xx/3xx -- response body is never needed
+        except urllib.error.HTTPError as e:
+            if attempt < self.opts.max_retries:
+                return self._retry(batch, attempt)
+            print(f"[cybat-sdk] ingest rejected batch ({e.code}), dropping {len(batch)} event(s)")
+        except Exception as e:  # network error, timeout, DNS failure, etc.
+            if attempt < self.opts.max_retries:
+                return self._retry(batch, attempt)
+            print(f"[cybat-sdk] failed to reach ingest endpoint, dropping {len(batch)} event(s): {e}")
+
+    def _retry(self, batch: List[Dict[str, Any]], attempt: int) -> None:
+        """Exponential backoff: attempt 0 waits retry_backoff_ms, attempt 1 waits 2x that, etc."""
+        delay_s = (self.opts.retry_backoff_ms * (2**attempt)) / 1000
+        timer = threading.Timer(delay_s, self._send, args=(batch, attempt + 1))
+        timer.daemon = True
+        timer.start()
+
+    def stop(self) -> None:
+        """Stops the flush timer. Call on graceful shutdown if you need a clean exit."""
+        self._stop_event.set()

cybat_sdk/integrations/asgi.py

@@ -0,0 +1,143 @@
+"""
+ASGI middleware -- works with FastAPI, Starlette, or any raw ASGI app. No
+FastAPI/Starlette import needed: this speaks the ASGI protocol (scope /
+receive / send) directly, not a framework-specific middleware base class, so
+it works correctly with streaming responses too.
+
+    # FastAPI / Starlette
+    from cybat_sdk.integrations.asgi import CybatASGIMiddleware
+    app.add_middleware(CybatASGIMiddleware, api_key=os.environ["CYBAT_API_KEY"], gcp_project_id="my-gcp-project")
+
+    # Any other ASGI app
+    app = CybatASGIMiddleware(app, api_key=..., gcp_project_id=...)
+
+FastAPI/Starlette's `add_middleware(cls, **options)` instantiates `cls(app, **options)`,
+which is exactly this class's constructor -- so it plugs directly into their
+middleware stack with no adapter needed.
+
+Behind your own load balancer or reverse proxy? Configure Starlette's
+ProxyHeadersMiddleware (or your ASGI server's --proxy-headers /
+--forwarded-allow-ips) -- otherwise `scope["client"]` is your proxy's address,
+not the real client's.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import time
+from typing import Any, Dict, List, Optional
+
+from ..collector import CybatCollector, CybatOptions
+from ..redact import mask_string
+
+_UNCAPTURABLE_PREFIXES = ("multipart/form-data",)
+
+
+def _iso(epoch_s: float) -> str:
+    return (
+        datetime.datetime.fromtimestamp(epoch_s, tz=datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3]
+        + "Z"
+    )
+
+
+def _headers_dict(raw_headers: List[tuple]) -> Dict[str, str]:
+    out: Dict[str, str] = {}
+    for k, v in raw_headers:
+        key = k.decode("latin1").lower()
+        # Multiple headers with the same name (rare for the ones we read) --
+        # first one wins, matching how most frameworks expose a single value.
+        out.setdefault(key, v.decode("latin1"))
+    return out
+
+
+class CybatASGIMiddleware:
+    def __init__(self, app: Any, **options: Any) -> None:
+        self.app = app
+        self.opts = CybatOptions(**options)
+        self.collector = CybatCollector(self.opts)
+
+    async def __call__(self, scope: dict, receive, send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        start = time.time()
+        state: Dict[str, Any] = {"status": 200, "headers": {}}
+        request_body_chunks: List[bytes] = []
+
+        async def receive_wrapper():
+            message = await receive()
+            if self.opts.capture_body and message.get("type") == "http.request":
+                body = message.get("body")
+                if body:
+                    request_body_chunks.append(body)
+            return message
+
+        async def send_wrapper(message: dict):
+            if message.get("type") == "http.response.start":
+                state["status"] = message.get("status", 200)
+                state["headers"] = _headers_dict(message.get("headers", []))
+            await send(message)
+
+        await self.app(scope, receive_wrapper, send_wrapper)
+
+        try:
+            self._record(scope, state, request_body_chunks, start)
+        except Exception:
+            pass  # instrumentation must never break the host app
+
+    def _record(self, scope: dict, state: dict, body_chunks: List[bytes], start: float) -> None:
+        status = state["status"]
+        if not self.collector.wants(status):
+            return
+
+        req_headers = _headers_dict(scope.get("headers", []))
+        qs = (scope.get("query_string") or b"").decode("utf-8", errors="replace")
+        url = f"{scope.get('path', '')}?{qs}" if qs else scope.get("path", "")
+        client = scope.get("client") or (None, None)
+
+        response_headers = state["headers"]
+        try:
+            bytes_sent = int(response_headers.get("content-length", 0) or 0)
+        except ValueError:
+            bytes_sent = 0
+
+        event: Dict[str, Any] = {
+            "method": scope.get("method", ""),
+            "url": mask_string(url),
+            "status": status,
+            "remoteIp": client[0] or "unknown",
+            "latencyMs": int((time.time() - start) * 1000),
+            "bytesSent": bytes_sent,
+            "timestamp": _iso(start),
+            "projectId": self.opts.gcp_project_id or self.opts.aws_project_id,
+            "serviceName": self.opts.service_name,
+        }
+        user_agent = req_headers.get("user-agent")
+        referer = req_headers.get("referer") or req_headers.get("referrer")
+        if user_agent:
+            event["userAgent"] = mask_string(user_agent)
+        if referer:
+            event["referer"] = mask_string(referer)
+
+        content_type = req_headers.get("content-type")
+        event.update(self.collector.capture_body_for(_parse_body(body_chunks, content_type), content_type, status))
+        self.collector.record(event)
+
+
+def _parse_body(chunks: List[bytes], content_type: Optional[str]) -> Any:
+    if not chunks:
+        return None
+    ct = (content_type or "").lower()
+    if any(ct.startswith(p) for p in _UNCAPTURABLE_PREFIXES):
+        return None  # never touch multipart -- may hold large file uploads
+    raw = b"".join(chunks)
+    if not raw:
+        return None
+    if "json" in ct:
+        try:
+            return json.loads(raw.decode("utf-8"))
+        except Exception:
+            return None
+    return raw.decode("utf-8", errors="replace")

cybat_sdk/integrations/django.py

@@ -0,0 +1,142 @@
+"""
+Django integration.
+
+    # settings.py
+    MIDDLEWARE = [..., "cybat_sdk.integrations.django.CybatMiddleware"]
+    CYBAT_API_KEY = os.environ["CYBAT_API_KEY"]
+    CYBAT_GCP_PROJECT_ID = "my-gcp-project"   # optional -- enables automatic blocking
+
+Django instantiates middleware classes itself with no way to pass constructor
+kwargs, so configuration comes from `django.conf.settings` instead of a
+function call, unlike the Flask/ASGI integrations. Every `CYBAT_*` setting
+maps to the matching CybatOptions field (see the table in the package README).
+
+Requires Django to be installed already -- it is not a dependency of
+cybat-sdk itself, this module just isn't importable without it.
+
+Behind your own load balancer or reverse proxy? Configure Django's
+SECURE_PROXY_SSL_HEADER / trust your proxy's X-Forwarded-For the way you
+already do for `request.META["REMOTE_ADDR"]` -- otherwise every event will
+report the proxy's address instead of the real client's.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+import time
+from typing import Any, Optional
+
+from django.conf import settings
+
+from ..collector import CybatCollector, CybatOptions
+from ..redact import mask_string
+
+_collector: Optional[CybatCollector] = None
+_opts: Optional[CybatOptions] = None
+
+
+def _options_from_settings() -> CybatOptions:
+    return CybatOptions(
+        api_key=getattr(settings, "CYBAT_API_KEY", ""),
+        gcp_project_id=getattr(settings, "CYBAT_GCP_PROJECT_ID", None),
+        aws_project_id=getattr(settings, "CYBAT_AWS_PROJECT_ID", None),
+        service_name=getattr(settings, "CYBAT_SERVICE_NAME", None),
+        ingest_url=getattr(settings, "CYBAT_INGEST_URL", None),
+        flush_interval_ms=getattr(settings, "CYBAT_FLUSH_INTERVAL_MS", 2000),
+        max_batch_size=getattr(settings, "CYBAT_MAX_BATCH_SIZE", 100),
+        max_retries=getattr(settings, "CYBAT_MAX_RETRIES", 2),
+        retry_backoff_ms=getattr(settings, "CYBAT_RETRY_BACKOFF_MS", 500),
+        status_filter=getattr(settings, "CYBAT_STATUS_FILTER", "all"),
+        capture_body=getattr(settings, "CYBAT_CAPTURE_BODY", False),
+        body_max_bytes=getattr(settings, "CYBAT_BODY_MAX_BYTES", 2048),
+        body_status_filter=getattr(settings, "CYBAT_BODY_STATUS_FILTER", "all"),
+    )
+
+
+def get_collector() -> CybatCollector:
+    """Returns the process-wide collector, creating it from settings on first use. Exposed so callers can flush()/stop() it, e.g. in tests or on shutdown."""
+    global _collector, _opts
+    if _collector is None:
+        _opts = _options_from_settings()
+        _collector = CybatCollector(_opts)
+    return _collector
+
+
+def _extract_body(request) -> Any:
+    ct = (request.content_type or "").lower()
+    if "multipart/form-data" in ct:
+        return None  # never touch multipart -- may hold large file uploads
+    if "json" in ct:
+        try:
+            return json.loads(request.body.decode("utf-8"))
+        except Exception:
+            return None
+    if "x-www-form-urlencoded" in ct:
+        # Reading request.POST (not .body) avoids Django's "you cannot access
+        # body after reading from request's data stream" for form submissions,
+        # since Django's own form parser already consumed the stream for us.
+        return dict(request.POST)
+    try:
+        return request.body.decode("utf-8", errors="replace")
+    except Exception:
+        return None
+
+
+def _iso(epoch_s: float) -> str:
+    return (
+        datetime.datetime.fromtimestamp(epoch_s, tz=datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3]
+        + "Z"
+    )
+
+
+class CybatMiddleware:
+    """Django middleware -- add to MIDDLEWARE, configuration comes from settings.py (see module docstring)."""
+
+    def __init__(self, get_response):
+        self.get_response = get_response
+        self.collector = get_collector()
+        self.opts = _opts
+
+    def __call__(self, request):
+        start = time.time()
+        response = self.get_response(request)
+        try:
+            self._record(request, response, start)
+        except Exception:
+            pass  # instrumentation must never break the host app
+        return response
+
+    def _record(self, request, response, start: float) -> None:
+        if not self.collector.wants(response.status_code):
+            return
+
+        qs = request.META.get("QUERY_STRING", "")
+        url = f"{request.path}?{qs}" if qs else request.path
+        referer = request.META.get("HTTP_REFERER")
+        user_agent = request.META.get("HTTP_USER_AGENT")
+
+        content_length = response.get("Content-Length")
+        try:
+            bytes_sent = int(content_length) if content_length is not None else len(getattr(response, "content", b""))
+        except (TypeError, ValueError):
+            bytes_sent = 0
+
+        event = {
+            "method": request.method,
+            "url": mask_string(url),
+            "status": response.status_code,
+            "remoteIp": request.META.get("REMOTE_ADDR", "unknown"),
+            "latencyMs": int((time.time() - start) * 1000),
+            "bytesSent": bytes_sent,
+            "timestamp": _iso(start),
+            "projectId": self.opts.gcp_project_id or self.opts.aws_project_id,
+            "serviceName": self.opts.service_name,
+        }
+        if user_agent:
+            event["userAgent"] = mask_string(user_agent)
+        if referer:
+            event["referer"] = mask_string(referer)
+
+        event.update(self.collector.capture_body_for(_extract_body(request), request.content_type, response.status_code))
+        self.collector.record(event)

cybat_sdk/integrations/flask.py

@@ -0,0 +1,102 @@
+"""
+Flask integration.
+
+    from flask import Flask
+    from cybat_sdk.integrations.flask import init_app
+
+    app = Flask(__name__)
+    init_app(app, api_key=os.environ["CYBAT_API_KEY"], gcp_project_id="my-gcp-project")
+
+Requires Flask to be installed in your project already -- it is not a
+dependency of cybat-sdk itself, this module just isn't importable without it.
+
+If your app sits behind a load balancer or reverse proxy you own, wrap it with
+Werkzeug's ProxyFix (or configure your proxy to set X-Forwarded-For correctly)
+-- otherwise `request.remote_addr` resolves to the proxy's address instead of
+the real client, and every event will look like it came from one source.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+from flask import Flask, Response, g, request
+
+from ..collector import CybatCollector, CybatOptions
+from ..redact import mask_string
+
+_UNCAPTURABLE_CONTENT = ("multipart/form-data",)
+
+
+def _extract_body(req) -> Any:
+    ct = (req.content_type or "").lower()
+    if any(u in ct for u in _UNCAPTURABLE_CONTENT):
+        return None  # never touch multipart -- may hold large file uploads
+    if "json" in ct:
+        return req.get_json(silent=True)
+    if "x-www-form-urlencoded" in ct:
+        return req.form.to_dict()
+    try:
+        # capture_body_for's own content-type check drops anything that isn't
+        # actually text/json/form, so a generic text read here is harmless.
+        return req.get_data(as_text=True)
+    except Exception:
+        return None
+
+
+def init_app(app: Flask, **options: Any) -> CybatCollector:
+    """Wires the collector into `app` via before_request/after_request hooks. Returns the collector (call .stop() on shutdown if you need a clean exit)."""
+    opts = CybatOptions(**options)
+    collector = CybatCollector(opts)
+
+    @app.before_request
+    def _cybat_mark_start() -> None:
+        g._cybat_start = time.time()
+
+    @app.after_request
+    def _cybat_record(response: Response) -> Response:
+        try:
+            _build_and_record(collector, opts, response)
+        except Exception:
+            pass  # instrumentation must never break the host app
+        return response
+
+    return collector
+
+
+def _build_and_record(collector: CybatCollector, opts: CybatOptions, response: Response) -> None:
+    if not collector.wants(response.status_code):
+        return
+
+    start: float = getattr(g, "_cybat_start", time.time())
+    qs = request.query_string.decode("utf-8", errors="replace")
+    url = f"{request.path}?{qs}" if qs else request.path
+
+    referer = request.headers.get("Referer") or request.headers.get("Referrer")
+    user_agent = request.headers.get("User-Agent")
+
+    event = {
+        "method": request.method,
+        "url": mask_string(url),
+        "status": response.status_code,
+        "remoteIp": request.remote_addr or "unknown",
+        "latencyMs": int((time.time() - start) * 1000),
+        "bytesSent": response.content_length or 0,
+        "timestamp": _iso(start),
+        "projectId": opts.gcp_project_id or opts.aws_project_id,
+        "serviceName": opts.service_name,
+    }
+    if user_agent:
+        event["userAgent"] = mask_string(user_agent)
+    if referer:
+        event["referer"] = mask_string(referer)
+
+    event.update(collector.capture_body_for(_extract_body(request), request.content_type, response.status_code))
+    collector.record(event)
+
+
+def _iso(epoch_s: float) -> str:
+    import datetime
+
+    return datetime.datetime.fromtimestamp(epoch_s, tz=datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"

cybat_sdk/redact.py

@@ -0,0 +1,309 @@
+"""
+Layer 1 of the data-protection stack: fast, local, dependency-free redaction.
+
+NOTE: this is a line-for-line port of SDK/node/src/redact.ts (also duplicated in
+soc-ai-agent/services/redact.ts and intelligence-api/services/redact.ts, separate
+deployables, no shared package) — keep all four in sync. Same patterns, same
+precedence, same idempotence guarantee.
+
+The SDK runs this on the customer's side BEFORE anything leaves their
+infrastructure; the server runs it again (the SDK may be old, modified or
+hostile) before persisting, before prompting the model, and before alerts. It
+is therefore idempotent: masking already-masked text leaves it unchanged.
+
+Design point: a redacted secret is replaced by a *shape descriptor*, not just
+"[REDACTED]" -- `[REDACTED len=13 sus=quote,comment]`. Blanking a `password`
+field entirely would also blank the SQL injection an attacker put in it; the
+descriptor keeps the attack signal (length + which suspicious character
+classes it contained) without keeping the value.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, List, Tuple, Optional
+from urllib.parse import unquote_plus
+
+REDACTED = "[REDACTED"
+
+# -- Attack-shape descriptor (content-free) ----------------------------------
+
+_SUSPICIOUS: List[Tuple[str, re.Pattern]] = [
+    ("quote", re.compile(r"""['"`]|%27|%22""", re.I)),
+    ("comment", re.compile(r"--|/\*|#\s*$")),
+    ("sqlkw", re.compile(r"\b(union|select|insert|update|delete|drop|sleep|benchmark|waitfor)\b", re.I)),
+    ("angle", re.compile(r"[<>]|%3c|%3e", re.I)),
+    ("semicolon", re.compile(r";")),
+    ("traversal", re.compile(r"\.\.[/\\]|%2e%2e", re.I)),
+    ("cmdchar", re.compile(r"[|&$`]|\$\(")),
+    ("template", re.compile(r"\{\{|\$\{|<%")),
+    ("nullbyte", re.compile(r"%00|\x00")),
+]
+
+
+def redacted_shape(value: Any) -> str:
+    """`[REDACTED len=N sus=a,b]` -- no characters of the original survive."""
+    s = "" if value is None else str(value)
+    sus = [name for name, pat in _SUSPICIOUS if pat.search(s)]
+    suffix = f" sus={','.join(sus)}" if sus else ""
+    return f"{REDACTED} len={len(s)}{suffix}]"
+
+
+# -- Credit cards (Luhn) ------------------------------------------------------
+
+def luhn_valid(digits: str) -> bool:
+    if not re.fullmatch(r"\d{13,19}", digits):
+        return False
+    total = 0
+    alt = False
+    for ch in reversed(digits):
+        n = ord(ch) - 48
+        if alt:
+            n *= 2
+            if n > 9:
+                n -= 9
+        total += n
+        alt = not alt
+    return total % 10 == 0
+
+
+def _mask_card(digits: str) -> str:
+    return f"XXXX-XXXX-XXXX-{digits[-4:]}"
+
+
+# -- Emails --------------------------------------------------------------------
+
+def mask_email(local: str, domain: str) -> str:
+    first = local[0] if local else ""
+    last = local[-1] if len(local) > 2 else ""
+    return f"{first}***{last}@{domain}"
+
+
+# `*` is in the local-part class so an already-masked address matches as a whole
+# (and is then left alone), instead of its tail being re-masked.
+# {1,64} is the RFC limit for a local part -- and, more to the point, it makes the
+# scan linear: an unbounded `+` re-scans the whole remaining run from every start
+# offset.
+_EMAIL_RE = re.compile(
+    r"([A-Za-z0-9._%+*-]{1,64})(?:@|%40)([A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63})*\.[A-Za-z]{2,24})"
+)
+_CARD_RE = re.compile(r"\b\d(?:[ -]?\d){12,18}\b")
+_JWT_RE = re.compile(r"\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]*")
+_BEARER_RE = re.compile(r"\b(Bearer|Basic)\s+(?!\[REDACTED)[A-Za-z0-9._~+/=-]{8,}", re.I)
+_PRIVKEY_RE = re.compile(r"-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)")
+_KEY_TOKEN_RES: List[re.Pattern] = [
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),  # AWS access key id
+    re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b"),  # Google API key
+    re.compile(r"\bgh[pousr]_[A-Za-z0-9]{36,}\b"),  # GitHub tokens
+    re.compile(r"\bxox[abprs]-[A-Za-z0-9-]{10,}\b"),  # Slack tokens
+    re.compile(r"\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}\b"),  # Stripe keys
+]
+
+# key=value pairs whose *name* says the value is a secret (URL query strings, form
+# bodies, cookie-style strings). The leading class stops `sort_key=` and `monkey=`
+# from matching. The value runs to the next `&`, `#`, newline or "; " --
+# deliberately NOT stopping at quotes or spaces, because a secret (or an
+# attacker's payload standing in for one) routinely contains them, and stopping
+# early would leave the rest of it unmasked.
+_PARAM_SECRET_RE = re.compile(
+    r"((?:^|[?&;,\s\"'])(?:access[_-]?token|refresh[_-]?token|id[_-]?token|token|api[_-]?key|apikey|"
+    r"client[_-]?secret|secret|password|passwd|passphrase|pwd|auth|authorization|session(?:[_-]?id)?|"
+    r"sid|signature|sig|key|credential|cc[_-]?num(?:ber)?|card[_-]?(?:number|no|num)?|cvv|cvc|ssn|iban)=)"
+    r"((?:(?!;\s)[^&#\r\n])+)",
+    re.I,
+)
+
+# Input is attacker-controlled and some patterns (emails) are quadratic on long
+# runs with no delimiter, so bound the work. Anything longer is cut, not skipped:
+# dropping the tail is safe; leaving it unscanned would not be.
+_MAX_INPUT_CHARS = 65536
+
+# `"key": "value"` pairs inside JSON text. Needed on top of mask_value because a
+# body that was truncated mid-way (the SDK caps bodies) no longer parses as JSON,
+# and this is the only pass left that can still see its keys. Bounded quantifiers
+# keep it linear; the key test is the same one mask_value uses.
+_JSON_PAIR_RE = re.compile(r'"([^"\\]{1,64})"(\s*:\s*)(?:"((?:[^"\\]|\\.){0,4000})"|(-?\d{1,25}))')
+
+_SENSITIVE_KEY_RE = re.compile(
+    r"(pass|pwd|secret|token|auth|cookie|session|credential|private|api[_-]?key|apikey|card|cvv|cvc|ssn|iban|\bpin\b)",
+    re.I,
+)
+_CARD_KEY_RE = re.compile(r"(card|cc[_-]?num|ccnum|pan)", re.I)
+
+
+def _safe_decode(v: str) -> str:
+    try:
+        return unquote_plus(v)
+    except Exception:
+        return v
+
+
+def mask_string(text: Optional[str]) -> Optional[str]:
+    """Redacts secrets and personal data inside free text. Idempotent."""
+    if not text:
+        return text
+    s = text if len(text) <= _MAX_INPUT_CHARS else f"{text[:_MAX_INPUT_CHARS]}\u2026[truncated]"
+
+    s = _PRIVKEY_RE.sub(f"{REDACTED} private-key]", s)
+    s = _JWT_RE.sub(f"{REDACTED} jwt]", s)
+    s = _BEARER_RE.sub(lambda m: f"{m.group(1)} {REDACTED}]", s)
+    for pat in _KEY_TOKEN_RES:
+        s = pat.sub(f"{REDACTED} key]", s)
+
+    def _param_repl(m: "re.Match") -> str:
+        prefix, value = m.group(1), m.group(2)
+        if value.startswith(REDACTED):
+            return m.group(0)
+        return f"{prefix}{redacted_shape(_safe_decode(value))}"
+
+    s = _PARAM_SECRET_RE.sub(_param_repl, s)
+
+    def _json_pair_repl(m: "re.Match") -> str:
+        key, colon, str_val, num_val = m.group(1), m.group(2), m.group(3), m.group(4)
+        if not _SENSITIVE_KEY_RE.search(key):
+            return m.group(0)
+        raw = str_val if str_val is not None else (num_val if num_val is not None else "")
+        if raw.startswith(REDACTED) or raw.startswith("XXXX-XXXX-XXXX-"):
+            return m.group(0)
+        digits = re.sub(r"\D", "", raw)
+        masked = _mask_card(digits) if _CARD_KEY_RE.search(key) and len(digits) >= 12 else redacted_shape(raw)
+        return f'"{key}"{colon}"{masked}"'
+
+    s = _JSON_PAIR_RE.sub(_json_pair_repl, s)
+
+    def _card_repl(m: "re.Match") -> str:
+        digits = re.sub(r"[ -]", "", m.group(0))
+        return _mask_card(digits) if luhn_valid(digits) else m.group(0)
+
+    s = _CARD_RE.sub(_card_repl, s)
+
+    def _email_repl(m: "re.Match") -> str:
+        local, domain = m.group(1), m.group(2)
+        return m.group(0) if "***" in local else mask_email(local, domain)
+
+    s = _EMAIL_RE.sub(_email_repl, s)
+
+    return s
+
+
+# -- Structured values (parsed JSON / form bodies) ----------------------------
+
+_MAX_DEPTH = 6
+_MAX_ITEMS = 50
+
+
+def mask_value(value: Any, depth: int = 0) -> Any:
+    """
+    Deep-masks a parsed body. Values under sensitive key names become a shape
+    descriptor (card-number fields keep only the last 4 digits); every other
+    string goes through mask_string. Depth and width are bounded so a hostile
+    payload can't make this expensive.
+    """
+    if value is None:
+        return value
+    if isinstance(value, str):
+        return mask_string(value)
+    if isinstance(value, bool) or isinstance(value, (int, float)):
+        return value
+    if depth >= _MAX_DEPTH:
+        return f"{REDACTED} depth-limit]"
+
+    if isinstance(value, (list, tuple)):
+        out = [mask_value(v, depth + 1) for v in list(value)[:_MAX_ITEMS]]
+        if len(value) > _MAX_ITEMS:
+            out.append(f"\u2026[{len(value) - _MAX_ITEMS} more items]")
+        return out
+
+    if isinstance(value, dict):
+        out: dict = {}
+        entries = list(value.items())
+        for k, v in entries[:_MAX_ITEMS]:
+            if _SENSITIVE_KEY_RE.search(str(k)) and isinstance(v, (str, int, float)) and not isinstance(v, bool):
+                raw = str(v)
+                if raw.startswith(REDACTED) or raw.startswith("XXXX-XXXX-XXXX-"):
+                    out[k] = raw  # already masked
+                    continue
+                digits = re.sub(r"\D", "", raw)
+                out[k] = _mask_card(digits) if _CARD_KEY_RE.search(str(k)) and len(digits) >= 12 else redacted_shape(raw)
+            else:
+                out[k] = mask_value(v, depth + 1)
+        if len(entries) > _MAX_ITEMS:
+            out["\u2026"] = f"{len(entries) - _MAX_ITEMS} more keys"
+        return out
+
+    return str(value)
+
+
+def mask_body(body: Any) -> Any:
+    """
+    Masks a request body of unknown shape: an already-parsed object, JSON text,
+    form-encoded text, or plain / truncated text. Shared by the SDK (client
+    side, before anything is sent) and the server (second pass), so both apply
+    the same rules.
+    """
+    if body is None:
+        return body
+    if not isinstance(body, str):
+        return mask_value(body)
+    trimmed = body.strip()
+    if trimmed.startswith("{") or trimmed.startswith("["):
+        try:
+            return json.dumps(mask_value(json.loads(trimmed)))
+        except (ValueError, TypeError):
+            pass  # truncated JSON -- text pass below
+    return mask_string(body)
+
+
+# -- Truncation (Layer 2) -----------------------------------------------------
+
+def _byte_len(s: str) -> int:
+    return len(s.encode("utf-8"))
+
+
+def cap_text(s: str, max_bytes: int) -> str:
+    """Byte-aware cap. Appends a marker so a reader knows content was dropped."""
+    if _byte_len(s) <= max_bytes:
+        return s
+    raw = s.encode("utf-8")
+    head_bytes = raw[: max(0, max_bytes - 32)]
+    # errors='ignore' silently drops a multi-byte sequence cut mid-character --
+    # equivalent to the Node version's Buffer decode + strip-trailing-replacement-char.
+    head = head_bytes.decode("utf-8", errors="ignore")
+    dropped = _byte_len(s) - _byte_len(head)
+    return f"{head}\u2026[truncated {dropped} bytes]"
+
+
+_TRIGGER_RES: List[re.Pattern] = [
+    re.compile(r"'\s*(or|and)\s+['\d]", re.I),
+    re.compile(r"union\s+select", re.I),
+    re.compile(r"<\s*script", re.I),
+    re.compile(r"on\w+\s*=", re.I),
+    re.compile(r"\.\.[/\\]"),
+    re.compile(r"\$\{jndi", re.I),
+    re.compile(r";\s*(cat|ls|curl|wget|nc|bash|sh)\b", re.I),
+    re.compile(r"(ignore|disregard)\s+(all\s+)?(previous|prior)", re.I),
+    re.compile(r"169\.254\.169\.254|metadata\.google\.internal", re.I),
+    re.compile(r"--\s*$", re.M),
+    re.compile(r"%27|%3c\s*script", re.I),
+]
+
+
+def snippet_around(text: str, max_bytes: int) -> str:
+    """
+    Keeps at most `max_bytes` of `text`, windowed around the first thing that
+    looks like the reason it was flagged (injection marker, traversal, SSRF
+    target...) so a capped payload still shows the analyst the interesting part
+    rather than its first N bytes. Falls back to the head when nothing stands out.
+    """
+    if _byte_len(text) <= max_bytes:
+        return text
+    at = -1
+    for pat in _TRIGGER_RES:
+        m = pat.search(text)
+        if m and (at == -1 or m.start() < at):
+            at = m.start()
+    if at <= max_bytes / 4:
+        return cap_text(text, max_bytes)
+    start = max(0, at - max_bytes // 4)
+    return f"\u2026{cap_text(text[start:], max_bytes - 3)}"

cybat_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: cybat-sdk
+Version: 0.1.1
+Summary: Cybat SDK for Python — WSGI/ASGI middleware that reports HTTP traffic directly to the Cybat Intelligence Engine
+License-Expression: MIT
+Project-URL: Homepage, https://cybat.co
+Project-URL: Documentation, https://cybat.co/#/docs
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# cybat-sdk (Python)
+
+Flask, Django and ASGI (FastAPI / Starlette / any ASGI app) integration for the Cybat Intelligence Engine. Captures HTTP traffic your app already receives and reports it directly to Cybat — no GCP org-level log sink required.
+
+## Install
+
+```bash
+pip install cybat-sdk
+```
+
+No required dependencies — Flask/Django/etc. are assumed already installed by your project; only the integration module for the framework you actually use imports it.
+
+## Usage
+
+### Flask
+
+```python
+from flask import Flask
+from cybat_sdk.integrations.flask import init_app
+
+app = Flask(__name__)
+init_app(app,
+    api_key=os.environ["CYBAT_API_KEY"],
+    gcp_project_id="my-gcp-project",  # enables automatic blocking — see below
+    service_name="checkout-api",      # optional, just a label on incidents
+)
+```
+
+### Django
+
+Django instantiates middleware classes itself with no way to pass constructor kwargs, so configuration comes from `settings.py` instead of a function call:
+
+```python
+# settings.py
+MIDDLEWARE = [
+    # ... your other middleware ...
+    "cybat_sdk.integrations.django.CybatMiddleware",
+]
+CYBAT_API_KEY = os.environ["CYBAT_API_KEY"]
+CYBAT_GCP_PROJECT_ID = "my-gcp-project"  # optional, enables automatic blocking
+```
+
+Every option has a `CYBAT_*` settings equivalent — see [Options](#options) below for the full list; the Django setting name is `CYBAT_` + the option name upper-cased (`retry_backoff_ms` → `CYBAT_RETRY_BACKOFF_MS`).
+
+### FastAPI / Starlette / any ASGI app
+
+```python
+from cybat_sdk.integrations.asgi import CybatASGIMiddleware
+
+app.add_middleware(CybatASGIMiddleware,
+    api_key=os.environ["CYBAT_API_KEY"],
+    gcp_project_id="my-gcp-project",
+)
+```
+
+This speaks the raw ASGI protocol (`scope`/`receive`/`send`) directly rather than wrapping a framework-specific base class, so it works correctly with streaming responses too, and needs no FastAPI/Starlette import. `add_middleware(cls, **options)` instantiates `cls(app, **options)`, which is exactly this class's constructor — no adapter needed. For a bare ASGI app without that helper: `app = CybatASGIMiddleware(app, api_key=...)`.
+
+Create an API key from the Intelligence Dashboard → **API Keys**. It's shown once at creation — store it as a secret (`CYBAT_API_KEY`), it can't be retrieved again.
+
+## Multi-cloud routing
+
+Set **one** of `gcp_project_id` or `aws_project_id` — never both on the same SDK instance. Which one you set decides where data is sent, automatically:
+
+| You set | Data goes to | Status |
+|---------|--------------|--------|
+| `gcp_project_id` (or neither) | `gcp-ingest.cybat.co` | Live |
+| `aws_project_id` | `aws-ingest.cybat.co` | **Not yet implemented** — batches will fail to send until AWS-based ingestion ships |
+
+An app that runs in both clouds needs two SDK instances, one per cloud — not one instance with both fields set (the constructor raises if you do that, since it's ambiguous which cloud's infrastructure should be enforced against).
+
+## ⚠️ Automatic blocking requires `gcp_project_id`
+
+Cybat classifies and alerts on threats regardless of `gcp_project_id`. But **automatically blocking** a malicious IP (VPC Firewall / Cloud Armor) requires knowing which GCP project to act on — your app might not even be hosted on GCP, so there's no way to infer this from the traffic itself. If you omit `gcp_project_id`, threats are still detected and you still get alerted, but nothing gets blocked automatically.
+
+To enable blocking:
+1. Set `gcp_project_id` to the GCP project your app's infrastructure lives in.
+2. Grant `soc-ai-agent@cybat-public.iam.gserviceaccount.com` the `roles/compute.securityAdmin` and `roles/compute.networkViewer` roles on that project (a Cloud Shell command for this is shown in the Intelligence Dashboard onboarding flow).
+
+## ⚠️ Behind a load balancer or reverse proxy?
+
+Each integration resolves the client IP from the framework's own notion of it (Flask's `request.remote_addr`, Django's `request.META["REMOTE_ADDR"]`, the ASGI `scope["client"]`), which reflects the *direct* TCP peer. If your app sits behind your own load balancer, CDN, or reverse proxy, configure that framework's standard mechanism for trusting `X-Forwarded-For` — otherwise every request reports the proxy's IP instead of the real client, and Cybat won't be able to tell your traffic apart:
+
+- **Flask**: wrap your WSGI app with Werkzeug's `ProxyFix`.
+- **Django**: set `SECURE_PROXY_SSL_HEADER` / put a proxy-aware middleware before Cybat's in `MIDDLEWARE`, per Django's deployment docs.
+- **ASGI**: use Starlette's/Uvicorn's `--proxy-headers --forwarded-allow-ips` (or `ProxyHeadersMiddleware`).
+
+## Options
+
+All three integrations take the same options (Flask/ASGI as keyword arguments, Django as `CYBAT_*` settings):
+
+```python
+{
+    "api_key": str,              # required
+    "gcp_project_id": str,       # enables automatic blocking + routes to GCP — see above
+    "aws_project_id": str,       # routes to AWS — NOT YET LIVE, see "Multi-cloud routing"
+    "service_name": str,         # optional label shown on incidents
+    "ingest_url": str,           # overrides cloud auto-detection entirely; default depends on gcp_project_id/aws_project_id
+    "flush_interval_ms": 2000,
+    "max_batch_size": 100,       # flushes immediately at this size
+    "max_retries": 2,            # a batch is dropped, not queued forever, after this
+    "retry_backoff_ms": 500,     # base delay before the first retry; doubles each retry (exponential)
+    "status_filter": "all",      # "all" | "errors" | a callable (status: int) -> bool
+    "capture_body": False,       # send a redacted excerpt of the request body — see "Request bodies & privacy"
+    "body_max_bytes": 2048,      # default 2048, max 8192 — cap on the body excerpt after redaction
+    "body_status_filter": "all", # capture bodies only for matching responses
+}
+```
+
+`status_filter` controls which captured requests actually get sent:
+- `"all"` (default) — every request, regardless of status code.
+- `"errors"` — only 4xx/5xx. Use this to cut ingestion volume/cost on high-traffic apps where 2xx telemetry isn't needed — Cybat still classifies and alerts on threats using only error responses, the same signal the old GCP Log Sink integration filtered down to.
+- A callable — full control, e.g. `lambda status: status != 304` to drop cache-hit noise but keep everything else, 2xx included.
+
+## Request bodies & privacy
+
+Off by default. Set `capture_body=True` to include the request body in each event — that's where SQL/command injection, credential stuffing and prompt-injection against LLM-backed endpoints actually show up, so it meaningfully improves detection. It also means request content leaves your infrastructure, so **redaction runs in your process, before an event is even buffered, and can't be turned off** once capture is on:
+
+| What | Becomes |
+|------|---------|
+| Emails | `j***n@example.com` |
+| Card numbers (Luhn-checked, 13–19 digits) | `XXXX-XXXX-XXXX-1234` |
+| JWTs, `Bearer …` / `Basic …` tokens | `[REDACTED jwt]`, `Bearer [REDACTED]` |
+| Provider keys (AWS, Google, GitHub, Slack, Stripe) and PEM private keys | `[REDACTED key]` |
+| The value of any field named like a secret (`password`, `token`, `secret`, `authorization`, `cookie`, `session`, `api_key`, `card`, `cvv`, `ssn`, `iban`…), in JSON, form bodies and query strings | `[REDACTED len=13 sus=quote,comment]` |
+
+A redacted secret is replaced by a **content-free shape**, not blanked: its length plus which kinds of attack characters it contained (`quote`, `comment`, `sqlkw`, `angle`, `semicolon`, `traversal`, `cmdchar`, `template`, `nullbyte`). That's deliberate — if you blanked a `password` field entirely you'd also blank the SQL injection an attacker typed into it. With the shape, Cybat can still see "a 14-character password containing quote, comment and SQL-keyword characters" without ever seeing the value.
+
+- JSON, form-encoded and text bodies only. Multipart, binary, and empty bodies are always skipped, regardless of `capture_body`.
+- The excerpt is capped at `body_max_bytes` after redaction, centered on the most attack-looking part rather than just the first N bytes, and flagged `bodyTruncated` (on the wire) when it was cut.
+- If redaction raises for any reason, no body is sent — never an unredacted one.
+- `body_status_filter="errors"` captures bodies only for 4xx/5xx responses, which keeps volume (and what you send) down while still covering most attacks.
+
+**URLs, referers and user agents are redacted the same way whether or not `capture_body` is on** — query strings routinely carry tokens and emails (`/reset?token=…&email=…`). Secret-named query values become the same shape, so `?password=' OR 1=1--` still reads as an injection attempt.
+
+Redaction is pattern-based. It covers the common cases above but can't know that a field called `notes` happens to contain something private — if a route handles data you don't want to leave your infrastructure at all, leave `capture_body` off, or use `body_status_filter` / a `status_filter` callable to exclude it.
+
+## Behavior
+
+- Never raises into your app. A network error, a rejected request, or a misconfigured key results in a dropped batch and a printed warning, not a crash.
+- Buffers in memory (thread-safe) and flushes on a background daemon thread every `flush_interval_ms` — there's no persistent queue in the SDK itself. If the process exits between flushes, buffered events are lost (matches the durability model of application logs in general). `collector.stop()` stops the background thread on shutdown; it does not force a final flush — call `collector.flush()` first if you need one.
+- Uses only the standard library (`urllib`) for the HTTP call — no extra dependency.
+- One HTTP event captured per request: method, URL, status, remote IP, user agent, referer, latency, response size, timestamp (plus a redacted body excerpt if `capture_body` is on).
+- A failed send retries `max_retries` times with exponential backoff (`retry_backoff_ms`, `retry_backoff_ms * 2`, `retry_backoff_ms * 4`, ...) before the batch is dropped for good. Retries are scheduled on a background timer thread and never block the request that triggered them.
+
+## Wire format
+
+See [`../README.md`](../README.md) for the shared batch/auth contract every language SDK implements. Field names on the wire (`remoteIp`, `latencyMs`, `bodyTruncated`, ...) are camelCase per that shared contract even though this package's own Python API (`gcp_project_id`, `status_filter`, ...) is snake_case — that boundary is deliberate: the wire format is a cross-language contract, the options are this language's idiomatic API.
+
+## Publishing (maintainers)
+
+CI is `.github/workflows/publish-python.yml`, using PyPI Trusted Publishing (OIDC) — no API token stored anywhere. One-time setup on [pypi.org](https://pypi.org) *before* the first release (PyPI lets you register a "pending publisher" for a project that doesn't exist yet):
+
+1. **pypi.org → Your projects → Publishing → Add a pending publisher**, with:
+   - PyPI project name: `cybat-sdk`
+   - Owner: `CybatInc`, Repository name: `SDK`, Workflow name: `publish-python.yml`, Environment name: `pypi`
+2. **GitHub repo → Settings → Environments → New environment**, name it `pypi` (must match exactly). Optionally add Required reviewers here for a manual approval gate before every publish — the OIDC equivalent of the 2FA-gated staging step `publish-node.yml` uses for npm.
+
+To release:
+
+```bash
+# bump "version" in pyproject.toml, commit that change, then tag THAT commit
+git add pyproject.toml && git commit -m "chore: bump cybat-sdk to 0.1.1"
+git tag 0.1.1
+git push origin main --tags
+```
+
+Same bare `X.Y.Z` tag format as `@cybat/sdk-node`'s releases — what keeps one tag from triggering both workflows is each one's `paths` filter (`python/**` here, `node/**` for Node's), which only matches if the tagged commit itself touched that package's directory. Tag the version-bump commit itself, not an unrelated one, or the path filter won't match and nothing will publish. The workflow runs the full test suite before building, then fails the build outright if the tag doesn't match `pyproject.toml`'s version.

cybat_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+cybat_sdk/__init__.py,sha256=5WZC-pE7TCY4R6OzMnJgUv_80ciRGe4ghn9fk6KZB0Y,169
+cybat_sdk/collector.py,sha256=5OF5CCCx1nZ5vctL_tfP6ARKY3oLqF9ERenD43vU2JM,9205
+cybat_sdk/redact.py,sha256=YXTWty_1U3VM6RW7cy-atA2oGipwnV0syNoK5MkWIW4,12245
+cybat_sdk/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cybat_sdk/integrations/asgi.py,sha256=1QheRTP1p7AjYcSSOs1D6zgZEtlnwjlLcfpjC6OX7mQ,5343
+cybat_sdk/integrations/django.py,sha256=k1XdDa7Svo93oJmfbn4uui0rhDSvzwg6VJmw2gMQD3o,5553
+cybat_sdk/integrations/flask.py,sha256=-LggPslXRXeiQZ3D8XNj4ntSArZOLxw9Et6xHFiC3xA,3574
+cybat_sdk-0.1.1.dist-info/METADATA,sha256=u4IegJG9eBvtKbw6cnyiGZwp3MNLJdaR9xgRCqozK7Q,12638
+cybat_sdk-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+cybat_sdk-0.1.1.dist-info/top_level.txt,sha256=XuJjX79AKcDAK081xI4GHjjkN2-7npz3YI3fIC9FsPg,10
+cybat_sdk-0.1.1.dist-info/RECORD,,

cybat_sdk-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cybat_sdk-0.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cybat_sdk