pangea-sdk 3.8.0b1__py3-none-any.whl → 5.3.0__py3-none-any.whl

pangea/services/intel.py

@@ -1,5 +1,7 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
+
 import enum
 import hashlib
 from typing import Dict, List, Optional
@@ -524,7 +526,7 @@ class FileIntel(ServiceBase):
             )
         """
         input = FileReputationRequest(hash=hash, hash_type=hash_type, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v1/reputation", FileReputationResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/reputation", FileReputationResult, data=input.model_dump(exclude_none=True))
 
     def hash_reputation_bulk(
         self,
@@ -563,7 +565,7 @@ class FileIntel(ServiceBase):
         input = FileReputationBulkRequest(  # type: ignore[call-arg]
             hashes=hashes, hash_type=hash_type, verbose=verbose, raw=raw, provider=provider
         )
-        return self.request.post("v2/reputation", FileReputationBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/reputation", FileReputationBulkResult, data=input.model_dump(exclude_none=True))
 
     def filepath_reputation(
         self,
@@ -708,7 +710,7 @@ class DomainIntel(ServiceBase):
             )
         """
         input = DomainReputationRequest(domain=domain, verbose=verbose, provider=provider, raw=raw)
-        return self.request.post("v1/reputation", DomainReputationResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/reputation", DomainReputationResult, data=input.model_dump(exclude_none=True))
 
     def reputation_bulk(
         self,
@@ -744,7 +746,7 @@ class DomainIntel(ServiceBase):
             )
         """
         input = DomainReputationBulkRequest(domains=domains, verbose=verbose, provider=provider, raw=raw)
-        return self.request.post("v2/reputation", DomainReputationBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/reputation", DomainReputationBulkResult, data=input.model_dump(exclude_none=True))
 
     def who_is(
         self, domain: str, verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -776,7 +778,7 @@ class DomainIntel(ServiceBase):
             )
         """
         input = DomainWhoIsRequest(domain=domain, verbose=verbose, provider=provider, raw=raw)  # type: ignore[call-arg]
-        return self.request.post("v1/whois", DomainWhoIsResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/whois", DomainWhoIsResult, data=input.model_dump(exclude_none=True))
 
 
 class IpIntel(ServiceBase):
@@ -819,7 +821,7 @@ class IpIntel(ServiceBase):
             ip (str): The IP to be looked up
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
-            provider (str, optional): Use reputation data from this provider: "crowdstrike"
+            provider (str, optional): Use reputation data from this provider
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -835,11 +837,11 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPReputationRequest(ip=ip, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v1/reputation", IPReputationResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/reputation", IPReputationResult, data=input.model_dump(exclude_none=True))
 
     def reputation_bulk(
         self, ips: List[str], verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
-    ) -> PangeaResponse[IPReputationResult]:
+    ) -> PangeaResponse[IPReputationBulkResult]:
         """
         Reputation V2
 
@@ -851,7 +853,7 @@ class IpIntel(ServiceBase):
             ips (List[str]): The IP list to be looked up
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
-            provider (str, optional): Use reputation data from this provider: "crowdstrike"
+            provider (str, optional): Use reputation data from this provider
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -867,7 +869,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPReputationBulkRequest(ips=ips, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v2/reputation", IPReputationBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/reputation", IPReputationBulkResult, data=input.model_dump(exclude_none=True))
 
     def geolocate(
         self, ip: str, verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -899,7 +901,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPGeolocateRequest(ip=ip, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v1/geolocate", IPGeolocateResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/geolocate", IPGeolocateResult, data=input.model_dump(exclude_none=True))
 
     def geolocate_bulk(
         self, ips: List[str], verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -931,7 +933,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPGeolocateBulkRequest(ips=ips, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v2/geolocate", IPGeolocateBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/geolocate", IPGeolocateBulkResult, data=input.model_dump(exclude_none=True))
 
     def get_domain(
         self, ip: str, verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -963,7 +965,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPDomainRequest(ip=ip, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v1/domain", IPDomainResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/domain", IPDomainResult, data=input.model_dump(exclude_none=True))
 
     def get_domain_bulk(
         self, ips: List[str], verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -995,7 +997,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPDomainBulkRequest(ips=ips, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v2/domain", IPDomainBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/domain", IPDomainBulkResult, data=input.model_dump(exclude_none=True))
 
     def is_vpn(
         self, ip: str, verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -1027,7 +1029,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPVPNRequest(ip=ip, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v1/vpn", IPVPNResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/vpn", IPVPNResult, data=input.model_dump(exclude_none=True))
 
     def is_vpn_bulk(
         self, ips: List[str], verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -1059,7 +1061,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPVPNBulkRequest(ips=ips, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v2/vpn", IPVPNBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/vpn", IPVPNBulkResult, data=input.model_dump(exclude_none=True))
 
     def is_proxy(
         self, ip: str, verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -1091,7 +1093,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPProxyRequest(ip=ip, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v1/proxy", IPProxyResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/proxy", IPProxyResult, data=input.model_dump(exclude_none=True))
 
     def is_proxy_bulk(
         self, ips: List[str], verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
@@ -1123,7 +1125,7 @@ class IpIntel(ServiceBase):
             )
         """
         input = IPProxyBulkRequest(ips=ips, verbose=verbose, raw=raw, provider=provider)
-        return self.request.post("v2/proxy", IPProxyBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/proxy", IPProxyBulkResult, data=input.model_dump(exclude_none=True))
 
 
 class UrlIntel(ServiceBase):
@@ -1170,7 +1172,7 @@ class UrlIntel(ServiceBase):
             url (str): The URL to be looked up
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
-            provider (str, optional): Use reputation data from this provider: "crowdstrike"
+            provider (str, optional): Use reputation data from this provider
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -1187,7 +1189,7 @@ class UrlIntel(ServiceBase):
         """
 
         input = URLReputationRequest(url=url, provider=provider, verbose=verbose, raw=raw)
-        return self.request.post("v1/reputation", URLReputationResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/reputation", URLReputationResult, data=input.model_dump(exclude_none=True))
 
     def reputation_bulk(
         self,
@@ -1195,7 +1197,7 @@ class UrlIntel(ServiceBase):
         verbose: Optional[bool] = None,
         raw: Optional[bool] = None,
         provider: Optional[str] = None,
-    ) -> PangeaResponse[URLReputationResult]:
+    ) -> PangeaResponse[URLReputationBulkResult]:
         """
         Reputation V2
 
@@ -1207,7 +1209,7 @@ class UrlIntel(ServiceBase):
             urls (List[str]): The URL list to be looked up
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
-            provider (str, optional): Use reputation data from this provider: "crowdstrike"
+            provider (str, optional): Use reputation data from this provider
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -1224,7 +1226,7 @@ class UrlIntel(ServiceBase):
         """
 
         input = URLReputationBulkRequest(urls=urls, provider=provider, verbose=verbose, raw=raw)
-        return self.request.post("v2/reputation", URLReputationBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/reputation", URLReputationBulkResult, data=input.model_dump(exclude_none=True))
 
 
 class UserBreachedRequest(IntelCommonRequest):
@@ -1237,6 +1239,7 @@ class UserBreachedRequest(IntelCommonRequest):
     phone_number (str): A phone number to search for. minLength: 7, maxLength: 15.
     start (str): Earliest date for search
     end (str): Latest date for search
+    cursor (str, optional): A token given in the raw response from SpyCloud. Post this back to paginate results
     """
 
     email: Optional[str] = None
@@ -1245,6 +1248,10 @@ class UserBreachedRequest(IntelCommonRequest):
     phone_number: Optional[str] = None
     start: Optional[str] = None
     end: Optional[str] = None
+    cursor: Optional[str] = None
+
+    severity: Optional[List[int]] = None
+    """Filter for records that match one of the given severities"""
 
 
 class UserBreachedBulkRequest(IntelCommonRequest):
@@ -1255,6 +1262,7 @@ class UserBreachedBulkRequest(IntelCommonRequest):
     usernames (List[str]): An username' list to search for
     ips (List[str]): An ip's list to search for
     phone_numbers (List[str]): A phone number's list to search for. minLength: 7, maxLength: 15.
+    domains (List[str]): Search for user under these domains.
     start (str): Earliest date for search
     end (str): Latest date for search
     """
@@ -1263,9 +1271,13 @@ class UserBreachedBulkRequest(IntelCommonRequest):
     usernames: Optional[List[str]] = None
     ips: Optional[List[str]] = None
     phone_numbers: Optional[List[str]] = None
+    domains: Optional[List[str]] = None
     start: Optional[str] = None
     end: Optional[str] = None
 
+    severity: Optional[List[int]] = None
+    """Filter for records that match one of the given severities"""
+
 
 class UserBreachedCommonData(PangeaResponseResult):
     """
@@ -1314,7 +1326,7 @@ class UserPasswordBreachedRequest(IntelCommonRequest):
 
 class UserPasswordBreachedBulkRequest(IntelCommonRequest):
     """
-    User password breached common request data
+    User password breached bulk request data
 
     hash_type (str): Hash type to be looked up
     hash_prefixes (List[str]): The list of prefixes of the hashes to be looked up.
@@ -1348,6 +1360,44 @@ class UserPasswordBreachedBulkResult(IntelCommonResult):
     data: Dict[str, UserPasswordBreachedData]
 
 
+class BreachRequest(APIRequestModel):
+    """Breach request data"""
+
+    breach_id: Optional[str] = None
+    """The ID of a breach returned by a provider."""
+
+    verbose: Optional[bool] = None
+    """Echo back the parameters of the API in the response."""
+
+    provider: Optional[str] = None
+    """Provider of the information. Default provider defined by the configuration."""
+
+    severity: Optional[List[int]] = None
+    """Filter for records that match one of the given severities"""
+
+    start: Optional[str] = None
+    """This parameter allows you to define the starting point for a date range query on the spycloud_publish_date field."""
+
+    end: Optional[str] = None
+    """This parameter allows you to define the ending point for a date range query on the spycloud_publish_date field."""
+
+    cursor: Optional[str] = None
+    """A token given in the raw response from SpyCloud. Post this back to paginate results"""
+
+
+class BreachResult(PangeaResponseResult):
+    """Breach result"""
+
+    found: bool
+    """A flag indicating if the lookup was successful."""
+
+    data: Optional[Dict] = None
+    """Breach details given by the provider."""
+
+    parameters: Optional[Dict] = None
+    """The parameters, which were passed in the request, echoed back."""
+
+
 class UserIntel(ServiceBase):
     """User Intel service client.
 
@@ -1385,6 +1435,8 @@ class UserIntel(ServiceBase):
         verbose: Optional[bool] = None,
         raw: Optional[bool] = None,
         provider: Optional[str] = None,
+        cursor: Optional[str] = None,
+        severity: Optional[List[int]] = None,
     ) -> PangeaResponse[UserBreachedResult]:
         """
         Look up breached users
@@ -1402,7 +1454,9 @@ class UserIntel(ServiceBase):
             end (str): Latest date for search
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
-            provider (str, optional): Use reputation data from this provider: "spycloud"
+            provider (str, optional): Use reputation data from this provider
+            cursor (str, optional): A token given in the raw response from SpyCloud. Post this back to paginate results
+            severity (List[int], optional): Filter for records that match one of the given severities
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -1430,8 +1484,10 @@ class UserIntel(ServiceBase):
             end=end,
             verbose=verbose,
             raw=raw,
+            cursor=cursor,
+            severity=severity,
         )
-        return self.request.post("v1/user/breached", UserBreachedResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/user/breached", UserBreachedResult, data=input.model_dump(exclude_none=True))
 
     def user_breached_bulk(
         self,
@@ -1439,11 +1495,13 @@ class UserIntel(ServiceBase):
         usernames: Optional[List[str]] = None,
         ips: Optional[List[str]] = None,
         phone_numbers: Optional[List[str]] = None,
+        domains: Optional[List[str]] = None,
         start: Optional[str] = None,
         end: Optional[str] = None,
         verbose: Optional[bool] = None,
         raw: Optional[bool] = None,
         provider: Optional[str] = None,
+        severity: Optional[List[int]] = None,
     ) -> PangeaResponse[UserBreachedBulkResult]:
         """
         Look up breached users V2
@@ -1457,11 +1515,13 @@ class UserIntel(ServiceBase):
             usernames (List[str]): A list of usernames to search for
             ips (List[str]): A list of ips to search for
             phone_numbers (List[str]): A list of phone numbers to search for. minLength: 7, maxLength: 15.
+            domains (List[str]): Search for user under these domains.
             start (str): Earliest date for search
             end (str): Latest date for search
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
-            provider (str, optional): Use reputation data from this provider: "spycloud"
+            provider (str, optional): Use reputation data from this provider
+            severity (List[int], optional): Filter for records that match one of the given severities
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -1484,13 +1544,15 @@ class UserIntel(ServiceBase):
             phone_numbers=phone_numbers,
             usernames=usernames,
             ips=ips,
+            domains=domains,
             provider=provider,
             start=start,
             end=end,
             verbose=verbose,
             raw=raw,
+            severity=severity,
         )
-        return self.request.post("v2/user/breached", UserBreachedBulkResult, data=input.dict(exclude_none=True))
+        return self.request.post("v2/user/breached", UserBreachedBulkResult, data=input.model_dump(exclude_none=True))
 
     def password_breached(
         self,
@@ -1512,7 +1574,7 @@ class UserIntel(ServiceBase):
             hash_prefix (str): The prefix of the hash to be looked up.
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
-            provider (str, optional): Use reputation data from this provider: "crowdstrike"
+            provider (str, optional): Use reputation data from this provider
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -1532,7 +1594,9 @@ class UserIntel(ServiceBase):
         input = UserPasswordBreachedRequest(
             hash_type=hash_type, hash_prefix=hash_prefix, provider=provider, verbose=verbose, raw=raw
         )
-        return self.request.post("v1/password/breached", UserPasswordBreachedResult, data=input.dict(exclude_none=True))
+        return self.request.post(
+            "v1/password/breached", UserPasswordBreachedResult, data=input.model_dump(exclude_none=True)
+        )
 
     def password_breached_bulk(
         self,
@@ -1554,7 +1618,7 @@ class UserIntel(ServiceBase):
             hash_prefixes (List[str]): The list of prefixes of the hashes to be looked up.
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
-            provider (str, optional): Use reputation data from this provider: "crowdstrike"
+            provider (str, optional): Use reputation data from this provider
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -1575,9 +1639,59 @@ class UserIntel(ServiceBase):
             hash_type=hash_type, hash_prefixes=hash_prefixes, provider=provider, verbose=verbose, raw=raw
         )
         return self.request.post(
-            "v2/password/breached", UserPasswordBreachedBulkResult, data=input.dict(exclude_none=True)
+            "v2/password/breached", UserPasswordBreachedBulkResult, data=input.model_dump(exclude_none=True)
         )
 
+    def breach(
+        self,
+        breach_id: Optional[str] = None,
+        verbose: Optional[bool] = None,
+        provider: Optional[str] = None,
+        cursor: Optional[str] = None,
+        start: Optional[str] = None,
+        end: Optional[str] = None,
+        severity: Optional[List[int]] = None,
+    ) -> PangeaResponse[BreachResult]:
+        """
+        Look up information about a specific breach
+
+        Given a provider specific breach ID, find details about the breach.
+
+        OperationId: user_intel_post_v1_breach
+
+        Args:
+            breach_id (str, optional): The ID of a breach returned by a provider
+            verbose (bool, optional): Echo the API parameters in the response
+            provider (str, optional): Use reputation data from this provider
+            cursor (str, optional): A token given in the raw response from SpyCloud. Post this back to paginate results
+            start (str, optional): This parameter allows you to define the starting point for a date range query on the spycloud_publish_date field
+            end (str, optional): This parameter allows you to define the ending point for a date range query on the spycloud_publish_date field
+            severity (List[int], optional): Filter for records that match one of the given severities
+
+        Raises:
+            PangeaAPIException: If an API Error happens
+
+        Returns:
+            A PangeaResponse where the breach details are in the
+                response.result field.  Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/user-intel)
+
+        Examples:
+            response = user_intel.breach(
+                breach_id="66111",
+            )
+        """
+
+        input = BreachRequest(
+            breach_id=breach_id,
+            provider=provider,
+            verbose=verbose,
+            cursor=cursor,
+            start=start,
+            end=end,
+            severity=severity,
+        )
+        return self.request.post("v1/breach", BreachResult, data=input.model_dump(exclude_none=True))
+
     class PasswordStatus(enum.Enum):
         BREACHED = 0
         UNBREACHED = 1
@@ -1585,6 +1699,17 @@ class UserIntel(ServiceBase):
 
     @staticmethod
     def is_password_breached(response: PangeaResponse[UserBreachedResult], hash: str) -> PasswordStatus:
+        """
+        Check if a password was breached
+
+        Helper function that simplifies searching the response's raw data for
+        the full hash.
+
+        Args:
+            response: API response from an earlier request
+            hash: Password hash
+        """
+
         if response.result.raw_data is None:  # type: ignore[union-attr]
             raise PangeaException("Need raw data to check if hash is breached. Send request with raw=true")