contrastapi 1.22.3__py3-none-any.whl

contrastapi/__init__.py

@@ -0,0 +1,39 @@
+"""ContrastAPI Python SDK.
+
+>>> from contrastapi import ContrastAPI
+>>> client = ContrastAPI()
+>>> client.cve.lookup("CVE-2021-44228")
+"""
+
+from ._version import __version__
+from .client import AsyncContrastAPI, ContrastAPI
+from .exceptions import (
+    AuthRequiredError,
+    ContrastAPIError,
+    InvalidArgumentError,
+    NotFoundError,
+    RateLimitError,
+    TierLimitError,
+    TransportError,
+    UpstreamError,
+    UpstreamTimeoutError,
+)
+from .shortcuts import audit_full, enrich_batch, triage_ioc
+
+__all__ = [
+    "AsyncContrastAPI",
+    "AuthRequiredError",
+    "ContrastAPI",
+    "ContrastAPIError",
+    "InvalidArgumentError",
+    "NotFoundError",
+    "RateLimitError",
+    "TierLimitError",
+    "TransportError",
+    "UpstreamError",
+    "UpstreamTimeoutError",
+    "__version__",
+    "audit_full",
+    "enrich_batch",
+    "triage_ioc",
+]

contrastapi/_transport.py

@@ -0,0 +1,170 @@
+"""HTTP transport for ContrastAPI SDK — sync (httpx.Client) and async (httpx.AsyncClient).
+
+Both transports share:
+  * Base URL + API key handling (HTTPS-only unless allow_insecure=True).
+  * Error envelope parsing via exceptions._parse_error.
+  * Response size cap (10 MB) to mirror Node SDK behaviour.
+  * Identical User-Agent (`contrastapi-python/<version>`).
+
+Design note: keeping sync and async classes side-by-side in one module avoids
+the duplicated-stub problem and makes the parity guarantee obvious. Namespace
+classes accept the transport instance and call `transport.get(...)` /
+`transport.post(...)` (or `aget` / `apost` for the async variant) — the rest is
+just URL construction.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+from ._version import __version__
+from .exceptions import ContrastAPIError, TransportError, _parse_error
+
+DEFAULT_BASE_URL = "https://api.contrastcyber.com"
+DEFAULT_TIMEOUT = 30.0
+MIN_TIMEOUT = 1.0
+MAX_TIMEOUT = 120.0
+MAX_RESPONSE_BYTES = 10 * 1024 * 1024  # 10 MB — parity with Node SDK
+USER_AGENT = f"contrastapi-python/{__version__}"
+
+
+def _normalize_base_url(base_url: str, *, allow_insecure: bool) -> str:
+    parts = urlsplit(base_url)
+    if parts.scheme not in ("https", "http"):
+        raise ValueError(f"Unsupported scheme: {parts.scheme!r}")
+    if parts.scheme == "http" and not allow_insecure:
+        raise ValueError("Only HTTPS is allowed. Pass allow_insecure=True to override.")
+    return base_url.rstrip("/")
+
+
+def _build_headers(api_key: str | None, base_scheme: str, has_body: bool) -> dict[str, str]:
+    headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+    if api_key:
+        if base_scheme != "https":
+            raise ValueError("Refusing to send API key over insecure connection")
+        headers["X-API-Key"] = api_key
+    if has_body:
+        headers["Content-Type"] = "application/json"
+    return headers
+
+
+def _clamp_timeout(value: float | None) -> float:
+    if value is None:
+        return DEFAULT_TIMEOUT
+    return max(MIN_TIMEOUT, min(float(value), MAX_TIMEOUT))
+
+
+def _decode_response(response: httpx.Response) -> Any:
+    """Parse JSON body with size cap. Raises ContrastAPIError on bad JSON or oversize."""
+    content = response.content
+    if len(content) > MAX_RESPONSE_BYTES:
+        raise ContrastAPIError(
+            f"Response too large ({len(content)} bytes > {MAX_RESPONSE_BYTES})",
+            status_code=response.status_code,
+        )
+    try:
+        return json.loads(content) if content else None
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise ContrastAPIError(
+            f"Invalid JSON response (HTTP {response.status_code}): {exc}",
+            status_code=response.status_code,
+        ) from exc
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    body = _decode_response(response)
+    if response.status_code >= 400:
+        raise _parse_error(response.status_code, body)
+    return body
+
+
+class _SyncTransport:
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float | None = None,
+        allow_insecure: bool = False,
+        client: httpx.Client | None = None,
+    ) -> None:
+        self.base_url = _normalize_base_url(base_url, allow_insecure=allow_insecure)
+        self._scheme = urlsplit(self.base_url).scheme
+        self.api_key = api_key
+        self.timeout = _clamp_timeout(timeout)
+        self._owns_client = client is None
+        self._client = client or httpx.Client(timeout=self.timeout)
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> Any:
+        headers = _build_headers(self.api_key, self._scheme, has_body=False)
+        try:
+            response = self._client.get(self.base_url + path, params=params, headers=headers)
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+        return _handle_response(response)
+
+    def post(self, path: str, *, json_body: Any | None = None) -> Any:
+        headers = _build_headers(self.api_key, self._scheme, has_body=json_body is not None)
+        try:
+            response = self._client.post(self.base_url + path, json=json_body, headers=headers)
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+        return _handle_response(response)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> _SyncTransport:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+
+class _AsyncTransport:
+    def __init__(
+        self,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        api_key: str | None = None,
+        timeout: float | None = None,
+        allow_insecure: bool = False,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = _normalize_base_url(base_url, allow_insecure=allow_insecure)
+        self._scheme = urlsplit(self.base_url).scheme
+        self.api_key = api_key
+        self.timeout = _clamp_timeout(timeout)
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=self.timeout)
+
+    async def aget(self, path: str, *, params: dict[str, Any] | None = None) -> Any:
+        headers = _build_headers(self.api_key, self._scheme, has_body=False)
+        try:
+            response = await self._client.get(self.base_url + path, params=params, headers=headers)
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+        return _handle_response(response)
+
+    async def apost(self, path: str, *, json_body: Any | None = None) -> Any:
+        headers = _build_headers(self.api_key, self._scheme, has_body=json_body is not None)
+        try:
+            response = await self._client.post(self.base_url + path, json=json_body, headers=headers)
+        except httpx.HTTPError as exc:
+            raise TransportError(str(exc)) from exc
+        return _handle_response(response)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> _AsyncTransport:
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()

contrastapi/_version.py

@@ -0,0 +1 @@
+__version__ = "1.22.3"

contrastapi/client.py

@@ -0,0 +1,171 @@
+"""ContrastAPI / AsyncContrastAPI — top-level clients.
+
+Two parallel surfaces:
+  * `ContrastAPI` (sync) → uses `httpx.Client`, namespace methods are plain `def`.
+  * `AsyncContrastAPI` (async) → uses `httpx.AsyncClient`, namespace methods are
+    `async def`.
+
+Both classes accept the same options (`api_key`, `base_url`, `timeout`,
+`allow_insecure`) and expose the same namespace property names. Choose whichever
+matches your application's I/O model.
+
+All 14 namespaces (cve, cwe, ioc, atlas, d3fend, domain, ip, asn, email, phone,
+password, username, check, scan) are exposed as instance attributes. The async
+client mirrors the sync surface 1:1 — same names, async methods.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ._transport import DEFAULT_BASE_URL, _AsyncTransport, _SyncTransport
+from ._version import __version__
+from .models import StatusResponse, UsageResponse
+from .namespaces.atlas import AsyncAtlas, Atlas
+from .namespaces.cve import AsyncCve, AsyncCwe, Cve, Cwe
+from .namespaces.d3fend import AsyncD3fend, D3fend
+from .namespaces.domain import AsyncDomain, Domain
+from .namespaces.intel import (
+    Asn,
+    AsyncAsn,
+    AsyncEmail,
+    AsyncIp,
+    AsyncPassword,
+    AsyncPhone,
+    AsyncUsername,
+    Email,
+    Ip,
+    Password,
+    Phone,
+    Username,
+)
+from .namespaces.ioc import AsyncIoc, Ioc
+from .namespaces.security import AsyncCheck, AsyncScan, Check, Scan
+
+
+class ContrastAPI:
+    """Synchronous ContrastAPI client.
+
+    Usage:
+        >>> from contrastapi import ContrastAPI
+        >>> client = ContrastAPI()  # keyless (free tier)
+        >>> cve = client.cve.lookup("CVE-2021-44228")
+        >>> assert cve["kev"]["in_kev"]
+        >>> client.close()
+
+    Or as context manager:
+        >>> with ContrastAPI(api_key="cc_...") as client:
+        ...     defenses = client.d3fend.defense_for_attack("T1059")
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = None,
+        allow_insecure: bool = False,
+    ) -> None:
+        self._transport = _SyncTransport(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            allow_insecure=allow_insecure,
+        )
+        self.cve = Cve(self._transport)
+        self.cwe = Cwe(self._transport)
+        self.ioc = Ioc(self._transport)
+        self.atlas = Atlas(self._transport)
+        self.d3fend = D3fend(self._transport)
+        self.domain = Domain(self._transport)
+        self.ip = Ip(self._transport)
+        self.asn = Asn(self._transport)
+        self.email = Email(self._transport)
+        self.phone = Phone(self._transport)
+        self.password = Password(self._transport)
+        self.username = Username(self._transport)
+        self.check = Check(self._transport)
+        self.scan = Scan(self._transport)
+
+    @property
+    def version(self) -> str:
+        return __version__
+
+    def status(self) -> StatusResponse:
+        """GET /v1/status — returns service health + version."""
+        return self._transport.get("/v1/status")
+
+    def usage(self) -> UsageResponse:
+        """GET /v1/usage — returns rate-limit window for current API key (or anonymous IP)."""
+        return self._transport.get("/v1/usage")
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> ContrastAPI:
+        return self
+
+    def __exit__(self, *exc_info: Any) -> None:
+        self.close()
+
+
+class AsyncContrastAPI:
+    """Asynchronous ContrastAPI client. Mirrors ContrastAPI namespace surface.
+
+    Usage:
+        >>> import asyncio
+        >>> from contrastapi import AsyncContrastAPI
+        >>> async def main():
+        ...     async with AsyncContrastAPI() as client:
+        ...         tech = await client.atlas.technique("AML.T0051")
+        ...         print(tech["name"])
+        >>> asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = None,
+        allow_insecure: bool = False,
+    ) -> None:
+        self._transport = _AsyncTransport(
+            base_url=base_url,
+            api_key=api_key,
+            timeout=timeout,
+            allow_insecure=allow_insecure,
+        )
+        self.cve = AsyncCve(self._transport)
+        self.cwe = AsyncCwe(self._transport)
+        self.ioc = AsyncIoc(self._transport)
+        self.atlas = AsyncAtlas(self._transport)
+        self.d3fend = AsyncD3fend(self._transport)
+        self.domain = AsyncDomain(self._transport)
+        self.ip = AsyncIp(self._transport)
+        self.asn = AsyncAsn(self._transport)
+        self.email = AsyncEmail(self._transport)
+        self.phone = AsyncPhone(self._transport)
+        self.password = AsyncPassword(self._transport)
+        self.username = AsyncUsername(self._transport)
+        self.check = AsyncCheck(self._transport)
+        self.scan = AsyncScan(self._transport)
+
+    @property
+    def version(self) -> str:
+        return __version__
+
+    async def status(self) -> StatusResponse:
+        return await self._transport.aget("/v1/status")
+
+    async def usage(self) -> UsageResponse:
+        return await self._transport.aget("/v1/usage")
+
+    async def aclose(self) -> None:
+        await self._transport.aclose()
+
+    async def __aenter__(self) -> AsyncContrastAPI:
+        return self
+
+    async def __aexit__(self, *exc_info: Any) -> None:
+        await self.aclose()

contrastapi/exceptions.py

@@ -0,0 +1,176 @@
+"""Exception hierarchy for ContrastAPI SDK.
+
+Mirrors the server-side `app.exceptions.AppException` tree so SDK users can
+catch typed exceptions instead of inspecting status codes. Each instance carries
+the parsed `ErrorDetail` envelope (dict) from the wire — `.code`, `.message`,
+`.retry_after_seconds`, `.upgrade_url`, `.docs_url`.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Wire-boundary defensive caps mirror server-side `_ERROR_MESSAGE_MAX_LEN` /
+# `_RETRY_AFTER_MAX_SECONDS` (see app/main.py). Server already enforces these,
+# but the SDK refuses to trust an untrusted response payload.
+_MESSAGE_MAX_LEN = 500
+_RETRY_AFTER_MAX_SECONDS = 3600
+
+
+class ContrastAPIError(Exception):
+    """Base exception for all ContrastAPI SDK errors."""
+
+    code: str = "internal_error"
+    status_code: int | None = None
+
+    def __init__(
+        self,
+        message: Any,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+        retry_after_seconds: int | None = None,
+        upgrade_url: str | None = None,
+        docs_url: str | None = None,
+        extras: dict[str, Any] | None = None,
+    ) -> None:
+        # CRIT (review): coerce to str — server response could send None / int / dict.
+        coerced = "" if message is None else str(message)
+        if len(coerced) > _MESSAGE_MAX_LEN:
+            coerced = coerced[:_MESSAGE_MAX_LEN]
+        super().__init__(coerced)
+        self.message = coerced
+        if status_code is not None:
+            self.status_code = status_code
+        if code is not None:
+            self.code = code
+        self.retry_after_seconds = _coerce_retry_after(retry_after_seconds)
+        self.upgrade_url = upgrade_url
+        self.docs_url = docs_url
+        self.extras = extras or {}
+
+
+def _coerce_retry_after(value: Any) -> int | None:
+    """Validate + clamp retry_after_seconds to [0, 3600].
+
+    Server sends int per ErrorDetail schema, but a malformed/proxied response
+    could deliver str/float/list/bool/inf/NaN. Defensive: ignore garbage
+    rather than crash user code that does `time.sleep(exc.retry_after_seconds)`.
+    """
+    if value is None:
+        return None
+    # Reject bool early — `int(True) == 1` would silently produce 1-second
+    # sleeps from a `{"retry_after_seconds": true}` upstream response. bool
+    # is also a subclass of int, so the `isinstance(value, bool)` guard must
+    # run before the int() coercion below.
+    if isinstance(value, bool):
+        return None
+    # Reject NaN — `int(float('nan'))` raises ValueError but inf raises
+    # OverflowError; both must be silently dropped to None per defensive policy.
+    if isinstance(value, float) and (value != value or value in (float("inf"), float("-inf"))):
+        return None
+    try:
+        as_int = int(value)
+    except (TypeError, ValueError, OverflowError):
+        return None
+    return max(0, min(as_int, _RETRY_AFTER_MAX_SECONDS))
+
+
+class InvalidArgumentError(ContrastAPIError):
+    code = "invalid_argument"
+    status_code = 400
+
+
+class AuthRequiredError(ContrastAPIError):
+    code = "auth_required"
+    status_code = 401
+
+
+class TierLimitError(ContrastAPIError):
+    code = "tier_limit"
+    status_code = 403
+
+
+class NotFoundError(ContrastAPIError):
+    code = "not_found"
+    status_code = 404
+
+
+class RateLimitError(ContrastAPIError):
+    code = "rate_limit_exceeded"
+    status_code = 429
+
+
+class UpstreamError(ContrastAPIError):
+    code = "upstream_error"
+    status_code = 502
+
+
+class UpstreamTimeoutError(ContrastAPIError):
+    code = "upstream_timeout"
+    status_code = 504
+
+
+class TransportError(ContrastAPIError):
+    """Raised when the HTTP layer fails before a response is received
+    (DNS error, connection refused, client timeout, TLS handshake fail).
+    """
+
+    code = "transport_error"
+
+
+_CODE_TO_EXCEPTION: dict[str, type[ContrastAPIError]] = {
+    "invalid_argument": InvalidArgumentError,
+    "auth_required": AuthRequiredError,
+    "tier_limit": TierLimitError,
+    "not_found": NotFoundError,
+    "rate_limit_exceeded": RateLimitError,
+    "upstream_error": UpstreamError,
+    "upstream_timeout": UpstreamTimeoutError,
+}
+
+
+_STATUS_TO_EXCEPTION: dict[int, type[ContrastAPIError]] = {
+    400: InvalidArgumentError,
+    401: AuthRequiredError,
+    403: TierLimitError,
+    404: NotFoundError,
+    422: InvalidArgumentError,
+    429: RateLimitError,
+    502: UpstreamError,
+    504: UpstreamTimeoutError,
+}
+
+
+def _parse_error(status_code: int, body: Any) -> ContrastAPIError:
+    """Convert a wire error envelope into the right typed exception.
+
+    Wire shape (v1.22.2+):
+        {"error": {"code": "...", "message": "...", "retry_after_seconds": 60,
+                   "upgrade_url": "...", "docs_url": "..."}, ...top-level extensions}
+
+    Falls back to status-code mapping if the body lacks a parseable envelope.
+    """
+    if not isinstance(body, dict):
+        cls = _STATUS_TO_EXCEPTION.get(status_code, ContrastAPIError)
+        return cls(f"HTTP {status_code}", status_code=status_code)
+
+    err = body.get("error") if isinstance(body.get("error"), dict) else None
+    if err is None:
+        message = body.get("detail") or body.get("message") or f"HTTP {status_code}"
+        cls = _STATUS_TO_EXCEPTION.get(status_code, ContrastAPIError)
+        return cls(str(message), status_code=status_code, extras=body)
+
+    code = err.get("code") or "upstream_error"
+    message = err.get("message") or f"HTTP {status_code}"
+    cls = _CODE_TO_EXCEPTION.get(code, _STATUS_TO_EXCEPTION.get(status_code, ContrastAPIError))
+    extras = {k: v for k, v in body.items() if k != "error"}
+    return cls(
+        str(message),
+        status_code=status_code,
+        code=code,
+        retry_after_seconds=err.get("retry_after_seconds"),
+        upgrade_url=err.get("upgrade_url"),
+        docs_url=err.get("docs_url"),
+        extras=extras,
+    )