Base

Base class for Data Masking

Usage Documentation

Data masking

CLASS	DESCRIPTION
`DataMasking`	The DataMasking class orchestrates erasing, encrypting, and decrypting

FUNCTION	DESCRIPTION
`prepare_data`	Recursively convert complex objects into dictionaries or simple types.

DataMasking ¶

DataMasking(provider: BaseProvider | None = None, raise_on_missing_field: bool = True)

The DataMasking class orchestrates erasing, encrypting, and decrypting for the base provider.

Example

from aws_lambda_powertools.utilities.data_masking.base import DataMasking

def lambda_handler(event, context):
    masker = DataMasking()

    data = {
        "project": "powertools",
        "sensitive": "password"
    }

    erased = masker.erase(data,fields=["sensitive"])

    return erased

METHOD	DESCRIPTION
`decrypt`	Decrypt data using the configured encryption provider.
`encrypt`	Encrypt data using the configured encryption provider.
`erase`	Erase or mask sensitive data in the input.

Source code in aws_lambda_powertools/utilities/data_masking/base.py

def __init__(
    self,
    provider: BaseProvider | None = None,
    raise_on_missing_field: bool = True,
):
    self.provider = provider or BaseProvider()
    # NOTE: we depend on Provider to not confuse customers in passing the same 2 serializers in 2 places
    self.json_serializer = self.provider.json_serializer
    self.json_deserializer = self.provider.json_deserializer
    self.raise_on_missing_field = raise_on_missing_field

decrypt ¶

decrypt(data, provider_options: dict | None = None, **encryption_context: str) -> Any

Decrypt data using the configured encryption provider.

PARAMETER	DESCRIPTION
`data`	The data to encrypt. TYPE: `dict, Mapping, Sequence, or Number`
`provider_options`	Provider-specific options for encryption. TYPE: `dict` DEFAULT: `None`
`**encryption_context`	Additional key-value pairs for encryption context. TYPE: `str` DEFAULT: `{}`

RETURNS	DESCRIPTION
`str`	The encrypted data as a base64-encoded string.

Example

encryption_provider = AWSEncryptionSDKProvider(keys=[KMS_KEY_ARN])
data_masker = DataMasking(provider=encryption_provider)
encrypted = data_masker.decrypt(encrypted_data)

Source code in aws_lambda_powertools/utilities/data_masking/base.py

def decrypt(
    self,
    data,
    provider_options: dict | None = None,
    **encryption_context: str,
) -> Any:
    """
    Decrypt data using the configured encryption provider.

    Parameters
    ----------
    data : dict, Mapping, Sequence, or Number
        The data to encrypt.
    provider_options : dict, optional
        Provider-specific options for encryption.
    **encryption_context : str
        Additional key-value pairs for encryption context.

    Returns
    -------
    str
        The encrypted data as a base64-encoded string.

    Example
    --------

        encryption_provider = AWSEncryptionSDKProvider(keys=[KMS_KEY_ARN])
        data_masker = DataMasking(provider=encryption_provider)
        encrypted = data_masker.decrypt(encrypted_data)
    """
    data = prepare_data(data)
    return self._apply_action(
        data=data,
        fields=None,
        action=self.provider.decrypt,
        provider_options=provider_options or {},
        dynamic_mask=None,
        custom_mask=None,
        regex_pattern=None,
        mask_format=None,
        **encryption_context,
    )

encrypt ¶

encrypt(data: dict | Mapping | Sequence | Number, provider_options: dict | None = None, **encryption_context: str) -> str

Encrypt data using the configured encryption provider.

PARAMETER	DESCRIPTION
`data`	The data to encrypt. TYPE: `dict, Mapping, Sequence, or Number`
`provider_options`	Provider-specific options for encryption. TYPE: `dict` DEFAULT: `None`
`**encryption_context`	Additional key-value pairs for encryption context. TYPE: `str` DEFAULT: `{}`

RETURNS	DESCRIPTION
`str`	The encrypted data as a base64-encoded string.

Example

encryption_provider = AWSEncryptionSDKProvider(keys=[KMS_KEY_ARN])
data_masker = DataMasking(provider=encryption_provider)
encrypted = data_masker.encrypt({"secret": "value"})

Source code in aws_lambda_powertools/utilities/data_masking/base.py

def encrypt(
    self,
    data: dict | Mapping | Sequence | Number,
    provider_options: dict | None = None,
    **encryption_context: str,
) -> str:
    """
    Encrypt data using the configured encryption provider.

    Parameters
    ----------
    data : dict, Mapping, Sequence, or Number
        The data to encrypt.
    provider_options : dict, optional
        Provider-specific options for encryption.
    **encryption_context : str
        Additional key-value pairs for encryption context.

    Returns
    -------
    str
        The encrypted data as a base64-encoded string.

    Example
    --------

        encryption_provider = AWSEncryptionSDKProvider(keys=[KMS_KEY_ARN])
        data_masker = DataMasking(provider=encryption_provider)
        encrypted = data_masker.encrypt({"secret": "value"})
    """
    data = prepare_data(data)
    return self._apply_action(
        data=data,
        fields=None,
        action=self.provider.encrypt,
        provider_options=provider_options or {},
        dynamic_mask=None,
        custom_mask=None,
        regex_pattern=None,
        mask_format=None,
        **encryption_context,
    )

erase ¶

erase(data: Any, fields: list[str] | None = None, *, dynamic_mask: bool | None = None, custom_mask: str | None = None, regex_pattern: str | None = None, mask_format: str | None = None, masking_rules: dict | None = None) -> Any

Erase or mask sensitive data in the input.

PARAMETER	DESCRIPTION
`data`	The data to be erased or masked. TYPE: `Any`
`fields`	List of field names to be erased or masked. TYPE: `list of str` DEFAULT: `None`
`dynamic_mask`	Whether to use dynamic masking. TYPE: `bool` DEFAULT: `None`
`custom_mask`	Custom mask to apply instead of the default. TYPE: `str` DEFAULT: `None`
`regex_pattern`	Regular expression pattern for identifying data to mask. TYPE: `str` DEFAULT: `None`
`mask_format`	Format string for the mask. TYPE: `str` DEFAULT: `None`
`masking_rules`	Dictionary of custom masking rules. TYPE: `dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`Any`	The data with sensitive information erased or masked.

Source code in aws_lambda_powertools/utilities/data_masking/base.py

def erase(
    self,
    data: Any,
    fields: list[str] | None = None,
    *,
    dynamic_mask: bool | None = None,
    custom_mask: str | None = None,
    regex_pattern: str | None = None,
    mask_format: str | None = None,
    masking_rules: dict | None = None,
) -> Any:
    """
    Erase or mask sensitive data in the input.

    Parameters
    ----------
    data : Any
        The data to be erased or masked.
    fields : list of str, optional
        List of field names to be erased or masked.
    dynamic_mask : bool, optional
        Whether to use dynamic masking.
    custom_mask : str, optional
        Custom mask to apply instead of the default.
    regex_pattern : str, optional
        Regular expression pattern for identifying data to mask.
    mask_format : str, optional
        Format string for the mask.
    masking_rules : dict, optional
        Dictionary of custom masking rules.

    Returns
    -------
    Any
        The data with sensitive information erased or masked.
    """
    if fields and masking_rules:
        raise DataMaskingError(
            "fields and masking_rules cannot be used together: use masking_rules alone to mask fields "
            "with different rules, or fields with the mask options for a single rule.",
        )

    data = prepare_data(data)
    if masking_rules:
        return self._apply_masking_rules(data=data, masking_rules=masking_rules)
    else:
        return self._apply_action(
            data=data,
            fields=fields,
            action=self.provider.erase,
            dynamic_mask=dynamic_mask,
            custom_mask=custom_mask,
            regex_pattern=regex_pattern,
            mask_format=mask_format,
        )

prepare_data ¶

prepare_data(data: Any, _visited: set[int] | None = None) -> Any

Recursively convert complex objects into dictionaries or simple types.

Handles dataclasses, Pydantic models, objects with __dict__ or __slots__, and prevents circular references. _visited holds only the ancestors of the current recursion path, so the same object referenced twice in a structure is converted twice instead of being mistaken for a cycle.

Source code in aws_lambda_powertools/utilities/data_masking/base.py

def prepare_data(data: Any, _visited: set[int] | None = None) -> Any:
    """
    Recursively convert complex objects into dictionaries or simple types.

    Handles dataclasses, Pydantic models, objects with ``__dict__`` or ``__slots__``,
    and prevents circular references. ``_visited`` holds only the ancestors of the current
    recursion path, so the same object referenced twice in a structure is converted twice
    instead of being mistaken for a cycle.
    """
    if isinstance(data, (str, int, float, bool, type(None))):
        return data

    _visited = set() if _visited is None else _visited
    data_id = id(data)
    if data_id in _visited:
        return data

    _visited.add(data_id)
    try:
        return _convert(data, _visited)
    finally:
        _visited.discard(data_id)