pangea-sdk 3.8.0b4__py3-none-any.whl → 3.9.0__py3-none-any.whl

pangea/services/audit/audit.py

@@ -1,11 +1,14 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
+
 import datetime
 import json
-from typing import Any, Dict, List, Optional, Set, Tuple, Union
+from typing import Any, Dict, List, Optional, Sequence, Set, Tuple, Union
 
 import pangea.exceptions as pexc
-from pangea.response import PangeaResponse
+from pangea.config import PangeaConfig
+from pangea.response import PangeaResponse, PangeaResponseResult
 from pangea.services.audit.exceptions import AuditException, EventCorruption
 from pangea.services.audit.models import (
     DownloadFormat,
@@ -14,6 +17,7 @@ from pangea.services.audit.models import (
     Event,
     EventEnvelope,
     EventVerification,
+    ExportRequest,
     LogBulkRequest,
     LogBulkResult,
     LogEvent,
@@ -51,8 +55,8 @@ from pangea.utils import canonicalize_nested_json
 
 class AuditBase:
     def __init__(
-        self, private_key_file: str = "", public_key_info: Dict[str, str] = {}, tenant_id: Optional[str] = None
-    ):
+        self, private_key_file: str = "", public_key_info: dict[str, str] = {}, tenant_id: str | None = None
+    ) -> None:
         self.pub_roots: Dict[int, PublishedRoot] = {}
         self.buffer_data: Optional[str] = None
         self.signer: Optional[Signer] = Signer(private_key_file) if private_key_file else None
@@ -332,7 +336,9 @@ class AuditBase:
         if audit_envelope and audit_envelope.signature and public_key:
             v = Verifier()
             verification = v.verify_signature(
-                audit_envelope.signature, canonicalize_event(audit_envelope.event), public_key  # type: ignore[arg-type]
+                audit_envelope.signature,
+                canonicalize_event(Event(**audit_envelope.event)),
+                public_key,
             )
             if verification is not None:
                 return EventVerification.PASS if verification else EventVerification.FAIL
@@ -374,14 +380,32 @@ class Audit(ServiceBase, 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 = Audit(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:
@@ -598,10 +622,11 @@ class Audit(ServiceBase, AuditBase):
         end: Optional[Union[datetime.datetime, str]] = None,
         limit: Optional[int] = None,
         max_results: Optional[int] = None,
-        search_restriction: Optional[dict] = None,
+        search_restriction: Optional[Dict[str, Sequence[str]]] = None,
         verbose: Optional[bool] = None,
         verify_consistency: bool = False,
         verify_events: bool = True,
+        return_context: Optional[bool] = None,
     ) -> PangeaResponse[SearchOutput]:
         """
         Search the log
@@ -627,10 +652,11 @@ class Audit(ServiceBase, AuditBase):
             end (datetime, optional): An RFC-3339 formatted timestamp, or relative time adjustment from the current time.
             limit (int, optional): Optional[int] = None,
             max_results (int, optional): Maximum number of results to return.
-            search_restriction (dict, optional): A list of keys to restrict the search results to. Useful for partitioning data available to the query string.
+            search_restriction (Dict[str, Sequence[str]], optional): A list of keys to restrict the search results to. Useful for partitioning data available to the query string.
             verbose (bool, optional): If true, response include root and membership and consistency proofs.
             verify_consistency (bool): True to verify logs consistency
             verify_events (bool): True to verify hash events and signatures
+            return_context (bool): Return the context data needed to decrypt secure audit events that have been redacted with format preserving encryption.
 
         Raises:
             AuditException: If an audit based api exception happens
@@ -664,6 +690,7 @@ class Audit(ServiceBase, AuditBase):
             max_results=max_results,
             search_restriction=search_restriction,
             verbose=verbose,
+            return_context=return_context,
         )
 
         response: PangeaResponse[SearchOutput] = self.request.post(
@@ -678,8 +705,10 @@ class Audit(ServiceBase, AuditBase):
         id: str,
         limit: Optional[int] = 20,
         offset: Optional[int] = 0,
+        assert_search_restriction: Optional[Dict[str, Sequence[str]]] = None,
         verify_consistency: bool = False,
         verify_events: bool = True,
+        return_context: Optional[bool] = None,
     ) -> PangeaResponse[SearchResultOutput]:
         """
         Results of a search
@@ -692,8 +721,10 @@ class Audit(ServiceBase, AuditBase):
             id (string): the id of a search action, found in `response.result.id`
             limit (integer, optional): the maximum number of results to return, default is 20
             offset (integer, optional): the position of the first result to return, default is 0
+            assert_search_restriction (Dict[str, Sequence[str]], optional): Assert the requested search results were queried with the exact same search restrictions, to ensure the results comply to the expected restrictions.
             verify_consistency (bool): True to verify logs consistency
             verify_events (bool): True to verify hash events and signatures
+            return_context (bool): Return the context data needed to decrypt secure audit events that have been redacted with format preserving encryption.
         Raises:
             AuditException: If an audit based api exception happens
             PangeaAPIException: If an API Error happens
@@ -716,6 +747,8 @@ class Audit(ServiceBase, AuditBase):
             id=id,
             limit=limit,
             offset=offset,
+            assert_search_restriction=assert_search_restriction,
+            return_context=return_context,
         )
         response: PangeaResponse[SearchResultOutput] = self.request.post(
             "v1/results", SearchResultOutput, data=input.dict(exclude_none=True)
@@ -724,6 +757,107 @@ class Audit(ServiceBase, AuditBase):
             self.update_published_roots(response.result)
         return self.handle_results_response(response, verify_consistency, verify_events)
 
+    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 = 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:
+                audit.poll_result(request_id=export_res.request_id)
+            except AcceptedRequestException:
+                # Retry later.
+
+            # Download the result when it's ready.
+            download_res = 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 self.request.post(
+                "v1/export", PangeaResponseResult, data=input.dict(exclude_none=True), poll_result=False
+            )
+        except pexc.AcceptedRequestException as e:
+            return e.response
+
+    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 = audit.log_stream(data)
+        """
+        return self.request.post("v1/log_stream", PangeaResponseResult, data=data)
+
     def root(self, tree_size: Optional[int] = None) -> PangeaResponse[RootResult]:
         """
         Tamperproof verification
@@ -749,7 +883,11 @@ class Audit(ServiceBase, AuditBase):
         return self.request.post("v1/root", RootResult, data=input.dict(exclude_none=True))
 
     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,
+        return_context: Optional[bool] = None,
     ) -> PangeaResponse[DownloadResult]:
         """
         Download search results
@@ -761,6 +899,8 @@ class Audit(ServiceBase, AuditBase):
         Args:
             result_id: ID returned by the search API.
             format: Format for the records.
+            request_id: ID returned by the export API.
+            return_context (bool): Return the context data needed to decrypt secure audit events that have been redacted with format preserving encryption.
 
         Returns:
             URL where search results can be downloaded.
@@ -776,7 +916,12 @@ class Audit(ServiceBase, 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_context=return_context
+        )
         return self.request.post("v1/download_results", DownloadResult, data=input.dict(exclude_none=True))
 
     def update_published_roots(self, result: SearchResultOutput):

pangea/services/audit/models.py

@@ -1,8 +1,10 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
+
 import datetime
 import enum
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional, Sequence, Union
 
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponseResult
 
@@ -19,14 +21,14 @@ class EventVerification(str, enum.Enum):
         return str(self.value)
 
 
-class Event(dict):
+class Event(Dict[str, Any]):
     """
     Event to perform an auditable activity
 
     Auxiliary class to be compatible with older SDKs
     """
 
-    def __init__(self, **data):
+    def __init__(self, **data) -> None:
         super().__init__(**data)
 
     @property
@@ -269,6 +271,7 @@ class SearchRequest(APIRequestModel):
     max_results -- Maximum number of results to return.
     search_restriction -- A list of keys to restrict the search results to. Useful for partitioning data available to the query string.
     verbose -- If true, include root, membership and consistency proofs in response.
+    return_context -- Return the context data needed to decrypt secure audit events that have been redacted with format preserving encryption.
     """
 
     query: str
@@ -279,8 +282,9 @@ class SearchRequest(APIRequestModel):
     end: Optional[str] = None
     limit: Optional[int] = None
     max_results: Optional[int] = None
-    search_restriction: Optional[dict] = None
+    search_restriction: Optional[Dict[str, Sequence[str]]] = None
     verbose: Optional[bool] = None
+    return_context: Optional[bool] = None
 
 
 class RootRequest(APIRequestModel):
@@ -361,6 +365,7 @@ class SearchEvent(APIResponseModel):
     consistency_verification -- Consistency verification calculated if required.
     membership_verification -- Membership verification calculated if required.
     signature_verification -- Signature verification calculated if required.
+    fpe_context -- The context data needed to decrypt secure audit events that have been redacted with format preserving encryption.
     """
 
     envelope: EventEnvelope
@@ -371,6 +376,7 @@ class SearchEvent(APIResponseModel):
     consistency_verification: EventVerification = EventVerification.NONE
     membership_verification: EventVerification = EventVerification.NONE
     signature_verification: EventVerification = EventVerification.NONE
+    fpe_context: Optional[str] = None
 
 
 class SearchResultOutput(PangeaResponseResult):
@@ -415,11 +421,15 @@ class SearchResultRequest(APIRequestModel):
     id -- A search results identifier returned by the search call.
     limit -- Number of audit records to include from the first page of the results.
     offset -- Offset from the start of the result set to start returning results from.
+    assert_search_restriction -- Assert the requested search results were queried with the exact same search restrictions, to ensure the results comply to the expected restrictions.
+    return_context -- Return the context data needed to decrypt secure audit events that have been redacted with format preserving encryption.
     """
 
     id: str
     limit: Optional[int] = 20
     offset: Optional[int] = 0
+    assert_search_restriction: Optional[Dict[str, Sequence[str]]] = None
+    return_context: Optional[bool] = None
 
 
 class DownloadFormat(str, enum.Enum):
@@ -437,13 +447,51 @@ class DownloadFormat(str, enum.Enum):
 
 
 class DownloadRequest(APIRequestModel):
-    result_id: str
+    request_id: Optional[str] = None
+    """ID returned by the export API."""
+
+    result_id: Optional[str] = None
     """ID returned by the search API."""
 
     format: Optional[str] = None
     """Format for the records."""
 
+    return_context: Optional[bool] = None
+    """Return the context data needed to decrypt secure audit events that have been redacted with format preserving encryption."""
+
 
 class DownloadResult(PangeaResponseResult):
     dest_url: str
     """URL where search results can be downloaded."""
+
+    expires_at: str
+    """
+    The time when the results will no longer be available to page through via
+    the results API.
+    """
+
+
+class ExportRequest(APIRequestModel):
+    format: DownloadFormat = DownloadFormat.CSV
+    """Format for the records."""
+
+    start: Optional[datetime.datetime] = None
+    """The start of the time range to perform the search on."""
+
+    end: Optional[datetime.datetime] = None
+    """
+    The end of the time range to perform the search on. If omitted, then all
+    records up to the latest will be searched.
+    """
+
+    order_by: Optional[str] = None
+    """Name of column to sort the results by."""
+
+    order: Optional[SearchOrder] = None
+    """Specify the sort order of the response."""
+
+    verbose: bool = True
+    """
+    Whether or not to include the root hash of the tree and the membership proof
+    for each record.
+    """