rds-proxy-password-rotation 0.1.0__tar.gz

rds_proxy_password_rotation-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

rds_proxy_password_rotation-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.2
+Name: rds-proxy-password-rotation
+Version: 0.1.0
+Summary: A program to rotate the password of an RDS database accessed via a RDS proxy
+Home-page: https://github.com/Hapag-Lloyd/rds-proxy-password-rotation
+Author: Hapag-Lloyd AG
+Author-email: info@hlag.com
+Project-URL: Bug Tracker, https://github.com/Hapag-Lloyd/rds-proxy-password-rotation/issues
+Project-URL: repository, https://github.com/Hapag-Lloyd/rds-proxy-password-rotation
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aws-lambda-powertools==3.19.0
+Requires-Dist: boto3==1.40.23
+Requires-Dist: boto3-stubs[secretsmanager]==1.40.23
+Requires-Dist: cachetools==6.2.0
+Requires-Dist: dependency-injector==4.48.1
+Requires-Dist: psycopg[binary]==3.2.9
+Requires-Dist: pydantic==2.11.7
+Provides-Extra: test
+Requires-Dist: pytest==8.3.4; extra == "test"
+Requires-Dist: pytest-cov==6.0.0; extra == "test"
+Requires-Dist: uuid==1.30; extra == "test"
+Requires-Dist: nose==1.3.7; extra == "test"
+
+# rds-proxy-password-rotation
+
+:warning: **Work in progress** :warning:
+
+- add docker image for AWS Lambda
+- add Terraform module
+
+Python script for multi-user password rotation using RDS and RDS proxy. It supports credentials for the application and the RDS
+proxy.
+
+We implemented this logic again, because current implementations
+
+- have no tests
+- have no release process
+- are not published to PyPI
+- have no Docker image available
+- have no Terraform module available
+
+## Pre-requisites
+
+1. Python 3.10 or later
+2. For each db user:
+   1. Clone the user in the database and grant the necessary permissions. We suggest to add a `-clone` suffix to the username.
+   2. Create a secret in AWS Secrets Manager with the following key-value pairs (for every user and its clone):
+      - `rotation_type`: "AWS RDS"
+      - `rotation_usernames`: Optional. The list of usernames that a part of the rotation, e.g. `["app_user", "app_user-clone"]`.
+         If not provided, `username` is used only.
+      - `proxy_secret_ids`: Optional. The list of ARNs of the secrets that are attached to the RDS Proxy, e.g.
+        `["arn:aws:secretsmanager:region:account-id:secret:secret-name"]`. If not provided, the proxy credentials are not adjusted.
+      - `database_host`: The hostname of the database
+      - `database_port`: The port of the database
+      - `database_name`: The name of the database
+      - `username`: The username for the user
+      - `password`: The password for the user
+
+      This credential will be used by the application to connect to the proxy. You may add additional key-value pairs as needed.
+3. If you are using RDS Proxy:
+   1. Create a secret in AWS Secrets Manager with the following key-value pairs:
+      - `username`: The username for the user that the proxy will use to connect to the database
+      - `password`: The password for the user that the proxy will use to connect to the database
+   2. Attach the secret to the RDS Proxy.
+
+## Architecture
+
+![Architecture](assets/architecture.png)
+
+## Challenges with RDS and RDS Proxy
+
+RDS Proxy is a fully managed, highly available database proxy for Amazon Relational Database Service (RDS) that makes applications
+more scalable, more resilient to database failures, and more secure. It allows applications to pool and share database connections
+to improve efficiency and reduce the load on your database instances.
+
+However, RDS Proxy does not support multi-user password rotation out of the box. This script provides a solution to this problem.
+
+Using an RDS Proxy requires a secret in AWS Secrets Manager with the credentials to connect to the database. This secret is used by
+the proxy to connect to the database. The proxy allows the application to connect to the database using the same credentials and
+then forwards the requests to the database with the same credentials. This means that the credentials in the secret must be valid
+in the database at all times. But what if you want to rotate the password for the user that the proxy uses to connect to the
+database? You can’t just update the secret in SecretsManager because the proxy will stop working as soon as the secret is updated.
+And you can’t just update the password in the database because the proxy will stop working as soon as the password is updated.
+
+## Why password rotation is a good practice
+
+Password rotation is a good idea for several reasons:
+
+1. **Enhanced Security**: Regularly changing passwords reduces the risk of unauthorized access due to compromised credentials.
+2. **Mitigates Risk**: Limits the time window an attacker has to exploit a stolen password.
+3. **Compliance**: Many regulatory standards and security policies require periodic password changes.
+4. **Reduces Impact of Breaches**: If a password is compromised, rotating it ensures that the compromised password is no longer valid.
+5. **Encourages Good Practices**: Promotes the use of strong, unique passwords and discourages password reuse.

rds_proxy_password_rotation-0.1.0/README.md

@@ -0,0 +1,70 @@
+# rds-proxy-password-rotation
+
+:warning: **Work in progress** :warning:
+
+- add docker image for AWS Lambda
+- add Terraform module
+
+Python script for multi-user password rotation using RDS and RDS proxy. It supports credentials for the application and the RDS
+proxy.
+
+We implemented this logic again, because current implementations
+
+- have no tests
+- have no release process
+- are not published to PyPI
+- have no Docker image available
+- have no Terraform module available
+
+## Pre-requisites
+
+1. Python 3.10 or later
+2. For each db user:
+   1. Clone the user in the database and grant the necessary permissions. We suggest to add a `-clone` suffix to the username.
+   2. Create a secret in AWS Secrets Manager with the following key-value pairs (for every user and its clone):
+      - `rotation_type`: "AWS RDS"
+      - `rotation_usernames`: Optional. The list of usernames that a part of the rotation, e.g. `["app_user", "app_user-clone"]`.
+         If not provided, `username` is used only.
+      - `proxy_secret_ids`: Optional. The list of ARNs of the secrets that are attached to the RDS Proxy, e.g.
+        `["arn:aws:secretsmanager:region:account-id:secret:secret-name"]`. If not provided, the proxy credentials are not adjusted.
+      - `database_host`: The hostname of the database
+      - `database_port`: The port of the database
+      - `database_name`: The name of the database
+      - `username`: The username for the user
+      - `password`: The password for the user
+
+      This credential will be used by the application to connect to the proxy. You may add additional key-value pairs as needed.
+3. If you are using RDS Proxy:
+   1. Create a secret in AWS Secrets Manager with the following key-value pairs:
+      - `username`: The username for the user that the proxy will use to connect to the database
+      - `password`: The password for the user that the proxy will use to connect to the database
+   2. Attach the secret to the RDS Proxy.
+
+## Architecture
+
+![Architecture](assets/architecture.png)
+
+## Challenges with RDS and RDS Proxy
+
+RDS Proxy is a fully managed, highly available database proxy for Amazon Relational Database Service (RDS) that makes applications
+more scalable, more resilient to database failures, and more secure. It allows applications to pool and share database connections
+to improve efficiency and reduce the load on your database instances.
+
+However, RDS Proxy does not support multi-user password rotation out of the box. This script provides a solution to this problem.
+
+Using an RDS Proxy requires a secret in AWS Secrets Manager with the credentials to connect to the database. This secret is used by
+the proxy to connect to the database. The proxy allows the application to connect to the database using the same credentials and
+then forwards the requests to the database with the same credentials. This means that the credentials in the secret must be valid
+in the database at all times. But what if you want to rotate the password for the user that the proxy uses to connect to the
+database? You can’t just update the secret in SecretsManager because the proxy will stop working as soon as the secret is updated.
+And you can’t just update the password in the database because the proxy will stop working as soon as the password is updated.
+
+## Why password rotation is a good practice
+
+Password rotation is a good idea for several reasons:
+
+1. **Enhanced Security**: Regularly changing passwords reduces the risk of unauthorized access due to compromised credentials.
+2. **Mitigates Risk**: Limits the time window an attacker has to exploit a stolen password.
+3. **Compliance**: Many regulatory standards and security policies require periodic password changes.
+4. **Reduces Impact of Breaches**: If a password is compromised, rotating it ensures that the compromised password is no longer valid.
+5. **Encourages Good Practices**: Promotes the use of strong, unique passwords and discourages password reuse.

rds_proxy_password_rotation-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ['setuptools==75.9.1']
+build-backend = 'setuptools.build_meta'

rds_proxy_password_rotation-0.1.0/setup.cfg

@@ -0,0 +1,46 @@
+[metadata]
+name = rds-proxy-password-rotation
+version = 0.1.0
+author = Hapag-Lloyd AG
+author_email = info@hlag.com
+description = A program to rotate the password of an RDS database accessed via a RDS proxy
+long_description = file: README.md
+long_description_content_type = text/markdown
+url = https://github.com/Hapag-Lloyd/rds-proxy-password-rotation
+project_urls = 
+	Bug Tracker = https://github.com/Hapag-Lloyd/rds-proxy-password-rotation/issues
+	repository = https://github.com/Hapag-Lloyd/rds-proxy-password-rotation
+classifiers = 
+	Programming Language :: Python :: 3
+	License :: OSI Approved :: Apache Software License
+	Operating System :: OS Independent
+
+[options]
+package_dir = 
+	= src
+packages = find:
+python_requires = >=3.10
+install_requires = 
+	aws-lambda-powertools==3.19.0
+	boto3==1.40.23
+	boto3-stubs[secretsmanager]==1.40.23
+	cachetools==6.2.0
+	dependency-injector==4.48.1
+	psycopg[binary]==3.2.9
+	pydantic==2.11.7
+
+[options.extras_require]
+test = 
+	pytest==8.3.4
+	pytest-cov==6.0.0
+	uuid==1.30
+	
+	nose==1.3.7
+
+[options.packages.find]
+where = src
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation/adapter/aws_lambda_function.py

@@ -0,0 +1,25 @@
+from dependency_injector.wiring import inject, Provide
+
+from aws_lambda_powertools.utilities.parser import event_parser
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+from rds_proxy_password_rotation.adapter.aws_lambda_function_model import AwsSecretManagerRotationEvent
+from rds_proxy_password_rotation.adapter.container import Container
+from rds_proxy_password_rotation.password_rotation_application import PasswordRotationApplication
+
+
+container = None
+
+@event_parser(model=AwsSecretManagerRotationEvent)
+def lambda_handler(event: AwsSecretManagerRotationEvent, context: LambdaContext) -> None:
+    global container
+
+    if container is None:
+        container = Container()
+        container.wire(modules=[__name__])
+
+    __call_application(event)
+
+@inject
+def __call_application(event: AwsSecretManagerRotationEvent, application: PasswordRotationApplication = Provide[Container.password_rotation_application]) -> None:
+    application.rotate_secret(event.step.to_rotation_step(), event.secret_id, event.client_request_token)

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation/adapter/aws_lambda_function_model.py

@@ -0,0 +1,43 @@
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from rds_proxy_password_rotation.model import RotationStep
+
+
+class AwsRotationStep(Enum):
+    CREATE_SECRET = "create_secret"
+    """Create a new version of the secret"""
+    SET_SECRET = "set_secret"
+    """Change the credentials in the database or service"""
+    TEST_SECRET = "test_secret"
+    """Test the new secret version"""
+    FINISH_SECRET = "finish_secret"
+    """Finish the rotation"""
+
+    def to_rotation_step(self) -> RotationStep:
+        match self:
+            case AwsRotationStep.CREATE_SECRET:
+                return RotationStep.CREATE_SECRET
+            case AwsRotationStep.SET_SECRET:
+                return RotationStep.SET_SECRET
+            case AwsRotationStep.TEST_SECRET:
+                return RotationStep.TEST_SECRET
+            case AwsRotationStep.FINISH_SECRET:
+                return RotationStep.FINISH_SECRET
+            case _:
+                raise ValueError(f"Invalid rotation step: {self.value}")
+
+
+class AwsSecretManagerRotationEvent(BaseModel):
+    step: AwsRotationStep = Field(alias='Step')
+    """The rotation step: create_secret, set_secret, test_secret, or finish_secret. For more information, see Four steps in a rotation function."""
+
+    secret_id: str = Field(alias='SecretId')
+    """The ARN of the secret to rotate."""
+
+    client_request_token: str = Field(alias='ClientRequestToken')
+    """A unique identifier for the new version of the secret. This value helps ensure idempotency. For more information, see PutSecretValue: ClientRequestToken in the AWS Secrets Manager API Reference."""
+
+    rotation_token: str = Field(alias='RotationToken')
+    """A unique identifier that indicates the source of the request. Required for secret rotation using an assumed role or cross-account rotation, in which you rotate a secret in one account by using a Lambda rotation function in another account. In both cases, the rotation function assumes an IAM role to call Secrets Manager and then Secrets Manager uses the rotation token to validate the IAM role identity."""

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation/adapter/aws_secrets_manager.py

@@ -0,0 +1,154 @@
+from uuid import uuid4
+
+from aws_lambda_powertools import Logger
+from mypy_boto3_secretsmanager.client import SecretsManagerClient
+from mypy_boto3_secretsmanager.type_defs import DescribeSecretResponseTypeDef
+from pydantic import ValidationError
+
+from rds_proxy_password_rotation.model import DatabaseCredentials, PasswordStage, UserCredentials, Credentials
+from rds_proxy_password_rotation.services import PasswordService
+
+
+class AwsSecretsManagerService(PasswordService):
+    def __init__(self, secretsmanager_client: SecretsManagerClient, logger: Logger):
+        self.client = secretsmanager_client
+        self.logger = logger
+
+    def is_rotation_enabled(self, secret_id: str) -> bool:
+        metadata = self.__get_secret_metadata(secret_id)
+
+        return 'RotationEnabled' in metadata and metadata['RotationEnabled']
+
+    def make_new_credentials_current(self, secret_id: str, token: str):
+        metadata = self.__get_secret_metadata(secret_id)
+        versions = metadata['VersionIdsToStages']
+
+        current_version = None
+        previous_version = None
+
+        for version, stages in versions.items():
+            if "AWSCURRENT" in stages:
+                if version == token:
+                    self.logger.info(f'current secret is already the pending one: {secret_id} and version {version}')
+                    return
+
+                current_version = version
+            elif "AWSPREVIOUS" in stages:
+                previous_version = version
+
+        if previous_version is not None:
+            self.client.update_secret_version_stage(
+                SecretId=secret_id,
+                VersionStage="AWSPREVIOUS",
+                MoveToVersionId=current_version,
+                RemoveFromVersionId=previous_version
+            )
+        else:
+            self.client.update_secret_version_stage(
+                SecretId=secret_id,
+                VersionStage="AWSPREVIOUS",
+                MoveToVersionId=current_version
+            )
+
+        self.client.update_secret_version_stage(
+            SecretId=secret_id,
+            VersionStage='AWSCURRENT',
+            MoveToVersionId=token,
+            RemoveFromVersionId=current_version)
+
+        self.client.update_secret_version_stage(
+            SecretId=secret_id,
+            VersionStage='AWSPENDING',
+            RemoveFromVersionId=token)
+
+    def ensure_valid_secret_state(self, secret_id: str, token: str) -> bool:
+        metadata = self.__get_secret_metadata(secret_id)
+        versions = metadata['VersionIdsToStages']
+
+        if token not in versions:
+            self.logger.error("Secret version %s has no stage for rotation of secret %s." % (token, secret_id))
+            raise ValueError("Secret version %s has no stage for rotation of secret %s." % (token, secret_id))
+        elif "AWSCURRENT" in versions[token]:
+            self.logger.info("Secret version %s already set as AWSCURRENT for secret %s." % (token, secret_id))
+            return False
+        elif "AWSPENDING" not in versions[token]:
+            self.logger.error("Secret version %s not set as AWSPENDING for rotation of secret %s." % (token, secret_id))
+            raise ValueError("Secret version %s not set as AWSPENDING for rotation of secret %s." % (token, secret_id))
+        else:
+            return True
+
+    def get_database_credentials(self, secret_id: str, stage: PasswordStage, token: str = None) -> DatabaseCredentials | None:
+        try:
+            return DatabaseCredentials.model_validate_json(self.__get_secret_value(secret_id, stage, token))
+        except ValidationError as e:
+            self.logger.error(f"Failed to parse secret value for secret {secret_id} (stage: {stage.name}, token: {token})")
+
+            raise e
+        except self.client.exceptions.ResourceNotFoundException:
+            self.logger.error(f"Failed to retrieve secret value for secret {secret_id} (stage: {stage.name}, token: {token})")
+
+        return None
+
+    def get_user_credentials(self, secret_id: str, stage: PasswordStage, token: str = None) -> UserCredentials | None:
+        try:
+            return UserCredentials.model_validate_json(self.__get_secret_value(secret_id, stage, token))
+        except ValidationError as e:
+            self.logger.error(f"Failed to parse secret value for secret {secret_id} (stage: {stage.name}, token: {token})")
+
+            raise e
+        except self.client.exceptions.ResourceNotFoundException:
+            self.logger.error(f"Failed to retrieve secret value for secret {secret_id} (stage: {stage.name}, token: {token})")
+
+        return None
+
+    def __get_secret_value(self, secret_id: str, stage: PasswordStage, token: str) -> str:
+        stage_string = AwsSecretsManagerService.__get_stage_string(stage)
+
+        if token is None:
+            secret = self.client.get_secret_value(SecretId=secret_id, VersionStage=stage_string)
+        else:
+            secret = self.client.get_secret_value(SecretId=secret_id, VersionId=token, VersionStage=stage_string)
+
+        return secret['SecretString']
+
+    def set_new_pending_password(self, secret_id: str, token: str, credential: DatabaseCredentials):
+        if token is None:
+            token = str(uuid4())
+
+        new_username = credential.get_next_username()
+        pending_credential = credential.model_copy(update={'username': new_username, 'password': self.client.get_random_password(ExcludeCharacters=':/@"\'\\')['RandomPassword']})
+
+        self.client.put_secret_value(
+                SecretId=secret_id,
+                ClientRequestToken=token,
+                SecretString=pending_credential.model_dump_json(),
+                VersionStages=[AwsSecretsManagerService.__get_stage_string(PasswordStage.PENDING)])
+
+        self.logger.info(f'new pending secret created: {secret_id} and version {token}')
+
+    def set_credentials(self, secret_id: str, token: str, credentials: Credentials):
+        if token is None:
+            token = str(uuid4())
+
+        self.client.put_secret_value(
+            SecretId=secret_id,
+            ClientRequestToken=token,
+            SecretString=credentials.model_dump_json(),
+            VersionStages=[AwsSecretsManagerService.__get_stage_string(PasswordStage.CURRENT)])
+
+        self.logger.info(f'credentials modified: {secret_id} and version {token}')
+
+    def __get_secret_metadata(self, secret_id: str) -> DescribeSecretResponseTypeDef:
+        return self.client.describe_secret(SecretId=secret_id)
+
+    @staticmethod
+    def __get_stage_string(stage: PasswordStage) -> str:
+        match stage:
+            case PasswordStage.CURRENT:
+                return "AWSCURRENT"
+            case PasswordStage.PENDING:
+                return "AWSPENDING"
+            case PasswordStage.PREVIOUS:
+                return "AWSPREVIOUS"
+            case _:
+                raise ValueError(f"Invalid stage: {stage}")

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation/adapter/container.py

@@ -0,0 +1,27 @@
+import boto3
+from aws_lambda_powertools import Logger
+from dependency_injector import containers, providers
+
+from rds_proxy_password_rotation.adapter.aws_secrets_manager import AwsSecretsManagerService
+from rds_proxy_password_rotation.password_rotation_application import PasswordRotationApplication
+
+
+class Container(containers.DeclarativeContainer):
+    config = providers.Configuration()
+
+    logger = providers.Singleton(
+        Logger,
+    )
+
+    boto3_secrets_manager = boto3.client(service_name='secretsmanager')
+
+    secrets_manager = providers.Singleton(
+        AwsSecretsManagerService,
+        boto3_secrets_manager=boto3_secrets_manager,
+    )
+
+    password_rotation_application = providers.Singleton(
+        PasswordRotationApplication,
+        secrets_manager=secrets_manager,
+        logger=logger,
+    )

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation/adapter/postgresql_database_service.py

@@ -0,0 +1,39 @@
+import psycopg
+from aws_lambda_powertools import Logger
+from psycopg import Connection, sql, ClientCursor
+
+from rds_proxy_password_rotation.model import DatabaseCredentials
+from rds_proxy_password_rotation.services import DatabaseService
+
+
+class PostgreSqlDatabaseService(DatabaseService):
+    def __init__(self, logger: Logger):
+        self.logger = logger
+
+    def test_user_credentials(self, credentials: DatabaseCredentials) -> bool:
+        with self._get_connection(credentials) as conn:
+            with conn.cursor() as cur:
+                cur.execute("SELECT 1")
+
+                return True
+
+    def change_user_credentials(self, old_credentials: DatabaseCredentials, new_password: str):
+        with self._get_connection(old_credentials) as conn:
+            with ClientCursor(conn) as cur:
+                cur.execute(sql.SQL("ALTER USER {} WITH PASSWORD %s").format(sql.Identifier(old_credentials.username)), (new_password,))
+                conn.commit()
+
+    def _get_connection(self, credentials: DatabaseCredentials) -> Connection:
+        """
+        Method is protected to allow testing.
+        :param credentials: used to connect to the database
+        :return: the database connection
+        """
+        connect_string = psycopg._connection_info.make_conninfo("", password=credentials.password, user=credentials.username, host=credentials.database_host, port=credentials.database_port, dbname=credentials.database_name, sslmode="require", connect_timeout=5)
+
+        try:
+            return psycopg.connect(connect_string)
+        except psycopg.OperationalError as e:
+            self.logger.error(f'Failed to connect to database {credentials.database_name} on {credentials.database_host}:{credentials.database_port} as {credentials.username}')
+
+            raise e

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation/model.py

@@ -0,0 +1,60 @@
+from enum import Enum
+from typing import List
+
+from pydantic import BaseModel
+from typing_extensions import Optional
+
+
+class RotationStep(Enum):
+    CREATE_SECRET = "create_secret"
+    """Create a new version of the secret"""
+    SET_SECRET = "set_secret"
+    """Change the credentials in the database or service"""
+    TEST_SECRET = "test_secret"
+    """Test the new secret version"""
+    FINISH_SECRET = "finish_secret"
+    """Finish the rotation"""
+
+
+class PasswordStage(Enum):
+    CURRENT = "CURRENT"
+    PENDING = "PENDING"
+    PREVIOUS = "PREVIOUS"
+
+
+class PasswordType(Enum):
+    AWS_RDS = "AWS RDS"
+
+
+class Credentials(BaseModel, extra='allow'):
+    rotation_type: PasswordType
+    rotation_usernames: Optional[List[str]] = []
+
+
+class UserCredentials(Credentials):
+    username: str
+    password: str
+
+    def get_next_username(self) -> str:
+        if not self.rotation_usernames:
+            return self.username
+
+        # e.g. user1 -> user2, user2 -> user3, user3 -> user1, ...
+        if self.username not in self.rotation_usernames:
+            self.logger.warning(f'current username {self.username} not in rotation usernames {self.rotation_usernames}. Using the first username in the list as the new one.')
+            return self.rotation_usernames[0]
+
+        current_index = self.rotation_usernames.index(self.username)
+        next_index = (current_index + 1) % len(self.rotation_usernames)
+
+        return self.rotation_usernames[next_index]
+
+class DatabaseCredentials(UserCredentials):
+    database_host: str
+    database_port: int
+    database_name: str
+
+    proxy_secret_ids: Optional[list[UserCredentials]] = None
+
+    def copy_and_replace_username(credentials: 'DatabaseCredentials', new_username: str) -> 'DatabaseCredentials':
+        return credentials.model_copy(update={'username': new_username})

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation/password_rotation_application.py

@@ -0,0 +1,81 @@
+from enum import Enum
+
+from aws_lambda_powertools import Logger
+
+from rds_proxy_password_rotation.model import RotationStep, PasswordStage
+from rds_proxy_password_rotation.services import PasswordService, DatabaseService
+
+
+class PasswordRotationResult(Enum):
+    NOTHING_TO_ROTATE = "nothing_to_rotate"
+    STEP_EXECUTED = "step_executed"
+
+
+class PasswordRotationApplication:
+    def __init__(self, password_service: PasswordService, database_service: DatabaseService, logger: Logger):
+        self.password_service = password_service
+        self.database_service = database_service
+        self.logger = logger
+
+    def rotate_secret(self, step: RotationStep, secret_id: str, token: str) -> PasswordRotationResult:
+        if not self.password_service.is_rotation_enabled(secret_id):
+            self.logger.warning("Rotation is not enabled for the secret %s", secret_id)
+            return PasswordRotationResult.NOTHING_TO_ROTATE
+
+        if step != RotationStep.CREATE_SECRET and not self.password_service.ensure_valid_secret_state(secret_id, token):
+            return PasswordRotationResult.NOTHING_TO_ROTATE
+
+        match step:
+            case RotationStep.CREATE_SECRET:
+                self.__create_secret(secret_id, token)
+            case RotationStep.SET_SECRET:
+                self.__set_secret(secret_id, token)
+            case RotationStep.TEST_SECRET:
+                self.__test_secret(secret_id, token)
+            case RotationStep.FINISH_SECRET:
+                self.__finish_secret(secret_id, token)
+            case _:
+                raise ValueError(f"Invalid rotation step: {step}")
+
+        return PasswordRotationResult.STEP_EXECUTED
+
+    def __finish_secret(self, secret_id: str, token: str):
+        self.password_service.make_new_credentials_current(secret_id, token)
+
+    def __test_secret(self, secret_id: str, token: str):
+        pending_credential = self.password_service.get_database_credentials(secret_id, PasswordStage.PENDING, token)
+        self.database_service.test_user_credentials(pending_credential)
+
+    def __set_secret(self, secret_id: str, token: str):
+        pending_credential = self.password_service.get_database_credentials(secret_id, PasswordStage.PENDING, token)
+        current_credential = self.password_service.get_database_credentials(secret_id, PasswordStage.CURRENT)
+
+        proxy_secret_id = None
+        proxy_secret = None
+
+        for secret_id in current_credential.proxy_secret_ids:
+            proxy_secret = self.password_service.get_user_credentials(secret_id, PasswordStage.CURRENT)
+            if proxy_secret.username == pending_credential.username:
+                proxy_secret_id = secret_id
+                break
+
+        self.database_service.change_user_credentials(current_credential, pending_credential.password)
+
+        # database and proxy user credentials have to be in sync as the proxy user is used to connect to the database
+        if proxy_secret_id is not None:
+            self.password_service.set_credentials(secret_id, token, proxy_secret)
+
+        self.logger.info(f'set_secret: successfully set password for user {pending_credential.username} for secret {secret_id}')
+
+    def __create_secret(self, secret_id: str, token: str):
+        """
+        Creates a new version of the secret with the password to rotate to unless a version tagged with AWSPENDING
+        already exists.
+        """
+
+        if self.password_service.get_database_credentials(secret_id, PasswordStage.PENDING, token) is not None:
+            return
+
+        credentials_to_rotate = self.password_service.get_database_credentials(secret_id, PasswordStage.CURRENT)
+
+        self.password_service.set_new_pending_password(secret_id, token, credentials_to_rotate)

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation/services.py

@@ -0,0 +1,43 @@
+from abc import ABC, abstractmethod
+
+from rds_proxy_password_rotation.model import DatabaseCredentials, PasswordStage, UserCredentials, Credentials
+
+
+class PasswordService(ABC):
+    @abstractmethod
+    def is_rotation_enabled(self, secret_id: str) -> bool:
+        pass
+
+    @abstractmethod
+    def ensure_valid_secret_state(self, secret_id: str, token: str) -> bool:
+        pass
+
+    @abstractmethod
+    def get_database_credentials(self, secret_id: str, stage: PasswordStage, token: str = None) -> DatabaseCredentials | None:
+        pass
+
+    @abstractmethod
+    def get_user_credentials(self, secret_id: str, stage: PasswordStage, token: str = None) -> UserCredentials | None:
+        pass
+
+    @abstractmethod
+    def set_new_pending_password(self, secret_id: str, token: str, credential: DatabaseCredentials):
+        pass
+
+    @abstractmethod
+    def set_credentials(self, secret_id: str, token: str, credential: Credentials):
+        pass
+
+    @abstractmethod
+    def make_new_credentials_current(self, secret_id: str, token: str):
+        pass
+
+
+class DatabaseService(ABC):
+    @abstractmethod
+    def change_user_credentials(self, old_credentials: DatabaseCredentials, new_password: str):
+        pass
+
+    @abstractmethod
+    def test_user_credentials(self, credentials: DatabaseCredentials):
+        pass

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.2
+Name: rds-proxy-password-rotation
+Version: 0.1.0
+Summary: A program to rotate the password of an RDS database accessed via a RDS proxy
+Home-page: https://github.com/Hapag-Lloyd/rds-proxy-password-rotation
+Author: Hapag-Lloyd AG
+Author-email: info@hlag.com
+Project-URL: Bug Tracker, https://github.com/Hapag-Lloyd/rds-proxy-password-rotation/issues
+Project-URL: repository, https://github.com/Hapag-Lloyd/rds-proxy-password-rotation
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aws-lambda-powertools==3.19.0
+Requires-Dist: boto3==1.40.23
+Requires-Dist: boto3-stubs[secretsmanager]==1.40.23
+Requires-Dist: cachetools==6.2.0
+Requires-Dist: dependency-injector==4.48.1
+Requires-Dist: psycopg[binary]==3.2.9
+Requires-Dist: pydantic==2.11.7
+Provides-Extra: test
+Requires-Dist: pytest==8.3.4; extra == "test"
+Requires-Dist: pytest-cov==6.0.0; extra == "test"
+Requires-Dist: uuid==1.30; extra == "test"
+Requires-Dist: nose==1.3.7; extra == "test"
+
+# rds-proxy-password-rotation
+
+:warning: **Work in progress** :warning:
+
+- add docker image for AWS Lambda
+- add Terraform module
+
+Python script for multi-user password rotation using RDS and RDS proxy. It supports credentials for the application and the RDS
+proxy.
+
+We implemented this logic again, because current implementations
+
+- have no tests
+- have no release process
+- are not published to PyPI
+- have no Docker image available
+- have no Terraform module available
+
+## Pre-requisites
+
+1. Python 3.10 or later
+2. For each db user:
+   1. Clone the user in the database and grant the necessary permissions. We suggest to add a `-clone` suffix to the username.
+   2. Create a secret in AWS Secrets Manager with the following key-value pairs (for every user and its clone):
+      - `rotation_type`: "AWS RDS"
+      - `rotation_usernames`: Optional. The list of usernames that a part of the rotation, e.g. `["app_user", "app_user-clone"]`.
+         If not provided, `username` is used only.
+      - `proxy_secret_ids`: Optional. The list of ARNs of the secrets that are attached to the RDS Proxy, e.g.
+        `["arn:aws:secretsmanager:region:account-id:secret:secret-name"]`. If not provided, the proxy credentials are not adjusted.
+      - `database_host`: The hostname of the database
+      - `database_port`: The port of the database
+      - `database_name`: The name of the database
+      - `username`: The username for the user
+      - `password`: The password for the user
+
+      This credential will be used by the application to connect to the proxy. You may add additional key-value pairs as needed.
+3. If you are using RDS Proxy:
+   1. Create a secret in AWS Secrets Manager with the following key-value pairs:
+      - `username`: The username for the user that the proxy will use to connect to the database
+      - `password`: The password for the user that the proxy will use to connect to the database
+   2. Attach the secret to the RDS Proxy.
+
+## Architecture
+
+![Architecture](assets/architecture.png)
+
+## Challenges with RDS and RDS Proxy
+
+RDS Proxy is a fully managed, highly available database proxy for Amazon Relational Database Service (RDS) that makes applications
+more scalable, more resilient to database failures, and more secure. It allows applications to pool and share database connections
+to improve efficiency and reduce the load on your database instances.
+
+However, RDS Proxy does not support multi-user password rotation out of the box. This script provides a solution to this problem.
+
+Using an RDS Proxy requires a secret in AWS Secrets Manager with the credentials to connect to the database. This secret is used by
+the proxy to connect to the database. The proxy allows the application to connect to the database using the same credentials and
+then forwards the requests to the database with the same credentials. This means that the credentials in the secret must be valid
+in the database at all times. But what if you want to rotate the password for the user that the proxy uses to connect to the
+database? You can’t just update the secret in SecretsManager because the proxy will stop working as soon as the secret is updated.
+And you can’t just update the password in the database because the proxy will stop working as soon as the password is updated.
+
+## Why password rotation is a good practice
+
+Password rotation is a good idea for several reasons:
+
+1. **Enhanced Security**: Regularly changing passwords reduces the risk of unauthorized access due to compromised credentials.
+2. **Mitigates Risk**: Limits the time window an attacker has to exploit a stolen password.
+3. **Compliance**: Many regulatory standards and security policies require periodic password changes.
+4. **Reduces Impact of Breaches**: If a password is compromised, rotating it ensures that the compromised password is no longer valid.
+5. **Encourages Good Practices**: Promotes the use of strong, unique passwords and discourages password reuse.

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+setup.cfg
+src/rds_proxy_password_rotation/__init__.py
+src/rds_proxy_password_rotation/model.py
+src/rds_proxy_password_rotation/password_rotation_application.py
+src/rds_proxy_password_rotation/services.py
+src/rds_proxy_password_rotation.egg-info/PKG-INFO
+src/rds_proxy_password_rotation.egg-info/SOURCES.txt
+src/rds_proxy_password_rotation.egg-info/dependency_links.txt
+src/rds_proxy_password_rotation.egg-info/requires.txt
+src/rds_proxy_password_rotation.egg-info/top_level.txt
+src/rds_proxy_password_rotation/adapter/__init__.py
+src/rds_proxy_password_rotation/adapter/aws_lambda_function.py
+src/rds_proxy_password_rotation/adapter/aws_lambda_function_model.py
+src/rds_proxy_password_rotation/adapter/aws_secrets_manager.py
+src/rds_proxy_password_rotation/adapter/container.py
+src/rds_proxy_password_rotation/adapter/postgresql_database_service.py

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation.egg-info/requires.txt

@@ -0,0 +1,13 @@
+aws-lambda-powertools==3.19.0
+boto3==1.40.23
+boto3-stubs[secretsmanager]==1.40.23
+cachetools==6.2.0
+dependency-injector==4.48.1
+psycopg[binary]==3.2.9
+pydantic==2.11.7
+
+[test]
+pytest==8.3.4
+pytest-cov==6.0.0
+uuid==1.30
+nose==1.3.7

rds_proxy_password_rotation-0.1.0/src/rds_proxy_password_rotation.egg-info/top_level.txt

@@ -0,0 +1 @@
+rds_proxy_password_rotation