contrastapi 1.22.3__tar.gz

contrastapi-1.22.3/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+*.db
+*.db-wal
+*.db-shm
+venv/
+.env
+test_*.db
+.mcpregistry_*
+scripts/*
+!scripts/backfill_mitre_fields.py
+plans/
+.npmrc
+node_modules/
+research_landing*.md
+.coverage
+deploy/
+.aider*

contrastapi-1.22.3/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: contrastapi
+Version: 1.22.3
+Summary: Official Python SDK for ContrastAPI — security intelligence for developers and AI agents
+Project-URL: Homepage, https://contrastcyber.com
+Project-URL: Documentation, https://api.contrastcyber.com/docs
+Project-URL: Repository, https://github.com/UPinar/contrastapi
+Project-URL: Issues, https://github.com/UPinar/contrastapi/issues
+Author-email: ContrastCyber <contact@contrastcyber.com>
+License-Expression: MIT
+Keywords: ai-security,api,atlas,attack,cve,cwe,d3fend,dns,domain,kev,mcp,mitre,osint,security,ssl,threat-intelligence,vulnerability,whois
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1.0,>=0.25
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Requires-Dist: respx>=0.20; extra == 'test'
+Description-Content-Type: text/markdown
+
+# ContrastAPI Python SDK
+
+Official Python client for [ContrastAPI](https://api.contrastcyber.com) — security intelligence for developers and AI agents.
+
+42 MCP tools / 50+ HTTP endpoints: CVE / EPSS / KEV / CWE, MITRE ATLAS (AI/ML attacks) + bulk drill, MITRE D3FEND defenses, domain audit, IOC + threat intel, OSINT, code-security checks, and more. No API key required for the free tier (100 req/hr).
+
+## Install
+
+```bash
+pip install contrastapi
+```
+
+Requires Python 3.10+. Depends only on `httpx>=0.25`.
+
+## Quickstart
+
+### Sync
+
+```python
+from contrastapi import ContrastAPI
+from contrastapi.models import CveResponse, AuditResponse
+
+with ContrastAPI() as client:                    # keyless, free tier
+    cve: CveResponse = client.cve.lookup("CVE-2021-44228")
+    print(cve["kev"]["in_kev"])                  # True (IDE autocompletes "kev", "epss"...)
+
+    techs = client.atlas.bulk_technique_lookup(["AML.T0051", "AML.T0043"])
+    print(techs["successful"])                   # 2
+
+    audit: AuditResponse = client.domain.audit("example.com")
+    print(audit["score"])
+```
+
+Every response method has a typed return — `client.cve.lookup(...)` returns `CveResponse`, `client.atlas.technique(...)` returns `AtlasTechniqueResponse`, etc. You never need to write the type annotation; IDEs (VSCode/PyCharm) infer it from the method signature and offer autocomplete on response keys. Import from `contrastapi.models` only if you want to annotate explicitly or pass responses across function boundaries.
+
+### Async
+
+```python
+import asyncio
+from contrastapi import AsyncContrastAPI
+
+async def main():
+    async with AsyncContrastAPI(api_key="cc_...") as client:
+        defenses = await client.d3fend.defense_for_attack("T1059")
+        print(len(defenses["defenses"]))
+
+asyncio.run(main())
+```
+
+### Shortcuts (multi-call helpers)
+
+```python
+from contrastapi import ContrastAPI, audit_full, enrich_batch, triage_ioc
+
+with ContrastAPI() as client:
+    # Auto-route IP/hash/domain to the right enrichment leg
+    report = triage_ioc(client, "8.8.8.8")              # ioc + threat_report
+
+    # Audit + subdomains + tech + per-subdomain SSL (capped)
+    audit = audit_full(client, "example.com", ssl_subdomains=5)
+
+    # Auto-detect CVE vs IOC and bulk-route
+    enriched = enrich_batch(client, ["CVE-2021-44228", "8.8.8.8", "evil.com"])
+```
+
+Shortcuts swallow per-leg `ContrastAPIError` so partial failures still return whatever succeeded — see `result["errors"]` for the failure map.
+
+## Authentication
+
+Pass an API key as the first positional argument or as `api_key=`:
+
+```python
+client = ContrastAPI("cc_<your-key>")            # 1000 req/hr (Pro tier)
+```
+
+Get a key at [contrastcyber.com/pricing](https://contrastcyber.com/pricing).
+
+## Exception model
+
+The SDK maps server error codes (v1.22.2+ wire envelope) to typed exceptions:
+
+| Exception | Status | Server code |
+| --- | --- | --- |
+| `InvalidArgumentError` | 400, 422 | `invalid_argument` |
+| `AuthRequiredError` | 401 | `auth_required` |
+| `TierLimitError` | 403 | `tier_limit` |
+| `NotFoundError` | 404 | `not_found` |
+| `RateLimitError` | 429 | `rate_limit_exceeded` |
+| `UpstreamError` | 502 | `upstream_error` |
+| `UpstreamTimeoutError` | 504 | `upstream_timeout` |
+| `TransportError` | n/a | (network failure, before HTTP) |
+| `ContrastAPIError` | * | base / unknown |
+
+Every exception carries the parsed envelope:
+
+```python
+from contrastapi import ContrastAPI, RateLimitError
+
+try:
+    client.cve.lookup("CVE-2021-44228")
+except RateLimitError as exc:
+    print(exc.message)                  # "Hourly limit reached"
+    print(exc.retry_after_seconds)      # 60 (capped at 3600)
+    print(exc.upgrade_url)              # "https://contrastcyber.com/pricing"
+    print(exc.extras)                   # back-compat top-level fields (tier, limit, ...)
+```
+
+## Namespaces
+
+| Namespace | Methods |
+| --- | --- |
+| `cve` | `lookup`, `search`, `leading`, `kev`, `exploit`, `bulk` |
+| `cwe` | `lookup` |
+| `ioc` | `lookup`, `hash`, `phishing`, `bulk` |
+| `atlas` | `technique`, `technique_search`, `bulk_technique_lookup`, `case_study`, `case_study_search` |
+| `d3fend` | `defense`, `defense_search`, `defense_for_attack`, `coverage` |
+| `domain` | `report`, `dns`, `whois`, `subdomains`, `certs`, `ssl`, `tech`, `threat`, `monitor`, `vulns`, `audit`, `wayback`, `bulk` |
+| `ip` | `lookup`, `threat_report` |
+| `asn` | `lookup` |
+| `email` | `mx`, `disposable` |
+| `phone` | `lookup` |
+| `password` | `check` (k-anonymity SHA-1 prefix) |
+| `username` | `lookup` |
+| `check` | `secrets`, `injection`, `headers`, `dependencies` |
+| `scan` | `headers` (live HTTP scan) |
+
+The async client (`AsyncContrastAPI`) exposes the same namespace surface 1:1 — every method is `async def`.
+
+## Parity with the Node SDK
+
+| Surface | Node SDK | Python SDK |
+| --- | --- | --- |
+| Sync | ✅ (Promise-based) | ✅ (`ContrastAPI`) |
+| Async | (Promise model) | ✅ (`AsyncContrastAPI`) |
+| Namespace count | 13 | 14 (adds `username`) |
+| `bulk_technique_lookup` (ATLAS) | (added in v1.4.0) | ✅ |
+| `wayback` archive lookup | (added in v1.4.0) | ✅ |
+| Typed errors | `Error` subclasses | full hierarchy with envelope fields |
+| Shortcuts | — | ✅ `triage_ioc`, `audit_full`, `enrich_batch` |
+| Response models | `Promise<any>` | ✅ `TypedDict` (IDE autocomplete, no runtime cost) |
+
+## Configuration
+
+```python
+client = ContrastAPI(
+    api_key="cc_...",                  # optional; keyless = free tier
+    base_url="https://api.contrastcyber.com",  # override for self-host
+    timeout=30.0,                       # seconds; clamped to [1, 120]
+    allow_insecure=False,               # set True to allow http:// (dev only)
+)
+```
+
+The transport hard-caps response bodies at 10 MB, sends a `User-Agent: contrastapi-python/<version>` header, and refuses to send your API key over plaintext HTTP even when `allow_insecure=True`.
+
+## Links
+
+- API docs: https://api.contrastcyber.com/docs
+- Pricing & API key: https://contrastcyber.com/pricing
+- Source: https://github.com/UPinar/contrastapi
+- Issues: https://github.com/UPinar/contrastapi/issues
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

contrastapi-1.22.3/README.md

@@ -0,0 +1,164 @@
+# ContrastAPI Python SDK
+
+Official Python client for [ContrastAPI](https://api.contrastcyber.com) — security intelligence for developers and AI agents.
+
+42 MCP tools / 50+ HTTP endpoints: CVE / EPSS / KEV / CWE, MITRE ATLAS (AI/ML attacks) + bulk drill, MITRE D3FEND defenses, domain audit, IOC + threat intel, OSINT, code-security checks, and more. No API key required for the free tier (100 req/hr).
+
+## Install
+
+```bash
+pip install contrastapi
+```
+
+Requires Python 3.10+. Depends only on `httpx>=0.25`.
+
+## Quickstart
+
+### Sync
+
+```python
+from contrastapi import ContrastAPI
+from contrastapi.models import CveResponse, AuditResponse
+
+with ContrastAPI() as client:                    # keyless, free tier
+    cve: CveResponse = client.cve.lookup("CVE-2021-44228")
+    print(cve["kev"]["in_kev"])                  # True (IDE autocompletes "kev", "epss"...)
+
+    techs = client.atlas.bulk_technique_lookup(["AML.T0051", "AML.T0043"])
+    print(techs["successful"])                   # 2
+
+    audit: AuditResponse = client.domain.audit("example.com")
+    print(audit["score"])
+```
+
+Every response method has a typed return — `client.cve.lookup(...)` returns `CveResponse`, `client.atlas.technique(...)` returns `AtlasTechniqueResponse`, etc. You never need to write the type annotation; IDEs (VSCode/PyCharm) infer it from the method signature and offer autocomplete on response keys. Import from `contrastapi.models` only if you want to annotate explicitly or pass responses across function boundaries.
+
+### Async
+
+```python
+import asyncio
+from contrastapi import AsyncContrastAPI
+
+async def main():
+    async with AsyncContrastAPI(api_key="cc_...") as client:
+        defenses = await client.d3fend.defense_for_attack("T1059")
+        print(len(defenses["defenses"]))
+
+asyncio.run(main())
+```
+
+### Shortcuts (multi-call helpers)
+
+```python
+from contrastapi import ContrastAPI, audit_full, enrich_batch, triage_ioc
+
+with ContrastAPI() as client:
+    # Auto-route IP/hash/domain to the right enrichment leg
+    report = triage_ioc(client, "8.8.8.8")              # ioc + threat_report
+
+    # Audit + subdomains + tech + per-subdomain SSL (capped)
+    audit = audit_full(client, "example.com", ssl_subdomains=5)
+
+    # Auto-detect CVE vs IOC and bulk-route
+    enriched = enrich_batch(client, ["CVE-2021-44228", "8.8.8.8", "evil.com"])
+```
+
+Shortcuts swallow per-leg `ContrastAPIError` so partial failures still return whatever succeeded — see `result["errors"]` for the failure map.
+
+## Authentication
+
+Pass an API key as the first positional argument or as `api_key=`:
+
+```python
+client = ContrastAPI("cc_<your-key>")            # 1000 req/hr (Pro tier)
+```
+
+Get a key at [contrastcyber.com/pricing](https://contrastcyber.com/pricing).
+
+## Exception model
+
+The SDK maps server error codes (v1.22.2+ wire envelope) to typed exceptions:
+
+| Exception | Status | Server code |
+| --- | --- | --- |
+| `InvalidArgumentError` | 400, 422 | `invalid_argument` |
+| `AuthRequiredError` | 401 | `auth_required` |
+| `TierLimitError` | 403 | `tier_limit` |
+| `NotFoundError` | 404 | `not_found` |
+| `RateLimitError` | 429 | `rate_limit_exceeded` |
+| `UpstreamError` | 502 | `upstream_error` |
+| `UpstreamTimeoutError` | 504 | `upstream_timeout` |
+| `TransportError` | n/a | (network failure, before HTTP) |
+| `ContrastAPIError` | * | base / unknown |
+
+Every exception carries the parsed envelope:
+
+```python
+from contrastapi import ContrastAPI, RateLimitError
+
+try:
+    client.cve.lookup("CVE-2021-44228")
+except RateLimitError as exc:
+    print(exc.message)                  # "Hourly limit reached"
+    print(exc.retry_after_seconds)      # 60 (capped at 3600)
+    print(exc.upgrade_url)              # "https://contrastcyber.com/pricing"
+    print(exc.extras)                   # back-compat top-level fields (tier, limit, ...)
+```
+
+## Namespaces
+
+| Namespace | Methods |
+| --- | --- |
+| `cve` | `lookup`, `search`, `leading`, `kev`, `exploit`, `bulk` |
+| `cwe` | `lookup` |
+| `ioc` | `lookup`, `hash`, `phishing`, `bulk` |
+| `atlas` | `technique`, `technique_search`, `bulk_technique_lookup`, `case_study`, `case_study_search` |
+| `d3fend` | `defense`, `defense_search`, `defense_for_attack`, `coverage` |
+| `domain` | `report`, `dns`, `whois`, `subdomains`, `certs`, `ssl`, `tech`, `threat`, `monitor`, `vulns`, `audit`, `wayback`, `bulk` |
+| `ip` | `lookup`, `threat_report` |
+| `asn` | `lookup` |
+| `email` | `mx`, `disposable` |
+| `phone` | `lookup` |
+| `password` | `check` (k-anonymity SHA-1 prefix) |
+| `username` | `lookup` |
+| `check` | `secrets`, `injection`, `headers`, `dependencies` |
+| `scan` | `headers` (live HTTP scan) |
+
+The async client (`AsyncContrastAPI`) exposes the same namespace surface 1:1 — every method is `async def`.
+
+## Parity with the Node SDK
+
+| Surface | Node SDK | Python SDK |
+| --- | --- | --- |
+| Sync | ✅ (Promise-based) | ✅ (`ContrastAPI`) |
+| Async | (Promise model) | ✅ (`AsyncContrastAPI`) |
+| Namespace count | 13 | 14 (adds `username`) |
+| `bulk_technique_lookup` (ATLAS) | (added in v1.4.0) | ✅ |
+| `wayback` archive lookup | (added in v1.4.0) | ✅ |
+| Typed errors | `Error` subclasses | full hierarchy with envelope fields |
+| Shortcuts | — | ✅ `triage_ioc`, `audit_full`, `enrich_batch` |
+| Response models | `Promise<any>` | ✅ `TypedDict` (IDE autocomplete, no runtime cost) |
+
+## Configuration
+
+```python
+client = ContrastAPI(
+    api_key="cc_...",                  # optional; keyless = free tier
+    base_url="https://api.contrastcyber.com",  # override for self-host
+    timeout=30.0,                       # seconds; clamped to [1, 120]
+    allow_insecure=False,               # set True to allow http:// (dev only)
+)
+```
+
+The transport hard-caps response bodies at 10 MB, sends a `User-Agent: contrastapi-python/<version>` header, and refuses to send your API key over plaintext HTTP even when `allow_insecure=True`.
+
+## Links
+
+- API docs: https://api.contrastcyber.com/docs
+- Pricing & API key: https://contrastcyber.com/pricing
+- Source: https://github.com/UPinar/contrastapi
+- Issues: https://github.com/UPinar/contrastapi/issues
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).

contrastapi-1.22.3/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-1.22.3/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-1.22.3/contrastapi/_version.py

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