pangea-sdk 3.7.0__py3-none-any.whl → 3.8.0__py3-none-any.whl

pangea/asyncio/services/authn.py

@@ -1,13 +1,14 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 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 .base import ServiceBaseAsync
-
 SERVICE_NAME = "authn"
 
 
@@ -38,10 +39,24 @@ class AuthNAsync(ServiceBaseAsync):
 
     def __init__(
         self,
-        token,
-        config=None,
-        logger_name="pangea",
-    ):
+        token: str,
+        config: PangeaConfig | None = None,
+        logger_name: str = "pangea",
+    ) -> None:
+        """
+        AuthN client
+
+        Initializes a new AuthN client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+
+        Examples:
+             config = PangeaConfig(domain="pangea_domain")
+             authn = AuthNAsync(token="pangea_token", config=config)
+        """
         super().__init__(token, config, logger_name=logger_name)
         self.user = AuthNAsync.UserAsync(token, config, logger_name=logger_name)
         self.flow = AuthNAsync.FlowAsync(token, config, logger_name=logger_name)
@@ -54,10 +69,10 @@ class AuthNAsync(ServiceBaseAsync):
 
         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)
 
         async def invalidate(self, session_id: str) -> PangeaResponse[m.SessionInvalidateResult]:
@@ -114,6 +129,9 @@ class AuthNAsync(ServiceBaseAsync):
             Examples:
                 response = authn.session.list()
             """
+            if isinstance(filter, dict):
+                filter = m.SessionListFilter(**filter)
+
             input = m.SessionListRequest(filter=filter, last=last, order=order, order_by=order_by, size=size)
             return await self.request.post("v2/session/list", m.SessionListResults, data=input.dict(exclude_none=True))
 
@@ -146,10 +164,10 @@ class AuthNAsync(ServiceBaseAsync):
 
         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)
             self.session = AuthNAsync.ClientAsync.SessionAsync(token, config, logger_name=logger_name)
             self.password = AuthNAsync.ClientAsync.PasswordAsync(token, config, logger_name=logger_name)
@@ -206,10 +224,10 @@ class AuthNAsync(ServiceBaseAsync):
 
             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)
 
             async def invalidate(self, token: str, session_id: str) -> PangeaResponse[m.ClientSessionInvalidateResult]:
@@ -272,6 +290,9 @@ class AuthNAsync(ServiceBaseAsync):
                         token="ptu_wuk7tvtpswyjtlsx52b7yyi2l7zotv4a",
                     )
                 """
+                if isinstance(filter, dict):
+                    filter = m.SessionListFilter(**filter)
+
                 input = m.ClientSessionListRequest(
                     token=token, filter=filter, last=last, order=order, order_by=order_by, size=size
                 )
@@ -338,10 +359,10 @@ class AuthNAsync(ServiceBaseAsync):
 
             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)
 
             async def change(
@@ -379,10 +400,10 @@ class AuthNAsync(ServiceBaseAsync):
 
             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)
 
             async def check(self, token: str) -> PangeaResponse[m.ClientTokenCheckResult]:
@@ -416,10 +437,10 @@ class AuthNAsync(ServiceBaseAsync):
 
         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)
             self.profile = AuthNAsync.UserAsync.ProfileAsync(token, config, logger_name=logger_name)
             self.authenticators = AuthNAsync.UserAsync.AuthenticatorsAsync(token, config, logger_name=logger_name)
@@ -593,6 +614,9 @@ class AuthNAsync(ServiceBaseAsync):
             Examples:
                 response = authn.user.list()
             """
+            if isinstance(filter, dict):
+                filter = m.UserListFilter(**filter)
+
             input = m.UserListRequest(
                 filter=filter,
                 last=last,
@@ -607,10 +631,10 @@ class AuthNAsync(ServiceBaseAsync):
 
             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)
 
             async def list(
@@ -642,6 +666,9 @@ class AuthNAsync(ServiceBaseAsync):
                 Examples:
                     response = authn.user.invites.list()
                 """
+                if isinstance(filter, dict):
+                    filter = m.UserInviteListFilter(**filter)
+
                 input = m.UserInviteListRequest(filter=filter, last=last, order=order, order_by=order_by, size=size)
                 return await self.request.post(
                     "v2/user/invite/list", m.UserInviteListResult, data=input.dict(exclude_none=True)
@@ -676,10 +703,10 @@ class AuthNAsync(ServiceBaseAsync):
 
             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)
 
             async def delete(
@@ -747,10 +774,10 @@ class AuthNAsync(ServiceBaseAsync):
 
             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)
 
             async def get(
@@ -827,10 +854,10 @@ class AuthNAsync(ServiceBaseAsync):
 
         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)
 
         async def complete(self, flow_id: str) -> PangeaResponse[m.FlowCompleteResult]:
@@ -967,10 +994,10 @@ class AuthNAsync(ServiceBaseAsync):
 
         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)
 
         async def create(
@@ -1064,6 +1091,8 @@ class AuthNAsync(ServiceBaseAsync):
             Examples:
                 response = authn.agreements.list()
             """
+            if isinstance(filter, dict):
+                filter = m.AgreementListFilter(**filter)
 
             input = m.AgreementListRequest(filter=filter, last=last, order=order, order_by=order_by, size=size)
             return await self.request.post(

pangea/asyncio/services/authz.py

@@ -0,0 +1,259 @@
+# 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#/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.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#/v1/tuple/list).
+
+        Examples:
+            await authz.tuple_list(TupleListFilter(subject_type="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("v1/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#/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.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#/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.dict(exclude_none=True))
+
+    async def list_resources(self, type: str, action: str, subject: Subject) -> 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.
+        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
+
+        Args:
+            type (str): The type 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#/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)
+        return await self.request.post(
+            "v1/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#/v1/list-subjects).
+
+        Examples:
+            await authz.list_subjects(
+                resource=Resource(type="file", id="file_1"),
+                action="update",
+            )
+        """
+
+        input_data = ListSubjectsRequest(resource=resource, action=action)
+        return await self.request.post("v1/list-subjects", ListSubjectsResult, data=input_data.dict(exclude_none=True))

pangea/asyncio/services/base.py

@@ -1,18 +1,18 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
 
-from typing import Optional, Type, Union
+from typing import Dict, Optional, Type, Union
 
 from pangea.asyncio.request import PangeaRequestAsync
 from pangea.exceptions import AcceptedRequestException
-from pangea.response import PangeaResponse, PangeaResponseResult
-from pangea.services.base import ServiceBase
+from pangea.response import AttachedFile, PangeaResponse, PangeaResponseResult
+from pangea.services.base import PangeaRequest, ServiceBase
 
 
 class ServiceBaseAsync(ServiceBase):
     @property
-    def request(self):
-        if not self._request:
+    def request(self) -> PangeaRequestAsync:  # type: ignore[override]
+        if self._request is None or isinstance(self._request, PangeaRequest):
             self._request = PangeaRequestAsync(
                 config=self.config,
                 token=self.token,
@@ -28,7 +28,7 @@ class ServiceBaseAsync(ServiceBase):
         exception: Optional[AcceptedRequestException] = None,
         response: Optional[PangeaResponse] = None,
         request_id: Optional[str] = None,
-        result_class: Union[Type[PangeaResponseResult], dict] = dict,  # type: ignore[assignment]
+        result_class: Union[Type[PangeaResponseResult], Type[Dict]] = dict,
     ) -> PangeaResponse:
         """
         Poll result
@@ -58,6 +58,9 @@ 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]
+        return await self.request.download_file(url=url, filename=filename)
+
     async def close(self):
         await self.request.session.close()
         # Loop over all attributes to check if they are derived from ServiceBaseAsync and close them

pangea/asyncio/services/file_scan.py

@@ -2,16 +2,15 @@
 # Author: Pangea Cyber Corporation
 import io
 import logging
-from typing import Dict, Optional
+from typing import Dict, List, Optional, Tuple
 
 import pangea.services.file_scan as m
 from pangea.asyncio.request import PangeaRequestAsync
+from pangea.asyncio.services.base import ServiceBaseAsync
 from pangea.request import PangeaConfig
 from pangea.response import PangeaResponse, TransferMethod
 from pangea.utils import FileUploadParams, get_file_upload_params
 
-from .base import ServiceBaseAsync
-
 
 class FileScanAsync(ServiceBaseAsync):
     """FileScan service client.
@@ -96,7 +95,7 @@ class FileScanAsync(ServiceBaseAsync):
                 size = params.size
             else:
                 crc, sha, size = None, None, None
-            files = [("upload", ("filename", file, "application/octet-stream"))]
+            files: List[Tuple] = [("upload", ("filename", file, "application/octet-stream"))]
         else:
             raise ValueError("Need to set file_path or file arguments")
 

pangea/asyncio/services/intel.py

@@ -4,11 +4,10 @@ import hashlib
 from typing import List, Optional
 
 import pangea.services.intel as m
+from pangea.asyncio.services.base import ServiceBaseAsync
 from pangea.response import PangeaResponse
 from pangea.utils import hash_256_filepath
 
-from .base import ServiceBaseAsync
-
 
 class FileIntelAsync(ServiceBaseAsync):
     """File Intel service client
@@ -77,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
 
@@ -183,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
         )
 
@@ -252,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
 
@@ -374,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,13 +1,14 @@
 # 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
 
-from .base import ServiceBaseAsync
-
 
 class RedactAsync(ServiceBaseAsync):
     """Redact service client.
@@ -36,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(