pangea-sdk 3.8.0b4__py3-none-any.whl → 3.9.0__py3-none-any.whl

pangea/asyncio/services/intel.py

@@ -76,7 +76,7 @@ class FileIntelAsync(ServiceBaseAsync):
         provider: Optional[str] = None,
         verbose: Optional[bool] = None,
         raw: Optional[bool] = None,
-    ) -> PangeaResponse[m.FileReputationResult]:
+    ) -> PangeaResponse[m.FileReputationBulkResult]:
         """
         Reputation check
 
@@ -182,7 +182,7 @@ class FileIntelAsync(ServiceBaseAsync):
             hash = hash_256_filepath(filepath)
             hashes.append(hash)
 
-        return await self.hash_reputation_bulk(  # type: ignore[return-value]
+        return await self.hash_reputation_bulk(
             hashes=hashes, hash_type="sha256", verbose=verbose, raw=raw, provider=provider
         )
 
@@ -251,7 +251,7 @@ class DomainIntelAsync(ServiceBaseAsync):
         verbose: Optional[bool] = None,
         raw: Optional[bool] = None,
         provider: Optional[str] = None,
-    ) -> PangeaResponse[m.DomainReputationResult]:
+    ) -> PangeaResponse[m.DomainReputationBulkResult]:
         """
         Reputation
 
@@ -373,7 +373,7 @@ class IpIntelAsync(ServiceBaseAsync):
 
     async def reputation_bulk(
         self, ips: List[str], verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
-    ) -> PangeaResponse[m.IPReputationResult]:
+    ) -> PangeaResponse[m.IPReputationBulkResult]:
         """
         Reputation
 

pangea/asyncio/services/redact.py

@@ -1,10 +1,12 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 from typing import Dict, List, Optional, Union
 
 import pangea.services.redact as m
 from pangea.asyncio.services.base import ServiceBaseAsync
+from pangea.config import PangeaConfig
 from pangea.response import PangeaResponse
 
 
@@ -35,7 +37,24 @@ class RedactAsync(ServiceBaseAsync):
 
     service_name = "redact"
 
-    def __init__(self, token, 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:
+        """
+        Redact client
+
+        Initializes a new Redact client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+
+        Examples:
+             config = PangeaConfig(domain="pangea_domain")
+             redact = RedactAsync(token="pangea_token", config=config)
+        """
+
         super().__init__(token, config, logger_name, config_id=config_id)
 
     async def redact(
@@ -45,6 +64,7 @@ class RedactAsync(ServiceBaseAsync):
         rules: Optional[List[str]] = None,
         rulesets: Optional[List[str]] = None,
         return_result: Optional[bool] = None,
+        redaction_method_overrides: Optional[m.RedactionMethodOverrides] = None,
     ) -> PangeaResponse[m.RedactResult]:
         """
         Redact
@@ -60,6 +80,7 @@ class RedactAsync(ServiceBaseAsync):
             rules (list[str], optional): An array of redact rule short names
             rulesets (list[str], optional): An array of redact rulesets short names
             return_result(bool, optional): Setting this value to false will omit the redacted result only returning count
+            redaction_method_overrides: A set of redaction method overrides for any enabled rule. These methods override the config declared methods
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -73,7 +94,14 @@ class RedactAsync(ServiceBaseAsync):
             response = redact.redact(text="Jenny Jenny... 555-867-5309")
         """
 
-        input = m.RedactRequest(text=text, debug=debug, rules=rules, rulesets=rulesets, return_result=return_result)
+        input = m.RedactRequest(
+            text=text,
+            debug=debug,
+            rules=rules,
+            rulesets=rulesets,
+            return_result=return_result,
+            redaction_method_overrides=redaction_method_overrides,
+        )
         return await self.request.post("v1/redact", m.RedactResult, data=input.dict(exclude_none=True))
 
     async def redact_structured(
@@ -85,6 +113,7 @@ class RedactAsync(ServiceBaseAsync):
         rules: Optional[List[str]] = None,
         rulesets: Optional[List[str]] = None,
         return_result: Optional[bool] = None,
+        redaction_method_overrides: Optional[m.RedactionMethodOverrides] = None,
     ) -> PangeaResponse[m.StructuredResult]:
         """
         Redact structured
@@ -104,6 +133,7 @@ class RedactAsync(ServiceBaseAsync):
             rules (list[str], optional): An array of redact rule short names
             rulesets (list[str], optional): An array of redact rulesets short names
             return_result(bool, optional): Setting this value to false will omit the redacted result only returning count
+            redaction_method_overrides: A set of redaction method overrides for any enabled rule. These methods override the config declared methods
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -130,5 +160,29 @@ class RedactAsync(ServiceBaseAsync):
             rules=rules,
             rulesets=rulesets,
             return_result=return_result,
+            redaction_method_overrides=redaction_method_overrides,
         )
         return await self.request.post("v1/redact_structured", m.StructuredResult, data=input.dict(exclude_none=True))
+
+    async def unredact(self, redacted_data: m.RedactedData, fpe_context: str) -> PangeaResponse[m.UnredactResult]:
+        """
+        Unredact
+
+        Decrypt or unredact fpe redactions
+
+        OperationId: redact_post_v1_unredact
+
+        Args:
+            redacted_data: Data to unredact
+            fpe_context (base64): FPE context used to decrypt and unredact data
+
+        Raises:
+            PangeaAPIException: If an API Error happens
+
+        Returns:
+            Pangea Response with redacted data in the response.result field,
+                available response fields can be found in our
+                [API Documentation](https://pangea.cloud/docs/api/redact#unredact)
+        """
+        input = m.UnredactRequest(redacted_data=redacted_data, fpe_context=fpe_context)
+        return await self.request.post("v1/unredact", m.UnredactResult, data=input.dict(exclude_none=True))

pangea/asyncio/services/vault.py

@@ -1,9 +1,12 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
+
 import datetime
 from typing import Dict, Optional, Union
 
 from pangea.asyncio.services.base import ServiceBaseAsync
+from pangea.config import PangeaConfig
 from pangea.response import PangeaResponse
 from pangea.services.vault.models.asymmetric import (
     AsymmetricGenerateRequest,
@@ -17,6 +20,8 @@ from pangea.services.vault.models.asymmetric import (
 )
 from pangea.services.vault.models.common import (
     AsymmetricAlgorithm,
+    DecryptTransformRequest,
+    DecryptTransformResult,
     DeleteRequest,
     DeleteResult,
     EncodedPrivateKey,
@@ -24,6 +29,8 @@ from pangea.services.vault.models.common import (
     EncodedSymmetricKey,
     EncryptStructuredRequest,
     EncryptStructuredResult,
+    EncryptTransformRequest,
+    EncryptTransformResult,
     FolderCreateRequest,
     FolderCreateResult,
     GetRequest,
@@ -50,6 +57,7 @@ from pangea.services.vault.models.common import (
     SymmetricAlgorithm,
     Tags,
     TDict,
+    TransformAlphabet,
     UpdateRequest,
     UpdateResult,
 )
@@ -98,10 +106,24 @@ class VaultAsync(ServiceBaseAsync):
 
     def __init__(
         self,
-        token,
-        config=None,
-        logger_name="pangea",
-    ):
+        token: str,
+        config: PangeaConfig | None = None,
+        logger_name: str = "pangea",
+    ) -> None:
+        """
+        Vault client
+
+        Initializes a new Vault client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+
+        Examples:
+             config = PangeaConfig(domain="pangea_domain")
+             vault = VaultAsync(token="pangea_token", config=config)
+        """
         super().__init__(token, config, logger_name)
 
     # Delete endpoint
@@ -1278,3 +1300,92 @@ class VaultAsync(ServiceBaseAsync):
             EncryptStructuredResult,
             data=input.dict(exclude_none=True),
         )
+
+    async def encrypt_transform(
+        self,
+        id: str,
+        plain_text: str,
+        alphabet: TransformAlphabet,
+        tweak: str | None = None,
+        version: int | None = None,
+    ) -> PangeaResponse[EncryptTransformResult]:
+        """
+        Encrypt transform
+
+        Encrypt using a format-preserving algorithm (FPE).
+
+        OperationId: vault_post_v1_key_encrypt_transform
+
+        Args:
+            id: The item ID.
+            plain_text: A message to be encrypted.
+            alphabet: Set of characters to use for format-preserving encryption (FPE).
+            tweak: User provided tweak string. If not provided, a random string will be generated and returned.
+            version: The item version. Defaults to the current version.
+
+        Raises:
+            PangeaAPIException: If an API error happens.
+
+        Returns:
+            A `PangeaResponse` containing the encrypted message.
+
+        Examples:
+            await vault.encrypt_transform(
+                id="pvi_[...]",
+                plain_text="message to encrypt",
+                alphabet=TransformAlphabet.ALPHANUMERIC,
+                tweak="MTIzMTIzMT==",
+            )
+        """
+
+        input = EncryptTransformRequest(
+            id=id,
+            plain_text=plain_text,
+            alphabet=alphabet,
+            tweak=tweak,
+            version=version,
+        )
+        return await self.request.post(
+            "v1/key/encrypt/transform",
+            EncryptTransformResult,
+            data=input.dict(exclude_none=True),
+        )
+
+    async def decrypt_transform(
+        self, id: str, cipher_text: str, tweak: str, alphabet: TransformAlphabet, version: int | None = None
+    ) -> PangeaResponse[DecryptTransformResult]:
+        """
+        Decrypt transform
+
+        Decrypt using a format-preserving algorithm (FPE).
+
+        OperationId: vault_post_v1_key_decrypt_transform
+
+        Args:
+            id: The item ID.
+            cipher_text: A message encrypted by Vault.
+            tweak: User provided tweak string.
+            alphabet: Set of characters to use for format-preserving encryption (FPE).
+            version: The item version. Defaults to the current version.
+
+        Raises:
+            PangeaAPIException: If an API error happens.
+
+        Returns:
+            A `PangeaResponse` containing the decrypted message.
+
+        Examples:
+            await vault.decrypt_transform(
+                id="pvi_[...]",
+                cipher_text="encrypted message",
+                tweak="MTIzMTIzMT==",
+                alphabet=TransformAlphabet.ALPHANUMERIC,
+            )
+        """
+
+        input = DecryptTransformRequest(id=id, cipher_text=cipher_text, tweak=tweak, alphabet=alphabet, version=version)
+        return await self.request.post(
+            "v1/key/decrypt/transform",
+            DecryptTransformResult,
+            data=input.dict(exclude_none=True),
+        )

pangea/request.py

@@ -5,12 +5,12 @@ import copy
 import json
 import logging
 import time
-from typing import Dict, List, Optional, Tuple, Type, Union
+from typing import TYPE_CHECKING, Dict, List, Optional, Tuple, Type, Union
 
-import aiohttp
 import requests
 from requests.adapters import HTTPAdapter, Retry
 from requests_toolbelt import MultipartDecoder  # type: ignore
+from typing_extensions import TypeVar
 
 import pangea
 import pangea.exceptions as pe
@@ -18,6 +18,9 @@ from pangea.config import PangeaConfig
 from pangea.response import AttachedFile, PangeaResponse, PangeaResponseResult, ResponseStatus, TransferMethod
 from pangea.utils import default_encoder
 
+if TYPE_CHECKING:
+    import aiohttp
+
 
 class MultipartResponse(object):
     pangea_json: Dict[str, str]
@@ -187,6 +190,9 @@ class PangeaRequestBase(object):
         raise pe.PangeaAPIException(f"{summary} ", response)
 
 
+TResult = TypeVar("TResult", bound=PangeaResponseResult, default=PangeaResponseResult)
+
+
 class PangeaRequest(PangeaRequestBase):
     """An object that makes direct calls to Pangea Service APIs.
 
@@ -202,12 +208,12 @@ class PangeaRequest(PangeaRequestBase):
     def post(
         self,
         endpoint: str,
-        result_class: Type[PangeaResponseResult],
+        result_class: Type[TResult],
         data: Union[str, Dict] = {},
         files: Optional[List[Tuple]] = None,
         poll_result: bool = True,
         url: Optional[str] = None,
-    ) -> PangeaResponse:
+    ) -> PangeaResponse[TResult]:
         """Makes the POST call to a Pangea Service endpoint.
 
         Args:
@@ -343,7 +349,7 @@ class PangeaRequest(PangeaRequestBase):
 
         return data, files
 
-    def _handle_queued_result(self, response: PangeaResponse) -> PangeaResponse[Type[PangeaResponseResult]]:
+    def _handle_queued_result(self, response: PangeaResponse[TResult]) -> PangeaResponse[TResult]:
         if self._queued_retry_enabled and response.http_status == 202:
             self.logger.debug(
                 json.dumps(
@@ -355,7 +361,7 @@ class PangeaRequest(PangeaRequestBase):
 
         return response
 
-    def get(self, path: str, result_class: Type[PangeaResponseResult], check_response: bool = True) -> PangeaResponse:
+    def get(self, path: str, result_class: Type[TResult], check_response: bool = True) -> PangeaResponse[TResult]:
         """Makes the GET call to a Pangea Service endpoint.
 
         Args:
@@ -427,21 +433,21 @@ class PangeaRequest(PangeaRequestBase):
             raise pe.DownloadFileError(f"Failed to download file. Status: {response.status_code}", response.text)
 
     def poll_result_by_id(
-        self, request_id: str, result_class: Union[Type[PangeaResponseResult], Type[dict]], check_response: bool = True
-    ):
+        self, request_id: str, result_class: Type[TResult], check_response: bool = True
+    ) -> PangeaResponse[TResult]:
         path = self._get_poll_path(request_id)
         self.logger.debug(json.dumps({"service": self.service, "action": "poll_result_once", "url": path}))
-        return self.get(path, result_class, check_response=check_response)  # type: ignore[arg-type]
+        return self.get(path, result_class, check_response=check_response)
 
     def poll_result_once(
-        self, response: PangeaResponse, check_response: bool = True
-    ) -> PangeaResponse[Type[PangeaResponseResult]]:
+        self, response: PangeaResponse[TResult], check_response: bool = True
+    ) -> PangeaResponse[TResult]:
         request_id = response.request_id
         if not request_id:
             raise pe.PangeaException("Poll result error: response did not include a 'request_id'")
 
         if response.status != ResponseStatus.ACCEPTED.value:
-            raise pe.PangeaException("Response already proccesed")
+            raise pe.PangeaException("Response already processed")
 
         return self.poll_result_by_id(request_id, response.result_class, check_response=check_response)
 
@@ -453,8 +459,10 @@ class PangeaRequest(PangeaRequestBase):
     ) -> PangeaResponse:
         # Send request
         try:
-            # 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)
+            # 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)
+
         except pe.AcceptedRequestException as e:
             accepted_exception = e
         except Exception as e:
@@ -512,9 +520,6 @@ 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:
@@ -526,7 +531,7 @@ class PangeaRequest(PangeaRequestBase):
         self.post_presigned_url(url=presigned_url, data=data_to_presigned, files=files)
         return response.raw_response
 
-    def _poll_result_retry(self, response: PangeaResponse) -> PangeaResponse[Type[PangeaResponseResult]]:
+    def _poll_result_retry(self, response: PangeaResponse[TResult]) -> PangeaResponse[TResult]:
         retry_count = 1
         start = time.time()
 
@@ -538,9 +543,7 @@ class PangeaRequest(PangeaRequestBase):
         self.logger.debug(json.dumps({"service": self.service, "action": "poll_result_retry", "step": "exit"}))
         return self._check_response(response)
 
-    def _poll_presigned_url(
-        self, response: PangeaResponse[Type[PangeaResponseResult]]
-    ) -> PangeaResponse[Type[PangeaResponseResult]]:
+    def _poll_presigned_url(self, response: PangeaResponse[TResult]) -> PangeaResponse[TResult]:
         if response.http_status != 202:
             raise AttributeError("Response should be 202")
 

pangea/response.py

@@ -3,16 +3,15 @@
 import datetime
 import enum
 import os
-from typing import Any, Dict, Generic, List, Optional, Type, TypeVar, Union
+from typing import Any, Dict, Generic, List, Optional, Type, Union
 
 import aiohttp
 import requests
 from pydantic import BaseModel
+from typing_extensions import TypeVar
 
 from pangea.utils import format_datetime
 
-T = TypeVar("T")
-
 
 class AttachedFile(object):
     filename: str
@@ -29,7 +28,6 @@ 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)
@@ -37,17 +35,6 @@ 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):
     MULTIPART = "multipart"
@@ -155,22 +142,34 @@ class ResponseStatus(str, enum.Enum):
 
 
 class ResponseHeader(APIResponseModel):
-    """
-    Pangea response API header.
-
-    Arguments:
-    request_id -- The request ID.
-    request_time -- The time the request was issued, ISO8601.
-    response_time -- The time the response was issued, ISO8601.
-    status -- Pangea response status
-    summary -- The summary of the response.
-    """
+    """Pangea response API header."""
 
     request_id: str
+    """A unique identifier assigned to each request made to the API."""
+
     request_time: str
+    """
+    Timestamp indicating the exact moment when a request is made to the API.
+    """
+
     response_time: str
+    """
+    Duration it takes for the API to process a request and generate a response.
+    """
+
     status: str
+    """
+    Represents the status or outcome of the API request.
+    """
+
     summary: str
+    """
+    Provides a concise and brief overview of the purpose or primary objective of
+    the API endpoint.
+    """
+
+
+T = TypeVar("T", bound=PangeaResponseResult, default=PangeaResponseResult)
 
 
 class PangeaResponse(Generic[T], ResponseHeader):
@@ -179,14 +178,14 @@ class PangeaResponse(Generic[T], ResponseHeader):
     result: Optional[T] = None
     pangea_error: Optional[PangeaError] = None
     accepted_result: Optional[AcceptedResult] = None
-    result_class: Union[Type[PangeaResponseResult], Type[dict]] = PangeaResponseResult
+    result_class: Type[T] = PangeaResponseResult  # type: ignore[assignment]
     _json: Any
     attached_files: List[AttachedFile] = []
 
     def __init__(
         self,
         response: requests.Response,
-        result_class: Union[Type[PangeaResponseResult], Type[dict]],
+        result_class: Type[T],
         json: dict,
         attached_files: List[AttachedFile] = [],
     ):
@@ -198,7 +197,7 @@ class PangeaResponse(Generic[T], ResponseHeader):
         self.attached_files = attached_files
 
         self.result = (
-            self.result_class(**self.raw_result)  # type: ignore[assignment]
+            self.result_class(**self.raw_result)
             if self.raw_result is not None and issubclass(self.result_class, PangeaResponseResult) and self.success
             else None
         )

pangea/services/__init__.py

@@ -5,6 +5,4 @@ from .embargo import Embargo
 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