contrastapi 1.22.3__py3-none-any.whl

contrastapi/namespaces/atlas.py

@@ -0,0 +1,134 @@
+"""ATLAS namespace — MITRE ATLAS AI/ML attack catalog (techniques + case studies)."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._transport import _AsyncTransport, _SyncTransport
+from ..models import (
+    AtlasCaseStudyResponse,
+    AtlasCaseStudySearchResponse,
+    AtlasTechniqueResponse,
+    AtlasTechniqueSearchResponse,
+    BulkAtlasTechniqueResponse,
+)
+
+
+def _enc(value: str) -> str:
+    if value is None or value == "":
+        raise ValueError("Missing required parameter")
+    return quote(str(value), safe="")
+
+
+def _resolve_keyword(keyword: str | None, q: str | None) -> str | None:
+    """Server param is `keyword`; SDK accepts `keyword=` or back-compat `q=` (Node parity)."""
+    if keyword is not None and q is not None:
+        raise ValueError("Pass only one of `keyword` or `q` (q is a back-compat alias)")
+    return keyword if keyword is not None else q
+
+
+def _technique_search_params(
+    *,
+    keyword: str | None = None,
+    q: str | None = None,
+    tactic: str | None = None,
+    maturity: str | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+    include: str | None = None,
+    exclude_id: str | None = None,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    kw = _resolve_keyword(keyword, q)
+    if kw is not None:
+        params["keyword"] = kw
+    if tactic is not None:
+        params["tactic"] = tactic
+    if maturity is not None:
+        params["maturity"] = maturity
+    if limit is not None:
+        params["limit"] = limit
+    if offset is not None:
+        params["offset"] = offset
+    if include is not None:
+        params["include"] = include
+    if exclude_id is not None:
+        params["exclude_id"] = exclude_id
+    return params
+
+
+def _case_study_search_params(
+    *,
+    keyword: str | None = None,
+    q: str | None = None,
+    target_type: str | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+    include: str | None = None,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    kw = _resolve_keyword(keyword, q)
+    if kw is not None:
+        params["keyword"] = kw
+    if target_type is not None:
+        params["target_type"] = target_type
+    if limit is not None:
+        params["limit"] = limit
+    if offset is not None:
+        params["offset"] = offset
+    if include is not None:
+        params["include"] = include
+    return params
+
+
+def _validate_bulk(ids: list[str]) -> list[str]:
+    if not isinstance(ids, list) or not all(isinstance(i, str) for i in ids):
+        raise ValueError("technique_ids must be a list of strings")
+    return ids
+
+
+class Atlas:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def technique(self, technique_id: str) -> AtlasTechniqueResponse:
+        return self._t.get(f"/v1/atlas/{_enc(technique_id)}")
+
+    def technique_search(self, **kwargs: Any) -> AtlasTechniqueSearchResponse:
+        return self._t.get("/v1/atlas/techniques", params=_technique_search_params(**kwargs))
+
+    def bulk_technique_lookup(self, technique_ids: list[str]) -> BulkAtlasTechniqueResponse:
+        return self._t.post(
+            "/v1/atlas/techniques/bulk",
+            json_body={"technique_ids": _validate_bulk(technique_ids)},
+        )
+
+    def case_study(self, case_study_id: str) -> AtlasCaseStudyResponse:
+        return self._t.get(f"/v1/atlas/case-studies/{_enc(case_study_id)}")
+
+    def case_study_search(self, **kwargs: Any) -> AtlasCaseStudySearchResponse:
+        return self._t.get("/v1/atlas/case-studies", params=_case_study_search_params(**kwargs))
+
+
+class AsyncAtlas:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def technique(self, technique_id: str) -> AtlasTechniqueResponse:
+        return await self._t.aget(f"/v1/atlas/{_enc(technique_id)}")
+
+    async def technique_search(self, **kwargs: Any) -> AtlasTechniqueSearchResponse:
+        return await self._t.aget("/v1/atlas/techniques", params=_technique_search_params(**kwargs))
+
+    async def bulk_technique_lookup(self, technique_ids: list[str]) -> BulkAtlasTechniqueResponse:
+        return await self._t.apost(
+            "/v1/atlas/techniques/bulk",
+            json_body={"technique_ids": _validate_bulk(technique_ids)},
+        )
+
+    async def case_study(self, case_study_id: str) -> AtlasCaseStudyResponse:
+        return await self._t.aget(f"/v1/atlas/case-studies/{_enc(case_study_id)}")
+
+    async def case_study_search(self, **kwargs: Any) -> AtlasCaseStudySearchResponse:
+        return await self._t.aget("/v1/atlas/case-studies", params=_case_study_search_params(**kwargs))

contrastapi/namespaces/cve.py

@@ -0,0 +1,125 @@
+"""CVE namespace — vulnerabilities, KEV, CWE, exploits, bulk lookup, leading list."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._transport import _AsyncTransport, _SyncTransport
+from ..models import (
+    BulkCveResponse,
+    CveResponse,
+    CveSearchResponse,
+    CweLookupResponse,
+    ExploitResponse,
+    KevDetailResponse,
+)
+
+
+def _enc(value: str) -> str:
+    if value is None or value == "":
+        raise ValueError("Missing required parameter")
+    return quote(str(value), safe="")
+
+
+def _search_params(
+    *,
+    product: str | None = None,
+    severity: str | None = None,
+    days: int | None = None,
+    limit: int | None = None,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    if product is not None:
+        params["product"] = product
+    if severity is not None:
+        params["severity"] = severity
+    if days is not None:
+        params["days"] = days
+    if limit is not None:
+        params["limit"] = limit
+    return params
+
+
+def _leading_params(
+    *,
+    limit: int | None = None,
+    offset: int | None = None,
+    include: str | None = None,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    if limit is not None:
+        params["limit"] = limit
+    if offset is not None:
+        params["offset"] = offset
+    if include is not None:
+        params["include"] = include
+    return params
+
+
+def _validate_bulk_ids(ids: list[str]) -> list[str]:
+    if not isinstance(ids, list) or not all(isinstance(c, str) for c in ids):
+        raise ValueError("cve_ids must be a list of strings")
+    return ids
+
+
+class Cve:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def lookup(self, cve_id: str) -> CveResponse:
+        return self._t.get(f"/v1/cve/{_enc(cve_id)}")
+
+    def search(self, **kwargs: Any) -> CveSearchResponse:
+        return self._t.get("/v1/cves", params=_search_params(**kwargs))
+
+    def leading(self, **kwargs: Any) -> CveSearchResponse:
+        return self._t.get("/v1/cve/leading", params=_leading_params(**kwargs))
+
+    def kev(self, cve_id: str) -> KevDetailResponse:
+        return self._t.get(f"/v1/kev/{_enc(cve_id)}")
+
+    def exploit(self, cve_id: str) -> ExploitResponse:
+        return self._t.get(f"/v1/exploit/{_enc(cve_id)}")
+
+    def bulk(self, cve_ids: list[str]) -> BulkCveResponse:
+        return self._t.post("/v1/cves/bulk", json_body={"cve_ids": _validate_bulk_ids(cve_ids)})
+
+
+class Cwe:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def lookup(self, cwe_id: str) -> CweLookupResponse:
+        return self._t.get(f"/v1/cwe/{_enc(cwe_id)}")
+
+
+class AsyncCve:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def lookup(self, cve_id: str) -> CveResponse:
+        return await self._t.aget(f"/v1/cve/{_enc(cve_id)}")
+
+    async def search(self, **kwargs: Any) -> CveSearchResponse:
+        return await self._t.aget("/v1/cves", params=_search_params(**kwargs))
+
+    async def leading(self, **kwargs: Any) -> CveSearchResponse:
+        return await self._t.aget("/v1/cve/leading", params=_leading_params(**kwargs))
+
+    async def kev(self, cve_id: str) -> KevDetailResponse:
+        return await self._t.aget(f"/v1/kev/{_enc(cve_id)}")
+
+    async def exploit(self, cve_id: str) -> ExploitResponse:
+        return await self._t.aget(f"/v1/exploit/{_enc(cve_id)}")
+
+    async def bulk(self, cve_ids: list[str]) -> BulkCveResponse:
+        return await self._t.apost("/v1/cves/bulk", json_body={"cve_ids": _validate_bulk_ids(cve_ids)})
+
+
+class AsyncCwe:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def lookup(self, cwe_id: str) -> CweLookupResponse:
+        return await self._t.aget(f"/v1/cwe/{_enc(cwe_id)}")

contrastapi/namespaces/d3fend.py

@@ -0,0 +1,124 @@
+"""D3FEND namespace — MITRE D3FEND defense catalog mapped to ATT&CK."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._transport import _AsyncTransport, _SyncTransport
+from ..models import (
+    D3fendCoverageResponse,
+    D3fendDefenseResponse,
+    D3fendDefenseSearchResponse,
+    D3fendForAttackResponse,
+)
+
+
+def _enc(value: str) -> str:
+    if value is None or value == "":
+        raise ValueError("Missing required parameter")
+    return quote(str(value), safe="")
+
+
+def _resolve_keyword(keyword: str | None, q: str | None) -> str | None:
+    """Server param is `keyword`; SDK accepts `keyword=` or back-compat `q=` (Node parity).
+    Passing both raises so we don't silently pick a winner.
+    """
+    if keyword is not None and q is not None:
+        raise ValueError("Pass only one of `keyword` or `q` (q is a back-compat alias)")
+    return keyword if keyword is not None else q
+
+
+def _defense_search_params(
+    *,
+    keyword: str | None = None,
+    q: str | None = None,
+    tactic: str | None = None,
+    artifact: str | None = None,
+    limit: int | None = None,
+    offset: int | None = None,
+    include: str | None = None,
+    exclude_id: str | None = None,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    kw = _resolve_keyword(keyword, q)
+    if kw is not None:
+        params["keyword"] = kw
+    if tactic is not None:
+        params["tactic"] = tactic
+    if artifact is not None:
+        params["artifact"] = artifact
+    if limit is not None:
+        params["limit"] = limit
+    if offset is not None:
+        params["offset"] = offset
+    if include is not None:
+        params["include"] = include
+    if exclude_id is not None:
+        params["exclude_id"] = exclude_id
+    return params
+
+
+def _for_attack_params(
+    *,
+    include: str | None = None,
+    exclude_id: str | None = None,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {}
+    if include is not None:
+        params["include"] = include
+    if exclude_id is not None:
+        params["exclude_id"] = exclude_id
+    return params
+
+
+def _validate_attack_ids(ids: list[str]) -> list[str]:
+    if not isinstance(ids, list) or not all(isinstance(i, str) for i in ids):
+        raise ValueError("attack_technique_ids must be a list of strings")
+    return ids
+
+
+class D3fend:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def defense(self, defense_id: str) -> D3fendDefenseResponse:
+        return self._t.get(f"/v1/d3fend/{_enc(defense_id)}")
+
+    def defense_search(self, **kwargs: Any) -> D3fendDefenseSearchResponse:
+        return self._t.get("/v1/d3fend/defenses", params=_defense_search_params(**kwargs))
+
+    def defense_for_attack(self, attack_technique_id: str, **kwargs: Any) -> D3fendForAttackResponse:
+        return self._t.get(
+            f"/v1/d3fend/attack/{_enc(attack_technique_id)}",
+            params=_for_attack_params(**kwargs),
+        )
+
+    def coverage(self, attack_technique_ids: list[str]) -> D3fendCoverageResponse:
+        return self._t.post(
+            "/v1/d3fend/coverage",
+            json_body={"attack_technique_ids": _validate_attack_ids(attack_technique_ids)},
+        )
+
+
+class AsyncD3fend:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def defense(self, defense_id: str) -> D3fendDefenseResponse:
+        return await self._t.aget(f"/v1/d3fend/{_enc(defense_id)}")
+
+    async def defense_search(self, **kwargs: Any) -> D3fendDefenseSearchResponse:
+        return await self._t.aget("/v1/d3fend/defenses", params=_defense_search_params(**kwargs))
+
+    async def defense_for_attack(self, attack_technique_id: str, **kwargs: Any) -> D3fendForAttackResponse:
+        return await self._t.aget(
+            f"/v1/d3fend/attack/{_enc(attack_technique_id)}",
+            params=_for_attack_params(**kwargs),
+        )
+
+    async def coverage(self, attack_technique_ids: list[str]) -> D3fendCoverageResponse:
+        return await self._t.apost(
+            "/v1/d3fend/coverage",
+            json_body={"attack_technique_ids": _validate_attack_ids(attack_technique_ids)},
+        )

contrastapi/namespaces/domain.py

@@ -0,0 +1,129 @@
+"""Domain namespace — DNS, WHOIS, SSL, subdomains, tech, threat, monitor, vulns, audit, wayback."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from .._transport import _AsyncTransport, _SyncTransport
+from ..models import (
+    AuditResponse,
+    BulkDomainResponse,
+    CertsResponse,
+    DnsResponse,
+    DomainReportResponse,
+    SslResponse,
+    SubdomainsResponse,
+    TechResponse,
+    ThreatResponse,
+    WaybackResponse,
+    WhoisResponse,
+)
+
+
+def _enc(value: str) -> str:
+    if value is None or value == "":
+        raise ValueError("Missing required parameter")
+    return quote(str(value), safe="")
+
+
+def _validate_domains(domains: list[str]) -> list[str]:
+    if not isinstance(domains, list) or not all(isinstance(d, str) for d in domains):
+        raise ValueError("domains must be a list of strings")
+    return domains
+
+
+def _report_params(lite: bool) -> dict[str, Any] | None:
+    """`lite=True` → {"lite": "true"}; `lite=False` → None (clean URL).
+
+    Server treats only the literal string `true` as truthy (lowercase).
+    """
+    return {"lite": "true"} if lite else None
+
+
+class Domain:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def report(self, domain: str, *, lite: bool = False) -> DomainReportResponse:
+        return self._t.get(f"/v1/domain/{_enc(domain)}", params=_report_params(lite))
+
+    def dns(self, domain: str) -> DnsResponse:
+        return self._t.get(f"/v1/dns/{_enc(domain)}")
+
+    def whois(self, domain: str) -> WhoisResponse:
+        return self._t.get(f"/v1/whois/{_enc(domain)}")
+
+    def subdomains(self, domain: str) -> SubdomainsResponse:
+        return self._t.get(f"/v1/subdomains/{_enc(domain)}")
+
+    def certs(self, domain: str) -> CertsResponse:
+        return self._t.get(f"/v1/certs/{_enc(domain)}")
+
+    def ssl(self, domain: str) -> SslResponse:
+        return self._t.get(f"/v1/ssl/{_enc(domain)}")
+
+    def tech(self, domain: str) -> TechResponse:
+        return self._t.get(f"/v1/tech/{_enc(domain)}")
+
+    def threat(self, domain: str) -> ThreatResponse:
+        return self._t.get(f"/v1/threat/{_enc(domain)}")
+
+    def monitor(self, domain: str) -> dict[str, Any]:
+        return self._t.get(f"/v1/monitor/{_enc(domain)}")
+
+    def vulns(self, domain: str) -> dict[str, Any]:
+        return self._t.get(f"/v1/domain/{_enc(domain)}/vulns")
+
+    def audit(self, domain: str) -> AuditResponse:
+        return self._t.get(f"/v1/audit/{_enc(domain)}")
+
+    def wayback(self, domain: str) -> WaybackResponse:
+        return self._t.get(f"/v1/archive/{_enc(domain)}")
+
+    def bulk(self, domains: list[str]) -> BulkDomainResponse:
+        return self._t.post("/v1/domains/bulk", json_body={"domains": _validate_domains(domains)})
+
+
+class AsyncDomain:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def report(self, domain: str, *, lite: bool = False) -> DomainReportResponse:
+        return await self._t.aget(f"/v1/domain/{_enc(domain)}", params=_report_params(lite))
+
+    async def dns(self, domain: str) -> DnsResponse:
+        return await self._t.aget(f"/v1/dns/{_enc(domain)}")
+
+    async def whois(self, domain: str) -> WhoisResponse:
+        return await self._t.aget(f"/v1/whois/{_enc(domain)}")
+
+    async def subdomains(self, domain: str) -> SubdomainsResponse:
+        return await self._t.aget(f"/v1/subdomains/{_enc(domain)}")
+
+    async def certs(self, domain: str) -> CertsResponse:
+        return await self._t.aget(f"/v1/certs/{_enc(domain)}")
+
+    async def ssl(self, domain: str) -> SslResponse:
+        return await self._t.aget(f"/v1/ssl/{_enc(domain)}")
+
+    async def tech(self, domain: str) -> TechResponse:
+        return await self._t.aget(f"/v1/tech/{_enc(domain)}")
+
+    async def threat(self, domain: str) -> ThreatResponse:
+        return await self._t.aget(f"/v1/threat/{_enc(domain)}")
+
+    async def monitor(self, domain: str) -> dict[str, Any]:
+        return await self._t.aget(f"/v1/monitor/{_enc(domain)}")
+
+    async def vulns(self, domain: str) -> dict[str, Any]:
+        return await self._t.aget(f"/v1/domain/{_enc(domain)}/vulns")
+
+    async def audit(self, domain: str) -> AuditResponse:
+        return await self._t.aget(f"/v1/audit/{_enc(domain)}")
+
+    async def wayback(self, domain: str) -> WaybackResponse:
+        return await self._t.aget(f"/v1/archive/{_enc(domain)}")
+
+    async def bulk(self, domains: list[str]) -> BulkDomainResponse:
+        return await self._t.apost("/v1/domains/bulk", json_body={"domains": _validate_domains(domains)})

contrastapi/namespaces/intel.py

@@ -0,0 +1,151 @@
+"""Compact namespaces for endpoints with 1-2 methods each:
+ip, asn, email, phone, password, username.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote
+
+from .._transport import _AsyncTransport, _SyncTransport
+from ..models import (
+    AsnResponse,
+    DisposableResponse,
+    EmailMxResponse,
+    IpLookupResponse,
+    PasswordResponse,
+    PhoneLookupResponse,
+    ThreatReportResponse,
+    UsernameLookupResponse,
+)
+
+
+def _enc(value: str) -> str:
+    if value is None or value == "":
+        raise ValueError("Missing required parameter")
+    return quote(str(value), safe="")
+
+
+# --- IP ---
+
+
+class Ip:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def lookup(self, ip: str) -> IpLookupResponse:
+        return self._t.get(f"/v1/ip/{_enc(ip)}")
+
+    def threat_report(self, ip: str) -> ThreatReportResponse:
+        return self._t.get(f"/v1/threat-report/{_enc(ip)}")
+
+
+class AsyncIp:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def lookup(self, ip: str) -> IpLookupResponse:
+        return await self._t.aget(f"/v1/ip/{_enc(ip)}")
+
+    async def threat_report(self, ip: str) -> ThreatReportResponse:
+        return await self._t.aget(f"/v1/threat-report/{_enc(ip)}")
+
+
+# --- ASN ---
+
+
+class Asn:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def lookup(self, target: str) -> AsnResponse:
+        return self._t.get(f"/v1/asn/{_enc(target)}")
+
+
+class AsyncAsn:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def lookup(self, target: str) -> AsnResponse:
+        return await self._t.aget(f"/v1/asn/{_enc(target)}")
+
+
+# --- Email ---
+
+
+class Email:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def mx(self, domain: str) -> EmailMxResponse:
+        return self._t.get(f"/v1/email/mx/{_enc(domain)}")
+
+    def disposable(self, email: str) -> DisposableResponse:
+        return self._t.get(f"/v1/email/disposable/{_enc(email)}")
+
+
+class AsyncEmail:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def mx(self, domain: str) -> EmailMxResponse:
+        return await self._t.aget(f"/v1/email/mx/{_enc(domain)}")
+
+    async def disposable(self, email: str) -> DisposableResponse:
+        return await self._t.aget(f"/v1/email/disposable/{_enc(email)}")
+
+
+# --- Phone ---
+
+
+class Phone:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def lookup(self, number: str) -> PhoneLookupResponse:
+        return self._t.get(f"/v1/phone/{_enc(number)}")
+
+
+class AsyncPhone:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def lookup(self, number: str) -> PhoneLookupResponse:
+        return await self._t.aget(f"/v1/phone/{_enc(number)}")
+
+
+# --- Password ---
+
+
+class Password:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def check(self, sha1_hash: str) -> PasswordResponse:
+        return self._t.get(f"/v1/password/{_enc(sha1_hash)}")
+
+
+class AsyncPassword:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def check(self, sha1_hash: str) -> PasswordResponse:
+        return await self._t.aget(f"/v1/password/{_enc(sha1_hash)}")
+
+
+# --- Username (NEW vs Node SDK v1.3.0) ---
+
+
+class Username:
+    def __init__(self, transport: _SyncTransport) -> None:
+        self._t = transport
+
+    def lookup(self, username: str) -> UsernameLookupResponse:
+        return self._t.get(f"/v1/username/{_enc(username)}")
+
+
+class AsyncUsername:
+    def __init__(self, transport: _AsyncTransport) -> None:
+        self._t = transport
+
+    async def lookup(self, username: str) -> UsernameLookupResponse:
+        return await self._t.aget(f"/v1/username/{_enc(username)}")