contrastapi 1.22.3__py3-none-any.whl

contrastapi/namespaces/ioc.py

@@ -0,0 +1,61 @@
+"""IOC namespace — indicator lookup, hash, phishing, bulk."""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from .._transport import _AsyncTransport, _SyncTransport
+from ..models import BulkIocResponse, HashResponse, IocResponse, PhishingResponse
+
+
+def _enc(value: str) -> str:
+    if value is None or value == "":
+        raise ValueError("Missing required parameter")
+    return quote(str(value), safe="")
+
+
+def _enc_path(value: str) -> str:
+    """For URL-typed indicators (paths) — preserve `/` as a separator."""
+    if value is None or value == "":
+        raise ValueError("Missing required parameter")
+    return "/".join(quote(seg, safe="") for seg in str(value).split("/"))
+
+
+def _validate_bulk(items: list[str]) -> list[str]:
+    if not isinstance(items, list) or not all(isinstance(i, str) for i in items):
+        raise ValueError("indicators must be a list of strings")
+    return items
+
+
+class Ioc:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def lookup(self, indicator: str) -> IocResponse:
+        return self._t.get(f"/v1/ioc/{_enc_path(indicator)}")
+
+    def hash(self, file_hash: str) -> HashResponse:
+        return self._t.get(f"/v1/hash/{_enc(file_hash)}")
+
+    def phishing(self, url: str) -> PhishingResponse:
+        return self._t.get(f"/v1/phishing/{_enc_path(url)}")
+
+    def bulk(self, indicators: list[str]) -> BulkIocResponse:
+        return self._t.post("/v1/iocs/bulk", json_body={"indicators": _validate_bulk(indicators)})
+
+
+class AsyncIoc:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def lookup(self, indicator: str) -> IocResponse:
+        return await self._t.aget(f"/v1/ioc/{_enc_path(indicator)}")
+
+    async def hash(self, file_hash: str) -> HashResponse:
+        return await self._t.aget(f"/v1/hash/{_enc(file_hash)}")
+
+    async def phishing(self, url: str) -> PhishingResponse:
+        return await self._t.aget(f"/v1/phishing/{_enc_path(url)}")
+
+    async def bulk(self, indicators: list[str]) -> BulkIocResponse:
+        return await self._t.apost("/v1/iocs/bulk", json_body={"indicators": _validate_bulk(indicators)})

contrastapi/namespaces/security.py

@@ -0,0 +1,94 @@
+"""Code-security + live-scan namespaces."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._transport import _AsyncTransport, _SyncTransport
+from ..models import (
+    CheckHeadersResponse,
+    CodeCheckResponse,
+    DependenciesResponse,
+    ScanHeadersResponse,
+)
+
+
+def _enc(value: str) -> str:
+    if value is None or value == "":
+        raise ValueError("Missing required parameter")
+    return quote(str(value), safe="")
+
+
+def _validate_packages(packages: list[str]) -> list[str]:
+    if not isinstance(packages, list) or not all(isinstance(p, str) for p in packages):
+        raise ValueError("packages must be a list of strings")
+    return packages
+
+
+def _validate_headers(headers: dict[str, str]) -> dict[str, str]:
+    if not isinstance(headers, dict):
+        raise ValueError("headers must be a dict[str, str]")
+    return headers
+
+
+class Check:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def secrets(self, code: str, language: str | None = None) -> CodeCheckResponse:
+        body: dict[str, Any] = {"code": code}
+        if language is not None:
+            body["language"] = language
+        return self._t.post("/v1/check/secrets", json_body=body)
+
+    def injection(self, code: str, language: str | None = None) -> CodeCheckResponse:
+        body: dict[str, Any] = {"code": code}
+        if language is not None:
+            body["language"] = language
+        return self._t.post("/v1/check/injection", json_body=body)
+
+    def headers(self, headers: dict[str, str]) -> CheckHeadersResponse:
+        return self._t.post("/v1/check/headers", json_body={"headers": _validate_headers(headers)})
+
+    def dependencies(self, packages: list[str]) -> DependenciesResponse:
+        return self._t.post("/v1/check/dependencies", json_body={"packages": _validate_packages(packages)})
+
+
+class Scan:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def headers(self, domain: str) -> ScanHeadersResponse:
+        return self._t.get(f"/v1/scan/headers/{_enc(domain)}")
+
+
+class AsyncCheck:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def secrets(self, code: str, language: str | None = None) -> CodeCheckResponse:
+        body: dict[str, Any] = {"code": code}
+        if language is not None:
+            body["language"] = language
+        return await self._t.apost("/v1/check/secrets", json_body=body)
+
+    async def injection(self, code: str, language: str | None = None) -> CodeCheckResponse:
+        body: dict[str, Any] = {"code": code}
+        if language is not None:
+            body["language"] = language
+        return await self._t.apost("/v1/check/injection", json_body=body)
+
+    async def headers(self, headers: dict[str, str]) -> CheckHeadersResponse:
+        return await self._t.apost("/v1/check/headers", json_body={"headers": _validate_headers(headers)})
+
+    async def dependencies(self, packages: list[str]) -> DependenciesResponse:
+        return await self._t.apost("/v1/check/dependencies", json_body={"packages": _validate_packages(packages)})
+
+
+class AsyncScan:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def headers(self, domain: str) -> ScanHeadersResponse:
+        return await self._t.aget(f"/v1/scan/headers/{_enc(domain)}")

contrastapi/shortcuts.py

@@ -0,0 +1,182 @@
+"""High-level convenience helpers that compose multiple namespace calls.
+
+These wrap common multi-call patterns so callers don't have to glue endpoints
+together by hand. Each helper accepts a `ContrastAPI` (sync) instance; async
+variants are intentionally omitted in this batch — call the async client's
+namespace methods directly with `asyncio.gather` if you need parallelism.
+
+Convention: shortcuts swallow per-leg ContrastAPIError instances and report
+them in the returned dict under `errors[<key>]` so a partial failure doesn't
+nuke the whole report. The caller still gets every leg that succeeded.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+from typing import Any
+
+from .client import ContrastAPI
+from .exceptions import ContrastAPIError, TransportError
+
+_HEX64 = re.compile(r"^[0-9a-fA-F]{32,128}$")
+
+
+def _record_or_reraise(out: dict[str, Any], key: str, exc: ContrastAPIError) -> None:
+    """Record a per-leg failure into the helper's error dict — but propagate
+    `TransportError` (network/MITM/DNS-poison) so security incidents aren't
+    masked as opaque error strings. Application-layer errors (4xx/5xx) keep
+    the swallow-and-report behaviour callers depend on for partial-success
+    reports.
+    """
+    if isinstance(exc, TransportError):
+        raise exc
+    out["errors"][key] = exc.message
+
+
+def _classify_ioc(value: str) -> str:
+    """Best-effort IOC type detection: 'ip' | 'hash' | 'domain' | 'unknown'.
+
+    Mirrors the server's input router so callers see the same routing the API
+    would apply. Domain is the broad fallback (anything with a dot or letters).
+    """
+    value = value.strip()
+    try:
+        ipaddress.ip_address(value)
+        return "ip"
+    except ValueError:
+        pass
+    if _HEX64.match(value):
+        return "hash"
+    if "." in value or value.replace("-", "").isalnum():
+        return "domain"
+    return "unknown"
+
+
+def triage_ioc(client: ContrastAPI, indicator: str) -> dict[str, Any]:
+    """Run the right enrichment for a single IOC.
+
+    For an IP: ioc_lookup + threat_report.
+    For a domain: ioc_lookup + domain_report.
+    For a hash: ioc_lookup + hash_lookup.
+    Any unrecognised input still gets ioc_lookup (the server is the final word).
+
+    Returns:
+        {"indicator": ..., "kind": ..., "ioc": {...}, "threat_report"|"domain_report"|"hash": {...},
+         "errors": {<leg>: <error message>}}
+    """
+    kind = _classify_ioc(indicator)
+    out: dict[str, Any] = {"indicator": indicator, "kind": kind, "errors": {}}
+
+    try:
+        out["ioc"] = client.ioc.lookup(indicator)
+    except ContrastAPIError as exc:
+        _record_or_reraise(out, "ioc", exc)
+
+    if kind == "ip":
+        try:
+            out["threat_report"] = client.ip.threat_report(indicator)
+        except ContrastAPIError as exc:
+            _record_or_reraise(out, "threat_report", exc)
+    elif kind == "domain":
+        try:
+            out["domain_report"] = client.domain.report(indicator)
+        except ContrastAPIError as exc:
+            _record_or_reraise(out, "domain_report", exc)
+    elif kind == "hash":
+        try:
+            out["hash"] = client.ioc.hash(indicator)
+        except ContrastAPIError as exc:
+            _record_or_reraise(out, "hash", exc)
+
+    return out
+
+
+def audit_full(
+    client: ContrastAPI,
+    domain: str,
+    *,
+    ssl_subdomains: int = 5,
+) -> dict[str, Any]:
+    """Run a deep audit on a domain.
+
+    Composes `audit_domain` + `subdomain_enum` (top-N) + `tech_fingerprint` +
+    per-subdomain `ssl_check` (capped at `ssl_subdomains` to keep credit cost
+    bounded — default 5).
+
+    Returns a dict with `audit`, `subdomains`, `tech`, `ssl` (per-subdomain
+    map), and `errors` (per-leg failure messages).
+    """
+    if ssl_subdomains < 0:
+        raise ValueError("ssl_subdomains must be >= 0")
+
+    out: dict[str, Any] = {"domain": domain, "errors": {}, "ssl": {}}
+
+    try:
+        out["audit"] = client.domain.audit(domain)
+    except ContrastAPIError as exc:
+        _record_or_reraise(out, "audit", exc)
+
+    subdomains: list[str] = []
+    try:
+        sub_response = client.domain.subdomains(domain)
+        out["subdomains"] = sub_response
+        # Server response shape: {"subdomains": [...], "count": N, ...}
+        candidates = sub_response.get("subdomains") or []
+        subdomains = [s for s in candidates if isinstance(s, str)][:ssl_subdomains]
+    except ContrastAPIError as exc:
+        _record_or_reraise(out, "subdomains", exc)
+
+    try:
+        out["tech"] = client.domain.tech(domain)
+    except ContrastAPIError as exc:
+        _record_or_reraise(out, "tech", exc)
+
+    for sub in subdomains:
+        try:
+            out["ssl"][sub] = client.domain.ssl(sub)
+        except ContrastAPIError as exc:
+            _record_or_reraise(out, f"ssl:{sub}", exc)
+
+    return out
+
+
+def enrich_batch(client: ContrastAPI, items: list[str]) -> dict[str, Any]:
+    """Auto-detect IOC vs CVE for each item and route to the right bulk endpoint.
+
+    Items matching the `CVE-YYYY-NNNN+` pattern go to `cve.bulk`; everything
+    else goes to `ioc.bulk`. If both buckets are non-empty the helper makes two
+    calls; if only one bucket has items it makes a single call. Returns:
+
+        {"cve": <bulk_cve_response or None>, "ioc": <bulk_ioc_response or None>,
+         "routed": {"cve": [...], "ioc": [...]}, "errors": {...}}
+    """
+    if not isinstance(items, list) or not all(isinstance(i, str) for i in items):
+        raise ValueError("items must be a list of strings")
+
+    # Match server-side validator: uppercase canonical, NVD spec allows 3+
+    # digit suffix (e.g. CVE-2024-123 is valid). Lowercase routes to IOC bucket.
+    cve_pattern = re.compile(r"^CVE-\d{4}-\d{3,}$")
+    cves = [i for i in items if cve_pattern.match(i)]
+    iocs = [i for i in items if not cve_pattern.match(i)]
+
+    out: dict[str, Any] = {
+        "cve": None,
+        "ioc": None,
+        "routed": {"cve": cves, "ioc": iocs},
+        "errors": {},
+    }
+
+    if cves:
+        try:
+            out["cve"] = client.cve.bulk(cves)
+        except ContrastAPIError as exc:
+            _record_or_reraise(out, "cve", exc)
+
+    if iocs:
+        try:
+            out["ioc"] = client.ioc.bulk(iocs)
+        except ContrastAPIError as exc:
+            _record_or_reraise(out, "ioc", exc)
+
+    return out

contrastapi-1.22.3.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,18 @@
+contrastapi/__init__.py,sha256=gqO2vZ1BJUh7p8nKHxEZk-K-DnY14ae2OUtS5vvyOUg,853
+contrastapi/_transport.py,sha256=B1XylHEm3irTph0_ifUKLUq_rgHuiXwgMgb5ajaBlec,6384
+contrastapi/_version.py,sha256=mumhYmLDqKimAeCXo3ds24UHb0h9ALM2B7GrhoFegAI,23
+contrastapi/client.py,sha256=bpon6dHpoQ3SLCi9NmhUuVENNEeB5bfjMBhZVvYJMzo,5513
+contrastapi/exceptions.py,sha256=VYsAiL1_aEzrdTiToGcO6a6VMQZ_8twbUrWwmrFyNwo,5881
+contrastapi/models.py,sha256=sbu3aQ_QwYrgHmNw_G3eB9qWW0f0lwkIe6Bmiw65ANs,14892
+contrastapi/shortcuts.py,sha256=edUnGiLg3xieZswX3SN1agJtNkxqbEg5sJ5MWVihX8w,6319
+contrastapi/namespaces/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+contrastapi/namespaces/atlas.py,sha256=vsVwxwKtSuB9UZj2RkAAHhxfaGzriDclnD79tsV8AgM,4664
+contrastapi/namespaces/cve.py,sha256=5-tHpVE1fsegvQ8BKrvAfVT6_BB3k1VJb0fqeoxGuZA,3841
+contrastapi/namespaces/d3fend.py,sha256=qsr1sdhCbiRYxbUBiGCAyBkcU0poe3iq-miKeWpOWnw,4169
+contrastapi/namespaces/domain.py,sha256=8fh6M3BPSlhApA8np3FH34fcCaY45oXne-LEDLthJOI,4611
+contrastapi/namespaces/intel.py,sha256=FepgCxs2xgm1qAlpdN-3BpEyZEh54VUE4DQ7wQSEO4Q,3955
+contrastapi/namespaces/ioc.py,sha256=gDgfqa5WlvpvPH7bZbCkQ81dexcQY_Ms4NiIXzfhMF4,2196
+contrastapi/namespaces/security.py,sha256=iVi-oSaYbXTlr3vMXJ3k8055aGbljnGgXEtkjilM2vU,3419
+contrastapi-1.22.3.dist-info/METADATA,sha256=-sOOxnwz_gj657nT2Cvltxt6Bxw7Wi-bKA9GeZyEjsc,7533
+contrastapi-1.22.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+contrastapi-1.22.3.dist-info/RECORD,,

contrastapi-1.22.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any