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

pangea/services/redact.py

@@ -1,9 +1,11 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
+from __future__ import annotations
 
 import enum
 from typing import Dict, List, Optional, Union
 
+from pangea.config import PangeaConfig
 from pangea.response import APIRequestModel, APIResponseModel, PangeaResponse, PangeaResponseResult
 from pangea.services.base import ServiceBase
 
@@ -15,6 +17,44 @@ class RedactFormat(str, enum.Enum):
     """JSON format."""
 
 
+class RedactType(str, enum.Enum):
+    MASK = "mask"
+    PARTIAL_MASKING = "partial_masking"
+    REPLACEMENT = "replacement"
+    DETECT_ONLY = "detect_only"
+    HASH = "hash"
+    FPE = "fpe"
+
+
+class FPEAlphabet(str, enum.Enum):
+    NUMERIC = "numeric"
+    ALPHANUMERICLOWER = "alphanumericlower"
+    ALPHANUMERIC = "alphanumeric"
+
+
+class MaskingType(str, enum.Enum):
+    MASK = "mask"
+    UNMASK = "unmask"
+
+
+class PartialMasking(APIRequestModel):
+    masking_type: Optional[MaskingType] = None
+    unmasked_from_left: Optional[int] = None
+    unmasked_from_right: Optional[int] = None
+    masked_from_left: Optional[int] = None
+    masked_from_right: Optional[int] = None
+    chars_to_ignore: Optional[List[str]] = None
+    masking_char: Optional[List[str]] = None
+
+
+class RedactionMethodOverrides(APIRequestModel):
+    redaction_type: RedactType
+    hash: Optional[Dict] = None
+    fpe_alphabet: Optional[FPEAlphabet] = None
+    partial_masking: Optional[PartialMasking] = None
+    redaction_value: Optional[str] = None
+
+
 class RedactRequest(APIRequestModel):
     """
     Input class to make a redact request
@@ -25,6 +65,7 @@ class RedactRequest(APIRequestModel):
     rules: Optional[List[str]] = None
     rulesets: Optional[List[str]] = None
     return_result: Optional[bool] = None
+    redaction_method_overrides: Optional[RedactionMethodOverrides] = None
 
 
 class RecognizerResult(APIResponseModel):
@@ -92,6 +133,7 @@ class StructuredRequest(APIRequestModel):
     rules: Optional[List[str]] = None
     rulesets: Optional[List[str]] = None
     return_result: Optional[bool] = None
+    redaction_method_overrides: Optional[RedactionMethodOverrides] = None
 
 
 class StructuredResult(PangeaResponseResult):
@@ -105,6 +147,32 @@ class StructuredResult(PangeaResponseResult):
     report: Optional[DebugReport] = None
 
 
+class UnredactRequest(APIRequestModel):
+    """
+    Class input to unredact data request
+
+    Arguments:
+    redacted_data: Data to unredact
+    fpe_context (base64): FPE context used to decrypt and unredact data
+
+    """
+
+    redacted_data: RedactedData
+    fpe_context: str
+
+
+RedactedData = Union[str, Dict]
+
+
+class UnredactResult(PangeaResponseResult):
+    """
+    Result class after an unredact request
+
+    """
+
+    data: RedactedData
+
+
 class Redact(ServiceBase):
     """Redact service client.
 
@@ -132,7 +200,24 @@ class Redact(ServiceBase):
 
     service_name = "redact"
 
-    def __init__(self, token, config=None, logger_name="pangea", config_id: Optional[str] = None):
+    def __init__(
+        self, token: str, config: PangeaConfig | None = None, logger_name: str = "pangea", config_id: str | None = None
+    ) -> None:
+        """
+        Redact client
+
+        Initializes a new Redact client.
+
+        Args:
+            token: Pangea API token.
+            config: Configuration.
+            logger_name: Logger name.
+            config_id: Configuration ID.
+
+        Examples:
+             config = PangeaConfig(domain="pangea_domain")
+             redact = Redact(token="pangea_token", config=config)
+        """
         super().__init__(token, config, logger_name, config_id=config_id)
 
     def redact(
@@ -142,6 +227,7 @@ class Redact(ServiceBase):
         rules: Optional[List[str]] = None,
         rulesets: Optional[List[str]] = None,
         return_result: Optional[bool] = None,
+        redaction_method_overrides: Optional[RedactionMethodOverrides] = None,
     ) -> PangeaResponse[RedactResult]:
         """
         Redact
@@ -157,6 +243,7 @@ class Redact(ServiceBase):
             rules (list[str], optional): An array of redact rule short names
             rulesets (list[str], optional): An array of redact rulesets short names
             return_result(bool, optional): Setting this value to false will omit the redacted result only returning count
+            redaction_method_overrides: A set of redaction method overrides for any enabled rule. These methods override the config declared methods
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -170,8 +257,15 @@ class Redact(ServiceBase):
             response = redact.redact(text="Jenny Jenny... 555-867-5309")
         """
 
-        input = RedactRequest(text=text, debug=debug, rules=rules, rulesets=rulesets, return_result=return_result)
-        return self.request.post("v1/redact", RedactResult, data=input.dict(exclude_none=True))
+        input = RedactRequest(
+            text=text,
+            debug=debug,
+            rules=rules,
+            rulesets=rulesets,
+            return_result=return_result,
+            redaction_method_overrides=redaction_method_overrides,
+        )
+        return self.request.post("v1/redact", RedactResult, data=input.model_dump(exclude_none=True))
 
     def redact_structured(
         self,
@@ -182,6 +276,7 @@ class Redact(ServiceBase):
         rules: Optional[List[str]] = None,
         rulesets: Optional[List[str]] = None,
         return_result: Optional[bool] = None,
+        redaction_method_overrides: Optional[RedactionMethodOverrides] = None,
     ) -> PangeaResponse[StructuredResult]:
         """
         Redact structured
@@ -201,6 +296,7 @@ class Redact(ServiceBase):
             rules (list[str], optional): An array of redact rule short names
             rulesets (list[str], optional): An array of redact rulesets short names
             return_result(bool, optional): Setting this value to false will omit the redacted result only returning count
+            redaction_method_overrides: A set of redaction method overrides for any enabled rule. These methods override the config declared methods
 
         Raises:
             PangeaAPIException: If an API Error happens
@@ -227,5 +323,29 @@ class Redact(ServiceBase):
             rules=rules,
             rulesets=rulesets,
             return_result=return_result,
+            redaction_method_overrides=redaction_method_overrides,
         )
-        return self.request.post("v1/redact_structured", StructuredResult, data=input.dict(exclude_none=True))
+        return self.request.post("v1/redact_structured", StructuredResult, data=input.model_dump(exclude_none=True))
+
+    def unredact(self, redacted_data: RedactedData, fpe_context: str) -> PangeaResponse[UnredactResult]:
+        """
+        Unredact
+
+        Decrypt or unredact fpe redactions
+
+        OperationId: redact_post_v1_unredact
+
+        Args:
+            redacted_data: Data to unredact
+            fpe_context (base64): FPE context used to decrypt and unredact data
+
+        Raises:
+            PangeaAPIException: If an API Error happens
+
+        Returns:
+            Pangea Response with redacted data in the response.result field,
+                available response fields can be found in our
+                [API Documentation](https://pangea.cloud/docs/api/redact#unredact)
+        """
+        input = UnredactRequest(redacted_data=redacted_data, fpe_context=fpe_context)
+        return self.request.post("v1/unredact", UnredactResult, data=input.model_dump(exclude_none=True))

pangea/services/vault/models/common.py

@@ -1,10 +1,10 @@
 # Copyright 2022 Pangea Cyber Corporation
 # Author: Pangea Cyber Corporation
-import datetime
+
 import enum
 from typing import Dict, Generic, List, NewType, Optional, TypeVar, Union
 
-from pangea.response import APIRequestModel, PangeaResponseResult
+from pangea.response import APIRequestModel, PangeaDateTime, PangeaResponseResult
 
 # EncodedPublicKey is a PEM public key, with no further encoding (i.e. no base64)
 # It may be used for example in openssh with no further processing
@@ -22,6 +22,8 @@ class KeyPurpose(str, enum.Enum):
     SIGNING = "signing"
     ENCRYPTION = "encryption"
     JWT = "jwt"
+    FPE = "fpe"
+    """Format-preserving encryption."""
 
     def __str__(self):
         return str(self.value)
@@ -84,6 +86,11 @@ class SymmetricAlgorithm(str, enum.Enum):
     AES128_CBC = "AES-CBC-128"
     AES256_CBC = "AES-CBC-256"
     AES = "AES-CFB-128"  # deprecated, use AES128_CFB instead
+    AES128_FF3_1_BETA = "AES-FF3-1-128-BETA"
+    """128-bit encryption using the FF3-1 algorithm."""
+
+    AES256_FF3_1_BETA = "AES-FF3-1-256-BETA"
+    """256-bit encryption using the FF3-1 algorithm."""
 
     def __str__(self):
         return str(self.value)
@@ -174,7 +181,7 @@ class CommonStoreRequest(APIRequestModel):
     tags: Optional[Tags] = None
     rotation_frequency: Optional[str] = None
     rotation_state: Optional[ItemVersionState] = None
-    expiration: Optional[datetime.datetime] = None
+    expiration: Optional[PangeaDateTime] = None
 
 
 class CommonStoreResult(PangeaResponseResult):
@@ -191,7 +198,7 @@ class CommonGenerateRequest(APIRequestModel):
     tags: Optional[Tags] = None
     rotation_frequency: Optional[str] = None
     rotation_state: Optional[ItemVersionState] = None
-    expiration: Optional[datetime.datetime] = None
+    expiration: Optional[PangeaDateTime] = None
 
 
 class CommonGenerateResult(PangeaResponseResult):
@@ -254,7 +261,7 @@ class ListItemData(ItemData):
 class ListResult(PangeaResponseResult):
     items: List[ListItemData] = []
     count: int
-    last: Optional[str]
+    last: Optional[str] = None
 
 
 class ListRequest(APIRequestModel):
@@ -305,7 +312,7 @@ class UpdateRequest(APIRequestModel):
     rotation_frequency: Optional[str] = None
     rotation_state: Optional[ItemVersionState] = None
     rotation_grace_period: Optional[str] = None
-    expiration: Optional[datetime.datetime] = None
+    expiration: Optional[PangeaDateTime] = None
     item_state: Optional[ItemState] = None
 
 
@@ -427,3 +434,111 @@ class EncryptStructuredResult(PangeaResponseResult, Generic[TDict]):
 
     structured_data: TDict
     """Encrypted structured data."""
+
+
+class TransformAlphabet(str, enum.Enum):
+    """Set of characters to use for format-preserving encryption (FPE)."""
+
+    NUMERIC = "numeric"
+    """Numeric (0-9)."""
+
+    ALPHA_LOWER = "alphalower"
+    """Lowercase alphabet (a-z)."""
+
+    ALPHA_UPPER = "alphaupper"
+    """Uppercase alphabet (A-Z)."""
+
+    ALPHANUMERIC_LOWER = "alphanumericlower"
+    """Lowercase alphabet with numbers (a-z, 0-9)."""
+
+    ALPHANUMERIC_UPPER = "alphanumericupper"
+    """Uppercase alphabet with numbers (A-Z, 0-9)."""
+
+    ALPHANUMERIC = "alphanumeric"
+    """Alphanumeric (a-z, A-Z, 0-9)."""
+
+    def __str__(self) -> str:
+        return str(self.value)
+
+    def __repr__(self) -> str:
+        return str(self.value)
+
+
+class EncryptTransformRequest(APIRequestModel):
+    id: str
+    """The item ID."""
+
+    plain_text: str
+    """A message to be encrypted."""
+
+    alphabet: TransformAlphabet
+    """Set of characters to use for format-preserving encryption (FPE)."""
+
+    tweak: Optional[str] = None
+    """
+    User provided tweak string. If not provided, a random string will be
+    generated and returned. The user must securely store the tweak source which
+    will be needed to decrypt the data.
+    """
+
+    version: Optional[int] = None
+    """The item version."""
+
+
+class EncryptTransformResult(PangeaResponseResult):
+    id: str
+    """The item ID."""
+
+    version: int
+    """The item version."""
+
+    algorithm: str
+    """The algorithm of the key."""
+
+    cipher_text: str
+    """The encrypted message."""
+
+    tweak: str
+    """
+    User provided tweak string. If not provided, a random string will be
+    generated and returned. The user must securely store the tweak source which
+    will be needed to decrypt the data.
+    """
+
+    alphabet: str
+    """Set of characters to use for format-preserving encryption (FPE)."""
+
+
+class DecryptTransformRequest(APIRequestModel):
+    id: str
+    """The item ID."""
+
+    cipher_text: str
+    """A message encrypted by Vault."""
+
+    tweak: str
+    """
+    User provided tweak string. If not provided, a random string will be
+    generated and returned. The user must securely store the tweak source which
+    will be needed to decrypt the data.
+    """
+
+    alphabet: TransformAlphabet
+    """Set of characters to use for format-preserving encryption (FPE)."""
+
+    version: Optional[int] = None
+    """The item version."""
+
+
+class DecryptTransformResult(PangeaResponseResult):
+    id: str
+    """The item ID."""
+
+    version: int
+    """The item version."""
+
+    algorithm: str
+    """The algorithm of the key."""
+
+    plain_text: str
+    """Decrypted message."""

pangea/services/vault/models/symmetric.py

@@ -39,7 +39,7 @@ class EncryptRequest(APIRequestModel):
     id: str
     plain_text: str
     version: Optional[int] = None
-    additional_data: Optional[str]
+    additional_data: Optional[str] = None
 
 
 class EncryptResult(PangeaResponseResult):
@@ -53,7 +53,7 @@ class DecryptRequest(APIRequestModel):
     id: str
     cipher_text: str
     version: Optional[int] = None
-    additional_data: Optional[str]
+    additional_data: Optional[str] = None
 
 
 class DecryptResult(PangeaResponseResult):