veltro-sdk 0.15.7__py3-none-any.whl

veltro_sdk/__init__.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+"""``veltro-sdk`` — the Python client for the Veltro security operations suite.
+
+Generated from the products' own OpenAPI documents (CHAD, Warden) and
+VectorFlow's REST v1 specification; see ``scripts/generate_sdk.py`` and
+``sdk/specs/*-operations.json`` in the ``veltrosecurity/veltro`` repository.
+
+Quick start (suite deployment)::
+
+    from veltro_sdk import VeltroClient
+
+    suite = VeltroClient.login("https://soc.example.com", email, password,
+                               vectorflow_key="vf_live_…")
+    data_sources = suite.chad.data_sources.list()
+    cases = suite.warden.cases.list(params={"limit": 25})
+    pipelines = suite.vectorflow.pipelines.list()
+
+Quick start (one product, personal access token through the gateway)::
+
+    from veltro_sdk import BearerToken, ChadClient
+
+    chad = ChadClient("https://soc.example.com/chad", auth=BearerToken(pat))
+    chad.rules.list()
+
+Stdlib only: no runtime dependencies.
+"""
+
+from ._auth import Auth, BearerToken, NoAuth, SuiteSession
+from ._http import (
+    Transport,
+    VeltroAPIError,
+    VeltroError,
+    VeltroResponseTooLarge,
+    VeltroTransportError,
+)
+from .client import (
+    SUITE_PREFIXES,
+    ChadClient,
+    MissingCredential,
+    VectorFlowClient,
+    VeltroClient,
+    WardenClient,
+)
+
+__version__ = "0.15.7"
+
+__all__ = [
+    "__version__",
+    # clients
+    "VeltroClient",
+    "ChadClient",
+    "WardenClient",
+    "VectorFlowClient",
+    "SUITE_PREFIXES",
+    # credentials
+    "Auth",
+    "NoAuth",
+    "BearerToken",
+    "SuiteSession",
+    # transport and errors
+    "Transport",
+    "VeltroError",
+    "VeltroAPIError",
+    "VeltroTransportError",
+    "VeltroResponseTooLarge",
+    "MissingCredential",
+]

veltro_sdk/_auth.py

@@ -0,0 +1,263 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Credentials the Veltro suite actually accepts, and nothing else.
+
+Three credential shapes exist across the suite, and they are not
+interchangeable — an SDK that guessed would fail closed in confusing ways:
+
+:class:`BearerToken`
+    ``Authorization: Bearer …``. A Veltro personal access token (``vmcp_…``)
+    for any product through the suite gateway (``/chad/api/*``,
+    ``/warden/api/*``, ``/vectorflow/api/*``), where identity turns it into
+    the request assertion the product verifies; VectorFlow's service-account
+    key (``vf_live_…``, environment-scoped, for ``/api/v1``); CHAD's SCIM
+    deployment token; Warden's session token.
+:class:`SuiteSession`
+    A suite deployment's own session, minted at the identity origin with
+    ``GET /api/auth/csrf`` + ``POST /api/auth/login`` and carried as the
+    session cookie. The gateway strips that cookie toward a product and
+    exchanges it for a short-lived request assertion, which is why one suite
+    login reaches all three products and why no product-local credential is
+    needed in suite mode.
+:class:`NoAuth`
+    Explicit anonymity, for the unauthenticated probes.
+
+Every implementation masks its material in ``repr`` and never writes it to a
+log; :class:`SuiteSession` additionally refuses to send a password over plain
+HTTP unless the caller opts in for a loopback deployment.
+"""
+
+from __future__ import annotations
+
+import http.cookiejar
+import json as _json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import MutableMapping
+
+from ._http import (
+    USER_AGENT,
+    VeltroAPIError,
+    VeltroTransportError,
+    _NoRedirect,
+    _read_capped,
+)
+
+__all__ = [
+    "Auth",
+    "NoAuth",
+    "BearerToken",
+    "SuiteSession",
+]
+
+SESSION_COOKIE_PREFIX = "authjs.session-token"
+LOGIN_MAX_RESPONSE_BYTES = 1024 * 1024
+
+
+class Auth:
+    """Applies one credential to an outgoing request."""
+
+    def apply(
+        self, method: str, url: str, headers: MutableMapping[str, str]
+    ) -> None:  # pragma: no cover - interface
+        raise NotImplementedError
+
+
+class NoAuth(Auth):
+    """Send no credential."""
+
+    def apply(
+        self, method: str, url: str, headers: MutableMapping[str, str]
+    ) -> None:
+        return None
+
+    def __repr__(self) -> str:
+        return "NoAuth()"
+
+
+class BearerToken(Auth):
+    """``Authorization: Bearer <token>``."""
+
+    def __init__(self, token: str) -> None:
+        if not token or not token.strip():
+            raise ValueError("token is required")
+        self._token = token.strip()
+
+    def apply(
+        self, method: str, url: str, headers: MutableMapping[str, str]
+    ) -> None:
+        headers["Authorization"] = f"Bearer {self._token}"
+
+    def __repr__(self) -> str:
+        return f"BearerToken({_mask(self._token)})"
+
+
+class SuiteSession(Auth):
+    """A suite session held as the identity-minted cookie.
+
+    ``identity_url`` is the suite origin (the identity authority owns the
+    origin root). The login is performed once, lazily, and re-performed if a
+    product answers 401 and :meth:`refresh` is called by the caller.
+    """
+
+    def __init__(
+        self,
+        identity_url: str,
+        email: str,
+        password: str,
+        *,
+        timeout: float = 30.0,
+        allow_insecure_transport: bool = False,
+    ) -> None:
+        if not identity_url:
+            raise ValueError("identity_url is required")
+        parsed = urllib.parse.urlsplit(identity_url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError("identity_url must be http(s)")
+        if parsed.scheme == "http" and not allow_insecure_transport:
+            raise ValueError(
+                "refusing to send suite credentials over plain HTTP; pass "
+                "allow_insecure_transport=True only for a loopback deployment"
+            )
+        self.identity_url = identity_url.rstrip("/")
+        self._email = email
+        self._password = password
+        self._timeout = timeout
+        self._jar = http.cookiejar.CookieJar()
+        self._opener = urllib.request.build_opener(
+            _NoRedirect(), urllib.request.HTTPCookieProcessor(self._jar)
+        )
+        self._logged_in = False
+
+    def __repr__(self) -> str:
+        return (
+            f"SuiteSession(identity_url={self.identity_url!r}, "
+            f"email={self._email!r}, password=***, "
+            f"logged_in={self._logged_in})"
+        )
+
+    # -- credential application -------------------------------------------
+    def apply(
+        self, method: str, url: str, headers: MutableMapping[str, str]
+    ) -> None:
+        if not self._logged_in:
+            self.login()
+        cookie = self._cookie_header(url)
+        if cookie:
+            headers["Cookie"] = cookie
+
+    def _cookie_header(self, url: str) -> str:
+        request = urllib.request.Request(url)
+        self._jar.add_cookie_header(request)
+        return request.get_header("Cookie", "")
+
+    # -- login -------------------------------------------------------------
+    def login(self) -> None:
+        """Mint a suite session. Raises :class:`VeltroAPIError` on refusal."""
+        csrf = self._csrf()
+        body = _json.dumps({"email": self._email, "password": self._password})
+        payload = self._call(
+            "POST",
+            "/api/auth/login",
+            body.encode("utf-8"),
+            {
+                "Content-Type": "application/json",
+                "x-csrf-token": csrf,
+            },
+        )
+        if not self._session_cookie_present():
+            raise VeltroAPIError(
+                200,
+                "POST",
+                f"{self.identity_url}/api/auth/login",
+                code="suite_login_no_session_cookie",
+                message=(
+                    "the identity authority accepted the login but set no "
+                    "session cookie"
+                ),
+                body=payload,
+            )
+        self._logged_in = True
+
+    def refresh(self) -> None:
+        """Drop the current session and log in again."""
+        self._jar.clear()
+        self._logged_in = False
+        self.login()
+
+    def _session_cookie_present(self) -> bool:
+        return any(
+            cookie.name.startswith(SESSION_COOKIE_PREFIX) for cookie in self._jar
+        )
+
+    def _csrf(self) -> str:
+        payload = self._call("GET", "/api/auth/csrf", None, {})
+        token = ""
+        if isinstance(payload, dict):
+            token = str(payload.get("csrfToken") or payload.get("csrf_token") or "")
+        if not token:
+            raise VeltroAPIError(
+                200,
+                "GET",
+                f"{self.identity_url}/api/auth/csrf",
+                code="suite_login_no_csrf_token",
+                message="the identity authority returned no CSRF token",
+                body=payload,
+            )
+        return token
+
+    def _call(
+        self,
+        method: str,
+        path: str,
+        body: bytes | None,
+        headers: dict[str, str],
+    ):
+        url = f"{self.identity_url}{path}"
+        request = urllib.request.Request(
+            url,
+            data=body,
+            method=method,
+            headers={"Accept": "application/json", "User-Agent": USER_AGENT, **headers},
+        )
+        try:
+            with self._opener.open(request, timeout=self._timeout) as response:
+                raw = _read_capped(
+                    response, LOGIN_MAX_RESPONSE_BYTES, method, url
+                )
+        except urllib.error.HTTPError as exc:
+            try:
+                detail = _read_capped(
+                    exc, LOGIN_MAX_RESPONSE_BYTES, method, url
+                )
+                message = ""
+                try:
+                    decoded = _json.loads(detail.decode("utf-8"))
+                    if isinstance(decoded, dict):
+                        message = str(decoded.get("error") or decoded.get("detail") or "")
+                except (UnicodeDecodeError, ValueError):
+                    message = ""
+                raise VeltroAPIError(
+                    exc.code,
+                    method,
+                    url,
+                    code="suite_login_refused",
+                    message=message,
+                ) from None
+            finally:
+                exc.close()
+        except urllib.error.URLError as exc:
+            raise VeltroTransportError(f"{method} {url}: {exc.reason}") from None
+        if not raw:
+            return None
+        try:
+            return _json.loads(raw.decode("utf-8"))
+        except (UnicodeDecodeError, ValueError):
+            return None
+
+
+def _mask(secret: str) -> str:
+    """Show enough to identify a credential, never enough to use it."""
+    if len(secret) <= 8:
+        return "'***'"
+    return f"'{secret[:4]}…***' (len {len(secret)})"

veltro_sdk/_http.py

@@ -0,0 +1,348 @@
+# SPDX-License-Identifier: Apache-2.0
+"""HTTP transport for the Veltro SDK: stdlib only, fail-closed, capped.
+
+Design constraints, each of them load-bearing:
+
+* **No dependencies.** An SDK that pulls a request stack is an SDK an operator
+  cannot drop into a hardened jump host. ``urllib.request`` is enough.
+* **Never log a credential.** Authorisation material lives behind
+  :class:`veltro_sdk.Auth` implementations whose ``repr`` masks the value, and
+  the transport never echoes request headers into an exception message.
+* **Cap the response.** A client that reads an unbounded body is a client one
+  hostile or broken deployment can OOM. ``max_response_bytes`` is enforced
+  while streaming, not after.
+* **Typed refusals.** Every non-2xx becomes a :class:`VeltroAPIError` carrying
+  the status, the product's own error code when it sends one, and the request
+  line — so a caller can branch on it instead of matching prose.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Iterable, Mapping
+
+__all__ = [
+    "VeltroError",
+    "VeltroAPIError",
+    "VeltroTransportError",
+    "VeltroResponseTooLarge",
+    "Transport",
+    "Resource",
+    "quote_segment",
+]
+
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024
+DEFAULT_RETRIES = 2
+RETRY_STATUSES = frozenset({429, 502, 503, 504})
+RETRY_METHODS = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
+USER_AGENT = "veltro-sdk/0.15.7 (+https://github.com/veltrosecurity/veltro)"
+
+
+class VeltroError(Exception):
+    """Base class for every SDK failure."""
+
+
+class VeltroTransportError(VeltroError):
+    """The request never produced an HTTP response (DNS, TLS, connect, timeout)."""
+
+
+class VeltroResponseTooLarge(VeltroError):
+    """The response body exceeded ``max_response_bytes``."""
+
+
+class VeltroAPIError(VeltroError):
+    """A product answered with a non-2xx status.
+
+    ``code`` is the product's own machine-readable refusal name when it sends
+    one (CHAD and Warden answer ``{"detail": ...}``; VectorFlow answers
+    ``{"error": {"code": ...}}``), otherwise ``None``.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        method: str,
+        url: str,
+        *,
+        code: str | None = None,
+        message: str = "",
+        body: Any = None,
+    ) -> None:
+        self.status = status
+        self.method = method
+        self.url = url
+        self.code = code
+        self.message = message
+        self.body = body
+        detail = f" {code}" if code else ""
+        text = f": {message}" if message else ""
+        super().__init__(f"{method} {url} -> HTTP {status}{detail}{text}")
+
+
+def quote_segment(value: object) -> str:
+    """Percent-encode one path segment.
+
+    Path parameters are interpolated into a URL, so an unencoded ``/`` or ``?``
+    in an identifier would silently retarget the request at another endpoint.
+    """
+    return urllib.parse.quote(str(value), safe="")
+
+
+def _decode(body: bytes, content_type: str) -> Any:
+    if not body:
+        return None
+    if "json" in content_type:
+        try:
+            return _json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, ValueError):
+            return body
+    if content_type.startswith("text/"):
+        try:
+            return body.decode("utf-8")
+        except UnicodeDecodeError:
+            return body
+    return body
+
+
+def _error_fields(payload: Any) -> tuple[str | None, str]:
+    """Pull (code, message) out of the three refusal shapes the suite emits."""
+    if isinstance(payload, Mapping):
+        error = payload.get("error")
+        if isinstance(error, Mapping):
+            code = error.get("code")
+            message = error.get("message") or ""
+            return (str(code) if code else None, str(message))
+        detail = payload.get("detail")
+        if isinstance(detail, Mapping):
+            code = detail.get("code") or detail.get("error")
+            message = detail.get("message") or detail.get("detail") or ""
+            return (str(code) if code else None, str(message))
+        if isinstance(detail, str):
+            return (None, detail)
+        if isinstance(detail, list):
+            return (None, _json.dumps(detail)[:500])
+        if isinstance(error, str):
+            return (None, error)
+        message = payload.get("message")
+        if isinstance(message, str):
+            return (None, message)
+    if isinstance(payload, str):
+        return (None, payload[:500])
+    return (None, "")
+
+
+def _read_capped(response, limit: int, method: str, url: str) -> bytes:
+    chunks: list[bytes] = []
+    read = 0
+    while True:
+        chunk = response.read(min(65536, limit - read + 1))
+        if not chunk:
+            break
+        read += len(chunk)
+        if read > limit:
+            raise VeltroResponseTooLarge(
+                f"{method} {url} -> response exceeded max_response_bytes={limit}"
+            )
+        chunks.append(chunk)
+    return b"".join(chunks)
+
+
+def _can_retry(method: str, headers: Mapping[str, str]) -> bool:
+    if method.upper() in RETRY_METHODS:
+        return True
+    return any(
+        key.lower() == "idempotency-key" and bool(value.strip())
+        for key, value in headers.items()
+    )
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Surface redirects instead of forwarding credentials to another origin."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class Transport:
+    """One product's HTTP surface: base URL, auth, retries, and caps.
+
+    ``base_url`` is the product's API origin *including* any suite gateway
+    prefix — ``https://soc.example.com/chad`` in a suite deployment,
+    ``https://chad.internal:8080`` standalone. Operation paths from the
+    generated bindings are appended to it verbatim.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        auth: "Auth | None" = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        retries: int = DEFAULT_RETRIES,
+        max_response_bytes: int = DEFAULT_MAX_RESPONSE_BYTES,
+        headers: Mapping[str, str] | None = None,
+        opener: urllib.request.OpenerDirector | None = None,
+        sleep=time.sleep,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        self.base_url = base_url.rstrip("/")
+        self.auth = auth
+        self.timeout = timeout
+        self.retries = max(0, int(retries))
+        self.max_response_bytes = int(max_response_bytes)
+        self.headers = dict(headers or {})
+        # No global opener: a process-wide opener would let one client's
+        # cookie policy leak into another's.
+        # API redirects are surfaced as typed 3xx responses. Automatically
+        # following one risks forwarding Authorization or API-key headers to
+        # an attacker-controlled Location.
+        self._opener = opener or urllib.request.build_opener(_NoRedirect())
+        self._sleep = sleep
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return f"Transport(base_url={self.base_url!r}, auth={self.auth!r})"
+
+    def url_for(self, path: str, params: Mapping[str, Any] | None = None) -> str:
+        if not path.startswith("/"):
+            path = "/" + path
+        url = f"{self.base_url}{path}"
+        query = _encode_params(params)
+        return f"{url}?{query}" if query else url
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any = None,
+        data: bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float | None = None,
+        raw: bool = False,
+    ) -> Any:
+        """Issue one request and return the decoded body (or the raw bytes)."""
+        if json is not None and data is not None:
+            raise ValueError("pass either json= or data=, not both")
+
+        url = self.url_for(path, params)
+        body = data
+        request_headers = {
+            "Accept": "application/json",
+            "User-Agent": USER_AGENT,
+            **self.headers,
+        }
+        if json is not None:
+            body = _json.dumps(json).encode("utf-8")
+            request_headers["Content-Type"] = "application/json"
+        if headers:
+            request_headers.update(headers)
+        if self.auth is not None:
+            self.auth.apply(method, url, request_headers)
+
+        attempts = self.retries + 1
+        last_error: VeltroError | None = None
+        for attempt in range(attempts):
+            request = urllib.request.Request(
+                url, data=body, method=method.upper(), headers=request_headers
+            )
+            try:
+                with self._opener.open(
+                    request, timeout=self.timeout if timeout is None else timeout
+                ) as response:
+                    payload = _read_capped(
+                        response, self.max_response_bytes, method.upper(), url
+                    )
+                    if raw:
+                        return payload
+                    return _decode(
+                        payload, response.headers.get("Content-Type", "") or ""
+                    )
+            except urllib.error.HTTPError as exc:  # noqa: PERF203 - retry loop
+                try:
+                    payload = _read_capped(
+                        exc, self.max_response_bytes, method.upper(), url
+                    )
+                finally:
+                    exc.close()
+                decoded = _decode(payload, exc.headers.get("Content-Type", "") or "")
+                code, message = _error_fields(decoded)
+                error = VeltroAPIError(
+                    exc.code,
+                    method.upper(),
+                    url,
+                    code=code,
+                    message=message,
+                    body=decoded,
+                )
+                if (
+                    exc.code in RETRY_STATUSES
+                    and attempt < attempts - 1
+                    and _can_retry(method, request_headers)
+                ):
+                    last_error = error
+                    self._sleep(_backoff(attempt, exc.headers.get("Retry-After")))
+                    continue
+                raise error from None
+            except VeltroResponseTooLarge:
+                raise
+            except urllib.error.URLError as exc:
+                error = VeltroTransportError(f"{method.upper()} {url}: {exc.reason}")
+                if attempt < attempts - 1 and _can_retry(method, request_headers):
+                    last_error = error
+                    self._sleep(_backoff(attempt, None))
+                    continue
+                raise error from None
+        assert last_error is not None  # unreachable: the loop returns or raises
+        raise last_error
+
+
+def _backoff(attempt: int, retry_after: str | None) -> float:
+    if retry_after:
+        try:
+            return min(30.0, max(0.0, float(retry_after)))
+        except ValueError:
+            pass
+    return min(8.0, 0.25 * (2**attempt))
+
+
+def _encode_params(params: Mapping[str, Any] | None) -> str:
+    if not params:
+        return ""
+    pairs: list[tuple[str, str]] = []
+    for key, value in params.items():
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            pairs.append((key, "true" if value else "false"))
+        elif isinstance(value, (list, tuple, set, frozenset)):
+            pairs.extend((key, str(item)) for item in _sorted(value))
+        else:
+            pairs.append((key, str(value)))
+    return urllib.parse.urlencode(pairs)
+
+
+def _sorted(value: Iterable[Any]) -> list[Any]:
+    items = list(value)
+    if isinstance(value, (set, frozenset)):
+        return sorted(items, key=str)
+    return items
+
+
+class Resource:
+    """Base class for the generated resource bindings."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._transport = transport
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return f"{type(self).__name__}(base_url={self._transport.base_url!r})"
+
+    def _request(self, method: str, path: str, **options: Any) -> Any:
+        return self._transport.request(method, path, **options)