pangea-sdk 3.1.0__tar.gz → 3.2.0__tar.gz

{pangea_sdk-3.1.0 → pangea_sdk-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pangea-sdk
-Version: 3.1.0
+Version: 3.2.0
 Summary: Pangea API SDK
 License: MIT
 Keywords: Pangea,SDK,Audit

{pangea_sdk-3.1.0 → pangea_sdk-3.2.0}/pangea/__init__.py

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

{pangea_sdk-3.1.0 → pangea_sdk-3.2.0}/pangea/asyncio/services/audit.py

@@ -1,13 +1,15 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
 import datetime
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
+import pangea.exceptions as pexc
 from pangea.response import PangeaResponse
 from pangea.services.audit.audit import AuditBase
 from pangea.services.audit.exceptions import AuditException
 from pangea.services.audit.models import (
     Event,
+    LogBulkResult,
     LogResult,
     RootRequest,
     RootResult,
@@ -172,9 +174,86 @@ class AuditAsync(ServiceBaseAsync, AuditBase):
                     print(f"\\t{err.detail} \\n")
         """
 
-        input = self._pre_log_process(event, sign_local=sign_local, verify=verify, verbose=verbose)
+        input = self._get_log_request(event, sign_local=sign_local, verify=verify, verbose=verbose)
         response = await self.request.post("v1/log", LogResult, data=input.dict(exclude_none=True))
-        return self.handle_log_response(response, verify=verify)
+        if response.success:
+            self._process_log_result(response.result, verify=verify)
+        return response
+
+    async def log_bulk(
+        self,
+        events: List[Dict[str, Any]],
+        sign_local: bool = False,
+        verbose: Optional[bool] = None,
+    ) -> PangeaResponse[LogBulkResult]:
+        """
+        Log an entry
+
+        Create a log entry in the Secure Audit Log.
+        Args:
+            events (List[dict[str, Any]]): events to be logged
+            verify (bool, optional): True to verify logs consistency after response.
+            sign_local (bool, optional): True to sign event with local key.
+            verbose (bool, optional): True to get a more verbose response.
+        Raises:
+            AuditException: If an audit based api exception happens
+            PangeaAPIException: If an API Error happens
+
+        Returns:
+            A PangeaResponse where the hash of event data and optional verbose
+                results are returned in the response.result field.
+                Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#log-an-entry).
+
+        Examples:
+            FIXME:
+        """
+
+        input = self._get_log_request(events, sign_local=sign_local, verify=False, verbose=verbose)
+        response = await self.request.post("v2/log", LogBulkResult, data=input.dict(exclude_none=True))
+        if response.success:
+            for result in response.result.results:
+                self._process_log_result(result, verify=True)
+        return response
+
+    async def log_bulk_async(
+        self,
+        events: List[Dict[str, Any]],
+        sign_local: bool = False,
+        verbose: Optional[bool] = None,
+    ) -> PangeaResponse[LogBulkResult]:
+        """
+        Log an entry
+
+        Create a log entry in the Secure Audit Log.
+        Args:
+            events (List[dict[str, Any]]): events to be logged
+            verify (bool, optional): True to verify logs consistency after response.
+            sign_local (bool, optional): True to sign event with local key.
+            verbose (bool, optional): True to get a more verbose response.
+        Raises:
+            AuditException: If an audit based api exception happens
+            PangeaAPIException: If an API Error happens
+
+        Returns:
+            A PangeaResponse where the hash of event data and optional verbose
+                results are returned in the response.result field.
+                Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#log-an-entry).
+
+        Examples:
+            FIXME:
+        """
+
+        input = self._get_log_request(events, sign_local=sign_local, verify=False, verbose=verbose)
+        try:
+            response = await self.request.post(
+                "v2/log_async", LogBulkResult, data=input.dict(exclude_none=True), poll_result=False
+            )
+        except pexc.AcceptedRequestException as e:
+            return e.response
+        if response.success:
+            for result in response.result.results:
+                self._process_log_result(result, verify=True)
+        return response
 
     async def search(
         self,

{pangea_sdk-3.1.0 → pangea_sdk-3.2.0}/pangea/exceptions.py

@@ -119,7 +119,7 @@ class AcceptedRequestException(PangeaAPIException):
     """Accepted request exception. Async response"""
 
     request_id: str
-    accepted_result: Optional[AcceptedResult]
+    accepted_result: Optional[AcceptedResult] = None
 
     def __init__(self, response: PangeaResponse):
         message = f"summary: {response.summary}. request_id: {response.request_id}."

{pangea_sdk-3.1.0 → pangea_sdk-3.2.0}/pangea/response.py

@@ -76,7 +76,7 @@ class AcceptedStatus(APIResponseModel):
 
 
 class AcceptedResult(PangeaResponseResult):
-    accepted_status: AcceptedStatus
+    accepted_status: Optional[AcceptedStatus] = None
 
 
 class PangeaError(PangeaResponseResult):
@@ -144,8 +144,11 @@ class PangeaResponse(Generic[T], ResponseHeader):
             if self.raw_result is not None and issubclass(self.result_class, PangeaResponseResult) and self.success
             else None
         )
-        if not self.success and self.http_status != 202:
-            self.pangea_error = PangeaError(**self.raw_result) if self.raw_result is not None else None
+        if not self.success:
+            if self.http_status == 202:
+                self.accepted_result = AcceptedResult(**self.raw_result) if self.raw_result is not None else None
+            else:
+                self.pangea_error = PangeaError(**self.raw_result) if self.raw_result is not None else None
 
     @property
     def success(self) -> bool:

{pangea_sdk-3.1.0 → pangea_sdk-3.2.0}/pangea/services/audit/audit.py

@@ -2,14 +2,18 @@
 # Author: Pangea Cyber Corporation
 import datetime
 import json
-from typing import Any, Dict, Optional, Union
+from typing import Any, Dict, List, Optional, Union
 
+import pangea.exceptions as pexc
 from pangea.response import PangeaResponse
 from pangea.services.audit.exceptions import AuditException, EventCorruption
 from pangea.services.audit.models import (
     Event,
     EventEnvelope,
     EventVerification,
+    LogBulkRequest,
+    LogBulkResult,
+    LogEvent,
     LogRequest,
     LogResult,
     PublishedRoot,
@@ -56,7 +60,29 @@ class AuditBase:
         self.prev_unpublished_root_hash: Optional[str] = None
         self.tenant_id = tenant_id
 
-    def _pre_log_process(self, event: dict, sign_local: bool, verify: bool, verbose: bool) -> LogRequest:
+    def _get_log_request(
+        self, events: Union[dict, List[dict]], sign_local: bool, verify: bool, verbose: Optional[bool]
+    ) -> Union[LogRequest, LogBulkResult]:
+        if isinstance(events, list):
+            request_events: List[LogEvent] = []
+            for e in events:
+                request_events.append(self._process_log(e, sign_local=sign_local))
+
+            input = LogBulkRequest(events=request_events, verbose=verbose)
+
+        elif isinstance(events, dict):
+            log = self._process_log(events, sign_local=sign_local)
+            input = LogRequest(event=log.event, signature=log.signature, public_key=log.public_key)
+            input.verbose = True if verify else verbose
+            if verify and self.prev_unpublished_root_hash:
+                input.prev_root = self.prev_unpublished_root_hash
+
+        else:
+            raise AttributeError(f"events should be a dict or a list[dict] and it is {type(events)}")
+
+        return input
+
+    def _process_log(self, event: dict, sign_local: bool) -> LogEvent:
         if event.get("tenant_id", None) is None and self.tenant_id:
             event["tenant_id"] = self.tenant_id
 
@@ -66,70 +92,60 @@ class AuditBase:
         if sign_local is True and self.signer is None:
             raise AuditException("Error: the `signing` parameter set, but `signer` is not configured")
 
-        input = LogRequest(event=event, verbose=verbose)
-
+        signature = None
+        pki = None
         if sign_local is True:
             data2sign = canonicalize_event(event)
             signature = self.signer.sign(data2sign)
-            if signature is not None:
-                input.signature = signature
-            else:
+            if signature is None:
                 raise AuditException("Error: failure signing message")
 
             # Add public key value to public key info and serialize
-            self._set_public_key(input, self.signer, self.public_key_info)
-
-        if verify:
-            input.verbose = True
-            if self.prev_unpublished_root_hash:
-                input.prev_root = self.prev_unpublished_root_hash
-
-        return input
+            pki = self._get_public_key_info(self.signer, self.public_key_info)
 
-    def handle_log_response(self, response: PangeaResponse, verify: bool) -> PangeaResponse[LogResult]:
-        if not response.success:
-            return response
+        return LogEvent(event=event, signature=signature, public_key=pki)
 
-        new_unpublished_root_hash = response.result.unpublished_root
+    def _process_log_result(self, result: LogResult, verify: bool):
+        new_unpublished_root_hash = result.unpublished_root
 
         if verify:
-            if response.result.envelope:
+            if result.envelope:
                 # verify event hash
-                if response.result.hash and not verify_envelope_hash(response.result.envelope, response.result.hash):
+                if result.hash and not verify_envelope_hash(result.envelope, result.hash):
                     # it's a extreme case, it's OK to raise an exception
-                    raise EventCorruption("Error: Event hash failed.", response.result.envelope)
+                    raise EventCorruption("Error: Event hash failed.", result.envelope)
 
-                response.result.signature_verification = self.verify_signature(response.result.envelope)
+                result.signature_verification = self.verify_signature(result.envelope)
 
             if new_unpublished_root_hash:
-                if response.result.membership_proof is not None:
+                if result.membership_proof is not None:
                     # verify membership proofs
-                    membership_proof = decode_membership_proof(response.result.membership_proof)
+                    membership_proof = decode_membership_proof(result.membership_proof)
                     if verify_membership_proof(
-                        node_hash=decode_hash(response.result.hash),
+                        node_hash=decode_hash(result.hash),
                         root_hash=decode_hash(new_unpublished_root_hash),
                         proof=membership_proof,
                     ):
-                        response.result.membership_verification = EventVerification.PASS
+                        result.membership_verification = EventVerification.PASS
                     else:
-                        response.result.membership_verification = EventVerification.FAIL
+                        result.membership_verification = EventVerification.FAIL
 
                 # verify consistency proofs (following events)
-                if response.result.consistency_proof is not None and self.prev_unpublished_root_hash:
-                    consistency_proof = decode_consistency_proof(response.result.consistency_proof)
+                if result.consistency_proof is not None and self.prev_unpublished_root_hash:
+                    consistency_proof = decode_consistency_proof(result.consistency_proof)
                     if verify_consistency_proof(
                         new_root=decode_hash(new_unpublished_root_hash),
                         prev_root=decode_hash(self.prev_unpublished_root_hash),
                         proof=consistency_proof,
                     ):
-                        response.result.consistency_verification = EventVerification.PASS
+                        result.consistency_verification = EventVerification.PASS
                     else:
-                        response.result.consistency_verification = EventVerification.FAIL
+                        result.consistency_verification = EventVerification.FAIL
 
         # Update prev unpublished root
         if new_unpublished_root_hash:
             self.prev_unpublished_root_hash = new_unpublished_root_hash
-        return response
+        return
 
     def handle_results_response(
         self, response: PangeaResponse[SearchResultOutput], verify_consistency: bool = False, verify_events: bool = True
@@ -348,12 +364,10 @@ class AuditBase:
         else:
             return EventVerification.NONE
 
-    def _set_public_key(self, input: LogRequest, signer: Signer, public_key_info: Dict[str, str]):
+    def _get_public_key_info(self, signer: Signer, public_key_info: Dict[str, str]):
         public_key_info["key"] = signer.get_public_key_PEM()
         public_key_info["algorithm"] = signer.get_algorithm()
-        input.public_key = json.dumps(
-            public_key_info, ensure_ascii=False, allow_nan=False, separators=(",", ":"), sort_keys=True
-        )
+        return json.dumps(public_key_info, ensure_ascii=False, allow_nan=False, separators=(",", ":"), sort_keys=True)
 
 
 class Audit(ServiceBase, AuditBase):
@@ -444,16 +458,13 @@ class Audit(ServiceBase, AuditBase):
             A PangeaResponse where the hash of event data and optional verbose
                 results are returned in the response.result field.
                 Available response fields can be found in our
-                [API documentation](https://pangea.cloud/docs/api/audit#log-an-entry).
+                [API documentation](https://pangea.cloud/docs/api/audit#/v1/log).
 
         Examples:
-            try:
-                log_response = audit.log(message="Hello world", verbose=False)
-                print(f"Response. Hash: {log_response.result.hash}")
-            except pe.PangeaAPIException as e:
-                print(f"Request Error: {e.response.summary}")
-                for err in e.errors:
-                    print(f"\\t{err.detail} \\n")
+            log_response = audit.log(
+                message="hello world", 
+                verbose=True,
+            )
         """
 
         event = Event(
@@ -481,6 +492,7 @@ class Audit(ServiceBase, AuditBase):
         Log an entry
 
         Create a log entry in the Secure Audit Log.
+
         Args:
             event (dict[str, Any]): event to be logged
             verify (bool, optional): True to verify logs consistency after response.
@@ -493,11 +505,11 @@ class Audit(ServiceBase, AuditBase):
         Returns:
             A PangeaResponse where the hash of event data and optional verbose
                 results are returned in the response.result field.
-                Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#log-an-entry).
+                Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#/v1/log).
 
         Examples:
             try:
-                log_response = audit.log({"message"="Hello world"}, verbose=False)
+                log_response = audit.log({"message": "hello world"}, verbose=True)
                 print(f"Response. Hash: {log_response.result.hash}")
             except pe.PangeaAPIException as e:
                 print(f"Request Error: {e.response.summary}")
@@ -505,9 +517,98 @@ class Audit(ServiceBase, AuditBase):
                     print(f"\\t{err.detail} \\n")
         """
 
-        input = self._pre_log_process(event, sign_local=sign_local, verify=verify, verbose=verbose)
+        input = self._get_log_request(event, sign_local=sign_local, verify=verify, verbose=verbose)
         response = self.request.post("v1/log", LogResult, data=input.dict(exclude_none=True))
-        return self.handle_log_response(response, verify=verify)
+        if response.success:
+            self._process_log_result(response.result, verify=verify)
+        return response
+
+    def log_bulk(
+        self,
+        events: List[Dict[str, Any]],
+        sign_local: bool = False,
+        verbose: Optional[bool] = None,
+    ) -> PangeaResponse[LogBulkResult]:
+        """
+        Log multiple entries
+
+        Create multiple log entries in the Secure Audit Log.
+
+        OperationId: audit_post_v2_log
+
+        Args:
+            events (List[dict[str, Any]]): events to be logged
+            sign_local (bool, optional): True to sign event with local key.
+            verbose (bool, optional): True to get a more verbose response.
+        Raises:
+            AuditException: If an audit based api exception happens
+            PangeaAPIException: If an API Error happens
+
+        Returns:
+            A PangeaResponse where the hash of event data and optional verbose
+                results are returned in the response.result field.
+                Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#/v2/log).
+
+        Examples:
+            log_response = audit.log_bulk(
+                events=[{"message": "hello world"}], 
+                verbose=True,
+            )
+        """
+
+        input = self._get_log_request(events, sign_local=sign_local, verify=False, verbose=verbose)
+        response = self.request.post("v2/log", LogBulkResult, data=input.dict(exclude_none=True))
+
+        if response.success:
+            for result in response.result.results:
+                self._process_log_result(result, verify=True)
+        return response
+
+    def log_bulk_async(
+        self,
+        events: List[Dict[str, Any]],
+        sign_local: bool = False,
+        verbose: Optional[bool] = None,
+    ) -> PangeaResponse[LogBulkResult]:
+        """
+        Log multiple entries asynchronously
+
+        Asynchronously create multiple log entries in the Secure Audit Log.
+
+        Args:
+            events (List[dict[str, Any]]): events to be logged
+            sign_local (bool, optional): True to sign event with local key.
+            verbose (bool, optional): True to get a more verbose response.
+        Raises:
+            AuditException: If an audit based api exception happens
+            PangeaAPIException: If an API Error happens
+
+        Returns:
+            A PangeaResponse where the hash of event data and optional verbose
+                results are returned in the response.result field.
+                Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#/v2/log_async).
+
+        Examples:
+            log_response = audit.log_bulk_async(
+                events=[{"message": "hello world"}], 
+                verbose=True,
+            )
+        """
+
+        input = self._get_log_request(events, sign_local=sign_local, verify=False, verbose=verbose)
+
+        try:
+            # Calling to v2 methods will return always a 202.
+            response = self.request.post(
+                "v2/log_async", LogBulkResult, data=input.dict(exclude_none=True), poll_result=False
+            )
+        except pexc.AcceptedRequestException as e:
+            return e.response
+
+        if response.success:
+            for result in response.result.results:
+                self._process_log_result(result, verify=True)
+        return response
 
     def search(
         self,
@@ -558,11 +659,17 @@ class Audit(ServiceBase, AuditBase):
 
         Returns:
             A PangeaResponse[SearchOutput] where the first page of matched events is returned in the
-                response.result field. Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#search-for-events).
-                Pagination can be found in the [search results endpoint](https://pangea.cloud/docs/api/audit#search-results).
+                response.result field. Available response fields can be found in our [API documentation](https://pangea.cloud/docs/api/audit#/v1/search).
+                Pagination can be found in the [search results endpoint](https://pangea.cloud/docs/api/audit#/v1/results).
 
         Examples:
-            response: PangeaResponse[SearchOutput] = audit.search(query="message:test", search_restriction={'source': ["monitor"]}, limit=1, verify_consistency=True, verify_events=True)
+            response = audit.search(
+                query="message:test", 
+                search_restriction={'source': ["monitor"]}, 
+                limit=1, 
+                verify_consistency=True, 
+                verify_events=True,
+            )
         """
 
         if verify_consistency:
@@ -609,17 +716,11 @@ class Audit(ServiceBase, AuditBase):
             PangeaAPIException: If an API Error happens
 
         Examples:
-            search_res: PangeaResponse[SearchOutput] = audit.search(
-                query="message:test",
-                search_restriction={'source': ["monitor"]},
-                limit=100,
-                verify_consistency=True,
-                verify_events=True)
-
-            result_res: PangeaResponse[SearchResultsOutput] = audit.results(
-                id=search_res.result.id,
+            response = audit.results(
+                id="pas_sqilrhruwu54uggihqj3aie24wrctakr",
                 limit=10,
-                offset=0)
+                offset=0,
+            )
         """
 
         if limit <= 0:

{pangea_sdk-3.1.0 → pangea_sdk-3.2.0}/pangea/services/audit/models.py

@@ -146,6 +146,34 @@ class LogRequest(APIRequestModel):
     prev_root: Optional[str] = None
 
 
+class LogEvent(APIRequestModel):
+    """
+    Event to perform a log action
+
+    Arguments:
+    event -- A structured event describing an auditable activity.
+    signature -- An optional client-side signature for forgery protection.
+    public_key -- The base64-encoded ed25519 public key used for the signature, if one is provided.
+    """
+
+    event: Dict[str, Any]
+    signature: Optional[str] = None
+    public_key: Optional[str] = None
+
+
+class LogBulkRequest(APIRequestModel):
+    """
+    Request to perform a bulk log action
+
+    Arguments:
+    events -- A list structured events describing an auditable activity.
+    verbose -- If true, be verbose in the response; include membership proof, unpublished root and consistency proof, etc.
+    """
+
+    events: List[LogEvent]
+    verbose: Optional[bool] = None
+
+
 class LogResult(PangeaResponseResult):
     """
     Result class after an audit log action
@@ -167,6 +195,10 @@ class LogResult(PangeaResponseResult):
     signature_verification: EventVerification = EventVerification.NONE
 
 
+class LogBulkResult(PangeaResponseResult):
+    results: List[LogResult] = []
+
+
 class SearchRestriction(APIResponseModel):
     """
     Set of restrictions when perform an audit search action

{pangea_sdk-3.1.0 → pangea_sdk-3.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "pangea-sdk"
-version = "3.1.0"
+version = "3.2.0"
 description = "Pangea API SDK"
 authors = ["Glenn Gallien <glenn.gallien@pangea.cloud>"]
 license = "MIT"