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

pangea/services/audit/models.py

@@ -1,5 +1,9 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
 from __future__ import annotations
 
 import datetime
@@ -7,7 +11,7 @@ import enum
 from typing import Any, Dict, List, Optional, Sequence, Union
 
 from pydantic import Field
-from typing_extensions import Annotated, Literal
+from typing_extensions import Annotated
 
 from pangea.response import APIRequestModel, APIResponseModel, PangeaDateTime, PangeaResponseResult
 
@@ -116,20 +120,25 @@ class Event(Dict[str, Any]):
 
 
 class EventEnvelope(APIResponseModel):
-    """
-    Contain extra information about an event.
+    event: Optional[dict[str, Any]] = None
 
-    Arguments:
-    event -- Event describing 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
-    received_at -- A server-supplied timestamp
+    signature: Optional[str] = None
+    """
+    This is the signature of the hash of the canonicalized event that can be
+    verified with the public key provided in the public_key field. Signatures
+    cannot be used with the redaction feature turned on. If redaction is
+    required, the user needs to perform redaction before computing the signature
+    that is to be sent with the message. The SDK facilitates this for users.
     """
 
-    event: Dict[str, Any]
-    signature: Optional[str] = None
     public_key: Optional[str] = None
-    received_at: PangeaDateTime
+    """
+    The base64-encoded ed25519 public key used for the signature, if one is
+    provided
+    """
+
+    received_at: Optional[PangeaDateTime] = None
+    """A Pangea provided timestamp of when the event was received."""
 
 
 class LogRequest(APIRequestModel):
@@ -180,21 +189,28 @@ class LogBulkRequest(APIRequestModel):
 
 
 class LogResult(PangeaResponseResult):
+    envelope: Optional[EventEnvelope] = None
     """
-    Result class after an audit log action
-
-    envelope -- Event envelope information.
-    hash -- Event envelope hash.
-    unpublished_root -- The current unpublished root.
-    membership_proof -- A proof for verifying the unpublished root.
-    consistency_proof -- If prev_root was present in the request, this proof verifies that the new unpublished root is a continuation of the prev_root
+    The sealed envelope containing the event that was logged. Includes event
+    metadata such as optional client-side signature details and server-added
+    timestamps.
     """
 
-    envelope: Optional[EventEnvelope] = None
-    hash: str
+    hash: Annotated[Optional[str], Field(max_length=64, min_length=64)] = None
+    """The hash of the event data."""
+
     unpublished_root: Optional[str] = None
+    """The current unpublished root."""
+
     membership_proof: Optional[str] = None
+    """A proof for verifying that the buffer_root contains the received event"""
+
     consistency_proof: Optional[List[str]] = None
+    """
+    If prev_buffer_root was present in the request, this proof verifies that the
+    new unpublished root is a continuation of prev_unpublished_root
+    """
+
     consistency_verification: EventVerification = EventVerification.NONE
     membership_verification: EventVerification = EventVerification.NONE
     signature_verification: EventVerification = EventVerification.NONE
@@ -357,29 +373,47 @@ class RootResult(PangeaResponseResult):
 
 
 class SearchEvent(APIResponseModel):
+    envelope: EventEnvelope
+
+    membership_proof: Optional[str] = None
+    """A cryptographic proof that the record has been persisted in the log"""
+
+    hash: Annotated[Optional[str], Field(max_length=64, min_length=64)] = None
+    """The record's hash"""
+
+    published: Optional[bool] = None
+    """
+    If true, a root has been published after this event. If false, there is no
+    published root for this event
     """
-    Event information received after a search request
 
-    Arguments:
-    envelope -- Event related information.
-    hash -- The record's hash.
-    leaf_index -- The index of the leaf of the Merkle Tree where this record was inserted.
-    membership_proof -- A cryptographic proof that the record has been persisted in the log.
-    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.
+    imported: Optional[bool] = None
+    """
+    If true, the even was imported manually and not logged by the standard
+    procedure. Some features such as tamper proofing may not be available
     """
 
-    envelope: EventEnvelope
-    hash: str
-    membership_proof: Optional[str] = None
-    published: Optional[bool] = None
     leaf_index: Optional[int] = None
+    """
+    The index of the leaf of the Merkle Tree where this record was inserted or
+    null if published=false
+    """
+
+    valid_signature: Optional[bool] = None
+    """
+    Result of the verification of the Vault signature, if the event was signed
+    and the parameter `verify_signature` is `true`
+    """
+
+    fpe_context: Optional[str] = None
+    """
+    The context data needed to decrypt secure audit events that have been
+    redacted with format preserving encryption.
+    """
+
     consistency_verification: EventVerification = EventVerification.NONE
     membership_verification: EventVerification = EventVerification.NONE
     signature_verification: EventVerification = EventVerification.NONE
-    fpe_context: Optional[str] = None
 
 
 class SearchResultOutput(PangeaResponseResult):
@@ -498,275 +532,3 @@ class ExportRequest(APIRequestModel):
     Whether or not to include the root hash of the tree and the membership proof
     for each record.
     """
-
-
-class AuditSchemaField(APIResponseModel):
-    """A description of a field in an audit log."""
-
-    id: str
-    """Prefix name / identity for the field."""
-
-    type: Literal["boolean", "datetime", "integer", "string", "string-unindexed", "text"]
-    """The data type for the field."""
-
-    description: Optional[str] = None
-    """Human display description of the field."""
-
-    name: Optional[str] = None
-    """Human display name/title of the field."""
-
-    redact: Optional[bool] = None
-    """If true, redaction is performed against this field (if configured.) Only valid for string type."""
-
-    required: Optional[bool] = None
-    """If true, this field is required to exist in all logged events."""
-
-    size: Optional[int] = None
-    """The maximum size of the field. Only valid for strings, which limits number of UTF-8 characters."""
-
-    ui_default_visible: Optional[bool] = None
-    """If true, this field is visible by default in audit UIs."""
-
-
-class AuditSchema(APIResponseModel):
-    """A description of acceptable fields for an audit log."""
-
-    client_signable: Optional[bool] = None
-    """If true, records contain fields to support client/vault signing."""
-
-    save_malformed: Optional[str] = None
-    """Save (or reject) malformed AuditEvents."""
-
-    tamper_proofing: Optional[bool] = None
-    """If true, records contain fields to support tamper-proofing."""
-
-    fields: Optional[List[AuditSchemaField]] = None
-    """List of field definitions."""
-
-
-class ForwardingConfiguration(APIResponseModel):
-    """Configuration for forwarding audit logs to external systems."""
-
-    type: str
-    """Type of forwarding configuration."""
-
-    forwarding_enabled: Optional[bool] = False
-    """Whether forwarding is enabled."""
-
-    event_url: Optional[str] = None
-    """URL where events will be written to. Must use HTTPS."""
-
-    ack_url: Optional[str] = None
-    """If indexer acknowledgement is required, this must be provided along with a 'channel_id'."""
-
-    channel_id: Optional[str] = None
-    """An optional splunk channel included in each request if indexer acknowledgement is required."""
-
-    public_cert: Optional[str] = None
-    """Public certificate if a self signed TLS cert is being used."""
-
-    index: Optional[str] = None
-    """Optional splunk index passed in the record bodies."""
-
-    vault_config_id: Optional[str] = None
-    """The vault config used to store the HEC token."""
-
-    vault_secret_id: Optional[str] = None
-    """The secret ID where the HEC token is stored in vault."""
-
-
-class ServiceConfigV1(PangeaResponseResult):
-    """Configuration options available for audit service"""
-
-    id: Optional[str] = None
-    """The config ID"""
-
-    version: Literal[1] = 1
-
-    created_at: Optional[str] = None
-    """The DB timestamp when this config was created. Ignored when submitted."""
-
-    updated_at: Optional[str] = None
-    """The DB timestamp when this config was last updated at"""
-
-    name: Optional[str] = None
-    """Configuration name"""
-
-    retention: Optional[str] = None
-    """Retention window to store audit logs."""
-
-    cold_query_result_retention: Optional[str] = None
-    """Retention window for cold query result / state information."""
-
-    hot_storage: Optional[str] = None
-    """Retention window to keep audit logs in hot storage."""
-
-    query_result_retention: Optional[str] = None
-    """Length of time to preserve server-side query result caching."""
-
-    redact_service_config_id: Optional[str] = None
-    """A redact service config that will be used to redact PII from logs."""
-
-    redaction_fields: Optional[List[str]] = None
-    """Fields to perform redaction against."""
-
-    vault_service_config_id: Optional[str] = None
-    """A vault service config that will be used to sign logs."""
-
-    vault_key_id: Optional[str] = None
-    """ID of the Vault key used for signing. If missing, use a default Audit key"""
-
-    vault_sign: Optional[bool] = None
-    """Enable/disable event signing"""
-
-
-class ServiceConfigV2(PangeaResponseResult):
-    """Configuration options available for audit service"""
-
-    audit_schema: AuditSchema = Field(alias="schema")
-    """Audit log field configuration. Only settable at create time."""
-
-    version: Literal[2] = 2
-
-    cold_query_result_retention: Optional[str] = None
-    """Retention window for cold query result / state information."""
-
-    created_at: Optional[str] = None
-    """The DB timestamp when this config was created. Ignored when submitted."""
-
-    hot_storage: Optional[str] = None
-    """Retention window to keep audit logs in hot storage."""
-
-    id: Optional[str] = None
-    """The config ID"""
-
-    name: Optional[str] = None
-    """Configuration name"""
-
-    query_result_retention: Optional[str] = None
-    """Length of time to preserve server-side query result caching."""
-
-    redact_service_config_id: Optional[str] = None
-    """A redact service config that will be used to redact PII from logs."""
-
-    retention: Optional[str] = None
-    """Retention window to store audit logs."""
-
-    updated_at: Optional[str] = None
-    """The DB timestamp when this config was last updated at"""
-
-    vault_key_id: Optional[str] = None
-    """ID of the Vault key used for signing. If missing, use a default Audit key"""
-
-    vault_service_config_id: Optional[str] = None
-    """A vault service config that will be used to sign logs."""
-
-    vault_sign: Optional[bool] = None
-    """Enable/disable event signing"""
-
-    forwarding_configuration: Optional[ForwardingConfiguration] = None
-    """Configuration for forwarding audit logs to external systems."""
-
-
-class ServiceConfigV3(PangeaResponseResult):
-    """Configuration options available for audit service"""
-
-    audit_schema: AuditSchema = Field(alias="schema")
-    """Audit log field configuration. Only settable at create time."""
-
-    version: Literal[3] = 3
-    """Version of the service config."""
-
-    cold_storage: Optional[str] = None
-    """Retention window for logs in cold storage. Deleted afterwards."""
-
-    created_at: Optional[str] = None
-    """The DB timestamp when this config was created. Ignored when submitted."""
-
-    forwarding_configuration: Optional[ForwardingConfiguration] = None
-    """Configuration for forwarding audit logs to external systems."""
-
-    hot_storage: Optional[str] = None
-    """Retention window for logs in hot storage. Migrated to warm, cold, or deleted afterwards."""
-
-    id: Optional[str] = None
-    """The config ID"""
-
-    name: Optional[str] = None
-    """Configuration name"""
-
-    redact_service_config_id: Optional[str] = None
-    """A redact service config that will be used to redact PII from logs."""
-
-    updated_at: Optional[str] = None
-    """The DB timestamp when this config was last updated at"""
-
-    vault_key_id: Optional[str] = None
-    """ID of the Vault key used for signing. If missing, use a default Audit key"""
-
-    vault_service_config_id: Optional[str] = None
-    """A vault service config that will be used to sign logs."""
-
-    vault_sign: Optional[bool] = None
-    """Enable/disable event signing"""
-
-    warm_storage: Optional[str] = None
-    """Retention window for logs in warm storage. Migrated to cold or deleted afterwards."""
-
-
-ServiceConfig = Annotated[
-    Union[ServiceConfigV1, ServiceConfigV2, ServiceConfigV3],
-    Field(discriminator="version"),
-]
-"""Configuration options available for audit service"""
-
-
-class ServiceConfigFilter(APIRequestModel):
-    id: Optional[str] = None
-    """Only records where id equals this value."""
-
-    id__contains: Optional[Sequence[str]] = None
-    """Only records where id includes each substring."""
-
-    id__in: Optional[Sequence[str]] = None
-    """Only records where id equals one of the provided substrings."""
-
-    created_at: Optional[str] = None
-    """Only records where created_at equals this value."""
-
-    created_at__gt: Optional[str] = None
-    """Only records where created_at is greater than this value."""
-
-    created_at__gte: Optional[str] = None
-    """Only records where created_at is greater than or equal to this value."""
-
-    created_at__lt: Optional[str] = None
-    """Only records where created_at is less than this value."""
-
-    created_at__lte: Optional[str] = None
-    """Only records where created_at is less than or equal to this value."""
-
-    updated_at: Optional[str] = None
-    """Only records where updated_at equals this value."""
-
-    updated_at__gt: Optional[str] = None
-    """Only records where updated_at is greater than this value."""
-
-    updated_at__gte: Optional[str] = None
-    """Only records where updated_at is greater than or equal to this value."""
-
-    updated_at__lt: Optional[str] = None
-    """Only records where updated_at is less than this value."""
-
-    updated_at__lte: Optional[str] = None
-    """Only records where updated_at is less than or equal to this value."""
-
-
-class ServiceConfigListResult(PangeaResponseResult):
-    count: int
-    """The total number of service configs matched by the list request."""
-
-    last: str
-    """Used to fetch the next page of the current listing when provided in a repeated request's last parameter."""
-
-    items: Sequence[ServiceConfig]

pangea/services/audit/signing.py

@@ -81,7 +81,7 @@ class Signer:
                 with open(self.private_key_file, "rb") as file:
                     file_bytes = file.read()
             except FileNotFoundError:
-                raise Exception(f"Error: Failed opening private key file {self.private_key_file}")
+                raise Exception(f"Error: Failed opening private key file {self.private_key_file}") from None
 
             privkey = self._decode_private_key(file_bytes)
             for cls, signer in signers.items():

pangea/services/audit/util.py

@@ -1,5 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+
+# TODO: Modernize.
+# ruff: noqa: UP006, UP035
+
+from __future__ import annotations
+
 import base64
 import json
 import logging
@@ -155,9 +161,9 @@ def verify_membership_proof(node_hash: Hash, root_hash: Hash, proof: MembershipP
 def normalize_log(data: dict) -> dict:
     ans = {}
     for key in data:
-        if type(data[key]) == datetime:
+        if isinstance(data[key], datetime):
             ans[key] = format_datetime(data[key])
-        elif type(data[key]) == dict:
+        elif isinstance(data[key], dict):
             ans[key] = normalize_log(data[key])  # type: ignore[assignment]
         else:
             ans[key] = data[key]
@@ -223,9 +229,7 @@ def get_arweave_published_roots(tree_name: str, tree_sizes: Collection[int]) ->
             }
         }
     }
-    """.replace(
-        "{tree_sizes}", ", ".join(f'"{tree_size}"' for tree_size in tree_sizes)
-    ).replace(
+    """.replace("{tree_sizes}", ", ".join(f'"{tree_size}"' for tree_size in tree_sizes)).replace(
         "{tree_name}", tree_name
     )
 
@@ -273,8 +277,4 @@ def verify_consistency_proof(new_root: Hash, prev_root: Hash, proof: Consistency
         return False
 
     logger.debug("Verifying the proofs for the new root")
-    for item in proof:
-        if not verify_membership_proof(item.node_hash, new_root, item.proof):
-            return False
-
-    return True
+    return all(verify_membership_proof(item.node_hash, new_root, item.proof) for item in proof)