pangea-sdk 3.8.0b1__tar.gz → 3.8.0b3__tar.gz

{pangea_sdk-3.8.0b1 → pangea_sdk-3.8.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pangea-sdk
-Version: 3.8.0b1
+Version: 3.8.0b3
 Summary: Pangea API SDK
 Home-page: https://pangea.cloud/docs/sdk/python/
 License: MIT
@@ -44,6 +44,8 @@ above.
 
 ## Installation
 
+#### GA releases
+
 Via pip:
 
 ```bash
@@ -56,10 +58,32 @@ Via poetry:
 $ poetry add pangea-sdk
 ```
 
+<a name="beta-releases"></a>
+
+#### Beta releases
+
+Pre-release versions may be available with the `b` (beta) denotation in the
+version number. These releases serve to preview beta services and APIs. Per
+Semantic Versioning, they are considered unstable and do not carry the same
+compatibility guarantees as stable releases. [Beta changelog](https://github.com/pangeacyber/pangea-python/blob/beta/CHANGELOG.md).
+
+Via pip:
+
+```bash
+$ pip3 install pangea-sdk==3.8.0b3
+```
+
+Via poetry:
+
+```bash
+$ poetry add pangea-sdk==3.8.0b3
+```
+
 ## Usage
 
 - [Documentation][]
-- [Examples][]
+- [GA Examples][]
+- [Beta Examples][]
 
 General usage would be to create a token for a service through the
 [Pangea Console][] and then construct an API client for that respective service.
@@ -213,7 +237,8 @@ It accepts multiple file formats:
 
 
    [Documentation]: https://pangea.cloud/docs/sdk/python/
-   [Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
+   [GA Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
+   [Beta Examples]: https://github.com/pangeacyber/pangea-python/tree/beta/examples
    [Pangea Console]: https://console.pangea.cloud/
    [Slack]: https://pangea.cloud/join-slack/
    [Secure Audit Log]: https://pangea.cloud/docs/audit

{pangea_sdk-3.8.0b1 → pangea_sdk-3.8.0b3}/README.md

@@ -14,6 +14,8 @@ above.
 
 ## Installation
 
+#### GA releases
+
 Via pip:
 
 ```bash
@@ -26,10 +28,32 @@ Via poetry:
 $ poetry add pangea-sdk
 ```
 
+<a name="beta-releases"></a>
+
+#### Beta releases
+
+Pre-release versions may be available with the `b` (beta) denotation in the
+version number. These releases serve to preview beta services and APIs. Per
+Semantic Versioning, they are considered unstable and do not carry the same
+compatibility guarantees as stable releases. [Beta changelog](https://github.com/pangeacyber/pangea-python/blob/beta/CHANGELOG.md).
+
+Via pip:
+
+```bash
+$ pip3 install pangea-sdk==3.8.0b3
+```
+
+Via poetry:
+
+```bash
+$ poetry add pangea-sdk==3.8.0b3
+```
+
 ## Usage
 
 - [Documentation][]
-- [Examples][]
+- [GA Examples][]
+- [Beta Examples][]
 
 General usage would be to create a token for a service through the
 [Pangea Console][] and then construct an API client for that respective service.
@@ -183,7 +207,8 @@ It accepts multiple file formats:
 
 
    [Documentation]: https://pangea.cloud/docs/sdk/python/
-   [Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
+   [GA Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
+   [Beta Examples]: https://github.com/pangeacyber/pangea-python/tree/beta/examples
    [Pangea Console]: https://console.pangea.cloud/
    [Slack]: https://pangea.cloud/join-slack/
    [Secure Audit Log]: https://pangea.cloud/docs/audit

{pangea_sdk-3.8.0b1 → pangea_sdk-3.8.0b3}/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_sdk-3.8.0b1 → pangea_sdk-3.8.0b3}/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_sdk-3.8.0b3/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_sdk-3.8.0b3/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)