cybat-sdk 0.1.1__tar.gz

cybat_sdk-0.1.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,167 @@
+# 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/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-0.1.1/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()