clear-skies-aws 2.0.12__tar.gz → 2.0.13__tar.gz

{clear_skies_aws-2.0.12 → clear_skies_aws-2.0.13}/.pre-commit-config.yaml

@@ -1,5 +1,4 @@
-# Pre-commit configuration for Clearkskies AWS project
-fail_fast: false
+# Pre-commit configuration for  Akeyless Custom Producer
 
 ci:
     autofix_commit_msg: "chore(pre-commit): autofix run"

{clear_skies_aws-2.0.12 → clear_skies_aws-2.0.13}/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.0.13] - 2026-01-28
+
+### Added
+- Add support for aws secrets
+
+### Changed
+- Update dependencies in [#13](https://github.com/clearskies-py/aws/pull/13)
+- Update to clearskies >=2.0.39
+
 ## [2.0.12] - 2026-01-27
 
 ### Added
@@ -12,6 +21,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add stepfucntions context with variables to ENV vars
 
 ### Changed
+- Bump version to v2.0.12 by @github-actions[bot]
 - Merge pull request #11 from clearskies-py/stepfunctions-variables by @cmancone in [#11](https://github.com/clearskies-py/aws/pull/11)
 - Update docstrings of stepfunctions
 - Move Environment to the input output of step functions
@@ -166,6 +176,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * @cmancone made their first contribution
 * @ made their first contribution
 * @github-actions[bot] made their first contribution
+[2.0.13]: https://github.com/clearskies-py/aws/compare/v2.0.12..v2.0.13
 [2.0.12]: https://github.com/clearskies-py/aws/compare/v2.0.11..v2.0.12
 [2.0.11]: https://github.com/clearskies-py/aws/compare/v2.0.10..v2.0.11
 [2.0.10]: https://github.com/clearskies-py/aws/compare/v2.0.9..v2.0.10

clear_skies_aws-2.0.13/LATEST_CHANGELOG.md

@@ -0,0 +1,9 @@
+## [2.0.13] - 2026-01-28
+
+### Added
+- Add support for aws secrets
+
+### Changed
+- Update dependencies in [#13](https://github.com/clearskies-py/aws/pull/13)
+- Update to clearskies >=2.0.39
+

{clear_skies_aws-2.0.12 → clear_skies_aws-2.0.13}/PKG-INFO

@@ -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 → clear_skies_aws-2.0.13}/pyproject.toml

@@ -3,14 +3,14 @@
 name = "clear-skies-aws"
 description = "clearskies bindings for working in AWS"
 license = "MIT"
-version = "2.0.12"
+version = "2.0.13"
 readme = "./README.md"
 authors = [{name = "tnijboer"}, {name = "Conor Mancone", email = "cmancone@gmail.com"}]
 requires-python = '>=3.11,<4.0'
 dependencies = [
     "awslambdaric>=3.1.1",
     'boto3 (>=1.26.148,<2.0.0)',
-    "clear-skies>=2.0.37,<3.0.0",
+    "clear-skies>=2.0.39,<3.0.0",
     "jinja2>=3.1.6",
     'types-boto3[dynamodb,sns,sqs,ses,ssm,secretsmanager,stepfunctions] (>=1.38.13,<2.0.0)',
 ]
@@ -47,11 +47,6 @@ exclude = [
     "tests/**"
 ]
 
-[tool.black]
-line-length = 120
-skip-magic-trailing-comma = false
-preview = false
-
 [tool.mypy]
 python_version = "3.11"
 
@@ -86,3 +81,6 @@ dev = [
     "types-boto3[boto3,essential,secretsmanager,ses,ssm,stepfunctions]>=1.40.40",
     "types-requests>=2.32.4",
 ]
+doc = [
+    "clear-skies-doc-builder>=2.0.7",
+]

{clear_skies_aws-2.0.12 → clear_skies_aws-2.0.13}/src/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"]

{clear_skies_aws-2.0.12 → clear_skies_aws-2.0.13}/src/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",
 ]

clear_skies_aws-2.0.13/src/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"]

clear_skies_aws-2.0.13/src/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)

clear_skies_aws-2.0.13/src/clearskies_aws/secrets/parameter_store.py

@@ -0,0 +1,188 @@
+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
+
+from clearskies_aws.secrets import 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__()
+
+    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.boto3_client.get_parameter(Name=sanitized_path, WithDecryption=True)
+        except ClientError as e:
+            error = e.response.get("Error", {})
+            if error.get("Code") == "ResourceNotFoundException":
+                if silent_if_not_found:
+                    return None
+                raise NotFound(f"Could not find secret '{path}' in parameter store")
+            raise e
+        return result["Parameter"].get("Value", "")
+
+    def list_secrets(self, path: str) -> list[str]:
+        """
+        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]
+        """
+        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="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[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.")

clear_skies_aws-2.0.13/src/clearskies_aws/secrets/secrets.py

@@ -0,0 +1,33 @@
+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 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()
+
+    def __init__(self):
+        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")

clear_skies_aws-2.0.13/src/clearskies_aws/secrets/secrets_manager.py

@@ -0,0 +1,193 @@
+from __future__ import annotations
+
+from typing import Any
+
+from botocore.exceptions import ClientError
+from clearskies.exceptions.not_found import NotFound
+from types_boto3_secretsmanager import SecretsManagerClient
+from types_boto3_secretsmanager.type_defs import SecretListEntryTypeDef
+
+from clearskies_aws.secrets import 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__()
+
+    @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.boto3_client.create_secret(**calling_parameters)
+        return bool(result.get("ARN"))
+
+    def get(  # type: ignore[override]
+        self,
+        secret_id: str,
+        version_id: str | None = None,
+        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
+        if version_id:
+            calling_parameters["VersionId"] = version_id
+        if version_stage:
+            calling_parameters["VersionStage"] = version_stage
+
+        try:
+            result = self.boto3_client.get_secret_value(**calling_parameters)
+        except ClientError as e:
+            error = e.response.get("Error", {})
+            if error.get("Code") == "ResourceNotFoundException":
+                if silent_if_not_found:
+                    return None
+                raise NotFound(
+                    f"Could not find secret '{secret_id}' with version '{version_id}' and stage '{version_stage}'"
+                )
+            raise e
+        if result.get("SecretString"):
+            return result.get("SecretString")
+        return result.get("SecretBinary")
+
+    def list_secrets(self, path: str) -> list[SecretListEntryTypeDef]:  # type: ignore[override]
+        """
+        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",
+                    "Values": [path],
+                },
+            ],
+        )
+        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,
+        }
+        if kms_key_id:
+            # If no KMS key is provided, we should not include it in the parameters
+            calling_parameters["KmsKeyId"] = kms_key_id
+
+        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,
+        }
+        if kms_key_id:
+            # If no KMS key is provided, we should not include it in the parameters
+            calling_parameters["KmsKeyId"] = kms_key_id
+
+        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.")