pangea-sdk 3.8.0b1__py3-none-any.whl → 5.3.0__py3-none-any.whl

pangea/asyncio/services/authz.py

@@ -0,0 +1,285 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from pangea.asyncio.services.base import ServiceBaseAsync
+from pangea.config import PangeaConfig
+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.
+
+    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>.
+
+    Examples:
+        import os
+        from pangea.asyncio.services import AuthZAsync
+        from pangea.config import PangeaConfig
+
+        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: PangeaConfig | None = None, logger_name: str = "pangea", config_id: str | None = None
+    ) -> None:
+        """
+        AuthZ client
+
+        Initializes a new AuthZ client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="aws.us.pangea.cloud")
+             authz = AuthZAsync(token="pangea_token", config=config)
+        """
+
+        super().__init__(token, config, logger_name, config_id=config_id)
+
+    async def tuple_create(self, tuples: List[Tuple]) -> PangeaResponse[TupleCreateResult]:
+        """Create tuples.
+
+        Create tuples in the AuthZ Service. The request will fail if there is no schema
+        or the tuples do not validate against the schema.
+
+        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#/v1/tuple/create).
+
+        Examples:
+            await authz.tuple_create(
+                tuples=[
+                    Tuple(
+                        resource=Resource(type="file", id="file_1"),
+                        relation="owner",
+                        subject=Subject(type="user", id="user_1"),
+                    )
+                ]
+            )
+        """
+
+        input_data = TupleCreateRequest(tuples=tuples)
+        return await self.request.post(
+            "v1/tuple/create", TupleCreateResult, data=input_data.model_dump(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.
+
+        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.
+
+        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#/v1/tuple/list).
+
+        Examples:
+            await authz.tuple_list(TupleListFilter(subject_type="user", subject_id="user_1"))
+        """
+        input_data = TupleListRequest(
+            filter=filter.model_dump(exclude_none=True), size=size, last=last, order=order, order_by=order_by
+        )
+        return await self.request.post("v1/tuple/list", TupleListResult, data=input_data.model_dump(exclude_none=True))
+
+    async def tuple_delete(self, tuples: List[Tuple]) -> PangeaResponse[TupleDeleteResult]:
+        """Delete tuples.
+
+        Delete tuples in the AuthZ Service.
+
+        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#/v1/tuple/delete).
+
+        Examples:
+            await authz.tuple_delete(
+                tuples=[
+                    Tuple(
+                        resource=Resource(type="file", id="file_1"),
+                        relation="owner",
+                        subject=Subject(type="user", id="user_1"),
+                    )
+                ]
+            )
+        """
+
+        input_data = TupleDeleteRequest(tuples=tuples)
+        return await self.request.post(
+            "v1/tuple/delete", TupleDeleteResult, data=input_data.model_dump(exclude_none=True)
+        )
+
+    async def check(
+        self,
+        resource: Resource,
+        action: str,
+        subject: Subject,
+        debug: Optional[bool] = None,
+        attributes: Optional[Dict[str, Any]] = None,
+    ) -> PangeaResponse[CheckResult]:
+        """Perform a check request.
+
+        Check if a subject has permission to perform an action on the resource.
+
+        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, Any]]): 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#/v1/check).
+
+        Examples:
+            await authz.check(
+                resource=Resource(type="file", id="file_1"),
+                action="update",
+                subject=Subject(type="user", id="user_1"),
+                debug=True,
+            )
+        """
+
+        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, attributes: Optional[Dict[str, Any]] = None
+    ) -> PangeaResponse[ListResourcesResult]:
+        """List resources.
+
+        Given a type, action, and subject, list all the resources in the
+        type that the subject has access to the action with.
+
+        Args:
+            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.
+
+        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#/v1/list-resources).
+
+        Examples:
+            await authz.list_resources(
+                type="file",
+                action="update",
+                subject=Subject(type="user", id="user_1"),
+            )
+        """
+
+        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, attributes: Optional[Dict[str, Any]] = None
+    ) -> PangeaResponse[ListSubjectsResult]:
+        """List subjects.
+
+        Given a resource and an action, return the list of subjects who have
+        access to the action for the given resource.
+
+        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.
+
+        Returns:
+            Pangea Response with a list of subjects.
+            Available response fields can be found in our
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/list-subjects).
+
+        Examples:
+            await authz.list_subjects(
+                resource=Resource(type="file", id="file_1"),
+                action="update",
+            )
+        """
+
+        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/base.py

@@ -1,8 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 from typing import Dict, Optional, Type, Union
 
+from typing_extensions import override
+
 from pangea.asyncio.request import PangeaRequestAsync
 from pangea.exceptions import AcceptedRequestException
 from pangea.response import AttachedFile, PangeaResponse, PangeaResponseResult
@@ -23,6 +26,7 @@ class ServiceBaseAsync(ServiceBase):
 
         return self._request
 
+    @override
     async def poll_result(  # type: ignore[override]
         self,
         exception: Optional[AcceptedRequestException] = None,
@@ -36,7 +40,8 @@ class ServiceBaseAsync(ServiceBase):
         Returns request's result that has been accepted by the server
 
         Args:
-            exception (AcceptedRequestException): Exception raise by SDK on the call that is been processed.
+            exception: Exception that was previously raised by the SDK on a call
+              that is being processed.
 
         Returns:
             PangeaResponse
@@ -58,7 +63,21 @@ class ServiceBaseAsync(ServiceBase):
         else:
             raise AttributeError("Need to set exception, response or request_id")
 
-    async def download_file(self, url: str, filename: Optional[str] = None) -> AttachedFile:  # type: ignore[override]
+    @override
+    async def download_file(self, url: str, filename: str | None = None) -> AttachedFile:  # type: ignore[override]
+        """
+        Download file
+
+        Download a file from the specified URL and save it with the given
+        filename.
+
+        Args:
+            url: URL of the file to download
+            filename: Name to save the downloaded file as. If not provided, the
+              filename will be determined from the Content-Disposition header or
+              the URL.
+        """
+
         return await self.request.download_file(url=url, filename=filename)
 
     async def close(self):

pangea/asyncio/services/embargo.py

@@ -57,7 +57,7 @@ class EmbargoAsync(ServiceBaseAsync):
             response = embargo.ip_check("190.6.64.94")
         """
         input = e.IPCheckRequest(ip=ip)
-        return await self.request.post("v1/ip/check", e.EmbargoResult, data=input.dict())
+        return await self.request.post("v1/ip/check", e.EmbargoResult, data=input.model_dump())
 
     async def iso_check(self, iso_code: str) -> PangeaResponse[e.EmbargoResult]:
         """
@@ -84,4 +84,4 @@ class EmbargoAsync(ServiceBaseAsync):
             response = embargo.iso_check("CU")
         """
         input = e.ISOCheckRequest(iso_code=iso_code)
-        return await self.request.post("v1/iso/check", result_class=e.EmbargoResult, data=input.dict())
+        return await self.request.post("v1/iso/check", result_class=e.EmbargoResult, data=input.model_dump())

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,
@@ -109,8 +120,12 @@ class FileScanAsync(ServiceBaseAsync):
             transfer_method=transfer_method,
             source_url=source_url,
         )
-        data = input.dict(exclude_none=True)
-        return await self.request.post("v1/scan", m.FileScanResult, data=data, files=files, poll_result=sync_call)
+        data = input.model_dump(exclude_none=True)
+        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,
@@ -131,7 +146,7 @@ class FileScanAsync(ServiceBaseAsync):
             input.sha256 = params.sha256_hex
             input.size = params.size
 
-        data = input.dict(exclude_none=True)
+        data = input.model_dump(exclude_none=True)
         return await self.request.request_presigned_url("v1/scan", m.FileScanResult, data=data)
 
 
@@ -154,7 +169,7 @@ class FileUploaderAsync:
     ) -> None:
         if transfer_method == TransferMethod.PUT_URL:
             files = [("file", ("filename", file, "application/octet-stream"))]
-            await self._request.put_presigned_url(url=url, files=files)  # type: ignore[arg-type]
+            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]