pangea-sdk 3.7.1__tar.gz → 3.8.0__tar.gz

{pangea_sdk-3.7.1 → pangea_sdk-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pangea-sdk
-Version: 3.7.1
+Version: 3.8.0
 Summary: Pangea API SDK
 Home-page: https://pangea.cloud/docs/sdk/python/
 License: MIT
@@ -18,13 +18,14 @@ Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Libraries
 Requires-Dist: aiohttp (>=3.8.6,<4.0.0)
 Requires-Dist: asyncio (>=3.4.3,<4.0.0)
-Requires-Dist: cryptography (>=42.0.5,<43.0.0)
+Requires-Dist: cryptography (>=42.0.7,<43.0.0)
 Requires-Dist: deprecated (>=1.2.14,<2.0.0)
 Requires-Dist: google-crc32c (>=1.5.0,<2.0.0)
-Requires-Dist: pydantic (>=1.10.14,<2.0.0)
+Requires-Dist: pydantic (>=1.10.15,<2.0.0)
 Requires-Dist: python-dateutil (>=2.9.0,<3.0.0)
 Requires-Dist: requests (>=2.31.0,<3.0.0)
 Requires-Dist: requests-toolbelt (>=1.0.0,<2.0.0)
+Requires-Dist: typing-extensions (>=4.7.1,<5.0.0)
 Project-URL: Repository, https://github.com/pangeacyber/pangea-python/tree/main/packages/pangea-sdk
 Description-Content-Type: text/markdown
 
@@ -44,6 +45,8 @@ above.
 
 ## Installation
 
+#### GA releases
+
 Via pip:
 
 ```bash
@@ -58,7 +61,7 @@ $ poetry add pangea-sdk
 
 <a name="beta-releases"></a>
 
-### Beta releases
+#### Beta releases
 
 Pre-release versions may be available with the `b` (beta) denotation in the
 version number. These releases serve to preview beta services and APIs. Per
@@ -68,19 +71,20 @@ compatibility guarantees as stable releases. [Beta changelog](https://github.com
 Via pip:
 
 ```bash
-$ pip3 install pangea-sdk==3.8.0b1
+$ pip3 install pangea-sdk==3.8.0b2
 ```
 
 Via poetry:
 
 ```bash
-$ poetry add pangea-sdk==3.8.0b1
+$ poetry add pangea-sdk==3.8.0b2
 ```
 
 ## Usage
 
 - [Documentation][]
-- [Examples][]
+- [GA Examples][]
+- [Beta Examples][]
 
 General usage would be to create a token for a service through the
 [Pangea Console][] and then construct an API client for that respective service.
@@ -224,7 +228,8 @@ It accepts multiple file formats:
 
 
    [Documentation]: https://pangea.cloud/docs/sdk/python/
-   [Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
+   [GA Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
+   [Beta Examples]: https://github.com/pangeacyber/pangea-python/tree/beta/examples
    [Pangea Console]: https://console.pangea.cloud/
    [Slack]: https://pangea.cloud/join-slack/
    [Secure Audit Log]: https://pangea.cloud/docs/audit

{pangea_sdk-3.7.1 → pangea_sdk-3.8.0}/README.md

@@ -14,6 +14,8 @@ above.
 
 ## Installation
 
+#### GA releases
+
 Via pip:
 
 ```bash
@@ -28,7 +30,7 @@ $ poetry add pangea-sdk
 
 <a name="beta-releases"></a>
 
-### Beta releases
+#### Beta releases
 
 Pre-release versions may be available with the `b` (beta) denotation in the
 version number. These releases serve to preview beta services and APIs. Per
@@ -38,19 +40,20 @@ compatibility guarantees as stable releases. [Beta changelog](https://github.com
 Via pip:
 
 ```bash
-$ pip3 install pangea-sdk==3.8.0b1
+$ pip3 install pangea-sdk==3.8.0b2
 ```
 
 Via poetry:
 
 ```bash
-$ poetry add pangea-sdk==3.8.0b1
+$ poetry add pangea-sdk==3.8.0b2
 ```
 
 ## Usage
 
 - [Documentation][]
-- [Examples][]
+- [GA Examples][]
+- [Beta Examples][]
 
 General usage would be to create a token for a service through the
 [Pangea Console][] and then construct an API client for that respective service.
@@ -194,7 +197,8 @@ It accepts multiple file formats:
 
 
    [Documentation]: https://pangea.cloud/docs/sdk/python/
-   [Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
+   [GA Examples]: https://github.com/pangeacyber/pangea-python/tree/main/examples
+   [Beta Examples]: https://github.com/pangeacyber/pangea-python/tree/beta/examples
    [Pangea Console]: https://console.pangea.cloud/
    [Slack]: https://pangea.cloud/join-slack/
    [Secure Audit Log]: https://pangea.cloud/docs/audit

{pangea_sdk-3.7.1 → pangea_sdk-3.8.0}/pangea/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "3.7.1"
+__version__ = "3.8.0"
 
 from pangea.asyncio.request import PangeaRequestAsync
 from pangea.config import PangeaConfig

{pangea_sdk-3.7.1 → pangea_sdk-3.8.0}/pangea/asyncio/request.py

@@ -8,12 +8,15 @@ from typing import Dict, List, Optional, Tuple, Type, Union
 
 import aiohttp
 from aiohttp import FormData
+from typing_extensions import TypeVar
 
 import pangea.exceptions as pe
 from pangea.request import MultipartResponse, PangeaRequestBase
 from pangea.response import AttachedFile, PangeaResponse, PangeaResponseResult, ResponseStatus, TransferMethod
 from pangea.utils import default_encoder
 
+TResult = TypeVar("TResult", bound=PangeaResponseResult, default=PangeaResponseResult)
+
 
 class PangeaRequestAsync(PangeaRequestBase):
     """An object that makes direct calls to Pangea Service APIs.
@@ -27,12 +30,12 @@ class PangeaRequestAsync(PangeaRequestBase):
     async def post(
         self,
         endpoint: str,
-        result_class: Type[PangeaResponseResult],
+        result_class: Type[TResult],
         data: Union[str, Dict] = {},
         files: List[Tuple] = [],
         poll_result: bool = True,
         url: Optional[str] = None,
-    ) -> PangeaResponse:
+    ) -> PangeaResponse[TResult]:
         """Makes the POST call to a Pangea Service endpoint.
 
         Args:
@@ -90,9 +93,7 @@ class PangeaRequestAsync(PangeaRequestBase):
 
         return self._check_response(pangea_response)
 
-    async def get(
-        self, path: str, result_class: Type[PangeaResponseResult], check_response: bool = True
-    ) -> PangeaResponse[Type[PangeaResponseResult]]:
+    async def get(self, path: str, result_class: Type[TResult], check_response: bool = True) -> PangeaResponse[TResult]:
         """Makes the GET call to a Pangea Service endpoint.
 
         Args:
@@ -109,7 +110,7 @@ class PangeaRequestAsync(PangeaRequestBase):
 
         async with self.session.get(url, headers=self._headers()) as requests_response:
             await self._check_http_errors(requests_response)
-            pangea_response = PangeaResponse(  # type: ignore[var-annotated]
+            pangea_response = PangeaResponse(
                 requests_response, result_class=result_class, json=await requests_response.json()
             )
 
@@ -130,11 +131,11 @@ class PangeaRequestAsync(PangeaRequestBase):
             raise pe.ServiceTemporarilyUnavailable(await resp.json())
 
     async def poll_result_by_id(
-        self, request_id: str, result_class: Union[Type[PangeaResponseResult], Type[dict]], check_response: bool = True
-    ):
+        self, request_id: str, result_class: Type[TResult], check_response: bool = True
+    ) -> PangeaResponse[TResult]:
         path = self._get_poll_path(request_id)
         self.logger.debug(json.dumps({"service": self.service, "action": "poll_result_once", "url": path}))
-        return await self.get(path, result_class, check_response=check_response)  # type: ignore[arg-type]
+        return await self.get(path, result_class, check_response=check_response)
 
     async def poll_result_once(self, response: PangeaResponse, check_response: bool = True):
         request_id = response.request_id
@@ -324,9 +325,7 @@ class PangeaRequestAsync(PangeaRequestBase):
         # Receive 202
         return await self._poll_presigned_url(accepted_exception.response)
 
-    async def _poll_presigned_url(
-        self, response: PangeaResponse[Type[PangeaResponseResult]]
-    ) -> PangeaResponse[Type[PangeaResponseResult]]:
+    async def _poll_presigned_url(self, response: PangeaResponse[TResult]) -> PangeaResponse[TResult]:
         if response.http_status != 202:
             raise AttributeError("Response should be 202")
 

{pangea_sdk-3.7.1 → pangea_sdk-3.8.0}/pangea/asyncio/services/__init__.py

@@ -1,5 +1,6 @@
 from .audit import AuditAsync
 from .authn import AuthNAsync
+from .authz import AuthZAsync
 from .embargo import EmbargoAsync
 from .file_scan import FileScanAsync
 from .intel import DomainIntelAsync, FileIntelAsync, IpIntelAsync, UrlIntelAsync, UserIntelAsync

{pangea_sdk-3.7.1 → pangea_sdk-3.8.0}/pangea/asyncio/services/audit.py

@@ -1,11 +1,14 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
+
 import datetime
 from typing import Any, Dict, List, Optional, Sequence, Union
 
 import pangea.exceptions as pexc
 from pangea.asyncio.services.base import ServiceBaseAsync
-from pangea.response import PangeaResponse
+from pangea.config import PangeaConfig
+from pangea.response import PangeaResponse, PangeaResponseResult
 from pangea.services.audit.audit import AuditBase
 from pangea.services.audit.exceptions import AuditException
 from pangea.services.audit.models import (
@@ -13,6 +16,7 @@ from pangea.services.audit.models import (
     DownloadRequest,
     DownloadResult,
     Event,
+    ExportRequest,
     LogBulkResult,
     LogResult,
     PublishedRoot,
@@ -56,14 +60,33 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
 
     def __init__(
         self,
-        token,
-        config=None,
+        token: str,
+        config: PangeaConfig | None = None,
         private_key_file: str = "",
-        public_key_info: Dict[str, str] = {},
-        tenant_id: Optional[str] = None,
-        logger_name="pangea",
-        config_id: Optional[str] = None,
-    ):
+        public_key_info: dict[str, str] = {},
+        tenant_id: str | None = None,
+        logger_name: str = "pangea",
+        config_id: str | None = None,
+    ) -> None:
+        """
+        Audit client
+
+        Initializes a new Audit client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            private_key_file: Private key filepath.
+            public_key_info: Public key information.
+            tenant_id: Tenant ID.
+            logger_name: Logger name.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="pangea_domain")
+             audit = AuditAsync(token="pangea_token", config=config)
+        """
+
         # FIXME: Temporary check to deprecate config_id from PangeaConfig.
         # Delete it when deprecate PangeaConfig.config_id
         if config_id and config is not None and config.config_id is not None:
@@ -402,6 +425,107 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
 
         return self.handle_results_response(response, verify_consistency, verify_events)
 
+    async def export(
+        self,
+        *,
+        format: DownloadFormat = DownloadFormat.CSV,
+        start: Optional[datetime.datetime] = None,
+        end: Optional[datetime.datetime] = None,
+        order: Optional[SearchOrder] = None,
+        order_by: Optional[str] = None,
+        verbose: bool = True,
+    ) -> PangeaResponse[PangeaResponseResult]:
+        """
+        Export from the audit log
+
+        Bulk export of data from the Secure Audit Log, with optional filtering.
+
+        OperationId: audit_post_v1_export
+
+        Args:
+            format: Format for the records.
+            start: The start of the time range to perform the search on.
+            end: The end of the time range to perform the search on. If omitted,
+                then all records up to the latest will be searched.
+            order: Specify the sort order of the response.
+            order_by: Name of column to sort the results by.
+            verbose: Whether or not to include the root hash of the tree and the
+                membership proof for each record.
+
+        Raises:
+            AuditException: If an audit based api exception happens
+            PangeaAPIException: If an API Error happens
+
+        Examples:
+            export_res = await audit.export(verbose=False)
+
+            # Export may take several dozens of minutes, so polling for the result
+            # should be done in a loop. That is omitted here for brevity's sake.
+            try:
+                await audit.poll_result(request_id=export_res.request_id)
+            except AcceptedRequestException:
+                # Retry later.
+
+            # Download the result when it's ready.
+            download_res = await audit.download_results(request_id=export_res.request_id)
+            download_res.result.dest_url
+            # => https://pangea-runtime.s3.amazonaws.com/audit/xxxxx/search_results_[...]
+        """
+        input = ExportRequest(
+            format=format,
+            start=start,
+            end=end,
+            order=order,
+            order_by=order_by,
+            verbose=verbose,
+        )
+        try:
+            return await self.request.post(
+                "v1/export", PangeaResponseResult, data=input.dict(exclude_none=True), poll_result=False
+            )
+        except pexc.AcceptedRequestException as e:
+            return e.response
+
+    async def log_stream(self, data: dict) -> PangeaResponse[PangeaResponseResult]:
+        """
+        Log streaming endpoint
+
+        This API allows 3rd party vendors (like Auth0) to stream events to this
+        endpoint where the structure of the payload varies across different
+        vendors.
+
+        OperationId: audit_post_v1_log_stream
+
+        Args:
+            data: Event data. The exact schema of this will vary by vendor.
+
+        Raises:
+            AuditException: If an audit based api exception happens
+            PangeaAPIException: If an API Error happens
+
+        Examples:
+            data = {
+                "logs": [
+                    {
+                        "log_id": "some log ID",
+                        "data": {
+                            "date": "2024-03-29T17:26:50.193Z",
+                            "type": "sapi",
+                            "description": "Create a log stream",
+                            "client_id": "some client ID",
+                            "ip": "127.0.0.1",
+                            "user_agent": "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/123.0.0.0",
+                            "user_id": "some user ID",
+                        },
+                    }
+                    # ...
+                ]
+            }
+
+            response = await audit.log_stream(data)
+        """
+        return await self.request.post("v1/log_stream", PangeaResponseResult, data=data)
+
     async def root(self, tree_size: Optional[int] = None) -> PangeaResponse[RootResult]:
         """
         Tamperproof verification
@@ -427,7 +551,10 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
         return await self.request.post("v1/root", RootResult, data=input.dict(exclude_none=True))
 
     async def download_results(
-        self, result_id: str, format: Optional[DownloadFormat] = None
+        self,
+        result_id: Optional[str] = None,
+        format: DownloadFormat = DownloadFormat.CSV,
+        request_id: Optional[str] = None,
     ) -> PangeaResponse[DownloadResult]:
         """
         Download search results
@@ -439,6 +566,7 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
         Args:
             result_id: ID returned by the search API.
             format: Format for the records.
+            request_id: ID returned by the export API.
 
         Returns:
             URL where search results can be downloaded.
@@ -454,7 +582,10 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
             )
         """
 
-        input = DownloadRequest(result_id=result_id, format=format)
+        if request_id is None and result_id is None:
+            raise ValueError("must pass one of `request_id` or `result_id`")
+
+        input = DownloadRequest(request_id=request_id, result_id=result_id, format=format)
         return await self.request.post("v1/download_results", DownloadResult, data=input.dict(exclude_none=True))
 
     async def update_published_roots(self, result: SearchResultOutput):

{pangea_sdk-3.7.1 → pangea_sdk-3.8.0}/pangea/asyncio/services/authn.py

@@ -1,10 +1,12 @@
 # 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
 
 SERVICE_NAME = "authn"
@@ -37,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)
@@ -53,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]:
@@ -148,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)
@@ -208,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]:
@@ -343,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(
@@ -384,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]:
@@ -421,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)
@@ -615,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(
@@ -687,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(
@@ -758,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(
@@ -838,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]:
@@ -978,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(