blackshield-sdk 0.1.0__py3-none-any.whl

blackshield/__init__.py

@@ -0,0 +1,47 @@
+"""BlackShield Python SDK — Official client for the BlackShield Security Platform.
+
+Quick start::
+
+    import blackshield
+
+    client = blackshield.BlackShield(api_key="bsk_live_...")
+    page = client.findings.list(severity=["critical", "high"])
+    for finding in page.items:
+        print(f"{finding.severity.value} | {finding.title}")
+
+For async usage::
+
+    from blackshield import AsyncBlackShield
+
+    async with AsyncBlackShield(api_key="bsk_live_...") as client:
+        page = await client.findings.list()
+"""
+
+from blackshield._async_client import AsyncBlackShield
+from blackshield._client import BlackShield
+from blackshield._exceptions import (
+    APIError,
+    AuthenticationError,
+    BlackShieldError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+)
+from blackshield._version import __version__
+
+__all__ = [
+    "APIError",
+    "AsyncBlackShield",
+    "AuthenticationError",
+    "BlackShield",
+    # Exceptions
+    "BlackShieldError",
+    "ConflictError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ValidationError",
+    "__version__",
+]

blackshield/_async_client.py

@@ -0,0 +1,130 @@
+"""Asynchronous BlackShield client — async/await variant."""
+
+from __future__ import annotations
+
+from blackshield._base_client import AsyncHTTPClient
+from blackshield.resources.ai_gateway import AsyncAiGatewayResource
+from blackshield.resources.alerts import AsyncAlertsResource
+from blackshield.resources.api_keys import AsyncApiKeysResource
+from blackshield.resources.audit import AsyncAuditResource
+from blackshield.resources.compliance import AsyncComplianceResource
+from blackshield.resources.connectors import AsyncConnectorsResource
+from blackshield.resources.dashboard import AsyncDashboardResource
+from blackshield.resources.easm import AsyncEasmResource
+from blackshield.resources.findings import AsyncFindingsResource
+from blackshield.resources.identity import AsyncIdentityResource
+from blackshield.resources.ingestion import AsyncIngestionResource
+from blackshield.resources.policies import AsyncPoliciesResource
+from blackshield.resources.remediation import AsyncRemediationResource
+from blackshield.resources.reports import AsyncReportsResource
+from blackshield.resources.security_reviews import AsyncSecurityReviewsResource
+from blackshield.resources.threat_intel import AsyncThreatIntelResource
+
+
+class AsyncBlackShield:
+    """Asynchronous client for the BlackShield Security Platform API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.blackshield.security",
+        timeout: float = 60.0,
+        max_retries: int = 3,
+    ) -> None:
+        self._http = AsyncHTTPClient(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            max_retries=max_retries,
+        )
+        self._findings = AsyncFindingsResource(self._http)
+        self._ingestion = AsyncIngestionResource(self._http)
+        self._dashboard = AsyncDashboardResource(self._http)
+        self._compliance = AsyncComplianceResource(self._http)
+        self._reports = AsyncReportsResource(self._http)
+        self._easm = AsyncEasmResource(self._http)
+        self._threat_intel = AsyncThreatIntelResource(self._http)
+        self._connectors = AsyncConnectorsResource(self._http)
+        self._api_keys = AsyncApiKeysResource(self._http)
+        self._policies = AsyncPoliciesResource(self._http)
+        self._security_reviews = AsyncSecurityReviewsResource(self._http)
+        self._audit = AsyncAuditResource(self._http)
+        self._alerts = AsyncAlertsResource(self._http)
+        self._identity = AsyncIdentityResource(self._http)
+        self._remediation = AsyncRemediationResource(self._http)
+        self._ai_gateway = AsyncAiGatewayResource(self._http)
+
+    @property
+    def findings(self) -> AsyncFindingsResource:
+        return self._findings
+
+    @property
+    def ingestion(self) -> AsyncIngestionResource:
+        return self._ingestion
+
+    @property
+    def dashboard(self) -> AsyncDashboardResource:
+        return self._dashboard
+
+    @property
+    def compliance(self) -> AsyncComplianceResource:
+        return self._compliance
+
+    @property
+    def reports(self) -> AsyncReportsResource:
+        return self._reports
+
+    @property
+    def easm(self) -> AsyncEasmResource:
+        return self._easm
+
+    @property
+    def threat_intel(self) -> AsyncThreatIntelResource:
+        return self._threat_intel
+
+    @property
+    def connectors(self) -> AsyncConnectorsResource:
+        return self._connectors
+
+    @property
+    def api_keys(self) -> AsyncApiKeysResource:
+        return self._api_keys
+
+    @property
+    def policies(self) -> AsyncPoliciesResource:
+        return self._policies
+
+    @property
+    def security_reviews(self) -> AsyncSecurityReviewsResource:
+        return self._security_reviews
+
+    @property
+    def audit(self) -> AsyncAuditResource:
+        return self._audit
+
+    @property
+    def alerts(self) -> AsyncAlertsResource:
+        return self._alerts
+
+    @property
+    def identity(self) -> AsyncIdentityResource:
+        return self._identity
+
+    @property
+    def remediation(self) -> AsyncRemediationResource:
+        return self._remediation
+
+    @property
+    def ai_gateway(self) -> AsyncAiGatewayResource:
+        return self._ai_gateway
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._http.close()
+
+    async def __aenter__(self) -> AsyncBlackShield:
+        return self
+
+    async def __aexit__(self, *_args: object) -> None:
+        await self.close()

blackshield/_base_client.py

@@ -0,0 +1,420 @@
+"""Shared HTTP transport — retry logic, auth, and error mapping.
+
+Both the sync and async clients delegate to these helpers so retry
+semantics and error classification live in one place.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import time
+from typing import Any
+
+import httpx
+
+from blackshield._exceptions import (
+    APIError,
+    AuthenticationError,
+    BlackShieldError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ValidationError,
+)
+from blackshield._types import Headers, JSONDict, QueryParams
+
+logger = logging.getLogger("blackshield")
+
+_RETRYABLE_STATUS_CODES = frozenset({429, 500, 502, 503, 504})
+_DEFAULT_BASE_URL = "https://api.blackshield.security"
+_DEFAULT_TIMEOUT = 60.0
+_DEFAULT_MAX_RETRIES = 3
+_RETRY_BASE_DELAY = 0.5
+_RETRY_MAX_DELAY = 8.0
+_JITTER_FACTOR = 0.1
+
+
+def _build_auth_headers(api_key: str) -> Headers:
+    """Construct default headers for every request."""
+    return {
+        "X-API-Key": api_key,
+        "Content-Type": "application/json",
+        "User-Agent": _user_agent(),
+    }
+
+
+def _user_agent() -> str:
+    from blackshield._version import __version__
+
+    return f"blackshield-python/{__version__}"
+
+
+def _retry_delay(attempt: int) -> float:
+    """Exponential backoff with jitter, capped at ``_RETRY_MAX_DELAY``."""
+    base = _RETRY_BASE_DELAY * (2 ** max(0, attempt - 1))
+    capped = min(base, _RETRY_MAX_DELAY)
+    jitter = capped * _JITTER_FACTOR * random.random()
+    return capped + jitter
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    """Map HTTP error status codes to typed SDK exceptions."""
+    if response.is_success:
+        return
+
+    status_code = response.status_code
+    try:
+        body: dict[str, Any] = response.json()
+    except Exception:
+        body = {}
+
+    detail = body.get("detail", response.text or "Unknown error")
+    message = f"HTTP {status_code}: {detail}"
+
+    exc_map: dict[int, type[BlackShieldError]] = {
+        401: AuthenticationError,
+        403: PermissionDeniedError,
+        404: NotFoundError,
+        409: ConflictError,
+        422: ValidationError,
+    }
+
+    if status_code == 429:
+        retry_after_raw = response.headers.get("retry-after")
+        retry_after = float(retry_after_raw) if retry_after_raw else None
+        raise RateLimitError(
+            message,
+            status_code=status_code,
+            response_body=body,
+            retry_after=retry_after,
+        )
+
+    exc_cls = exc_map.get(status_code)
+    if exc_cls:
+        raise exc_cls(message, status_code=status_code, response_body=body)
+
+    if status_code >= 500:
+        raise APIError(message, status_code=status_code, response_body=body)
+
+    # Fallback for any other 4xx we didn't map.
+    raise BlackShieldError(message, status_code=status_code, response_body=body)
+
+
+def _is_retryable(status_code: int) -> bool:
+    return status_code in _RETRYABLE_STATUS_CODES
+
+
+# ---------------------------------------------------------------------------
+# Sync transport
+# ---------------------------------------------------------------------------
+
+
+class SyncHTTPClient:
+    """Synchronous HTTP client with retry support."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        api_key: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max(1, max_retries)
+        self._client = httpx.Client(
+            timeout=timeout,
+            headers=_build_auth_headers(api_key),
+        )
+
+    # -- public interface --------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: JSONDict | list[JSONDict] | None = None,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        """Execute an HTTP request with automatic retries."""
+        url = f"{self._base_url}{path}"
+        clean_params = _strip_none_params(params)
+        last_exc: Exception | None = None
+
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                response = self._client.request(
+                    method,
+                    url,
+                    json=json,
+                    params=clean_params,
+                )
+                if response.is_success:
+                    return response
+                if not _is_retryable(response.status_code):
+                    _raise_for_status(response)
+                last_exc = None  # will retry
+                if attempt < self._max_retries:
+                    _sleep_for_retry(attempt, response)
+                    continue
+                # Final attempt — raise
+                _raise_for_status(response)
+            except BlackShieldError:
+                raise
+            except (
+                httpx.TimeoutException,
+                httpx.ConnectError,
+                httpx.NetworkError,
+                httpx.TransportError,
+            ) as exc:
+                last_exc = exc
+                if attempt == self._max_retries:
+                    raise APIError(
+                        f"Request failed after {self._max_retries} attempts: {exc}",
+                        status_code=None,
+                    ) from exc
+                delay = _retry_delay(attempt)
+                logger.warning(
+                    "Retrying %s %s (attempt %d/%d, sleep %.2fs): %s",
+                    method,
+                    path,
+                    attempt,
+                    self._max_retries,
+                    delay,
+                    exc,
+                )
+                time.sleep(delay)
+
+        # Unreachable in practice but satisfies the type checker.
+        assert last_exc is not None
+        raise APIError(f"Request failed: {last_exc}", status_code=None)
+
+    def get(
+        self,
+        path: str,
+        *,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json: JSONDict | list[JSONDict] | None = None,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return self.request("POST", path, json=json, params=params)
+
+    def put(
+        self,
+        path: str,
+        *,
+        json: JSONDict | None = None,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return self.request("PUT", path, json=json, params=params)
+
+    def patch(
+        self,
+        path: str,
+        *,
+        json: JSONDict | None = None,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return self.request("PATCH", path, json=json, params=params)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return self.request("DELETE", path, params=params)
+
+    def close(self) -> None:
+        self._client.close()
+
+
+# ---------------------------------------------------------------------------
+# Async transport
+# ---------------------------------------------------------------------------
+
+
+class AsyncHTTPClient:
+    """Asynchronous HTTP client with retry support."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        api_key: str,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max(1, max_retries)
+        self._client = httpx.AsyncClient(
+            timeout=timeout,
+            headers=_build_auth_headers(api_key),
+        )
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: JSONDict | list[JSONDict] | None = None,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        """Execute an async HTTP request with automatic retries."""
+        import asyncio
+
+        url = f"{self._base_url}{path}"
+        clean_params = _strip_none_params(params)
+        last_exc: Exception | None = None
+
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                response = await self._client.request(
+                    method,
+                    url,
+                    json=json,
+                    params=clean_params,
+                )
+                if response.is_success:
+                    return response
+                if not _is_retryable(response.status_code):
+                    _raise_for_status(response)
+                last_exc = None
+                if attempt < self._max_retries:
+                    await _async_sleep_for_retry(attempt, response)
+                    continue
+                _raise_for_status(response)
+            except BlackShieldError:
+                raise
+            except (
+                httpx.TimeoutException,
+                httpx.ConnectError,
+                httpx.NetworkError,
+                httpx.TransportError,
+            ) as exc:
+                last_exc = exc
+                if attempt == self._max_retries:
+                    raise APIError(
+                        f"Request failed after {self._max_retries} attempts: {exc}",
+                        status_code=None,
+                    ) from exc
+                delay = _retry_delay(attempt)
+                logger.warning(
+                    "Retrying %s %s (attempt %d/%d, sleep %.2fs): %s",
+                    method,
+                    path,
+                    attempt,
+                    self._max_retries,
+                    delay,
+                    exc,
+                )
+                await asyncio.sleep(delay)
+
+        assert last_exc is not None
+        raise APIError(f"Request failed: {last_exc}", status_code=None)
+
+    async def get(
+        self,
+        path: str,
+        *,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return await self.request("GET", path, params=params)
+
+    async def post(
+        self,
+        path: str,
+        *,
+        json: JSONDict | list[JSONDict] | None = None,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return await self.request("POST", path, json=json, params=params)
+
+    async def put(
+        self,
+        path: str,
+        *,
+        json: JSONDict | None = None,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return await self.request("PUT", path, json=json, params=params)
+
+    async def patch(
+        self,
+        path: str,
+        *,
+        json: JSONDict | None = None,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return await self.request("PATCH", path, json=json, params=params)
+
+    async def delete(
+        self,
+        path: str,
+        *,
+        params: QueryParams | None = None,
+    ) -> httpx.Response:
+        return await self.request("DELETE", path, params=params)
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _strip_none_params(params: QueryParams | None) -> dict[str, str | int | float | bool]:
+    """Remove None-valued query params so httpx doesn't send ``key=None``."""
+    if not params:
+        return {}
+    return {k: v for k, v in params.items() if v is not None}
+
+
+def _sleep_for_retry(attempt: int, response: httpx.Response) -> None:
+    retry_after = response.headers.get("retry-after")
+    if retry_after:
+        try:
+            delay = float(retry_after)
+        except ValueError:
+            delay = _retry_delay(attempt)
+    else:
+        delay = _retry_delay(attempt)
+    logger.warning(
+        "Retrying after %d (attempt %d, sleep %.2fs)",
+        response.status_code,
+        attempt,
+        delay,
+    )
+    time.sleep(delay)
+
+
+async def _async_sleep_for_retry(attempt: int, response: httpx.Response) -> None:
+    import asyncio
+
+    retry_after = response.headers.get("retry-after")
+    if retry_after:
+        try:
+            delay = float(retry_after)
+        except ValueError:
+            delay = _retry_delay(attempt)
+    else:
+        delay = _retry_delay(attempt)
+    logger.warning(
+        "Retrying after %d (attempt %d, sleep %.2fs)",
+        response.status_code,
+        attempt,
+        delay,
+    )
+    await asyncio.sleep(delay)