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

{clear_skies_aws-2.0.12.dist-info → clear_skies_aws-2.0.13.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clear-skies-aws
-Version: 2.0.12
+Version: 2.0.13
 Summary: clearskies bindings for working in AWS
 Project-URL: Repository, https://github.com/clearskies-py/clearskies-aws
 Project-URL: Issues, https://github.com/clearskies-py/clearskies-aws/issues
@@ -17,7 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: <4.0,>=3.11
 Requires-Dist: awslambdaric>=3.1.1
 Requires-Dist: boto3<2.0.0,>=1.26.148
-Requires-Dist: clear-skies<3.0.0,>=2.0.37
+Requires-Dist: clear-skies<3.0.0,>=2.0.39
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: types-boto3[dynamodb,secretsmanager,ses,sns,sqs,ssm,stepfunctions]<2.0.0,>=1.38.13
 Provides-Extra: akeyless

{clear_skies_aws-2.0.12.dist-info → clear_skies_aws-2.0.13.dist-info}/RECORD

@@ -29,7 +29,7 @@ clearskies_aws/cursors/port_forwarding/__init__.py,sha256=LBcFYeIIfmGhxf3Ezn1KCh
 clearskies_aws/cursors/port_forwarding/ssm.py,sha256=2tEznKflMG5a8g1AzHWghHkMp4BdBFhewB8WigFR5F4,4878
 clearskies_aws/di/__init__.py,sha256=pLHSIKxS1oELOgttRuwM0yXdJRxjZKXQ6tPxme2db0U,222
 clearskies_aws/di/aws_additional_config_auto_import.py,sha256=94h_YsPBcdwMhqn0VAAfId1jLL5vCsk76kUrr-6ET_U,1275
-clearskies_aws/di/inject/__init__.py,sha256=5_x5_BBQwC6J4k5YLdTm1DfIDM-95zXz1L5a1nMrlrY,186
+clearskies_aws/di/inject/__init__.py,sha256=uuQlXuGgVH1rwMeQtIEQS9NiVjSHm4H4WkctWIakPS8,272
 clearskies_aws/di/inject/boto3.py,sha256=yUDiEpR2Si6pKcLrqMOlQEUU0pi6MS1tXNdoyC2mjwk,408
 clearskies_aws/di/inject/boto3_session.py,sha256=11UYHz5kgrrx5lawoYaOFBm-QIoa45YUCMAOn4gT8Jo,383
 clearskies_aws/di/inject/parameter_store.py,sha256=g0uAVwQEywLO9bCcYLbDKuyYnYgVyrfcYsOBJWYGads,475
@@ -54,17 +54,13 @@ clearskies_aws/mocks/actions/sqs.py,sha256=y0Vq7IMbjlfT5JMNHfbPsq9XVZhUF-G0kdXzQ
 clearskies_aws/mocks/actions/step_function.py,sha256=ENEVy8Ai3vPymbQre5aWa5z2McBjlnopfsLxdO7oEbc,937
 clearskies_aws/models/__init__.py,sha256=tAU5cPGRSzSClNVRCBxzwlBq6eZO8fftuI3bG1jEyVQ,87
 clearskies_aws/models/web_socket_connection_model.py,sha256=5M1qfQHKuWMYPUDkwT48QPo2ROey7koizvWLfapsfow,7492
-clearskies_aws/secrets/__init__.py,sha256=0mqYja2ETBHJh4b3jgRhhJV1uGdZc9S7cUvcV5QByPs,445
-clearskies_aws/secrets/akeyless_with_ssm_cache.py,sha256=32HUS1KQ5F6Fu70HDtojqDL7VZvP_YDgbWLTTmNJvPA,2073
-clearskies_aws/secrets/parameter_store.py,sha256=nMpkbUnxHGcCoMD5T-weCS13f1RZA7ZHl24O7qXaZLE,1882
-clearskies_aws/secrets/secrets.py,sha256=aDMPj-tuXdRhh8YKMnsJe9V_VLrD8Cru-xUKs8cyDIY,485
-clearskies_aws/secrets/secrets_manager.py,sha256=hK10lVmEFJltTv7h2AkYR3ySCVXx1JVy56jWU1hyYso,3708
-clearskies_aws/secrets/additional_configs/__init__.py,sha256=0NFOMVod8tte_K0Jq1Qf7_DDBvp6aEE4wF4hddQaW8w,1927
-clearskies_aws/secrets/additional_configs/iam_db_auth.py,sha256=PwyiLaacpRfhBKzQBdvGWHUYf5Ymth1sG2ly7Z6RoR0,1238
-clearskies_aws/secrets/additional_configs/iam_db_auth_with_ssm.py,sha256=ABY29X-YvrE6vvNo6kVdf4DqyRNq5cFR5SfK7MNkltE,3463
-clearskies_aws/secrets/additional_configs/mysql_connection_dynamic_producer_via_ssh_cert_bastion.py,sha256=mLaplwvJLSbGh6oXgdOKL9Mv-6hLv5OUYCfEwHbHvLE,3700
-clearskies_aws/secrets/additional_configs/mysql_connection_dynamic_producer_via_ssm_bastion.py,sha256=2VHOwto4I9gBwrpd2HGpL-Wr0T2S-jFjUhe2Ib8hNJ8,6596
-clear_skies_aws-2.0.12.dist-info/METADATA,sha256=Peh_b5gfQkU62yNOdIGRsPWVpVXsyGS0YeQGKZgcWe8,9077
-clear_skies_aws-2.0.12.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-clear_skies_aws-2.0.12.dist-info/licenses/LICENSE,sha256=MkEX8JF8kZxdyBpTTcB0YTd-xZpWnHvbRlw-pQh8u58,1069
-clear_skies_aws-2.0.12.dist-info/RECORD,,
+clearskies_aws/secrets/__init__.py,sha256=5QWfe6IyHdAyfOJVZJ52qM5hTkw1siMJ6q6YW95-Jl8,345
+clearskies_aws/secrets/parameter_store.py,sha256=abeG72LdOdx1WxZpjph2b3T9E7ClXqAYqQ9mxoHI2VQ,6565
+clearskies_aws/secrets/secrets.py,sha256=P30Yx0pkxjPnwCNw8ixoUu--4B7EEsg6gpOlazrk4Oc,956
+clearskies_aws/secrets/secrets_manager.py,sha256=VhqKw4W65y3RRoFt9Ws5g7Q8nv2ACqkDYwxwgRpU-sk,7026
+clearskies_aws/secrets/cache_storage/__init__.py,sha256=A6_rUn95NQjJu_VDDNQ1mDDNye18QYGGhXM66orGnb8,255
+clearskies_aws/secrets/cache_storage/parameter_store_cache.py,sha256=k2FVmFepZgssvsGuiAj0t3M56K5ZIVqmsRfTLlQFDWk,4028
+clear_skies_aws-2.0.13.dist-info/METADATA,sha256=JOWiWVeM4tWzx2NeijR9B9Ihv3Zakh5BvrewvhyzpEU,9077
+clear_skies_aws-2.0.13.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+clear_skies_aws-2.0.13.dist-info/licenses/LICENSE,sha256=MkEX8JF8kZxdyBpTTcB0YTd-xZpWnHvbRlw-pQh8u58,1069
+clear_skies_aws-2.0.13.dist-info/RECORD,,

clearskies_aws/di/inject/__init__.py

@@ -2,5 +2,6 @@ from __future__ import annotations
 
 from clearskies_aws.di.inject.boto3 import Boto3
 from clearskies_aws.di.inject.boto3_session import Boto3Session
+from clearskies_aws.di.inject.parameter_store import ParameterStore
 
-__all__ = ["Boto3", "Boto3Session"]
+__all__ = ["Boto3", "Boto3Session", "ParameterStore"]

clearskies_aws/secrets/__init__.py

@@ -1,5 +1,6 @@
-from clearskies_aws.secrets import additional_configs
-from clearskies_aws.secrets.akeyless_with_ssm_cache import AkeylessWithSsmCache
+import importlib
+
+from clearskies_aws.secrets import cache_storage
 from clearskies_aws.secrets.parameter_store import ParameterStore
 from clearskies_aws.secrets.secrets import Secrets
 from clearskies_aws.secrets.secrets_manager import SecretsManager
@@ -8,6 +9,5 @@ __all__ = [
     "Secrets",
     "ParameterStore",
     "SecretsManager",
-    "AkeylessWithSsmCache",
-    "additional_configs",
+    "cache_storage",
 ]

clearskies_aws/secrets/cache_storage/__init__.py

@@ -0,0 +1,9 @@
+"""
+AWS-specific secret cache implementations.
+
+This module provides cache storage backends for secrets using AWS services.
+"""
+
+from clearskies_aws.secrets.cache_storage.parameter_store_cache import ParameterStoreCache
+
+__all__ = ["ParameterStoreCache"]

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,
-        }

clearskies_aws/secrets/additional_configs/iam_db_auth_with_ssm.py

@@ -1,96 +0,0 @@
-from __future__ import annotations
-
-import time
-
-import clearskies
-
-
-class IAMDBAuthWithSSM(clearskies.di.AdditionalConfig):
-    def provide_subprocess(self):
-        import subprocess
-
-        return subprocess
-
-    def provide_socket(self):
-        import socket
-
-        return socket
-
-    def provide_connection_details(self, environment, subprocess, socket, boto3):
-        local_port = self.open_tunnel(environment, subprocess, socket, boto3)
-
-        return {
-            "host": "127.0.0.1",
-            "database": environment.get("db_database"),
-            "username": environment.get("db_username"),
-            "password": self.get_password(environment, boto3),
-            "ssl_ca": "rds-cert-bundle.pem",
-            "port": local_port,
-        }
-
-    def get_password(self, environment, boto3):
-        endpoint = environment.get("db_endpoint")
-        username = environment.get("db_username")
-        region = environment.get("db_region")
-
-        rds_api = boto3.Session().client("rds", region_name=region)
-        return rds_api.generate_db_auth_token(DBHostname=endpoint, Port="3306", DBUsername=username, Region=region)
-
-    def open_tunnel(self, environment, subprocess, socket, boto3):
-        endpoint = environment.get("db_endpoint")
-        region = environment.get("db_region")
-        instance_name = environment.get("instance_name")
-        local_proxy_port = int(environment.get("local_proxy_port", "9000"))
-
-        ec2_api = boto3.client("ec2", region_name=region)
-        running_instances = ec2_api.describe_instances(
-            Filters=[
-                {"Name": "tag:Name", "Values": [instance_name]},
-                {"Name": "instance-state-name", "Values": ["running"]},
-            ],
-        )
-        instance_ids = []
-        for reservation in running_instances["Reservations"]:
-            for instance in reservation["Instances"]:
-                instance_ids.append(instance["InstanceId"])
-
-        if len(instance_ids) == 0:
-            raise ValueError("Failed to launch SSM tunnel! Cannot find bastion!")
-
-        instance_id = instance_ids.pop()
-        self._connect_to_bastion(local_proxy_port, instance_id, endpoint, subprocess, socket)
-        return local_proxy_port
-
-    def _connect_to_bastion(self, local_proxy_port, instance_id, endpoint, subprocess, socket):
-        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        result = sock.connect_ex(("127.0.0.1", local_proxy_port))
-        if result == 0:
-            sock.close()
-            return
-
-        tunnel_command = [
-            "aws",
-            "--region",
-            "us-east-1",
-            "ssm",
-            "start-session",
-            "--target",
-            "{}".format(instance_id),
-            "--document-name",
-            "AWS-StartPortForwardingSessionToRemoteHost",
-            '--parameters={{"host":["{}"], "portNumber":["3306"],"localPortNumber":["{}"]}}'.format(
-                endpoint, local_proxy_port
-            ),
-        ]
-
-        subprocess.Popen(tunnel_command)
-        connected = False
-        attempts = 0
-        while not connected and attempts < 6:
-            attempts += 1
-            time.sleep(0.5)
-            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-            result = sock.connect_ex(("127.0.0.1", local_proxy_port))
-            if result == 0:
-                return
-        raise ValueError("Failed to launch SSM tunnel with command: " + " ".join(tunnel_command))

clearskies_aws/secrets/additional_configs/mysql_connection_dynamic_producer_via_ssh_cert_bastion.py

@@ -1,80 +0,0 @@
-from __future__ import annotations
-
-import os
-import socket
-import subprocess
-import time
-from pathlib import Path
-
-from clearskies.secrets.additional_configs import MySQLConnectionDynamicProducerViaSSHCertBastion as Base
-
-
-class MySQLConnectionDynamicProducerViaSSHCertBastion(Base):
-    _config = None
-    _boto3 = None
-
-    def __init__(
-        self,
-        producer_name=None,
-        bastion_region=None,
-        bastion_name=None,
-        bastion_host=None,
-        bastion_username=None,
-        public_key_file_path=None,
-        local_proxy_port=None,
-        cert_issuer_name=None,
-        database_host=None,
-        database_name=None,
-    ):
-        # not using kwargs because I want the argument list to be explicit
-        self.config = {
-            "producer_name": producer_name,
-            "bastion_host": bastion_host,
-            "bastion_region": bastion_region,
-            "bastion_name": bastion_name,
-            "bastion_username": bastion_username,
-            "public_key_file_path": public_key_file_path,
-            "local_proxy_port": local_proxy_port,
-            "cert_issuer_name": cert_issuer_name,
-            "database_host": database_host,
-            "database_name": database_name,
-        }
-
-    def provide_connection_details(self, environment, secrets, boto3):
-        self._boto3 = boto3
-        return super().provide_connection_details(environment, secrets)
-
-    def _get_bastion_host(self, environment):
-        bastion_host = self._fetch_config(environment, "bastion_host", "akeyless_mysql_bastion_host", default="")
-        bastion_name = self._fetch_config(environment, "bastion_name", "akeyless_mysql_bastion_name", default="")
-        if bastion_host:
-            return bastion_host
-        if bastion_name:
-            bastion_region = self._fetch_config(environment, "bastion_region", "akeyless_mysql_bastion_region")
-            return self._public_ip_from_name(bastion_name, bastion_region)
-        raise ValueError(
-            f"I was asked to connect to a database via an AKeyless dynamic producer through an SSH bastion with certificate auth, but I'm missing some configuration. I need either the bastion host or the name of the instance in AWS.  These can be set in the call to `clearskies.backends.akeyless_aws.mysql_connection_dynamic_producer_via_ssh_cert_bastion()` by providing the 'bastion_host' or 'bastion_name' argument, or by setting an environment variable named 'akeyless_mysql_bastion_host' or 'akeyless_mysql_bastion_name'."
-        )
-
-    def _public_ip_from_name(self, bastion_name, bastion_region):
-        ec2 = self._boto3.client("ec2", region_name=bastion_region)
-        response = ec2.describe_instances(
-            Filters=[
-                {"Name": "tag:Name", "Values": [bastion_name]},
-                {"Name": "instance-state-name", "Values": ["running"]},
-            ],
-        )
-        if not response.get("Reservations"):
-            raise ValueError(
-                f"Could not find a running instance with the designated bastion name, '{bastion_name}' in region '{bastion_region}'"
-            )
-        if not response.get("Reservations")[0].get("Instances"):
-            raise ValueError(
-                f"Could not find a running instance with the designated bastion name, '{bastion_name}' in region '{bastion_region}'"
-            )
-        instance = response.get("Reservations")[0].get("Instances")[0]
-        if not instance.get("PublicIpAddress"):
-            raise ValueError(
-                f"I found the bastion instance with a name of '{bastion_name}' in region '{bastion_region}', but it doesn't have a public IP address"
-            )
-        return instance.get("PublicIpAddress")

clearskies_aws/secrets/additional_configs/mysql_connection_dynamic_producer_via_ssm_bastion.py

@@ -1,162 +0,0 @@
-from __future__ import annotations
-
-import os
-import socket
-import subprocess
-import time
-from pathlib import Path
-
-from .mysql_connection_dynamic_producer_via_ssh_cert_bastion import (
-    MySQLConnectionDynamicProducerViaSSHCertBastion as Base,
-)
-
-
-class MySQLConnectionDynamicProducerViaSSMBastion(Base):
-    _config = None
-    _boto3 = None
-
-    def __init__(
-        self,
-        producer_name=None,
-        bastion_region=None,
-        bastion_name=None,
-        bastion_username=None,
-        bastion_instance_id=None,
-        public_key_file_path=None,
-        local_proxy_port=None,
-        database_host=None,
-        database_name=None,
-    ):
-        # not using kwargs because I want the argument list to be explicit
-        self.config = {
-            "producer_name": producer_name,
-            "bastion_instance_id": bastion_instance_id,
-            "bastion_region": bastion_region,
-            "bastion_name": bastion_name,
-            "bastion_username": bastion_username,
-            "public_key_file_path": public_key_file_path,
-            "local_proxy_port": local_proxy_port,
-            "database_host": database_host,
-            "database_name": database_name,
-        }
-
-    def provide_connection_details(self, environment, secrets, boto3):
-        self._boto3 = boto3
-        if not secrets:
-            raise ValueError(
-                "I was asked to connect to a database via an AKeyless dynamic producer but AKeyless itself wasn't configured.  Try setting the AKeyless auth method via clearskies.secrets.akeyless_[jwt|saml|aws_iam]_auth()"
-            )
-
-        producer_name = self._fetch_config(environment, "producer_name", "akeyless_mysql_dynamic_producer")
-        bastion_username = self._fetch_config(environment, "bastion_username", "mysql_bastion_username", default="ssm")
-        bastion_instance_id = self._get_bastion_instance_id(environment)
-        public_key_file_path = self._fetch_config(
-            environment, "public_key_file_path", "mysql_bastion_public_key_file_path"
-        )
-        local_proxy_port = self._fetch_config(
-            environment, "local_proxy_port", "akeyless_mysql_bastion_local_proxy_port", default=8888
-        )
-        database_host = self._fetch_config(environment, "database_host", "db_host")
-        database_name = self._fetch_config(environment, "database_name", "db_database")
-
-        # Create the SSH tunnel (yeah, it's obnoxious)
-        self._create_tunnel(
-            secrets,
-            bastion_instance_id,
-            bastion_username,
-            bastion_region,
-            public_key_file_path,
-            local_proxy_port,
-            database_host,
-        )
-
-        # and now we can fetch credentials
-        credentials = secrets.get_dynamic_secret(producer_name)
-
-        return {
-            "username": credentials["user"],
-            "password": credentials["password"],
-            "host": "127.0.0.1",
-            "database": database_name,
-            "port": local_proxy_port,
-        }
-
-    def _get_bastion_instance_id(self, environment):
-        bastion_instance_id = self._fetch_config(
-            environment, "bastion_instance_id", "mysql_bastion_instance_id", default=""
-        )
-        bastion_name = self._fetch_config(environment, "bastion_name", "mysql_bastion_name", default="")
-        if bastion_instance_id:
-            return bastion_instance_id
-        if bastion_name:
-            bastion_region = self._fetch_config(environment, "bastion_region", "mysql_bastion_region")
-            return self._instance_id_from_name(bastion_name, bastion_region)
-        raise ValueError(
-            f"I was asked to connect to a database via an AKeyless dynamic producer through an SSH bastion with certificate auth, but I'm missing some configuration. I need either the bastion host or the name of the instance in AWS.  These can be set in the call to `clearskies.backends.akeyless_aws.mysql_connection_dynamic_producer_via_ssh_cert_bastion()` by providing the 'bastion_host' or 'bastion_name' argument, or by setting an environment variable named 'akeyless_mysql_bastion_host' or 'akeyless_mysql_bastion_name'."
-        )
-
-    def _instance_id_from_name(self, bastion_name, bastion_region):
-        ec2 = self._boto3.client("ec2", region_name=bastion_region)
-        response = ec2.describe_instances(
-            Filters=[
-                {"Name": "tag:Name", "Values": [bastion_name]},
-                {"Name": "instance-state-name", "Values": ["running"]},
-            ],
-        )
-        if not response.get("Reservations"):
-            raise ValueError(
-                f"Could not find a running instance with the designated bastion name, '{bastion_name}' in region '{bastion_region}'"
-            )
-        if not response.get("Reservations")[0].get("Instances"):
-            raise ValueError(
-                f"Could not find a running instance with the designated bastion name, '{bastion_name}' in region '{bastion_region}'"
-            )
-        return response.get("Reservations")[0].get("Instances")[0]["InstanceId"]
-
-    def _create_tunnel(
-        self,
-        secrets,
-        bastion_instance_id,
-        bastion_username,
-        bastion_region,
-        public_key_file_path,
-        local_proxy_port,
-        database_host,
-    ):
-        # first see if the socket is already open, since we don't close it.
-        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        result = sock.connect_ex(("127.0.0.1", local_proxy_port))
-        if result == 0:
-            sock.close()
-            return
-
-        # and now we can do this thing.
-        tunnel_command = [
-            "ssh",
-            "-i",
-            public_key_file_path,
-            "-o",
-            "ConnectTimeout=2",
-            "-N",
-            "-L",
-            f"{local_proxy_port}:{database_host}:3306",
-            "-p",
-            "22",
-            f"{bastion_username}@{bastion_instance_id}",
-        ]
-        my_env = os.environ.copy()
-        my_env["AWS_DEFAULT_REGION"] = bastion_region
-        subprocess.Popen(tunnel_command)
-        connected = False
-        attempts = 0
-        while not connected and attempts < 6:
-            attempts += 1
-            time.sleep(0.5)
-            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-            result = sock.connect_ex(("127.0.0.1", local_proxy_port))
-            if result == 0:
-                connected = True
-        if not connected:
-            raise ValueError(
-                "Failed to open SSH tunnel.  The following command was used: \n" + " ".join(tunnel_command)
-            )

clearskies_aws/secrets/akeyless_with_ssm_cache.py

@@ -1,60 +0,0 @@
-from __future__ import annotations
-
-import re
-from typing import Any
-
-from clearskies.secrets.akeyless import Akeyless
-from types_boto3_ssm import SSMClient
-
-from clearskies_aws.secrets import parameter_store
-
-
-class AkeylessWithSsmCache(parameter_store.ParameterStore, Akeyless):
-    def get(self, path: str, refresh: bool = False) -> str | None:  # type: ignore[override]
-        # AWS SSM parameter paths only allow a-z, A-Z, 0-9, -, _, ., /, @, and :
-        # Replace any disallowed characters with hyphens
-        ssm_name = re.sub(r"[^a-zA-Z0-9\-_\./@:]", "-", path)
-        # if we're not forcing a refresh, then see if it is in paramater store
-        if not refresh:
-            missing = False
-            try:
-                response = self.ssm.get_parameter(Name=ssm_name, WithDecryption=True)
-            except self.ssm.exceptions.ParameterNotFound:
-                missing = True
-            if not missing:
-                value = response["Parameter"].get("Value", "")
-                if value:
-                    return value
-
-        # otherwise get it out of Akeyless
-        value = str(super().get(path))
-
-        # and make sure and store the new value in parameter store
-        if value:
-            self.ssm.put_parameter(
-                Name=ssm_name,
-                Value=value,
-                Type="SecureString",
-                Overwrite=True,
-            )
-
-        return value
-
-    def update(self, path: str, value: Any) -> bool:  # type: ignore[override]
-        res = self._api.update_secret_val(
-            self.akeyless.UpdateSecretVal(name=path, value=str(value), token=self._get_token())
-        )
-        self.ssm.put_parameter(
-            Name=re.sub(r"[^a-zA-Z0-9\-_\./@:]", "-", path),
-            Value=value,
-            Type="SecureString",
-            Overwrite=True,
-        )
-        return True
-
-    def upsert(self, path: str, value: Any) -> bool:  # type: ignore[override]
-        try:
-            self.update(path, value)
-        except Exception as e:
-            self.create(path, value)
-        return True