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

pangea/services/authn/models.py

@@ -1,10 +1,16 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
 
+from __future__ import annotations
+
 import enum
 from typing import Dict, List, NewType, Optional, Union
+from warnings import warn
+
+from typing_extensions import deprecated
 
 import pangea.services.intel as im
+from pangea.deprecated import pangea_deprecated
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponseResult
 from pangea.services.vault.models.common import JWK, JWKec, JWKrsa
 
@@ -12,9 +18,49 @@ Scopes = NewType("Scopes", List[str])
 
 
 class Profile(Dict[str, str]):
-    first_name: str
-    last_name: str
-    phone: Optional[str] = None
+    @property
+    def first_name(self) -> str:
+        warn(
+            '`Profile.first_name` is deprecated. Use `Profile["first_name"]` instead.', DeprecationWarning, stacklevel=2
+        )
+        return self["first_name"]
+
+    @first_name.setter
+    def first_name(self, value: str) -> None:
+        warn(
+            '`Profile.first_name` is deprecated. Use `Profile["first_name"]` instead.', DeprecationWarning, stacklevel=2
+        )
+        self["first_name"] = value
+
+    @property
+    def last_name(self) -> str:
+        warn('`Profile.last_name` is deprecated. Use `Profile["last_name"]` instead.', DeprecationWarning, stacklevel=2)
+        return self["last_name"]
+
+    @last_name.setter
+    def last_name(self, value: str) -> None:
+        warn('`Profile.last_name` is deprecated. Use `Profile["last_name"]` instead.', DeprecationWarning, stacklevel=2)
+        self["last_name"] = value
+
+    @property
+    def phone(self) -> str:
+        warn('`Profile.phone` is deprecated. Use `Profile["phone"]` instead.', DeprecationWarning, stacklevel=2)
+        return self["phone"]
+
+    @phone.setter
+    def phone(self, value: str) -> None:
+        warn('`Profile.phone` is deprecated. Use `Profile["phone"]` instead.', DeprecationWarning, stacklevel=2)
+        self["phone"] = value
+
+    @deprecated("`Profile.model_dump()` is deprecated. `Profile` is already a `dict[str, str]`.")
+    @pangea_deprecated(reason="`Profile` is already a `dict[str, str]`.")
+    def model_dump(self, *, exclude_none: bool = False) -> dict[str, str]:
+        warn(
+            "`Profile.model_dump()` is deprecated. `Profile` is already a `dict[str, str]`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self
 
 
 class ClientPasswordChangeRequest(APIRequestModel):
@@ -59,7 +105,7 @@ class SessionToken(PangeaResponseResult):
     identity: str
     email: str
     scopes: Optional[Scopes] = None
-    profile: Profile
+    profile: Union[Profile, Dict[str, str]]
     created_at: str
     intelligence: Optional[Intelligence] = None
 
@@ -69,7 +115,7 @@ class LoginToken(SessionToken):
 
 
 class ClientTokenCheckResult(SessionToken):
-    token: Optional[str]
+    token: Optional[str] = None
 
 
 class IDProvider(str, enum.Enum):
@@ -150,34 +196,93 @@ class UserListOrderBy(enum.Enum):
 
 
 class Authenticator(APIResponseModel):
+    """Authenticator."""
+
     id: str
+    """An ID for an authenticator."""
+
     type: str
+    """An authentication mechanism."""
+
     enabled: bool
+    """Enabled."""
+
     provider: Optional[str] = None
+    """Provider."""
+
+    provider_name: Optional[str] = None
+    """Provider name."""
+
     rpid: Optional[str] = None
+    """RPID."""
+
     phase: Optional[str] = None
+    """Phase."""
+
+    enrolling_browser: Optional[str] = None
+    """Enrolling browser."""
+
+    enrolling_ip: Optional[str] = None
+    """Enrolling IP."""
+
+    created_at: str
+    """A time in ISO-8601 format."""
+
+    updated_at: str
+    """A time in ISO-8601 format."""
+
+    state: Optional[str] = None
+    """State."""
 
 
 class User(PangeaResponseResult):
     id: str
+    """The identity of a user or a service."""
+
     email: str
-    profile: Profile
+    """An email address."""
+
+    username: str
+    """A username."""
+
+    profile: Union[Profile, Dict[str, str]]
+    """A user profile as a collection of string properties."""
+
     verified: bool
+    """True if the user's email has been verified."""
+
     disabled: bool
+    """True if the service administrator has disabled user account."""
+
     accepted_eula_id: Optional[str] = None
+    """An ID for an agreement."""
+
     accepted_privacy_policy_id: Optional[str] = None
+    """An ID for an agreement."""
+
     last_login_at: Optional[str] = None
+    """A time in ISO-8601 format."""
+
     created_at: str
+    """A time in ISO-8601 format."""
+
     login_count: int = 0
     last_login_ip: Optional[str] = None
     last_login_city: Optional[str] = None
     last_login_country: Optional[str] = None
     authenticators: List[Authenticator] = []
+    """A list of authenticators."""
 
 
 class UserCreateRequest(APIRequestModel):
     email: str
-    profile: Profile
+    """An email address."""
+
+    profile: Union[Profile, Dict[str, str]]
+    """A user profile as a collection of string properties."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserCreateResult(User):
@@ -186,7 +291,13 @@ class UserCreateResult(User):
 
 class UserDeleteRequest(APIRequestModel):
     email: Optional[str] = None
+    """An email address."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserDeleteResult(PangeaResponseResult):
@@ -289,7 +400,7 @@ class UserInviterOrderBy(enum.Enum):
 
 
 class UserInviteListFilter(APIRequestModel):
-    callback: Optional[str]
+    callback: Optional[str] = None
     callback__contains: Optional[List[str]] = None
     callback__in: Optional[List[str]] = None
     created_at: Optional[str] = None
@@ -343,7 +454,13 @@ class UserInviteDeleteResult(PangeaResponseResult):
 
 class UserProfileGetRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserProfileGetResult(User):
@@ -351,9 +468,17 @@ class UserProfileGetResult(User):
 
 
 class UserProfileUpdateRequest(APIRequestModel):
-    profile: Profile
+    profile: Union[Profile, Dict[str, str]]
+    """Updates to a user profile."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserProfileUpdateResult(User):
@@ -362,9 +487,25 @@ class UserProfileUpdateResult(User):
 
 class UserUpdateRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
     disabled: Optional[bool] = None
+    """
+    New disabled value. Disabling a user account will prevent them from logging
+    in.
+    """
+
     unlock: Optional[bool] = None
+    """
+    Unlock a user account if it has been locked out due to failed authentication
+    attempts.
+    """
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserUpdateResult(User):
@@ -386,8 +527,16 @@ class ClientJWKSResult(PangeaResponseResult):
 
 class UserAuthenticatorsDeleteRequest(APIRequestModel):
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
     email: Optional[str] = None
+    """An email address."""
+
     authenticator_id: str
+    """An ID for an authenticator."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserAuthenticatorsDeleteResult(PangeaResponseResult):
@@ -396,11 +545,18 @@ class UserAuthenticatorsDeleteResult(PangeaResponseResult):
 
 class UserAuthenticatorsListRequest(APIRequestModel):
     email: Optional[str] = None
+    """An email address."""
+
     id: Optional[str] = None
+    """The identity of a user or a service."""
+
+    username: Optional[str] = None
+    """A username."""
 
 
 class UserAuthenticatorsListResult(PangeaResponseResult):
     authenticators: List[Authenticator] = []
+    """A list of authenticators."""
 
 
 class FlowCompleteRequest(APIRequestModel):
@@ -499,7 +655,7 @@ class FlowUpdateDataPassword(APIRequestModel):
 
 
 class FlowUpdateDataProfile(APIRequestModel):
-    profile: Profile
+    profile: Union[Profile, Dict[str, str]]
 
 
 class FlowUpdateDataProvisionalEnrollment(APIRequestModel):
@@ -621,7 +777,7 @@ class SessionItem(APIResponseModel):
     expire: str
     email: str
     scopes: Optional[Scopes] = None
-    profile: Profile
+    profile: Union[Profile, Dict[str, str]]
     created_at: str
     active_token: Optional[SessionToken] = None
 

pangea/services/authz.py

@@ -1,9 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 import enum
 from typing import Any, Dict, List, Optional, Union
 
+from pangea.config import PangeaConfig
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
 from pangea.services.base import ServiceBase
 
@@ -113,7 +115,7 @@ class CheckRequest(APIRequestModel):
 class DebugPath(APIResponseModel):
     type: str
     id: str
-    action: Optional[str]
+    action: Optional[str] = None
 
 
 class Debug(APIResponseModel):
@@ -132,6 +134,7 @@ class ListResourcesRequest(APIRequestModel):
     type: str
     action: str
     subject: Subject
+    attributes: Optional[Dict[str, Any]] = None
 
 
 class ListResourcesResult(PangeaResponseResult):
@@ -141,6 +144,7 @@ class ListResourcesResult(PangeaResponseResult):
 class ListSubjectsRequest(APIRequestModel):
     resource: Resource
     action: str
+    attributes: Optional[Dict[str, Any]] = None
 
 
 class ListSubjectsResult(PangeaResponseResult):
@@ -148,12 +152,11 @@ class ListSubjectsResult(PangeaResponseResult):
 
 
 class AuthZ(ServiceBase):
-    """AuthZ service client. (Beta)
+    """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>. Note that this service is in Beta and
-    is subject to change.
+    <https://pangea.cloud/docs/api/authz>.
 
     Examples:
         import os
@@ -170,15 +173,32 @@ class AuthZ(ServiceBase):
 
     service_name = "authz"
 
-    def __init__(self, token: str, 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:
+        """
+        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 = AuthZ(token="pangea_token", config=config)
+        """
+
         super().__init__(token, config, logger_name, config_id=config_id)
 
     def tuple_create(self, tuples: List[Tuple]) -> PangeaResponse[TupleCreateResult]:
-        """Create tuples. (Beta)
+        """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.
-        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         Args:
             tuples (List[Tuple]): List of tuples to be created.
@@ -204,7 +224,7 @@ class AuthZ(ServiceBase):
         """
 
         input_data = TupleCreateRequest(tuples=tuples)
-        return self.request.post("v1/tuple/create", TupleCreateResult, data=input_data.dict(exclude_none=True))
+        return self.request.post("v1/tuple/create", TupleCreateResult, data=input_data.model_dump(exclude_none=True))
 
     def tuple_list(
         self,
@@ -214,12 +234,11 @@ class AuthZ(ServiceBase):
         order: Optional[ItemOrder] = None,
         order_by: Optional[TupleOrderBy] = None,
     ) -> PangeaResponse[TupleListResult]:
-        """List tuples. (Beta)
+        """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.
-        How to install a [Beta release](https://pangea.cloud/docs/sdk/python/#beta-releases).
 
         Args:
             filter (TupleListFilter): The filter for listing tuples.
@@ -240,15 +259,14 @@ class AuthZ(ServiceBase):
             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
+            filter=filter.model_dump(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))
+        return self.request.post("v1/tuple/list", TupleListResult, data=input_data.model_dump(exclude_none=True))
 
     def tuple_delete(self, tuples: List[Tuple]) -> PangeaResponse[TupleDeleteResult]:
-        """Delete tuples. (Beta)
+        """Delete tuples.
 
         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.
@@ -274,7 +292,7 @@ class AuthZ(ServiceBase):
         """
 
         input_data = TupleDeleteRequest(tuples=tuples)
-        return self.request.post("v1/tuple/delete", TupleDeleteResult, data=input_data.dict(exclude_none=True))
+        return self.request.post("v1/tuple/delete", TupleDeleteResult, data=input_data.model_dump(exclude_none=True))
 
     def check(
         self,
@@ -282,19 +300,18 @@ class AuthZ(ServiceBase):
         action: str,
         subject: Subject,
         debug: Optional[bool] = None,
-        attributes: Optional[Dict[str, Union[int, str]]] = None,
+        attributes: Optional[Dict[str, Any]] = None,
     ) -> PangeaResponse[CheckResult]:
-        """Perform a check request. (Beta)
+        """Perform a check request.
 
         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.
+            attributes (Optional[Dict[str, Any]]): Additional attributes for the check.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -314,19 +331,21 @@ class AuthZ(ServiceBase):
         """
 
         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))
+        return self.request.post("v1/check", CheckResult, data=input_data.model_dump(exclude_none=True))
 
-    def list_resources(self, type: str, action: str, subject: Subject) -> PangeaResponse[ListResourcesResult]:
-        """List resources. (Beta)
+    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.
-        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.
+            attributes (Optional[Dict[str, Any]]): A JSON object of attribute data.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -344,19 +363,23 @@ class AuthZ(ServiceBase):
             )
         """
 
-        input_data = ListResourcesRequest(type=type, action=action, subject=subject)
-        return self.request.post("v1/list-resources", ListResourcesResult, data=input_data.dict(exclude_none=True))
+        input_data = ListResourcesRequest(type=type, action=action, subject=subject, attributes=attributes)
+        return self.request.post(
+            "v1/list-resources", ListResourcesResult, data=input_data.model_dump(exclude_none=True)
+        )
 
-    def list_subjects(self, resource: Resource, action: str) -> PangeaResponse[ListSubjectsResult]:
-        """List subjects. (Beta)
+    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.
-        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.
+            attributes (Optional[Dict[str, Any]]): A JSON object of attribute data.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -373,5 +396,5 @@ class AuthZ(ServiceBase):
             )
         """
 
-        input_data = ListSubjectsRequest(resource=resource, action=action)
-        return self.request.post("v1/list-subjects", ListSubjectsResult, data=input_data.dict(exclude_none=True))
+        input_data = ListSubjectsRequest(resource=resource, action=action, attributes=attributes)
+        return self.request.post("v1/list-subjects", ListSubjectsResult, data=input_data.model_dump(exclude_none=True))

pangea/services/base.py

@@ -80,7 +80,8 @@ class ServiceBase(object):
         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
@@ -100,5 +101,18 @@ class ServiceBase(object):
         else:
             raise AttributeError("Need to set exception, response or request_id")
 
-    def download_file(self, url: str, filename: Optional[str] = None) -> AttachedFile:
+    def download_file(self, url: str, filename: str | None = None) -> AttachedFile:
+        """
+        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 self.request.download_file(url=url, filename=filename)

pangea/services/embargo.py

@@ -103,7 +103,7 @@ class Embargo(ServiceBase):
             response = embargo.ip_check("190.6.64.94")
         """
         input = IPCheckRequest(ip=ip)
-        return self.request.post("v1/ip/check", EmbargoResult, data=input.dict())
+        return self.request.post("v1/ip/check", EmbargoResult, data=input.model_dump())
 
     def iso_check(self, iso_code: str) -> PangeaResponse[EmbargoResult]:
         """
@@ -130,4 +130,4 @@ class Embargo(ServiceBase):
             response = embargo.iso_check("CU")
         """
         input = ISOCheckRequest(iso_code=iso_code)
-        return self.request.post("v1/iso/check", result_class=EmbargoResult, data=input.dict())
+        return self.request.post("v1/iso/check", result_class=EmbargoResult, data=input.model_dump())

pangea/services/file_scan.py

@@ -11,22 +11,25 @@ from pangea.utils import FileUploadParams, get_file_upload_params
 
 
 class FileScanRequest(APIRequestModel):
-    """
-    File Scan request data
-
-    provider (str, optional): Provider of the information. Default provider defined by the configuration.
-    verbose (bool, optional): Echo back the parameters of the API in the response
-    raw (bool, optional): Return additional details from the provider.
-    """
+    """File Scan request data."""
 
     verbose: Optional[bool] = None
+    """Echo back the parameters of the API in the response."""
+
     raw: Optional[bool] = None
+    """Return additional details from the provider."""
+
     provider: Optional[str] = None
+    """Provider of the information. Default provider defined by the configuration."""
+
     size: Optional[int] = None
     crc32c: Optional[str] = None
     sha256: Optional[str] = None
     source_url: Optional[str] = None
+    """A URL where the file to be scanned can be downloaded."""
+
     transfer_method: TransferMethod = TransferMethod.POST_URL
+    """The transfer method used to upload the file data."""
 
 
 class FileScanData(PangeaResponseResult):
@@ -71,7 +74,6 @@ class FileScan(ServiceBase):
     """
 
     service_name = "file-scan"
-    version = "v1"
 
     def file_scan(
         self,
@@ -92,12 +94,14 @@ class FileScan(ServiceBase):
         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
@@ -118,6 +122,15 @@ class FileScan(ServiceBase):
                     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")
@@ -128,9 +141,9 @@ class FileScan(ServiceBase):
                 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 = FileScanRequest(
             verbose=verbose,
@@ -142,8 +155,12 @@ class FileScan(ServiceBase):
             transfer_method=transfer_method,
             source_url=source_url,
         )
-        data = input.dict(exclude_none=True)
-        return self.request.post("v1/scan", FileScanResult, data=data, files=files, poll_result=sync_call)
+        data = input.model_dump(exclude_none=True)
+        try:
+            return self.request.post("v1/scan", FileScanResult, data=data, files=files, poll_result=sync_call)
+        finally:
+            if file_path and file:
+                file.close()
 
     def request_upload_url(
         self,
@@ -164,7 +181,7 @@ class FileScan(ServiceBase):
             input.sha256 = params.sha256_hex
             input.size = params.size
 
-        data = input.dict(exclude_none=True)
+        data = input.model_dump(exclude_none=True)
         return self.request.request_presigned_url("v1/scan", FileScanResult, data=data)