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

pangea/services/authz.py

@@ -0,0 +1,377 @@
+# Copyright 2022 Pangea Cyber Corporation
+# Author: Pangea Cyber Corporation
+
+import enum
+from typing import Any, Dict, List, Optional, Union
+
+from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
+from pangea.services.base import ServiceBase
+
+
+class ItemOrder(str, enum.Enum):
+    ASC = "asc"
+    DESC = "desc"
+
+    def __str__(self):
+        return str(self.value)
+
+    def __repr__(self):
+        return str(self.value)
+
+
+class TupleOrderBy(str, enum.Enum):
+    RESOURCE_TYPE = "resource_type"
+    RESOURCE_ID = "resource_id"
+    RELATION = "relation"
+    SUBJECT_TYPE = "subject_type"
+    SUBJECT_ID = "subject_id"
+    SUBJECT_ACTION = "subject_action"
+
+    def __str__(self):
+        return str(self.value)
+
+    def __repr__(self):
+        return str(self.value)
+
+
+class Resource(PangeaResponseResult):
+    type: str
+    id: Optional[str] = None
+
+
+class Subject(PangeaResponseResult):
+    type: str
+    id: Optional[str] = None
+    action: Optional[str] = None
+
+
+class Tuple(PangeaResponseResult):
+    resource: Resource
+    relation: str
+    subject: Subject
+
+
+class TupleCreateRequest(APIRequestModel):
+    tuples: List[Tuple]
+
+
+class TupleCreateResult(PangeaResponseResult):
+    pass
+
+
+class TupleListFilter(APIRequestModel):
+    resource_type: Optional[str] = None
+    resource_type__contains: Optional[List[str]] = None
+    resource_type__in: Optional[List[str]] = None
+    resource_id: Optional[str] = None
+    resource_id__contains: Optional[List[str]] = None
+    resource_id__in: Optional[List[str]] = None
+    relation: Optional[str] = None
+    relation__contains: Optional[List[str]] = None
+    relation__in: Optional[List[str]] = None
+    subject_type: Optional[str] = None
+    subject_type__contains: Optional[List[str]] = None
+    subject_type__in: Optional[List[str]] = None
+    subject_id: Optional[str] = None
+    subject_id__contains: Optional[List[str]] = None
+    subject_id__in: Optional[List[str]] = None
+    subject_action: Optional[str] = None
+    subject_action__contains: Optional[List[str]] = None
+    subject_action__in: Optional[List[str]] = None
+
+
+class TupleListRequest(APIRequestModel):
+    filter: Optional[Union[Dict, TupleListFilter]] = None
+    size: Optional[int] = None
+    last: Optional[str] = None
+    order: Optional[ItemOrder] = None
+    order_by: Optional[TupleOrderBy] = None
+
+
+class TupleListResult(PangeaResponseResult):
+    tuples: List[Tuple]
+    last: str
+    count: int
+
+
+class TupleDeleteRequest(APIRequestModel):
+    tuples: List[Tuple]
+
+
+class TupleDeleteResult(PangeaResponseResult):
+    pass
+
+
+class CheckRequest(APIRequestModel):
+    resource: Resource
+    action: str
+    subject: Subject
+    debug: Optional[bool] = None
+    attributes: Optional[Dict[str, Any]] = None
+
+
+class DebugPath(APIResponseModel):
+    type: str
+    id: str
+    action: Optional[str]
+
+
+class Debug(APIResponseModel):
+    path: List[DebugPath]
+
+
+class CheckResult(PangeaResponseResult):
+    schema_id: str
+    schema_version: int
+    depth: int
+    allowed: bool
+    debug: Optional[Debug] = None
+
+
+class ListResourcesRequest(APIRequestModel):
+    type: str
+    action: str
+    subject: Subject
+
+
+class ListResourcesResult(PangeaResponseResult):
+    ids: List[str]
+
+
+class ListSubjectsRequest(APIRequestModel):
+    resource: Resource
+    action: str
+
+
+class ListSubjectsResult(PangeaResponseResult):
+    subjects: List[Subject]
+
+
+class AuthZ(ServiceBase):
+    """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 = AuthZ(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)
+
+    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:
+            response = 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 self.request.post("v1/tuple/create", TupleCreateResult, data=input_data.dict(exclude_none=True))
+
+    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:
+            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 self.request.post("v1/tuple/list", TupleListResult, data=input_data.dict(exclude_none=True))
+
+    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:
+            response = 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 self.request.post("v1/tuple/delete", TupleDeleteResult, data=input_data.dict(exclude_none=True))
+
+    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:
+            response = 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 self.request.post("v1/check", CheckResult, data=input_data.dict(exclude_none=True))
+
+    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:
+            authz.list_resources(
+                type="file",
+                action="update",
+                subject=Subject(type="user", id="user_1"),
+            )
+        """
+
+        input_data = ListResourcesRequest(type=type, action=action, subject=subject)
+        return self.request.post("v1/list-resources", ListResourcesResult, data=input_data.dict(exclude_none=True))
+
+    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:
+            response = authz.list_subjects(
+                resource=Resource(type="file", id="file_1"),
+                action="update",
+            )
+        """
+
+        input_data = ListSubjectsRequest(resource=resource, action=action)
+        return self.request.post("v1/list-subjects", ListSubjectsResult, data=input_data.dict(exclude_none=True))

pangea/services/base.py

@@ -1,45 +1,62 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 import copy
 import logging
-from typing import Optional, Type, Union
+from typing import Dict, Optional, Type, Union
+
+from typing_extensions import TypeVar
 
 from pangea.asyncio.request import PangeaRequestAsync
 from pangea.config import PangeaConfig
 from pangea.exceptions import AcceptedRequestException
 from pangea.request import PangeaRequest
-from pangea.response import PangeaResponse, PangeaResponseResult
+from pangea.response import AttachedFile, PangeaResponse, PangeaResponseResult
+
+TResult = TypeVar("TResult", bound=PangeaResponseResult, default=PangeaResponseResult)
 
 
 class ServiceBase(object):
     service_name: str = "base"
 
     def __init__(
-        self, token, config: Optional[PangeaConfig] = None, logger_name: str = "pangea", config_id: Optional[str] = None
-    ):
+        self,
+        token: str,
+        config: PangeaConfig | None = None,
+        logger_name: str = "pangea",
+        config_id: str | None = None,
+    ) -> None:
+        """
+        Initializes a new Pangea service client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+        """
         if not token:
             raise Exception("No token provided")
 
-        self.config = config if copy.deepcopy(config) else PangeaConfig()
+        self.config = copy.deepcopy(config) if config is not None else PangeaConfig()
         self.logger = logging.getLogger(logger_name)
         self._token = token
-        self.config_id: Optional[None] = config_id  # type: ignore[assignment]
-        self._request: Union[PangeaRequest, PangeaRequestAsync] = None  # type: ignore[assignment]
-        extra_headers = {}  # type: ignore[var-annotated]
+        self.config_id: Optional[str] = config_id
+        self._request: Optional[Union[PangeaRequest, PangeaRequestAsync]] = None
+        extra_headers: Dict = {}
         self.request.set_extra_headers(extra_headers)
 
     @property
-    def token(self):
+    def token(self) -> str:
         return self._token
 
     @token.setter
-    def token(self, value):
+    def token(self, value: str) -> None:
         self._token = value
 
     @property
-    def request(self):
-        if not self._request:
+    def request(self) -> PangeaRequest:
+        if self._request is None or isinstance(self._request, PangeaRequestAsync):
             self._request = PangeaRequest(
                 config=self.config,
                 token=self.token,
@@ -55,8 +72,8 @@ class ServiceBase(object):
         exception: Optional[AcceptedRequestException] = None,
         response: Optional[PangeaResponse] = None,
         request_id: Optional[str] = None,
-        result_class: Union[Type[PangeaResponseResult], dict] = dict,  # type: ignore[assignment]
-    ) -> PangeaResponse:
+        result_class: Type[TResult] = PangeaResponseResult,  # type: ignore[assignment]
+    ) -> PangeaResponse[TResult]:
         """
         Poll result
 
@@ -82,3 +99,6 @@ class ServiceBase(object):
             return self.request.poll_result_by_id(request_id=request_id, result_class=result_class, check_response=True)
         else:
             raise AttributeError("Need to set exception, response or request_id")
+
+    def download_file(self, url: str, filename: Optional[str] = None) -> AttachedFile:
+        return self.request.download_file(url=url, filename=filename)

pangea/services/embargo.py

@@ -3,8 +3,7 @@
 from typing import Any, Dict, List
 
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
-
-from .base import ServiceBase
+from pangea.services.base import ServiceBase
 
 
 class IPCheckRequest(APIRequestModel):

pangea/services/file_scan.py

@@ -2,14 +2,13 @@
 # Author: Pangea Cyber Corporation
 import io
 import logging
-from typing import Dict, List, Optional
+from typing import Dict, List, Optional, Tuple
 
 from pangea.request import PangeaConfig, PangeaRequest
 from pangea.response import APIRequestModel, PangeaResponse, PangeaResponseResult, TransferMethod
+from pangea.services.base import ServiceBase
 from pangea.utils import FileUploadParams, get_file_upload_params
 
-from .base import ServiceBase
-
 
 class FileScanRequest(APIRequestModel):
     """
@@ -129,7 +128,7 @@ class FileScan(ServiceBase):
                 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/services/intel.py

@@ -6,10 +6,9 @@ from typing import Dict, List, Optional
 
 from pangea.exceptions import PangeaException
 from pangea.response import APIRequestModel, PangeaResponse, PangeaResponseResult
+from pangea.services.base import ServiceBase
 from pangea.utils import hash_256_filepath
 
-from .base import ServiceBase
-
 
 class IntelCommonRequest(APIRequestModel):
     """
@@ -840,7 +839,7 @@ class IpIntel(ServiceBase):
 
     def reputation_bulk(
         self, ips: List[str], verbose: Optional[bool] = None, raw: Optional[bool] = None, provider: Optional[str] = None
-    ) -> PangeaResponse[IPReputationResult]:
+    ) -> PangeaResponse[IPReputationBulkResult]:
         """
         Reputation V2
 
@@ -1196,7 +1195,7 @@ class UrlIntel(ServiceBase):
         verbose: Optional[bool] = None,
         raw: Optional[bool] = None,
         provider: Optional[str] = None,
-    ) -> PangeaResponse[URLReputationResult]:
+    ) -> PangeaResponse[URLReputationBulkResult]:
         """
         Reputation V2
 

pangea/services/redact.py

@@ -1,12 +1,13 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 import enum
 from typing import Dict, List, Optional, Union
 
+from pangea.config import PangeaConfig
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
-
-from .base import ServiceBase
+from pangea.services.base import ServiceBase
 
 
 class RedactFormat(str, enum.Enum):
@@ -133,7 +134,24 @@ class Redact(ServiceBase):
 
     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.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="pangea_domain")
+             redact = Redact(token="pangea_token", config=config)
+        """
         super().__init__(token, config, logger_name, config_id=config_id)
 
     def redact(

pangea/services/vault/vault.py

@@ -1,8 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
+
 import datetime
 from typing import Dict, Optional, Union
 
+from pangea.config import PangeaConfig
 from pangea.response import PangeaResponse
 from pangea.services.base import ServiceBase
 from pangea.services.vault.models.asymmetric import (
@@ -48,8 +51,8 @@ from pangea.services.vault.models.common import (
     StateChangeRequest,
     StateChangeResult,
     SymmetricAlgorithm,
-    TDict,
     Tags,
+    TDict,
     UpdateRequest,
     UpdateResult,
 )
@@ -91,17 +94,31 @@ class Vault(ServiceBase):
         vault_config = PangeaConfig(domain="pangea.cloud")
 
         # Setup Pangea Vault service
-        vault = Vault(token=PANGEA_VAULT_TOKEN, config=audit_config)
+        vault = Vault(token=PANGEA_VAULT_TOKEN, config=vault_config)
     """
 
     service_name = "vault"
 
     def __init__(
         self,
-        token,
-        config=None,
-        logger_name="pangea",
-    ):
+        token: str,
+        config: PangeaConfig | None = None,
+        logger_name: str = "pangea",
+    ) -> None:
+        """
+        Vault client
+
+        Initializes a new Vault client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+
+        Examples:
+             config = PangeaConfig(domain="pangea_domain")
+             vault = Vault(token="pangea_token", config=config)
+        """
         super().__init__(token, config, logger_name)
 
     # Delete endpoint
@@ -866,8 +883,8 @@ class Vault(ServiceBase):
 
                 Default is `deactivated`.
             public_key (EncodedPublicKey, optional): The public key (in PEM format)
-            private_key: (EncodedPrivateKey, optional): The private key (in PEM format)
-            key: (EncodedSymmetricKey, optional): The key material (in base64)
+            private_key (EncodedPrivateKey, optional): The private key (in PEM format)
+            key (EncodedSymmetricKey, optional): The key material (in base64)
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -1216,7 +1233,7 @@ class Vault(ServiceBase):
         Args:
             id (str): The item ID.
             structured_data (dict): Structured data for applying bulk operations.
-            filter (str, optional): A filter expression for applying bulk operations to the data field.
+            filter (str): A filter expression for applying bulk operations to the data field.
             version (int, optional): The item version. Defaults to the current version.
             additional_data (str, optional): User provided authentication data.
 
@@ -1237,7 +1254,7 @@ class Vault(ServiceBase):
             )
         """
 
-        input = EncryptStructuredRequest(
+        input: EncryptStructuredRequest[TDict] = EncryptStructuredRequest(
             id=id, structured_data=structured_data, filter=filter, version=version, additional_data=additional_data
         )
         return self.request.post(
@@ -1265,7 +1282,7 @@ class Vault(ServiceBase):
         Args:
             id (str): The item ID.
             structured_data (dict): Structured data to decrypt.
-            filter (str, optional): A filter expression for applying bulk operations to the data field.
+            filter (str): A filter expression for applying bulk operations to the data field.
             version (int, optional): The item version. Defaults to the current version.
             additional_data (str, optional): User provided authentication data.
 
@@ -1286,7 +1303,7 @@ class Vault(ServiceBase):
             )
         """
 
-        input = EncryptStructuredRequest(
+        input: EncryptStructuredRequest[TDict] = EncryptStructuredRequest(
             id=id, structured_data=structured_data, filter=filter, version=version, additional_data=additional_data
         )
         return self.request.post(