pangea-sdk 6.2.0b1__py3-none-any.whl → 6.3.0__py3-none-any.whl

pangea/services/authz.py

@@ -1,12 +1,16 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
 from __future__ import annotations
 
 import enum
-from typing import Any, Dict, List, Optional, Union
+from collections.abc import Mapping, Sequence
+from typing import Annotated, Any, Optional, Union
+
+from pydantic import Field
 
 from pangea.config import PangeaConfig
-from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
+from pangea.response import APIRequestModel, APIResponseModel, PangeaDateTime, PangeaResponse, PangeaResponseResult
 from pangea.services.base import ServiceBase
 
 
@@ -43,20 +47,18 @@ class Resource(PangeaResponseResult):
 
 class Subject(PangeaResponseResult):
     type: str
-    id: Optional[str] = None
-    action: Optional[str] = None
+    id: Annotated[str, Field(pattern="^([a-zA-Z0-9_][a-zA-Z0-9/|_.@-]*)$")]
+    action: Annotated[Optional[str], Field(pattern="^([a-zA-Z0-9_][a-zA-Z0-9/|_]*)$")] = None
 
 
 class Tuple(PangeaResponseResult):
     resource: Resource
-    relation: str
+    relation: Annotated[str, Field(pattern="^([a-zA-Z0-9_][a-zA-Z0-9/|_]*)$")]
     subject: Subject
-    expires_at: Optional[str] = None
+    expires_at: Optional[PangeaDateTime] = None
     """A time in ISO-8601 format"""
-
-
-class TupleCreateRequest(APIRequestModel):
-    tuples: List[Tuple]
+    attributes: Optional[dict[str, Any]] = None
+    """A JSON object of attribute data."""
 
 
 class TupleCreateResult(PangeaResponseResult):
@@ -66,54 +68,54 @@ class TupleCreateResult(PangeaResponseResult):
 class TupleListFilter(APIRequestModel):
     resource_type: Optional[str] = None
     """Only records where resource type equals this value."""
-    resource_type__contains: Optional[List[str]] = None
+    resource_type__contains: Optional[list[str]] = None
     """Only records where resource type includes each substring."""
-    resource_type__in: Optional[List[str]] = None
+    resource_type__in: Optional[list[str]] = None
     """Only records where resource type equals one of the provided substrings."""
     resource_id: Optional[str] = None
     """Only records where resource id equals this value."""
-    resource_id__contains: Optional[List[str]] = None
+    resource_id__contains: Optional[list[str]] = None
     """Only records where resource id includes each substring."""
-    resource_id__in: Optional[List[str]] = None
+    resource_id__in: Optional[list[str]] = None
     """Only records where resource id equals one of the provided substrings."""
     relation: Optional[str] = None
     """Only records where relation equals this value."""
-    relation__contains: Optional[List[str]] = None
+    relation__contains: Optional[list[str]] = None
     """Only records where relation includes each substring."""
-    relation__in: Optional[List[str]] = None
+    relation__in: Optional[list[str]] = None
     """Only records where relation equals one of the provided substrings."""
     subject_type: Optional[str] = None
     """Only records where subject type equals this value."""
-    subject_type__contains: Optional[List[str]] = None
+    subject_type__contains: Optional[list[str]] = None
     """Only records where subject type includes each substring."""
-    subject_type__in: Optional[List[str]] = None
+    subject_type__in: Optional[list[str]] = None
     """Only records where subject type equals one of the provided substrings."""
     subject_id: Optional[str] = None
     """Only records where subject id equals this value."""
-    subject_id__contains: Optional[List[str]] = None
+    subject_id__contains: Optional[list[str]] = None
     """Only records where subject id includes each substring."""
-    subject_id__in: Optional[List[str]] = None
+    subject_id__in: Optional[list[str]] = None
     """Only records where subject id equals one of the provided substrings."""
     subject_action: Optional[str] = None
     """Only records where subject action equals this value."""
-    subject_action__contains: Optional[List[str]] = None
+    subject_action__contains: Optional[list[str]] = None
     """Only records where subject action includes each substring."""
-    subject_action__in: Optional[List[str]] = None
+    subject_action__in: Optional[list[str]] = None
     """Only records where subject action equals one of the provided substrings."""
-    expires_at: Optional[str] = None
+    expires_at: Optional[PangeaDateTime] = None
     """Only records where expires_at equals this value."""
-    expires_at__gt: Optional[str] = None
+    expires_at__gt: Optional[PangeaDateTime] = None
     """Only records where expires_at is greater than this value."""
-    expires_at__gte: Optional[str] = None
+    expires_at__gte: Optional[PangeaDateTime] = None
     """Only records where expires_at is greater than or equal to this value."""
-    expires_at__lt: Optional[str] = None
+    expires_at__lt: Optional[PangeaDateTime] = None
     """Only records where expires_at is less than this value."""
-    expires_at__lte: Optional[str] = None
+    expires_at__lte: Optional[PangeaDateTime] = None
     """Only records where expires_at is less than or equal to this value."""
 
 
 class TupleListRequest(APIRequestModel):
-    filter: Optional[Union[Dict, TupleListFilter]] = None
+    filter: Optional[Union[dict, TupleListFilter]] = None
     size: Optional[int] = None
     last: Optional[str] = None
     order: Optional[ItemOrder] = None
@@ -121,37 +123,27 @@ class TupleListRequest(APIRequestModel):
 
 
 class TupleListResult(PangeaResponseResult):
-    tuples: List[Tuple]
+    tuples: list[Tuple]
     last: str
     count: int
 
 
 class TupleDeleteRequest(APIRequestModel):
-    tuples: List[Tuple]
+    tuples: list[Tuple]
 
 
 class TupleDeleteResult(PangeaResponseResult):
     pass
 
 
-class CheckRequest(APIRequestModel):
-    resource: Resource
-    action: str
-    subject: Subject
-    debug: Optional[bool] = None
-    """In the event of an allowed check, return a path that granted access."""
-    attributes: Optional[Dict[str, Any]] = None
-    """A JSON object of attribute data."""
-
-
 class DebugPath(APIResponseModel):
-    type: str
-    id: str
+    type: Optional[str] = None
+    id: Optional[str] = None
     action: Optional[str] = None
 
 
 class Debug(APIResponseModel):
-    path: List[DebugPath]
+    path: list[DebugPath]
 
 
 class CheckResult(PangeaResponseResult):
@@ -162,27 +154,47 @@ class CheckResult(PangeaResponseResult):
     debug: Optional[Debug] = None
 
 
+class BulkCheckRequestItem(APIRequestModel):
+    resource: Resource
+    action: Annotated[str, Field(pattern="^([a-zA-Z0-9_][a-zA-Z0-9/|_]*)$")]
+    subject: Subject
+
+
+class BulkCheckItemResult(APIResponseModel):
+    checked: str
+    allowed: bool
+    depth: int
+    debug: Optional[Debug] = None
+
+
+class BulkCheckResult(PangeaResponseResult):
+    schema_id: str
+    schema_version: int
+    allowed: bool
+    results: list[BulkCheckItemResult]
+
+
 class ListResourcesRequest(APIRequestModel):
     type: str
     action: str
     subject: Subject
-    attributes: Optional[Dict[str, Any]] = None
+    attributes: Optional[dict[str, Any]] = None
 
 
 class ListResourcesResult(PangeaResponseResult):
-    ids: List[str]
+    ids: list[str]
 
 
 class ListSubjectsRequest(APIRequestModel):
     resource: Resource
     action: str
-    attributes: Optional[Dict[str, Any]] = None
+    attributes: Optional[dict[str, Any]] = None
     debug: Optional[bool] = None
     """Return a path for each found subject"""
 
 
 class ListSubjectsResult(PangeaResponseResult):
-    subjects: List[Subject]
+    subjects: list[Subject]
 
 
 class AuthZ(ServiceBase):
@@ -228,7 +240,7 @@ class AuthZ(ServiceBase):
 
         super().__init__(token, config, logger_name, config_id=config_id)
 
-    def tuple_create(self, tuples: list[Tuple]) -> PangeaResponse[TupleCreateResult]:
+    def tuple_create(self, tuples: Sequence[Tuple]) -> PangeaResponse[TupleCreateResult]:
         """Create tuples.
 
         Create tuples in the AuthZ Service. The request will fail if there is no schema
@@ -243,7 +255,7 @@ class AuthZ(ServiceBase):
         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).
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/tuple/create-post).
 
         Examples:
             response = authz.tuple_create(
@@ -257,8 +269,7 @@ class AuthZ(ServiceBase):
             )
         """
 
-        input_data = TupleCreateRequest(tuples=tuples)
-        return self.request.post("v1/tuple/create", TupleCreateResult, data=input_data.model_dump(exclude_none=True))
+        return self.request.post("v1/tuple/create", TupleCreateResult, data={"tuples": tuples})
 
     def tuple_list(
         self,
@@ -287,7 +298,7 @@ class AuthZ(ServiceBase):
         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).
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/tuple/list-post).
 
         Examples:
             authz.tuple_list(TupleListFilter(subject_type="user", subject_id="user_1"))
@@ -311,7 +322,7 @@ class AuthZ(ServiceBase):
         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).
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/tuple/delete-post).
 
         Examples:
             response = authz.tuple_delete(
@@ -333,8 +344,9 @@ class AuthZ(ServiceBase):
         resource: Resource,
         action: str,
         subject: Subject,
+        *,
         debug: bool | None = None,
-        attributes: dict[str, Any] | None = None,
+        attributes: Mapping[str, Any] | None = None,
     ) -> PangeaResponse[CheckResult]:
         """Perform a check request.
 
@@ -345,7 +357,7 @@ class AuthZ(ServiceBase):
             action: The action to check.
             subject: The subject to check.
             debug: In the event of an allowed check, return a path that granted access.
-            attributes: Additional attributes for the check.
+            attributes: A JSON object of attribute data.
 
         Raises:
             PangeaAPIException: If an API Error happens.
@@ -353,7 +365,7 @@ class AuthZ(ServiceBase):
         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).
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/check-post).
 
         Examples:
             response = authz.check(
@@ -364,8 +376,44 @@ 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.model_dump(exclude_none=True))
+        return self.request.post(
+            "v1/check",
+            CheckResult,
+            data={"resource": resource, "action": action, "subject": subject, "debug": debug, "attributes": attributes},
+        )
+
+    def bulk_check(
+        self,
+        checks: Sequence[BulkCheckRequestItem],
+        *,
+        debug: bool | None = None,
+        attributes: Mapping[str, Any] | None = None,
+    ) -> PangeaResponse[BulkCheckResult]:
+        """Perform a bulk check request
+
+        Perform multiple checks in a single request to see if a subjects have
+        permission to do actions on the resources.
+
+        Args:
+            checks: Check requests to perform.
+            debug: In the event of an allowed check, return a path that granted access.
+            attributes: A JSON object of attribute data.
+
+        Examples:
+            authz.bulk_check(
+                checks=[
+                    BulkCheckRequestItem(
+                        resource=Resource(type="file", id="file_1"),
+                        action="read",
+                        subject=Subject(type="user", id="user_1", action="read"),
+                    )
+                ]
+            )
+        """
+
+        return self.request.post(
+            "v1/check/bulk", BulkCheckResult, data={"checks": checks, "debug": debug, "attributes": attributes}
+        )
 
     def list_resources(
         self, type: str, action: str, subject: Subject, attributes: dict[str, Any] | None = None
@@ -387,7 +435,7 @@ class AuthZ(ServiceBase):
         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).
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/list-resources-post).
 
         Examples:
             authz.list_resources(
@@ -422,7 +470,7 @@ class AuthZ(ServiceBase):
         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).
+            [API Documentation](https://pangea.cloud/docs/api/authz#/v1/list-subjects-post).
 
         Examples:
             response = authz.list_subjects(

pangea/services/base.py

@@ -1,10 +1,14 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
 import copy
 import logging
-from typing import Dict, Optional, Type, Union
+from typing import Optional, Type, Union
 
 from typing_extensions import TypeVar
 
@@ -17,7 +21,7 @@ from pangea.response import AttachedFile, PangeaResponse, PangeaResponseResult
 TResult = TypeVar("TResult", bound=PangeaResponseResult, default=PangeaResponseResult)
 
 
-class ServiceBase(object):
+class ServiceBase:
     service_name: str = "base"
 
     def __init__(
@@ -43,8 +47,7 @@ class ServiceBase(object):
         self._token = token
         self.config_id: Optional[str] = config_id
         self._request: Optional[Union[PangeaRequest, PangeaRequestAsync]] = None
-        extra_headers: Dict = {}
-        self.request.set_extra_headers(extra_headers)
+        self.request.set_extra_headers({})
 
     @property
     def token(self) -> str:

pangea/services/embargo.py

@@ -1,5 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Use `list` instead of `List`.
+# ruff: noqa: UP006, UP035
+
+from __future__ import annotations
+
 from typing import Any, Dict, List
 
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult

pangea/services/file_scan.py

@@ -1,5 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Use `list` instead of `List`.
+# ruff: noqa: UP006, UP035
+
+from __future__ import annotations
+
 import io
 import logging
 from typing import Dict, List, Optional, Tuple
@@ -52,7 +58,7 @@ class FileScan(ServiceBase):
     """FileScan service client.
 
     Provides methods to interact with Pangea FileScan Service:
-        https://pangea.cloud/docs/api/embargo
+        https://pangea.cloud/docs/api/file-scan
 
     The following information is needed:
         PANGEA_TOKEN - service token which can be found on the Pangea User
@@ -133,7 +139,7 @@ class FileScan(ServiceBase):
         files: Optional[List[Tuple]] = None
         if file or file_path:
             if file_path:
-                file = open(file_path, "rb")
+                file = open(file_path, "rb")  # noqa: SIM115
             if transfer_method == TransferMethod.POST_URL:
                 params = get_file_upload_params(file)  # type: ignore[arg-type]
                 crc = params.crc_hex

pangea/services/intel.py

@@ -1,10 +1,14 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Use `list` instead of `List`.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
 import enum
 import hashlib
-from typing import Dict, List, Optional
+from typing import Dict, List, Literal, Optional
 
 from pangea.exceptions import PangeaException
 from pangea.response import APIRequestModel, PangeaResponse, PangeaResponseResult
@@ -61,8 +65,20 @@ class FileReputationBulkRequest(APIRequestModel):
     hash_type (str): Type of hash, can be "sha256", "sha" or "md5"
     """
 
-    hashes: List[str]
-    hash_type: str
+    hashes: list[str]
+    """The hash of the file to be looked up"""
+
+    hash_type: Literal["sha256", "sha", "md5"]
+    """One of "sha256", "sha", "md5"."""
+
+    verbose: Optional[bool] = None
+    """Echo the API parameters in the response"""
+
+    raw: Optional[bool] = None
+    """Include raw data from this provider"""
+
+    provider: Optional[Literal["reversinglabs", "crowdstrike"]] = None
+    """Use reputation data from this provider"""
 
 
 class FileReputationData(IntelReputationData):
@@ -356,7 +372,8 @@ class DomainWhoIsRequest(DomainCommonRequest):
     Domain whois request data
     """
 
-    pass
+    domain: str
+    """The domain to query."""
 
 
 class DomainWhoIsData(PangeaResponseResult):
@@ -530,11 +547,11 @@ class FileIntel(ServiceBase):
 
     def hash_reputation_bulk(
         self,
-        hashes: List[str],
-        hash_type: str,
-        provider: Optional[str] = None,
-        verbose: Optional[bool] = None,
-        raw: Optional[bool] = None,
+        hashes: list[str],
+        hash_type: Literal["sha256", "sha", "md5"],
+        provider: Literal["reversinglabs", "crowdstrike"] | None = None,
+        verbose: bool | None = None,
+        raw: bool | None = None,
     ) -> PangeaResponse[FileReputationBulkResult]:
         """
         Reputation check V2
@@ -562,7 +579,7 @@ class FileIntel(ServiceBase):
                 provider="reversinglabs",
             )
         """
-        input = FileReputationBulkRequest(  # type: ignore[call-arg]
+        input = FileReputationBulkRequest(
             hashes=hashes, hash_type=hash_type, verbose=verbose, raw=raw, provider=provider
         )
         return self.request.post("v2/reputation", FileReputationBulkResult, data=input.model_dump(exclude_none=True))
@@ -610,10 +627,10 @@ class FileIntel(ServiceBase):
 
     def filepath_reputation_bulk(
         self,
-        filepaths: List[str],
-        provider: Optional[str] = None,
-        verbose: Optional[bool] = None,
-        raw: Optional[bool] = None,
+        filepaths: list[str],
+        provider: Literal["reversinglabs", "crowdstrike"] | None = None,
+        verbose: bool | None = None,
+        raw: bool | None = None,
     ) -> PangeaResponse[FileReputationBulkResult]:
         """
         Reputation, from filepath V2
@@ -624,10 +641,10 @@ class FileIntel(ServiceBase):
         OperationId: file_intel_post_v2_reputation
 
         Args:
-            filepaths (List[str]): The path list to the files to be looked up
-            provider (str, optional): Use reputation data from these providers: "reversinglabs" or "crowdstrike"
-            verbose (bool, optional): Echo the API parameters in the response
-            raw (bool, optional): Include raw data from this provider
+            filepaths: The path list to the files to be looked up
+            provider: Use reputation data from these providers: "reversinglabs" or "crowdstrike"
+            verbose: Echo the API parameters in the response
+            raw: Include raw data from this provider
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -777,7 +794,7 @@ class DomainIntel(ServiceBase):
                 provider="whoisxml",
             )
         """
-        input = DomainWhoIsRequest(domain=domain, verbose=verbose, provider=provider, raw=raw)  # type: ignore[call-arg]
+        input = DomainWhoIsRequest(domain=domain, verbose=verbose, provider=provider, raw=raw)
         return self.request.post("v1/whois", DomainWhoIsResult, data=input.model_dump(exclude_none=True))