clear-skies-aws 2.0.11__py3-none-any.whl → 2.0.13__py3-none-any.whl

clearskies_aws/secrets/cache_storage/parameter_store_cache.py

@@ -0,0 +1,118 @@
+"""
+AWS Parameter Store implementation of SecretCache.
+
+This module provides a cache storage backend using AWS Systems Manager Parameter Store.
+"""
+
+from __future__ import annotations
+
+from clearskies.configs import Boolean, String
+from clearskies.decorators import parameters_to_properties
+from clearskies.di.inject import ByClass
+from clearskies.secrets.cache_storage import SecretCache
+
+from clearskies_aws.di import inject
+from clearskies_aws.secrets import parameter_store
+
+
+class ParameterStoreCache(SecretCache):
+    """
+    Cache storage backend using AWS Systems Manager Parameter Store.
+
+    This class implements the SecretCache interface to store cached secrets in AWS
+    Parameter Store. Paths are automatically sanitized by the underlying ParameterStore
+    to comply with SSM parameter naming requirements.
+
+    ### Example Usage
+
+    ```python
+    from clearskies.secrets import Akeyless
+    from clearskies_aws.secrets.secrets_cache import ParameterStoreCache
+
+    cache = ParameterStoreCache(prefix="/cache/secrets")
+    akeyless = Akeyless(
+        access_id="p-xxx",
+        access_type="aws_iam",
+        cache_storage=cache,
+    )
+
+    # First call fetches from Akeyless and caches in Parameter Store
+    secret = akeyless.get("/path/to/secret")
+
+    # Subsequent calls return from Parameter Store cache
+    secret = akeyless.get("/path/to/secret")
+
+    # Force refresh bypasses cache
+    secret = akeyless.get("/path/to/secret", refresh=True)
+    ```
+    """
+
+    boto3 = inject.Boto3()
+
+    parameter_store = ByClass(parameter_store.ParameterStore)
+
+    prefix = String(default=None)
+    allow_cleanup = Boolean(default=False)
+
+    @parameters_to_properties
+    def __init__(self, prefix: str | None = None, allow_cleanup: bool = False):
+        """
+        Initialize the Parameter Store cache.
+
+        The prefix is prepended to all secret paths when storing in Parameter Store.
+        This helps organize cached secrets and avoid conflicts with other parameters.
+        """
+        super().__init__()
+
+    def _build_path(self, path: str) -> str:
+        """
+        Build the full parameter path by prepending the prefix.
+
+        The path is sanitized by the underlying ParameterStore.
+        """
+        return f"{self.prefix}/{path.lstrip('/')}"
+
+    def get(self, path: str) -> str | None:
+        """
+        Retrieve a cached secret value from Parameter Store.
+
+        Returns the cached secret value for the given path, or None if not found.
+        """
+        ssm_name = self._build_path(path)
+        return self.parameter_store.get(ssm_name, silent_if_not_found=True)
+
+    def set(self, path: str, value: str, ttl: int | None = None) -> None:
+        """
+        Store a secret value in Parameter Store.
+
+        Stores the secret value as a SecureString parameter. Note that Parameter Store
+        does not natively support TTL, so the ttl parameter is ignored. Consider using
+        a cleanup process or Lambda function to remove stale cached secrets.
+        """
+        ssm_name = self._build_path(path)
+        self.parameter_store.update(ssm_name, value)
+
+    def delete(self, path: str) -> None:
+        """
+        Remove a secret from the Parameter Store cache.
+
+        Deletes the parameter at the given path. Does nothing if the parameter
+        doesn't exist.
+        """
+        ssm_name = self._build_path(path)
+        self.parameter_store.delete(ssm_name)
+
+    def clear(self) -> None:
+        """
+        Remove all cached secrets from Parameter Store under the configured prefix.
+
+        This method deletes all parameters under the cache prefix. Use with caution
+        in production environments.
+        """
+        if not self.allow_cleanup:
+            raise RuntimeError(
+                "Clearing the Parameter Store cache is not allowed. Set allow_cleanup=True to enable this operation."
+            )
+        names = self.parameter_store.list_by_path(self.prefix, recursive=True)
+        if names:
+            self.parameter_store.delete_many(names)

clearskies_aws/secrets/parameter_store.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+import re
+from typing import Any
+
 from botocore.exceptions import ClientError
 from clearskies.exceptions.not_found import NotFound
 from types_boto3_ssm import SSMClient
@@ -7,19 +10,84 @@ from types_boto3_ssm import SSMClient
 from clearskies_aws.secrets import secrets
 
 
-class ParameterStore(secrets.Secrets):
+class ParameterStore(secrets.Secrets[SSMClient]):
+    """
+    Backend for managing secrets using AWS Systems Manager Parameter Store.
+
+    This class provides integration with AWS SSM Parameter Store, allowing you to store,
+    retrieve, update, and delete secrets. All values are stored as SecureString by default
+    for security.
+
+    Paths are automatically sanitized to comply with SSM parameter naming requirements.
+    AWS SSM parameter paths only allow: a-z, A-Z, 0-9, -, _, ., /, @, and :
+    Any disallowed characters in the path are replaced with hyphens.
+
+    ### Example Usage
+
+    ```python
+    from clearskies_aws.secrets import ParameterStore
+
+    secrets = ParameterStore()
+
+    # Create/update a secret (stored as SecureString)
+    secrets.update("/my-app/database-password", "super-secret")
+
+    # Get a secret
+    password = secrets.get("/my-app/database-password")
+
+    # Delete a secret
+    secrets.delete("/my-app/database-password")
+    ```
+    """
+
     ssm: SSMClient
 
     def __init__(self):
+        """Initialize the Parameter Store backend."""
         super().__init__()
-        self.ssm = self.boto3.client("ssm", region_name=self.environment.get("AWS_REGION"))
+
+    def _sanitize_path(self, path: str) -> str:
+        """
+        Sanitize a secret path for use as an SSM parameter name.
+
+        AWS SSM parameter paths only allow a-z, A-Z, 0-9, -, _, ., /, @, and :
+        Any disallowed characters are replaced with hyphens.
+        """
+        return re.sub(r"[^a-zA-Z0-9\-_\./@:]", "-", path)
+
+    @property
+    def boto3_client(self) -> SSMClient:
+        """
+        Return the boto3 SSM client.
+
+        Creates a new client if one doesn't exist yet, using the AWS_REGION environment variable.
+        """
+        if hasattr(self, "ssm"):
+            return self.ssm
+        self.ssm = self.boto3.client(
+            "ssm",
+            region_name=self.environment.get("AWS_REGION"),
+        )
+        return self.ssm
 
     def create(self, path: str, value: str) -> bool:
+        """
+        Create a new parameter in Parameter Store.
+
+        This is an alias for update() since Parameter Store uses upsert semantics.
+        """
         return self.update(path, value)
 
     def get(self, path: str, silent_if_not_found: bool = False) -> str | None:  # type: ignore[override]
+        """
+        Retrieve a parameter value from Parameter Store.
+
+        Returns the decrypted parameter value for the given path. If silent_if_not_found
+        is True, returns None when the parameter is not found instead of raising NotFound.
+        """
+        sanitized_path = self._sanitize_path(path)
         try:
-            result = self.ssm.get_parameter(Name=path, WithDecryption=True)
+            result = self.boto3_client.get_parameter(Name=sanitized_path, WithDecryption=True)
         except ClientError as e:
             error = e.response.get("Error", {})
             if error.get("Code") == "ResourceNotFoundException":
@@ -30,23 +98,91 @@ class ParameterStore(secrets.Secrets):
         return result["Parameter"].get("Value", "")
 
     def list_secrets(self, path: str) -> list[str]:
-        response = self.ssm.get_parameters_by_path(Path=path, Recursive=False)
+        """
+        List parameters at the given path.
+
+        Returns a list of parameter names at the specified path (non-recursive).
+        """
+        sanitized_path = self._sanitize_path(path)
+        response = self.boto3_client.get_parameters_by_path(Path=sanitized_path, Recursive=False)
         return [parameter["Name"] for parameter in response["Parameters"] if "Name" in parameter]
 
     def update(self, path: str, value: str) -> bool:  # type: ignore[override]
-        response = self.ssm.put_parameter(
-            Name=path,
+        """
+        Update or create a secret as a SecureString.
+
+        Creates the parameter if it doesn't exist, or updates it if it does.
+        The value is stored as an encrypted SecureString using the default KMS key.
+        """
+        sanitized_path = self._sanitize_path(path)
+        self.boto3_client.put_parameter(
+            Name=sanitized_path,
             Value=value,
-            Type="String",
+            Type="SecureString",
             Overwrite=True,
         )
         return True
 
     def upsert(self, path: str, value: str) -> bool:  # type: ignore[override]
+        """
+        Create or update a secret.
+
+        This is an alias for update() since Parameter Store uses upsert semantics.
+        """
         return self.update(path, value)
 
+    def delete(self, path: str) -> bool:
+        """
+        Delete a parameter from Parameter Store.
+
+        Returns True if the parameter was deleted, False if it didn't exist.
+        """
+        sanitized_path = self._sanitize_path(path)
+        try:
+            self.boto3_client.delete_parameter(Name=sanitized_path)
+            return True
+        except ClientError as e:
+            error = e.response.get("Error", {})
+            if error.get("Code") == "ParameterNotFound":
+                return False
+            raise e
+
+    def delete_many(self, paths: list[str]) -> bool:
+        """
+        Delete multiple parameters from Parameter Store.
+
+        Deletes up to 10 parameters at a time (SSM limit). For larger lists,
+        recursively calls itself to delete in batches.
+        """
+        if not paths:
+            return True
+        sanitized_paths = [self._sanitize_path(p) for p in paths]
+        self.boto3_client.delete_parameters(Names=sanitized_paths[:10])
+        if len(sanitized_paths) > 10:
+            return self.delete_many(paths[10:])
+        return True
+
+    def list_by_path(self, path: str, recursive: bool = True) -> list[str]:
+        """
+        List all parameter names under a given path.
+
+        Returns a list of parameter names (not values) under the specified path.
+        Uses pagination to handle large result sets.
+        """
+        sanitized_path = self._sanitize_path(path)
+        names: list[str] = []
+        paginator = self.boto3_client.get_paginator("get_parameters_by_path")
+        for page in paginator.paginate(Path=sanitized_path, Recursive=recursive):
+            names.extend([param["Name"] for param in page.get("Parameters", [])])
+        return names
+
     def list_sub_folders(
         self,
         path: str,
-    ) -> list[str]:  # type: ignore[override]
+    ) -> list[Any]:
+        """
+        List sub-folders at the given path.
+
+        This operation is not supported by Parameter Store.
+        """
         raise NotImplementedError("Parameter store doesn't support list_sub_folders.")

clearskies_aws/secrets/secrets.py

@@ -1,12 +1,24 @@
 from __future__ import annotations
 
+import profile
+from typing import Generic, Protocol, TypeVar
+
 from clearskies.di.inject import Di, Environment
 from clearskies.secrets import Secrets as BaseSecrets
 
 from clearskies_aws.di import inject
 
 
-class Secrets(BaseSecrets):
+class Boto3Client(Protocol):
+    """Protocol for boto3 clients to enable type-safe generic return types."""
+
+    ...
+
+
+ClientT = TypeVar("ClientT", bound=Boto3Client)
+
+
+class Secrets(BaseSecrets, Generic[ClientT]):
     boto3 = inject.Boto3()
     environment = Environment()
 
@@ -14,3 +26,8 @@ class Secrets(BaseSecrets):
         super().__init__()
         if not self.environment.get("AWS_REGION", True):
             raise ValueError("To use secrets manager you must use set the 'AWS_REGION' environment variable")
+
+    @property
+    def boto3_client(self) -> ClientT:
+        """Return the boto3 client for the secrets manager implementation."""
+        raise NotImplementedError("You must implement the client property in subclasses")

clearskies_aws/secrets/secrets_manager.py

@@ -10,21 +10,69 @@ from types_boto3_secretsmanager.type_defs import SecretListEntryTypeDef
 from clearskies_aws.secrets import secrets
 
 
-class SecretsManager(secrets.Secrets):
+class SecretsManager(secrets.Secrets[SecretsManagerClient]):
+    """
+    Backend for managing secrets using AWS Secrets Manager.
+
+    This class provides integration with AWS Secrets Manager, allowing you to store,
+    retrieve, update, and delete secrets. It supports versioning and KMS encryption.
+
+    ### Example Usage
+
+    ```python
+    from clearskies_aws.secrets import SecretsManager
+
+    secrets = SecretsManager()
+
+    # Create a new secret
+    secrets.create("my-app/database-password", "super-secret-password")
+
+    # Get a secret
+    password = secrets.get("my-app/database-password")
+
+    # Update a secret
+    secrets.update("my-app/database-password", "new-password")
+
+    # Delete a secret
+    secrets.delete("my-app/database-password")
+    ```
+    """
+
     secrets_manager: SecretsManagerClient
 
     def __init__(self):
+        """Initialize the Secrets Manager backend."""
         super().__init__()
-        self.secrets_manager = self.boto3.client("secretsmanager", region_name=self.environment.get("AWS_REGION"))
+
+    @property
+    def boto3_client(self) -> SecretsManagerClient:
+        """
+        Return the boto3 Secrets Manager client.
+
+        Creates a new client if one doesn't exist yet, using the AWS_REGION environment variable.
+        """
+        if hasattr(self, "secrets_manager"):
+            return self.secrets_manager
+        self.secrets_manager = self.boto3.client(
+            "secretsmanager",
+            region_name=self.environment.get("AWS_REGION"),
+        )
+        return self.secrets_manager
 
     def create(self, secret_id: str, value: Any, kms_key_id: str | None = None) -> bool:
+        """
+        Create a new secret in Secrets Manager.
+
+        Creates a new secret with the given ID and value. Optionally encrypts the secret
+        with a custom KMS key. Returns True if the secret was created successfully.
+        """
         calling_parameters = {
             "SecretId": secret_id,
             "SecretString": value,
             "KmsKeyId": kms_key_id,
         }
         calling_parameters = {key: value for (key, value) in calling_parameters.items() if value}
-        result = self.secrets_manager.create_secret(**calling_parameters)
+        result = self.boto3_client.create_secret(**calling_parameters)
         return bool(result.get("ARN"))
 
     def get(  # type: ignore[override]
@@ -34,6 +82,13 @@ class SecretsManager(secrets.Secrets):
         version_stage: str | None = None,
         silent_if_not_found: bool = False,
     ) -> str | bytes | None:
+        """
+        Retrieve a secret value from Secrets Manager.
+
+        Returns the secret value for the given ID. Optionally retrieves a specific version
+        by version_id or version_stage. If silent_if_not_found is True, returns None when
+        the secret is not found instead of raising NotFound.
+        """
         calling_parameters = {"SecretId": secret_id}
 
         # Only add optional parameters if they are not None
@@ -43,7 +98,7 @@ class SecretsManager(secrets.Secrets):
             calling_parameters["VersionStage"] = version_stage
 
         try:
-            result = self.secrets_manager.get_secret_value(**calling_parameters)
+            result = self.boto3_client.get_secret_value(**calling_parameters)
         except ClientError as e:
             error = e.response.get("Error", {})
             if error.get("Code") == "ResourceNotFoundException":
@@ -58,7 +113,12 @@ class SecretsManager(secrets.Secrets):
         return result.get("SecretBinary")
 
     def list_secrets(self, path: str) -> list[SecretListEntryTypeDef]:  # type: ignore[override]
-        results = self.secrets_manager.list_secrets(
+        """
+        List secrets matching the given path filter.
+
+        Returns a list of secret metadata entries that match the path filter.
+        """
+        results = self.boto3_client.list_secrets(
             Filters=[
                 {
                     "Key": "name",
@@ -69,6 +129,12 @@ class SecretsManager(secrets.Secrets):
         return results["SecretList"]
 
     def update(self, secret_id: str, value: str, kms_key_id: str | None = None) -> bool:  # type: ignore[override]
+        """
+        Update an existing secret's value.
+
+        Updates the secret with the given ID to the new value. Optionally re-encrypts
+        with a different KMS key. Returns True if the update was successful.
+        """
         calling_parameters = {
             "SecretId": secret_id,
             "SecretString": value,
@@ -77,10 +143,16 @@ class SecretsManager(secrets.Secrets):
             # If no KMS key is provided, we should not include it in the parameters
             calling_parameters["KmsKeyId"] = kms_key_id
 
-        result = self.secrets_manager.update_secret(**calling_parameters)
+        result = self.boto3_client.update_secret(**calling_parameters)
         return bool(result.get("ARN"))
 
     def upsert(self, secret_id: str, value: str, kms_key_id: str | None = None) -> bool:  # type: ignore[override]
+        """
+        Create or update a secret value.
+
+        Creates a new version of the secret with the given value. This is useful for
+        rotating secrets. Returns True if the operation was successful.
+        """
         calling_parameters = {
             "SecretId": secret_id,
             "SecretString": value,
@@ -89,8 +161,33 @@ class SecretsManager(secrets.Secrets):
             # If no KMS key is provided, we should not include it in the parameters
             calling_parameters["KmsKeyId"] = kms_key_id
 
-        result = self.secrets_manager.put_secret_value(**calling_parameters)
+        result = self.boto3_client.put_secret_value(**calling_parameters)
         return bool(result.get("ARN"))
 
+    def delete(self, secret_id: str, force_delete: bool = False) -> bool:
+        """
+        Delete a secret from Secrets Manager.
+
+        If force_delete is True, the secret is deleted immediately without recovery window.
+        Otherwise, the secret is scheduled for deletion with a 7-day recovery window.
+        Returns True if the secret was deleted, False if it didn't exist.
+        """
+        try:
+            if force_delete:
+                self.boto3_client.delete_secret(SecretId=secret_id, ForceDeleteWithoutRecovery=True)
+            else:
+                self.boto3_client.delete_secret(SecretId=secret_id)
+            return True
+        except ClientError as e:
+            error = e.response.get("Error", {})
+            if error.get("Code") == "ResourceNotFoundException":
+                return False
+            raise e
+
     def list_sub_folders(self, path: str, value: str) -> list[str]:  # type: ignore[override]
+        """
+        List sub-folders at the given path.
+
+        This operation is not supported by Secrets Manager.
+        """
         raise NotImplementedError("Secrets Manager doesn't support list_sub_folders.")

clearskies_aws/secrets/additional_configs/__init__.py

@@ -1,62 +0,0 @@
-from .iam_db_auth import IAMDBAuth
-from .iam_db_auth_with_ssm import IAMDBAuthWithSSM
-from .mysql_connection_dynamic_producer_via_ssh_cert_bastion import MySQLConnectionDynamicProducerViaSSHCertBastion
-from .mysql_connection_dynamic_producer_via_ssm_bastion import MySQLConnectionDynamicProducerViaSSMBastion
-
-
-def mysql_connection_dynamic_producer_via_ssh_cert_bastion(
-    producer_name=None,
-    bastion_host=None,
-    bastion_name=None,
-    bastion_region=None,
-    bastion_username=None,
-    public_key_file_path=None,
-    cert_issuer_name=None,
-    database_host=None,
-    database_name=None,
-    local_proxy_port=None,
-):
-    return MySQLConnectionDynamicProducerViaSSHCertBastion(
-        producer_name=producer_name,
-        bastion_host=bastion_host,
-        bastion_name=bastion_name,
-        bastion_region=bastion_region,
-        bastion_username=bastion_username,
-        cert_issuer_name=cert_issuer_name,
-        public_key_file_path=public_key_file_path,
-        database_host=database_host,
-        database_name=database_name,
-        local_proxy_port=local_proxy_port,
-    )
-
-
-def mysql_connection_dynamic_producer_via_ssm_bastion(
-    producer_name=None,
-    bastion_instance_id=None,
-    bastion_name=None,
-    bastion_region=None,
-    bastion_username=None,
-    public_key_file_path=None,
-    database_host=None,
-    database_name=None,
-    local_proxy_port=None,
-):
-    return MySQLConnectionDynamicProducerViaSSMBastion(
-        producer_name=producer_name,
-        bastion_instance_id=bastion_instance_id,
-        bastion_name=bastion_name,
-        bastion_region=bastion_region,
-        bastion_username=bastion_username,
-        public_key_file_path=public_key_file_path,
-        database_host=database_host,
-        database_name=database_name,
-        local_proxy_port=local_proxy_port,
-    )
-
-
-def iam_db_auth():
-    return IAMDBAuth()
-
-
-def iam_db_auth_with_ssm():
-    return IAMDBAuthWithSSM()

clearskies_aws/secrets/additional_configs/iam_db_auth.py

@@ -1,39 +0,0 @@
-from __future__ import annotations
-
-import os
-
-import clearskies
-
-
-class IAMDBAuth(clearskies.di.AdditionalConfig):
-    def provide_boto3(self):
-        import boto3
-
-        return boto3
-
-    def provide_connection_details(self, environment, boto3):
-        """
-        Make configuration values and environment variables customizable.
-
-        Allows both the values and the environment variable names to be set for flexible configuration.
-
-        Returns:
-            dict: Connection details for IAM DB authentication.
-        """
-        endpoint = environment.get("db_endpoint")
-        username = environment.get("db_username")
-        database = environment.get("db_database")
-        region = environment.get("AWS_REGION")
-        ssl_ca_bundle_name = environment.get("ssl_ca_bundle_filename")
-        os.environ["LIBMYSQL_ENABLE_CLEARTEXT_PLUGIN"] = "1"
-
-        rds_api = boto3.Session().client("rds")
-        rds_token = rds_api.generate_db_auth_token(DBHostname=endpoint, Port="3306", DBUsername=username, Region=region)
-
-        return {
-            "username": username,
-            "password": rds_token,
-            "host": endpoint,
-            "database": database,
-            "ssl_ca": ssl_ca_bundle_name,
-        }