pangea-sdk 4.1.0__py3-none-any.whl → 4.3.0__py3-none-any.whl

pangea/__init__.py

@@ -1,6 +1,7 @@
-__version__ = "4.1.0"
+__version__ = "4.3.0"
 
 from pangea.asyncio.request import PangeaRequestAsync
 from pangea.config import PangeaConfig
+from pangea.file_uploader import FileUploader
 from pangea.request import PangeaRequest
 from pangea.response import PangeaResponse

pangea/asyncio/__init__.py

@@ -0,0 +1 @@
+from .file_uploader import FileUploaderAsync

pangea/asyncio/file_uploader.py

@@ -0,0 +1,39 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+import io
+import logging
+from typing import Dict, Optional
+
+from pangea.asyncio.request import PangeaRequestAsync
+from pangea.request import PangeaConfig
+from pangea.response import TransferMethod
+
+
+class FileUploaderAsync:
+    def __init__(self) -> None:
+        self.logger = logging.getLogger("pangea")
+        self._request: PangeaRequestAsync = PangeaRequestAsync(
+            config=PangeaConfig(),
+            token="",
+            service="FileUploader",
+            logger=self.logger,
+        )
+
+    async def upload_file(
+        self,
+        url: str,
+        file: io.BufferedReader,
+        transfer_method: TransferMethod = TransferMethod.PUT_URL,
+        file_details: Optional[Dict] = None,
+    ) -> None:
+        if transfer_method == TransferMethod.PUT_URL:
+            files = [("file", ("filename", file, "application/octet-stream"))]
+            await self._request.put_presigned_url(url=url, files=files)
+        elif transfer_method == TransferMethod.POST_URL:
+            files = [("file", ("filename", file, "application/octet-stream"))]
+            await self._request.post_presigned_url(url=url, data=file_details, files=files)  # type: ignore[arg-type]
+        else:
+            raise ValueError(f"Transfer method not supported: {transfer_method}")
+
+    async def close(self) -> None:
+        await self._request.session.close()

pangea/asyncio/request.py

@@ -32,7 +32,7 @@ class PangeaRequestAsync(PangeaRequestBase):
         endpoint: str,
         result_class: Type[TResult],
         data: Union[str, Dict] = {},
-        files: List[Tuple] = [],
+        files: Optional[List[Tuple]] = None,
         poll_result: bool = True,
         url: Optional[str] = None,
     ) -> PangeaResponse[TResult]:
@@ -250,7 +250,7 @@ class PangeaRequestAsync(PangeaRequestBase):
         url: str,
         headers: Dict = {},
         data: Union[str, Dict] = {},
-        files: List[Tuple] = [],
+        files: Optional[List[Tuple]] = [],
         presigned_url_post: bool = False,
     ) -> aiohttp.ClientResponse:
         if files:

pangea/asyncio/services/__init__.py

@@ -5,4 +5,5 @@ from .embargo import EmbargoAsync
 from .file_scan import FileScanAsync
 from .intel import DomainIntelAsync, FileIntelAsync, IpIntelAsync, UrlIntelAsync, UserIntelAsync
 from .redact import RedactAsync
+from .sanitize import SanitizeAsync
 from .vault import VaultAsync

pangea/asyncio/services/authn.py

@@ -7,7 +7,7 @@ from typing import Dict, List, Optional, Union
 import pangea.services.authn.models as m
 from pangea.asyncio.services.base import ServiceBaseAsync
 from pangea.config import PangeaConfig
-from pangea.response import PangeaResponse
+from pangea.response import PangeaResponse, PangeaResponseResult
 
 SERVICE_NAME = "authn"
 
@@ -399,6 +399,25 @@ class AuthNAsync(ServiceBaseAsync):
                     "v2/client/password/change", m.ClientPasswordChangeResult, data=input.model_dump(exclude_none=True)
                 )
 
+            async def expire(self, user_id: str) -> PangeaResponse[PangeaResponseResult]:
+                """
+                Expire a user's password
+
+                Expire a user's password.
+
+                OperationId: authn_post_v2_user_password_expire
+
+                Args:
+                    user_id: The identity of a user or a service.
+
+                Returns:
+                    A PangeaResponse with an empty object in the response.result field.
+
+                Examples:
+                    await authn.client.password.expire("pui_[...]")
+                """
+                return await self.request.post("v2/user/password/expire", PangeaResponseResult, {"id": user_id})
+
         class TokenAsync(ServiceBaseAsync):
             service_name = SERVICE_NAME
 

pangea/asyncio/services/authz.py

@@ -1,7 +1,7 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
 
-from typing import Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional
 
 from pangea.asyncio.services.base import ServiceBaseAsync
 from pangea.response import PangeaResponse
@@ -162,7 +162,7 @@ class AuthZAsync(ServiceBaseAsync):
         action: str,
         subject: Subject,
         debug: Optional[bool] = None,
-        attributes: Optional[Dict[str, Union[int, str]]] = None,
+        attributes: Optional[Dict[str, Any]] = None,
     ) -> PangeaResponse[CheckResult]:
         """Perform a check request.
 
@@ -173,7 +173,7 @@ class AuthZAsync(ServiceBaseAsync):
             action (str): The action to check.
             subject (Subject): The subject to check.
             debug (Optional[bool]): Setting this value to True will provide a detailed analysis of the check.
-            attributes (Optional[Dict[str, Union[int, str]]]): Additional attributes for the check.
+            attributes (Optional[Dict[str, Any]]): Additional attributes for the check.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -195,8 +195,10 @@ class AuthZAsync(ServiceBaseAsync):
         input_data = CheckRequest(resource=resource, action=action, subject=subject, debug=debug, attributes=attributes)
         return await self.request.post("v1/check", CheckResult, data=input_data.model_dump(exclude_none=True))
 
-    async def list_resources(self, type: str, action: str, subject: Subject) -> PangeaResponse[ListResourcesResult]:
-        """List resources.
+    async def list_resources(
+        self, type: str, action: str, subject: Subject, attributes: Optional[Dict[str, Any]] = None
+    ) -> PangeaResponse[ListResourcesResult]:
+        """List resources. (Beta)
 
         Given a type, action, and subject, list all the resources in the
         type that the subject has access to the action with.
@@ -205,6 +207,7 @@ class AuthZAsync(ServiceBaseAsync):
             type (str): The type to filter resources.
             action (str): The action to filter resources.
             subject (Subject): The subject to filter resources.
+            attributes (Optional[Dict[str, Any]]): A JSON object of attribute data.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -222,13 +225,15 @@ class AuthZAsync(ServiceBaseAsync):
             )
         """
 
-        input_data = ListResourcesRequest(type=type, action=action, subject=subject)
+        input_data = ListResourcesRequest(type=type, action=action, subject=subject, attributes=attributes)
         return await self.request.post(
             "v1/list-resources", ListResourcesResult, data=input_data.model_dump(exclude_none=True)
         )
 
-    async def list_subjects(self, resource: Resource, action: str) -> PangeaResponse[ListSubjectsResult]:
-        """List subjects.
+    async def list_subjects(
+        self, resource: Resource, action: str, attributes: Optional[Dict[str, Any]] = None
+    ) -> PangeaResponse[ListSubjectsResult]:
+        """List subjects. (Beta)
 
         Given a resource and an action, return the list of subjects who have
         access to the action for the given resource.
@@ -236,6 +241,7 @@ class AuthZAsync(ServiceBaseAsync):
         Args:
             resource (Resource): The resource to filter subjects.
             action (str): The action to filter subjects.
+            attributes (Optional[Dict[str, Any]]): A JSON object of attribute data.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -252,7 +258,7 @@ class AuthZAsync(ServiceBaseAsync):
             )
         """
 
-        input_data = ListSubjectsRequest(resource=resource, action=action)
+        input_data = ListSubjectsRequest(resource=resource, action=action, attributes=attributes)
         return await self.request.post(
             "v1/list-subjects", ListSubjectsResult, data=input_data.model_dump(exclude_none=True)
         )

pangea/asyncio/services/file_scan.py

@@ -59,12 +59,14 @@ class FileScanAsync(ServiceBaseAsync):
         OperationId: file_scan_post_v1_scan
 
         Args:
-            file (io.BufferedReader, optional): file to be scanned (should be opened with read permissions and in binary format)
             file_path (str, optional): filepath to be opened and scanned
+            file (io.BufferedReader, optional): file to be scanned (should be opened with read permissions and in binary format)
             verbose (bool, optional): Echo the API parameters in the response
             raw (bool, optional): Include raw data from this provider
             provider (str, optional): Scan file using this provider
             sync_call (bool, optional): True to wait until server returns a result, False to return immediately and retrieve result asynchronously
+            transfer_method (TransferMethod, optional): Transfer method used to upload the file data.
+            source_url (str, optional): A URL where the Pangea APIs can fetch the contents of the input file.
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -77,7 +79,7 @@ class FileScanAsync(ServiceBaseAsync):
         Examples:
             try:
                 with open("./path/to/file.pdf", "rb") as f:
-                    response = client.file_scan(file=f, verbose=True, provider="crowdstrike")
+                    response = await client.file_scan(file=f, verbose=True, provider="crowdstrike")
                     print(f"Response: {response.result}")
             except pe.PangeaAPIException as e:
                 print(f"Request Error: {e.response.summary}")
@@ -85,6 +87,15 @@ class FileScanAsync(ServiceBaseAsync):
                     print(f"\\t{err.detail} \\n")
         """
 
+        if transfer_method == TransferMethod.SOURCE_URL and source_url is None:
+            raise ValueError("`source_url` argument is required when using `TransferMethod.SOURCE_URL`.")
+
+        if source_url is not None and transfer_method != TransferMethod.SOURCE_URL:
+            raise ValueError(
+                "`transfer_method` should be `TransferMethod.SOURCE_URL` when using the `source_url` argument."
+            )
+
+        files: Optional[List[Tuple]] = None
         if file or file_path:
             if file_path:
                 file = open(file_path, "rb")
@@ -95,9 +106,9 @@ class FileScanAsync(ServiceBaseAsync):
                 size = params.size
             else:
                 crc, sha, size = None, None, None
-            files: List[Tuple] = [("upload", ("filename", file, "application/octet-stream"))]
-        else:
-            raise ValueError("Need to set file_path or file arguments")
+            files = [("upload", ("filename", file, "application/octet-stream"))]
+        elif source_url is None:
+            raise ValueError("Need to set one of `file_path`, `file`, or `source_url` arguments.")
 
         input = m.FileScanRequest(
             verbose=verbose,
@@ -110,7 +121,11 @@ class FileScanAsync(ServiceBaseAsync):
             source_url=source_url,
         )
         data = input.model_dump(exclude_none=True)
-        return await self.request.post("v1/scan", m.FileScanResult, data=data, files=files, poll_result=sync_call)
+        try:
+            return await self.request.post("v1/scan", m.FileScanResult, data=data, files=files, poll_result=sync_call)
+        finally:
+            if file_path and file:
+                file.close()
 
     async def request_upload_url(
         self,

pangea/asyncio/services/sanitize.py

@@ -0,0 +1,193 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+import io
+from typing import List, Optional, Tuple
+
+import pangea.services.sanitize as m
+from pangea.asyncio.services.base import ServiceBaseAsync
+from pangea.response import PangeaResponse, TransferMethod
+from pangea.utils import FileUploadParams, get_file_upload_params
+
+
+class SanitizeAsync(ServiceBaseAsync):
+    """Sanitize service client.
+
+    Examples:
+        import os
+
+        # Pangea SDK
+        from pangea.config import PangeaConfig
+        from pangea.asyncio.services import Sanitize
+
+        PANGEA_SANITIZE_TOKEN = os.getenv("PANGEA_SANITIZE_TOKEN")
+        config = PangeaConfig(domain="pangea.cloud")
+
+        sanitize = Sanitize(token=PANGEA_SANITIZE_TOKEN, config=config)
+    """
+
+    service_name = "sanitize"
+
+    async def sanitize(
+        self,
+        transfer_method: TransferMethod = TransferMethod.POST_URL,
+        file_path: Optional[str] = None,
+        file: Optional[io.BufferedReader] = None,
+        source_url: Optional[str] = None,
+        share_id: Optional[str] = None,
+        file_scan: Optional[m.SanitizeFile] = None,
+        content: Optional[m.SanitizeContent] = None,
+        share_output: Optional[m.SanitizeShareOutput] = None,
+        size: Optional[int] = None,
+        crc32c: Optional[str] = None,
+        sha256: Optional[str] = None,
+        uploaded_file_name: Optional[str] = None,
+        sync_call: bool = True,
+    ) -> PangeaResponse[m.SanitizeResult]:
+        """
+        Sanitize
+
+        Apply file sanitization actions according to specified rules.
+
+        OperationId: sanitize_post_v1_sanitize
+
+        Args:
+            transfer_method: The transfer method used to upload the file data.
+            file_path: Path to file to sanitize.
+            file: File to sanitize.
+            source_url: A URL where the file to be sanitized can be downloaded.
+            share_id: A Pangea Secure Share ID where the file to be sanitized is stored.
+            file_scan: Options for File Scan.
+            content: Options for how the file should be sanitized.
+            share_output: Integration with Secure Share.
+            size: The size (in bytes) of the file. If the upload doesn't match, the call will fail.
+            crc32c: The CRC32C hash of the file data, which will be verified by the server if provided.
+            sha256: The hexadecimal-encoded SHA256 hash of the file data, which will be verified by the server if provided.
+            uploaded_file_name: Name of the user-uploaded file, required for `TransferMethod.PUT_URL` and `TransferMethod.POST_URL`.
+            sync_call: Whether or not to poll on HTTP/202.
+
+        Raises:
+            PangeaAPIException: If an API error happens.
+
+        Returns:
+            The sanitized file and information on the sanitization that was
+            performed.
+
+        Examples:
+            with open("/path/to/file.pdf", "rb") as f:
+                response = await sanitize.sanitize(
+                    file=f,
+                    transfer_method=TransferMethod.POST_URL,
+                    uploaded_file_name="uploaded_file",
+                )
+        """
+
+        if transfer_method == TransferMethod.SOURCE_URL and source_url is None:
+            raise ValueError("`source_url` argument is required when using `TransferMethod.SOURCE_URL`.")
+
+        if source_url is not None and transfer_method != TransferMethod.SOURCE_URL:
+            raise ValueError(
+                "`transfer_method` should be `TransferMethod.SOURCE_URL` when using the `source_url` argument."
+            )
+
+        files: Optional[List[Tuple]] = None
+        if file or file_path:
+            if file_path:
+                file = open(file_path, "rb")
+            if transfer_method == TransferMethod.POST_URL and (sha256 is None or crc32c is None or size is None):
+                params = get_file_upload_params(file)  # type: ignore[arg-type]
+                crc32c = params.crc_hex if crc32c is None else crc32c
+                sha256 = params.sha256_hex if sha256 is None else sha256
+                size = params.size if size is None else size
+            else:
+                crc32c, sha256, size = None, None, None
+            files = [("upload", ("filename", file, "application/octet-stream"))]
+        elif source_url is None:
+            raise ValueError("Need to set one of `file_path`, `file`, or `source_url` arguments.")
+
+        input = m.SanitizeRequest(
+            transfer_method=transfer_method,
+            source_url=source_url,
+            share_id=share_id,
+            file=file_scan,
+            content=content,
+            share_output=share_output,
+            crc32c=crc32c,
+            sha256=sha256,
+            size=size,
+            uploaded_file_name=uploaded_file_name,
+        )
+        data = input.model_dump(exclude_none=True)
+        try:
+            return await self.request.post(
+                "v1/sanitize", m.SanitizeResult, data=data, files=files, poll_result=sync_call
+            )
+        finally:
+            if file_path and file is not None:
+                file.close()
+
+    async def request_upload_url(
+        self,
+        transfer_method: TransferMethod = TransferMethod.PUT_URL,
+        params: Optional[FileUploadParams] = None,
+        file_scan: Optional[m.SanitizeFile] = None,
+        content: Optional[m.SanitizeContent] = None,
+        share_output: Optional[m.SanitizeShareOutput] = None,
+        size: Optional[int] = None,
+        crc32c: Optional[str] = None,
+        sha256: Optional[str] = None,
+        uploaded_file_name: Optional[str] = None,
+    ) -> PangeaResponse[m.SanitizeResult]:
+        """
+        Sanitize via presigned URL
+
+        Apply file sanitization actions according to specified rules via a
+        [presigned URL](https://pangea.cloud/docs/api/transfer-methods).
+
+        OperationId: sanitize_post_v1_sanitize 2
+
+        Args:
+            transfer_method: The transfer method used to upload the file data.
+            params: File upload parameters.
+            file_scan: Options for File Scan.
+            content: Options for how the file should be sanitized.
+            share_output: Integration with Secure Share.
+            size: The size (in bytes) of the file. If the upload doesn't match, the call will fail.
+            crc32c: The CRC32C hash of the file data, which will be verified by the server if provided.
+            sha256: The hexadecimal-encoded SHA256 hash of the file data, which will be verified by the server if provided.
+            uploaded_file_name: Name of the user-uploaded file, required for `TransferMethod.PUT_URL` and `TransferMethod.POST_URL`.
+
+        Raises:
+            PangeaAPIException: If an API error happens.
+
+        Returns:
+            A presigned URL.
+
+        Examples:
+            presignedUrl = await sanitize.request_upload_url(
+                transfer_method=TransferMethod.PUT_URL,
+                uploaded_file_name="uploaded_file",
+            )
+
+            # Upload file to `presignedUrl.accepted_result.put_url`.
+
+            # Poll for Sanitize's result.
+            response: PangeaResponse[SanitizeResult] = await sanitize.poll_result(response=presignedUrl)
+        """
+
+        input = m.SanitizeRequest(
+            transfer_method=transfer_method,
+            file=file_scan,
+            content=content,
+            share_output=share_output,
+            crc32c=crc32c,
+            sha256=sha256,
+            size=size,
+            uploaded_file_name=uploaded_file_name,
+        )
+        if params is not None and (transfer_method == TransferMethod.POST_URL):
+            input.crc32c = params.crc_hex
+            input.sha256 = params.sha256_hex
+            input.size = params.size
+
+        data = input.model_dump(exclude_none=True)
+        return await self.request.request_presigned_url("v1/sanitize", m.SanitizeResult, data=data)

pangea/file_uploader.py

@@ -0,0 +1,35 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+import io
+import logging
+from typing import Dict, Optional
+
+from pangea.request import PangeaConfig, PangeaRequest
+from pangea.response import TransferMethod
+
+
+class FileUploader:
+    def __init__(self):
+        self.logger = logging.getLogger("pangea")
+        self._request = PangeaRequest(
+            config=PangeaConfig(),
+            token="",
+            service="FileUploader",
+            logger=self.logger,
+        )
+
+    def upload_file(
+        self,
+        url: str,
+        file: io.BufferedReader,
+        transfer_method: TransferMethod = TransferMethod.PUT_URL,
+        file_details: Optional[Dict] = None,
+    ):
+        if transfer_method == TransferMethod.PUT_URL:
+            files = [("file", ("filename", file, "application/octet-stream"))]
+            self._request.put_presigned_url(url=url, files=files)
+        elif transfer_method == TransferMethod.POST_URL:
+            files = [("file", ("filename", file, "application/octet-stream"))]
+            self._request.post_presigned_url(url=url, data=file_details, files=files)
+        else:
+            raise ValueError(f"Transfer method not supported: {transfer_method}")

pangea/request.py

@@ -182,7 +182,7 @@ class PangeaRequestBase(object):
         elif status == ResponseStatus.VAULT_ITEM_NOT_FOUND.value:
             raise pe.VaultItemNotFound(summary, response)
         elif status == ResponseStatus.NOT_FOUND.value:
-            raise pe.NotFound(str(response.raw_response.url) if response.raw_response is not None else "", response)  # type: ignore[arg-type]
+            raise pe.NotFound(str(response.raw_response.url) if response.raw_response is not None else "", response)
         elif status == ResponseStatus.INTERNAL_SERVER_ERROR.value:
             raise pe.InternalServerError(response)
         elif status == ResponseStatus.ACCEPTED.value:

pangea/response.py

@@ -37,10 +37,24 @@ class AttachedFile(object):
 
 
 class TransferMethod(str, enum.Enum):
+    """Transfer methods for uploading file data."""
+
     MULTIPART = "multipart"
     POST_URL = "post-url"
     PUT_URL = "put-url"
     SOURCE_URL = "source-url"
+    """
+    A `source-url` is a caller-specified URL where the Pangea APIs can fetch the
+    contents of the input file. When calling a Pangea API with a
+    `transfer_method` of `source-url`, you must also specify a `source_url`
+    input parameter that provides a URL to the input file. The source URL can be
+    a presigned URL created by the caller, and it will be used to download the
+    content of the input file. The `source-url` transfer method is useful when
+    you already have a file in your storage and can provide a URL from which
+    Pangea API can fetch the input file—there is no need to transfer it to
+    Pangea with a separate POST or PUT request.
+    """
+
     DEST_URL = "dest-url"
 
     def __str__(self):
@@ -222,4 +236,4 @@ class PangeaResponse(ResponseHeader, Generic[T]):
 
     @property
     def url(self) -> str:
-        return str(self.raw_response.url)  # type: ignore[arg-type,union-attr]
+        return str(self.raw_response.url)  # type: ignore[union-attr]

pangea/services/__init__.py

@@ -5,4 +5,5 @@ 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 .vault.vault import Vault

pangea/services/audit/signing.py

@@ -96,7 +96,7 @@ class Signer:
 
         for func in (serialization.load_pem_private_key, serialization.load_ssh_private_key):
             try:
-                return func(private_key, None)  # type: ignore[operator]
+                return func(private_key, None)
             except exceptions.UnsupportedAlgorithm as e:
                 raise e
             except ValueError:

pangea/services/authn/authn.py

@@ -6,7 +6,7 @@ from typing import Dict, List, Optional, Union
 
 import pangea.services.authn.models as m
 from pangea.config import PangeaConfig
-from pangea.response import PangeaResponse
+from pangea.response import PangeaResponse, PangeaResponseResult
 from pangea.services.base import ServiceBase
 
 SERVICE_NAME = "authn"
@@ -363,10 +363,10 @@ class AuthN(ServiceBase):
 
             def __init__(
                 self,
-                token,
-                config=None,
-                logger_name="pangea",
-            ):
+                token: str,
+                config: PangeaConfig | None = None,
+                logger_name: str = "pangea",
+            ) -> None:
                 super().__init__(token, config, logger_name=logger_name)
 
             def change(
@@ -399,6 +399,25 @@ class AuthN(ServiceBase):
                     "v2/client/password/change", m.ClientPasswordChangeResult, data=input.model_dump(exclude_none=True)
                 )
 
+            def expire(self, user_id: str) -> PangeaResponse[PangeaResponseResult]:
+                """
+                Expire a user's password
+
+                Expire a user's password.
+
+                OperationId: authn_post_v2_user_password_expire
+
+                Args:
+                    user_id: The identity of a user or a service.
+
+                Returns:
+                    A PangeaResponse with an empty object in the response.result field.
+
+                Examples:
+                    authn.client.password.expire("pui_[...]")
+                """
+                return self.request.post("v2/user/password/expire", PangeaResponseResult, {"id": user_id})
+
         class Token(ServiceBase):
             service_name = SERVICE_NAME