pangea-sdk 5.0.0__py3-none-any.whl → 5.2.0__py3-none-any.whl

pangea/request.py

@@ -11,7 +11,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Sequence, Tuple, Ty
 import requests
 from pydantic import BaseModel
 from requests.adapters import HTTPAdapter, Retry
-from requests_toolbelt import MultipartDecoder  # type: ignore
+from requests_toolbelt import MultipartDecoder  # type: ignore[import-untyped]
 from typing_extensions import TypeVar
 
 import pangea
@@ -402,7 +402,20 @@ class PangeaRequest(PangeaRequestBase):
 
         return self._check_response(pangea_response)
 
-    def download_file(self, url: str, filename: Optional[str] = None) -> AttachedFile:
+    def download_file(self, url: str, filename: str | None = None) -> AttachedFile:
+        """
+        Download file
+
+        Download a file from the specified URL and save it with the given
+        filename.
+
+        Args:
+            url: URL of the file to download
+            filename: Name to save the downloaded file as. If not provided, the
+              filename will be determined from the Content-Disposition header or
+              the URL.
+        """
+
         self.logger.debug(
             json.dumps(
                 {
@@ -467,10 +480,8 @@ class PangeaRequest(PangeaRequestBase):
     ) -> PangeaResponse:
         # Send request
         try:
-            # This should return 202 (AcceptedRequestException)
-            resp = self.post(endpoint=endpoint, result_class=result_class, data=data, poll_result=False)
-            raise pe.PresignedURLException("Should return 202", resp)
-
+            # This should return 202 (AcceptedRequestException) at least zero size file is sent
+            return self.post(endpoint=endpoint, result_class=result_class, data=data, poll_result=False)
         except pe.AcceptedRequestException as e:
             accepted_exception = e
         except Exception as e:
@@ -528,6 +539,9 @@ class PangeaRequest(PangeaRequestBase):
             raise AttributeError("files attribute should have at least 1 file")
 
         response = self.request_presigned_url(endpoint=endpoint, result_class=result_class, data=data)
+
+        if response.success:  # This should only happen when uploading a zero bytes file
+            return response.raw_response
         if response.accepted_result is None:
             raise pe.PangeaException("No accepted_result field when requesting presigned url")
         if response.accepted_result.post_url is None:

pangea/response.py

@@ -28,6 +28,7 @@ class AttachedFile(object):
             filename = self.filename if self.filename else "default_save_filename"
 
         filepath = os.path.join(dest_folder, filename)
+        filepath = self._find_available_file(filepath)
         directory = os.path.dirname(filepath)
         if not os.path.exists(directory):
             os.makedirs(directory)
@@ -35,6 +36,17 @@ class AttachedFile(object):
         with open(filepath, "wb") as file:
             file.write(self.file)
 
+    def _find_available_file(self, file_path):
+        base_name, ext = os.path.splitext(file_path)
+        counter = 1
+        while os.path.exists(file_path):
+            if ext:
+                file_path = f"{base_name}_{counter}{ext}"
+            else:
+                file_path = f"{base_name}_{counter}"
+            counter += 1
+        return file_path
+
 
 class TransferMethod(str, enum.Enum):
     """Transfer methods for uploading file data."""

pangea/services/__init__.py

@@ -6,4 +6,5 @@ from .file_scan import FileScan
 from .intel import DomainIntel, FileIntel, IpIntel, UrlIntel, UserIntel
 from .redact import Redact
 from .sanitize import Sanitize
+from .share.share import Share
 from .vault.vault import Vault

pangea/services/audit/audit.py

@@ -492,7 +492,7 @@ class Audit(ServiceBase, AuditBase):
         verbose: Optional[bool] = None,
     ) -> PangeaResponse[LogResult]:
         """
-        Log an entry
+        Log an event
 
         Create a log entry in the Secure Audit Log.
 
@@ -501,6 +501,7 @@ class Audit(ServiceBase, AuditBase):
             verify (bool, optional): True to verify logs consistency after response.
             sign_local (bool, optional): True to sign event with local key.
             verbose (bool, optional): True to get a more verbose response.
+
         Raises:
             AuditException: If an audit based api exception happens
             PangeaAPIException: If an API Error happens
@@ -511,13 +512,7 @@ class Audit(ServiceBase, AuditBase):
                 Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#/v1/log).
 
         Examples:
-            try:
-                log_response = audit.log({"message": "hello world"}, verbose=True)
-                print(f"Response. Hash: {log_response.result.hash}")
-            except pe.PangeaAPIException as e:
-                print(f"Request Error: {e.response.summary}")
-                for err in e.errors:
-                    print(f"\\t{err.detail} \\n")
+            response = audit.log_event({"message": "hello world"}, verbose=True)
         """
 
         input = self._get_log_request(event, sign_local=sign_local, verify=verify, verbose=verbose)
@@ -961,9 +956,9 @@ class Audit(ServiceBase, AuditBase):
             if pub_root is not None:
                 self.pub_roots[tree_size] = pub_root
 
-        self.fix_consistency_proofs(tree_sizes)
+        self._fix_consistency_proofs(tree_sizes)
 
-    def fix_consistency_proofs(self, tree_sizes: Iterable[int]):
+    def _fix_consistency_proofs(self, tree_sizes: Iterable[int]) -> None:
         # on very rare occasions, the consistency proof in Arweave may be wrong
         # override it with the proof from pangea (not the root hash, just the proof)
         for tree_size in tree_sizes:

pangea/services/authz.py

@@ -1,9 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 import enum
 from typing import Any, Dict, List, Optional, Union
 
+from pangea.config import PangeaConfig
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
 from pangea.services.base import ServiceBase
 
@@ -171,7 +173,25 @@ class AuthZ(ServiceBase):
 
     service_name = "authz"
 
-    def __init__(self, token: str, config=None, logger_name="pangea", config_id: Optional[str] = None):
+    def __init__(
+        self, token: str, config: PangeaConfig | None = None, logger_name: str = "pangea", config_id: str | None = None
+    ) -> None:
+        """
+        AuthZ client
+
+        Initializes a new AuthZ client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="aws.us.pangea.cloud")
+             authz = AuthZ(token="pangea_token", config=config)
+        """
+
         super().__init__(token, config, logger_name, config_id=config_id)
 
     def tuple_create(self, tuples: List[Tuple]) -> PangeaResponse[TupleCreateResult]:

pangea/services/base.py

@@ -80,7 +80,8 @@ class ServiceBase(object):
         Returns request's result that has been accepted by the server
 
         Args:
-            exception (AcceptedRequestException): Exception raise by SDK on the call that is been processed.
+            exception: Exception that was previously raised by the SDK on a call
+              that is being processed.
 
         Returns:
             PangeaResponse
@@ -100,5 +101,18 @@ class ServiceBase(object):
         else:
             raise AttributeError("Need to set exception, response or request_id")
 
-    def download_file(self, url: str, filename: Optional[str] = None) -> AttachedFile:
+    def download_file(self, url: str, filename: str | None = None) -> AttachedFile:
+        """
+        Download file
+
+        Download a file from the specified URL and save it with the given
+        filename.
+
+        Args:
+            url: URL of the file to download
+            filename: Name to save the downloaded file as. If not provided, the
+              filename will be determined from the Content-Disposition header or
+              the URL.
+        """
+
         return self.request.download_file(url=url, filename=filename)

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
@@ -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,7 @@ class UserBreachedRequest(IntelCommonRequest):
     phone_number: Optional[str] = None
     start: Optional[str] = None
     end: Optional[str] = None
+    cursor: Optional[str] = None
 
 
 class UserBreachedBulkRequest(IntelCommonRequest):
@@ -1387,6 +1391,7 @@ class UserIntel(ServiceBase):
         verbose: Optional[bool] = None,
         raw: Optional[bool] = None,
         provider: Optional[str] = None,
+        cursor: Optional[str] = None,
     ) -> PangeaResponse[UserBreachedResult]:
         """
         Look up breached users
@@ -1405,6 +1410,7 @@ class UserIntel(ServiceBase):
             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"
+            cursor (str, optional): A token given in the raw response from SpyCloud. Post this back to paginate results
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -1432,6 +1438,7 @@ class UserIntel(ServiceBase):
             end=end,
             verbose=verbose,
             raw=raw,
+            cursor=cursor,
         )
         return self.request.post("v1/user/breached", UserBreachedResult, data=input.model_dump(exclude_none=True))
 
@@ -1592,6 +1599,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")
 

pangea/services/redact.py

@@ -66,6 +66,18 @@ class RedactRequest(APIRequestModel):
     rulesets: Optional[List[str]] = None
     return_result: Optional[bool] = None
     redaction_method_overrides: Optional[RedactionMethodOverrides] = None
+    vault_parameters: Optional[VaultParameters] = None
+
+    llm_request: Optional[bool] = None
+    """Is this redact call going to be used in an LLM request?"""
+
+
+class VaultParameters(APIRequestModel):
+    fpe_key_id: Optional[str] = None
+    """A vault key ID of an exportable key used to redact with FPE instead of using the service config default."""
+
+    salt_secret_id: Optional[str] = None
+    """A vault secret ID of a secret used to salt a hash instead of using the service config default."""
 
 
 class RecognizerResult(APIResponseModel):
@@ -134,6 +146,10 @@ class StructuredRequest(APIRequestModel):
     rulesets: Optional[List[str]] = None
     return_result: Optional[bool] = None
     redaction_method_overrides: Optional[RedactionMethodOverrides] = None
+    vault_parameters: Optional[VaultParameters] = None
+
+    llm_request: Optional[bool] = None
+    """Is this redact call going to be used in an LLM request?"""
 
 
 class StructuredResult(PangeaResponseResult):

pangea/services/sanitize.py

@@ -7,6 +7,7 @@ from typing import Dict, List, Optional, Tuple
 
 from pydantic import Field
 
+from pangea.config import PangeaConfig
 from pangea.response import APIRequestModel, PangeaResponse, PangeaResponseResult, TransferMethod
 from pangea.services.base import ServiceBase
 from pangea.utils import FileUploadParams, get_file_upload_params
@@ -197,6 +198,27 @@ class Sanitize(ServiceBase):
 
     service_name = "sanitize"
 
+    def __init__(
+        self, token: str, config: PangeaConfig | None = None, logger_name: str = "pangea", config_id: str | None = None
+    ) -> None:
+        """
+        Sanitize client
+
+        Initializes a new Sanitize client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="aws.us.pangea.cloud")
+             authz = Sanitize(token="pangea_token", config=config)
+        """
+
+        super().__init__(token, config, logger_name, config_id=config_id)
+
     def sanitize(
         self,
         transfer_method: TransferMethod = TransferMethod.POST_URL,

pangea/services/share/file_format.py

@@ -0,0 +1,170 @@
+import enum
+
+
+class FileFormat(str, enum.Enum):
+    F3G2 = "3G2"
+    F3GP = "3GP"
+    F3MF = "3MF"
+    F7Z = "7Z"
+    A = "A"
+    AAC = "AAC"
+    ACCDB = "ACCDB"
+    AIFF = "AIFF"
+    AMF = "AMF"
+    AMR = "AMR"
+    APE = "APE"
+    ASF = "ASF"
+    ATOM = "ATOM"
+    AU = "AU"
+    AVI = "AVI"
+    AVIF = "AVIF"
+    BIN = "BIN"
+    BMP = "BMP"
+    BPG = "BPG"
+    BZ2 = "BZ2"
+    CAB = "CAB"
+    CLASS = "CLASS"
+    CPIO = "CPIO"
+    CRX = "CRX"
+    CSV = "CSV"
+    DAE = "DAE"
+    DBF = "DBF"
+    DCM = "DCM"
+    DEB = "DEB"
+    DJVU = "DJVU"
+    DLL = "DLL"
+    DOC = "DOC"
+    DOCX = "DOCX"
+    DWG = "DWG"
+    EOT = "EOT"
+    EPUB = "EPUB"
+    EXE = "EXE"
+    FDF = "FDF"
+    FITS = "FITS"
+    FLAC = "FLAC"
+    FLV = "FLV"
+    GBR = "GBR"
+    GEOJSON = "GEOJSON"
+    GIF = "GIF"
+    GLB = "GLB"
+    GML = "GML"
+    GPX = "GPX"
+    GZ = "GZ"
+    HAR = "HAR"
+    HDR = "HDR"
+    HEIC = "HEIC"
+    HEIF = "HEIF"
+    HTML = "HTML"
+    ICNS = "ICNS"
+    ICO = "ICO"
+    ICS = "ICS"
+    ISO = "ISO"
+    JAR = "JAR"
+    JP2 = "JP2"
+    JPF = "JPF"
+    JPG = "JPG"
+    JPM = "JPM"
+    JS = "JS"
+    JSON = "JSON"
+    JXL = "JXL"
+    JXR = "JXR"
+    KML = "KML"
+    LIT = "LIT"
+    LNK = "LNK"
+    LUA = "LUA"
+    LZ = "LZ"
+    M3U = "M3U"
+    M4A = "M4A"
+    MACHO = "MACHO"
+    MDB = "MDB"
+    MIDI = "MIDI"
+    MKV = "MKV"
+    MOBI = "MOBI"
+    MOV = "MOV"
+    MP3 = "MP3"
+    MP4 = "MP4"
+    MPC = "MPC"
+    MPEG = "MPEG"
+    MQV = "MQV"
+    MRC = "MRC"
+    MSG = "MSG"
+    MSI = "MSI"
+    NDJSON = "NDJSON"
+    NES = "NES"
+    ODC = "ODC"
+    ODF = "ODF"
+    ODG = "ODG"
+    ODP = "ODP"
+    ODS = "ODS"
+    ODT = "ODT"
+    OGA = "OGA"
+    OGV = "OGV"
+    OTF = "OTF"
+    OTG = "OTG"
+    OTP = "OTP"
+    OTS = "OTS"
+    OTT = "OTT"
+    OWL = "OWL"
+    P7S = "P7S"
+    PAT = "PAT"
+    PDF = "PDF"
+    PHP = "PHP"
+    PL = "PL"
+    PNG = "PNG"
+    PPT = "PPT"
+    PPTX = "PPTX"
+    PS = "PS"
+    PSD = "PSD"
+    PUB = "PUB"
+    PY = "PY"
+    QCP = "QCP"
+    RAR = "RAR"
+    RMVB = "RMVB"
+    RPM = "RPM"
+    RSS = "RSS"
+    RTF = "RTF"
+    SHP = "SHP"
+    SHX = "SHX"
+    SO = "SO"
+    SQLITE = "SQLITE"
+    SRT = "SRT"
+    SVG = "SVG"
+    SWF = "SWF"
+    SXC = "SXC"
+    TAR = "TAR"
+    TCL = "TCL"
+    TCX = "TCX"
+    TIFF = "TIFF"
+    TORRENT = "TORRENT"
+    TSV = "TSV"
+    TTC = "TTC"
+    TTF = "TTF"
+    TXT = "TXT"
+    VCF = "VCF"
+    VOC = "VOC"
+    VTT = "VTT"
+    WARC = "WARC"
+    WASM = "WASM"
+    WAV = "WAV"
+    WEBM = "WEBM"
+    WEBP = "WEBP"
+    WOFF = "WOFF"
+    WOFF2 = "WOFF2"
+    X3D = "X3D"
+    XAR = "XAR"
+    XCF = "XCF"
+    XFDF = "XFDF"
+    XLF = "XLF"
+    XLS = "XLS"
+    XLSX = "XLSX"
+    XML = "XML"
+    XPM = "XPM"
+    XZ = "XZ"
+    ZIP = "ZIP"
+    ZST = "ZST"
+
+    def __str__(self):
+        return str(self.value)
+
+    def __repr__(self):
+        return str(self.value)