pangea-sdk 3.8.0b1__py3-none-any.whl → 3.8.0b3__py3-none-any.whl

pangea/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "3.8.0beta1"
+__version__ = "3.8.0beta3"
 
 from pangea.asyncio.request import PangeaRequestAsync
 from pangea.config import PangeaConfig

pangea/asyncio/services/__init__.py

@@ -1,8 +1,10 @@
 from .audit import AuditAsync
 from .authn import AuthNAsync
+from .authz import AuthZAsync
 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 .share import ShareAsync
 from .vault import VaultAsync

pangea/asyncio/services/authz.py

@@ -0,0 +1,267 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+
+from typing import Dict, List, Optional, Union
+
+from pangea.asyncio.services.base import ServiceBaseAsync
+from pangea.response import PangeaResponse
+from pangea.services.authz import (
+    CheckRequest,
+    CheckResult,
+    ItemOrder,
+    ListResourcesRequest,
+    ListResourcesResult,
+    ListSubjectsRequest,
+    ListSubjectsResult,
+    Resource,
+    Subject,
+    Tuple,
+    TupleCreateRequest,
+    TupleCreateResult,
+    TupleDeleteRequest,
+    TupleDeleteResult,
+    TupleListFilter,
+    TupleListRequest,
+    TupleListResult,
+    TupleOrderBy,
+)
+
+
+class AuthZAsync(ServiceBaseAsync):
+    """AuthZ service client. (Beta)
+
+    Provides methods to interact with the Pangea AuthZ Service.
+    Documentation for the AuthZ Service API can be found at
+    <https://pangea.cloud/docs/api/authz>. Note that this service is in Beta and
+    is subject to change.
+
+    Examples:
+        import os
+        from pangea.config import PangeaConfig
+        from pangea.services import AuthZ
+
+        PANGEA_TOKEN = os.getenv("PANGEA_AUTHZ_TOKEN")
+
+        authz_config = PangeaConfig(domain="aws.us.pangea.cloud")
+
+        # Setup Pangea AuthZ service client
+        authz = AuthZAsync(token=PANGEA_TOKEN, config=authz_config)
+    """
+
+    service_name = "authz"
+
+    def __init__(self, token: str, config=None, logger_name="pangea", config_id: Optional[str] = None):
+        super().__init__(token, config, logger_name, config_id=config_id)
+
+    async def tuple_create(self, tuples: List[Tuple]) -> PangeaResponse[TupleCreateResult]:
+        """Create tuples. (Beta)
+
+        Create tuples in the AuthZ Service. The request will fail if there is no schema
+        or the tuples do not validate against the schema.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            tuples (List[Tuple]): List of tuples to be created.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with empty result.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/tuple/create).
+
+        Examples:
+            await authz.tuple_create(
+                tuples=[
+                    Tuple(
+                        resource=Resource(namespace="file", id="file_1"),
+                        relation="owner",
+                        subject=Subject(namespace="user", id="user_1"),
+                    )
+                ]
+            )
+        """
+
+        input_data = TupleCreateRequest(tuples=tuples)
+        return await self.request.post(
+            "v1beta/tuple/create", TupleCreateResult, data=input_data.dict(exclude_none=True)
+        )
+
+    async def tuple_list(
+        self,
+        filter: TupleListFilter,
+        size: Optional[int] = None,
+        last: Optional[str] = None,
+        order: Optional[ItemOrder] = None,
+        order_by: Optional[TupleOrderBy] = None,
+    ) -> PangeaResponse[TupleListResult]:
+        """List tuples. (Beta)
+
+        Return a paginated list of filtered tuples. The filter is given in terms
+        of a tuple. Fill out the fields that you want to filter. If the filter
+        is empty it will return all the tuples.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            filter (TupleListFilter): The filter for listing tuples.
+            size (Optional[int]): The size of the result set. Default is None.
+            last (Optional[str]): The last token from a previous response. Default is None.
+            order (Optional[ItemOrder]): Order results asc(ending) or desc(ending).
+            order_by (Optional[TupleOrderBy]): Which field to order results by.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of tuples and the last token.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/tuple/list).
+
+        Examples:
+            await authz.tuple_list(TupleListFilter(subject_namespace="user", subject_id="user_1"))
+        """
+        input_data = TupleListRequest(
+            filter=filter.dict(exclude_none=True), size=size, last=last, order=order, order_by=order_by
+        )
+        return await self.request.post("v1beta/tuple/list", TupleListResult, data=input_data.dict(exclude_none=True))
+
+    async def tuple_delete(self, tuples: List[Tuple]) -> PangeaResponse[TupleDeleteResult]:
+        """Delete tuples. (Beta)
+
+        Delete tuples in the AuthZ Service.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            tuples (List[Tuple]): List of tuples to be deleted.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with empty result.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/tuple/delete).
+
+        Examples:
+            await authz.tuple_delete(
+                tuples=[
+                    Tuple(
+                        resource=Resource(namespace="file", id="file_1"),
+                        relation="owner",
+                        subject=Subject(namespace="user", id="user_1"),
+                    )
+                ]
+            )
+        """
+
+        input_data = TupleDeleteRequest(tuples=tuples)
+        return await self.request.post(
+            "v1beta/tuple/delete", TupleDeleteResult, data=input_data.dict(exclude_none=True)
+        )
+
+    async def check(
+        self,
+        resource: Resource,
+        action: str,
+        subject: Subject,
+        debug: Optional[bool] = None,
+        attributes: Optional[Dict[str, Union[int, str]]] = None,
+    ) -> PangeaResponse[CheckResult]:
+        """Perform a check request. (Beta)
+
+        Check if a subject has permission to perform an action on the resource.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            resource (Resource): The resource to check.
+            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.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with the result of the check.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/check).
+
+        Examples:
+            await authz.check(
+                resource=Resource(namespace="file", id="file_1"),
+                action="update",
+                subject=Subject(namespace="user", id="user_1"),
+                debug=True,
+            )
+        """
+
+        input_data = CheckRequest(resource=resource, action=action, subject=subject, debug=debug, attributes=attributes)
+        return await self.request.post("v1beta/check", CheckResult, data=input_data.dict(exclude_none=True))
+
+    async def list_resources(
+        self, namespace: str, action: str, subject: Subject
+    ) -> PangeaResponse[ListResourcesResult]:
+        """List resources. (Beta)
+
+        Given a namespace, action, and subject, list all the resources in the
+        namespace that the subject has access to the action with.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            namespace (str): The namespace to filter resources.
+            action (str): The action to filter resources.
+            subject (Subject): The subject to filter resources.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of resource IDs.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/list-resources).
+
+        Examples:
+            await authz.list_resources(
+                namespace="file",
+                action="update",
+                subject=Subject(namespace="user", id="user_1"),
+            )
+        """
+
+        input_data = ListResourcesRequest(namespace=namespace, action=action, subject=subject)
+        return await self.request.post(
+            "v1beta/list-resources", ListResourcesResult, data=input_data.dict(exclude_none=True)
+        )
+
+    async def list_subjects(self, resource: Resource, action: str) -> 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.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            resource (Resource): The resource to filter subjects.
+            action (str): The action to filter subjects.
+
+        Raises:
+            PangeaAPIException: If an API Error happens.
+
+        Returns:
+            Pangea Response with a list of subjects.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1beta/list-subjects).
+
+        Examples:
+            await authz.list_subjects(
+                resource=Resource(namespace="file", id="file_1"),
+                action="update",
+            )
+        """
+
+        input_data = ListSubjectsRequest(resource=resource, action=action)
+        return await self.request.post(
+            "v1beta/list-subjects", ListSubjectsResult, data=input_data.dict(exclude_none=True)
+        )

pangea/asyncio/services/sanitize.py

@@ -0,0 +1,185 @@
+# 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 (Beta)
+
+        Apply file sanitization actions according to specified rules.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        OperationId: sanitize_post_v1beta_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 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: List[Tuple] = [("upload", ("filename", file, "application/octet-stream"))]
+        else:
+            raise ValueError("Need to set file_path or file 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.dict(exclude_none=True)
+        response = await self.request.post(
+            "v1beta/sanitize", m.SanitizeResult, data=data, files=files, poll_result=sync_call
+        )
+        if file_path and file is not None:
+            file.close()
+        return response
+
+    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 (Beta)
+
+        Apply file sanitization actions according to specified rules via a
+        [presigned URL](https://pangea.cloud/docs/api/presigned-urls).
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        OperationId: sanitize_post_v1beta_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.dict(exclude_none=True)
+        return await self.request.request_presigned_url("v1beta/sanitize", m.SanitizeResult, data=data)

pangea/asyncio/services/share.py

@@ -19,10 +19,11 @@ class ShareAsync(ServiceBaseAsync):
         self, id: Optional[str] = None, path: Optional[str] = None, force: Optional[bool] = None
     ) -> PangeaResponse[m.DeleteResult]:
         """
-        Delete
+        Delete (Beta)
 
         Delete object by ID or path. If both are supplied, the path must match
-        that of the object represented by the ID. Beta API.
+        that of the object represented by the ID.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_delete
 
@@ -50,9 +51,10 @@ class ShareAsync(ServiceBaseAsync):
         tags: Optional[m.Tags] = None,
     ) -> PangeaResponse[m.FolderCreateResult]:
         """
-        Create a folder
+        Create a folder (Beta)
 
-        Create a folder, either by name or path and parent_id. Beta API.
+        Create a folder, either by name or path and parent_id.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_folder_create
 
@@ -85,10 +87,11 @@ class ShareAsync(ServiceBaseAsync):
         self, id: Optional[str] = None, path: Optional[str] = None, transfer_method: Optional[TransferMethod] = None
     ) -> PangeaResponse[m.GetResult]:
         """
-        Get an object
+        Get an object (Beta)
 
         Get object. If both ID and Path are supplied, the call will fail if the
-        target object doesn't match both properties. Beta API.
+        target object doesn't match both properties.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_get
 
@@ -121,9 +124,10 @@ class ShareAsync(ServiceBaseAsync):
         transfer_method: Optional[TransferMethod] = None,
     ) -> PangeaResponse[m.GetArchiveResult]:
         """
-        Get archive
+        Get archive (Beta)
 
-        Get an archive file of multiple objects. Beta API.
+        Get an archive file of multiple objects.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_get_archive
 
@@ -160,9 +164,10 @@ class ShareAsync(ServiceBaseAsync):
         size: Optional[int] = None,
     ) -> PangeaResponse[m.ListResult]:
         """
-        List
+        List (Beta)
 
-        List or filter/search records. Beta API.
+        List or filter/search records.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_list
 
@@ -202,9 +207,10 @@ class ShareAsync(ServiceBaseAsync):
         size: Optional[int] = None,
     ) -> PangeaResponse[m.PutResult]:
         """
-        Upload a file
+        Upload a file (Beta)
 
-        Upload a file. Beta API.
+        Upload a file.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_put
 
@@ -287,9 +293,10 @@ class ShareAsync(ServiceBaseAsync):
         size: Optional[int] = None,
     ) -> PangeaResponse[m.PutResult]:
         """
-        Request upload URL
+        Request upload URL (Beta)
 
-        Request an upload URL. Beta API.
+        Request an upload URL.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_put 2
 
@@ -362,9 +369,10 @@ class ShareAsync(ServiceBaseAsync):
         updated_at: Optional[str] = None,
     ) -> PangeaResponse[m.UpdateResult]:
         """
-        Update a file
+        Update a file (Beta)
 
-        Update a file. Beta API.
+        Update a file.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_update
 
@@ -410,9 +418,10 @@ class ShareAsync(ServiceBaseAsync):
 
     async def share_link_create(self, links: List[m.ShareLinkCreateItem]) -> PangeaResponse[m.ShareLinkCreateResult]:
         """
-        Create share links
+        Create share links (Beta)
 
-        Create a share link. Beta API.
+        Create a share link.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_share_link_create
 
@@ -446,9 +455,10 @@ class ShareAsync(ServiceBaseAsync):
 
     async def share_link_get(self, id: str) -> PangeaResponse[m.ShareLinkGetResult]:
         """
-        Get share link
+        Get share link (Beta)
 
-        Get a share link. Beta API.
+        Get a share link.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_share_link_get
 
@@ -478,9 +488,10 @@ class ShareAsync(ServiceBaseAsync):
         size: Optional[int] = None,
     ) -> PangeaResponse[m.ShareLinkListResult]:
         """
-        List share links
+        List share links (Beta)
 
-        Look up share links by filter options. Beta API.
+        Look up share links by filter options.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_share_link_list
 
@@ -505,9 +516,10 @@ class ShareAsync(ServiceBaseAsync):
 
     async def share_link_delete(self, ids: List[str]) -> PangeaResponse[m.ShareLinkDeleteResult]:
         """
-        Delete share links
+        Delete share links (Beta)
 
-        Delete share links. Beta API.
+        Delete share links.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_share_link_delete
 
@@ -532,12 +544,13 @@ class ShareAsync(ServiceBaseAsync):
         self, links: List[m.ShareLinkSendItem], sender_email: str, sender_name: Optional[str] = None
     ) -> PangeaResponse[m.ShareLinkSendResult]:
         """
-        Send share links
+        Send share links (Beta)
 
         Send a secure share-link notification to a set of email addresses. The
         notification email will contain an Open button that the recipient can
         use to follow the secured share-link to authenticate and then access the
-        shared content. Beta API.
+        shared content.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         OperationId: share_post_v1beta_share_link_send
 

pangea/services/__init__.py

@@ -1,8 +1,10 @@
 from .audit.audit import Audit
 from .authn.authn import AuthN
+from .authz import AuthZ
 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