{"id":4484,"library":"credstash","title":"credstash","description":"credstash is a Python utility for securely managing secrets in the cloud by leveraging AWS Key Management Service (KMS) for encryption and Amazon DynamoDB for storage. It provides a simple command-line interface and a Python API to store, retrieve, and version secrets such as database passwords or API keys. The library is actively maintained, with version 1.17.1 being the latest, and receives regular updates for bug fixes and new features.","status":"active","version":"1.17.1","language":"en","source_language":"en","source_url":"https://github.com/fugue/credstash","tags":["aws","kms","dynamodb","secrets","security","credentials","encryption"],"install":[{"cmd":"pip install credstash","lang":"bash","label":"Basic installation"},{"cmd":"pip install credstash[YAML]","lang":"bash","label":"With YAML support"}],"dependencies":[{"reason":"Required for interacting with AWS KMS and DynamoDB services.","package":"boto3","optional":false},{"reason":"Required for cryptographic operations (encryption/decryption of secrets).","package":"cryptography","optional":false},{"reason":"Optional dependency for YAML configuration support.","package":"PyYAML","optional":true}],"imports":[{"note":"The common pattern is to import the `credstash` module directly and call methods like `credstash.getSecret()` or `credstash.putSecret()`.","wrong":"from credstash import getSecret","symbol":"credstash","correct":"import credstash"}],"quickstart":{"code":"import os\nimport credstash\nimport boto3\n\n# Ensure AWS credentials are set up (e.g., via environment variables like AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)\n# Or configure a Boto3 session explicitly\n\n# For demonstration, assume credentials are in env or IAM role is attached\n# Set a specific region if not relying on AWS_DEFAULT_REGION or instance metadata\naws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')\n\n# Initialize Boto3 clients if custom sessions or specific clients are needed\nkms_client = boto3.client('kms', region_name=aws_region)\ndynamodb_client = boto3.client('dynamodb', region_name=aws_region)\n\n# Instantiate Credstash (optional, can also call functions directly)\nstash = credstash.Credstash(table='credential-store', region=aws_region)\n\nsecret_name = \"my_test_secret\"\nsecret_value = \"supersecretpassword123\"\n\ntry:\n    # Put a secret\n    # By default, uses the 'credential-store' table and 'alias/credstash' KMS key\n    # ensure these are set up (credstash setup and KMS key creation)\n    stash.putSecret(name=secret_name, secret=secret_value, version='1', kms_key='alias/credstash', kms_client=kms_client)\n    print(f\"Secret '{secret_name}' version 1 stored successfully.\")\n\n    # Get the secret\n    retrieved_secret = stash.getSecret(name=secret_name, kms_client=kms_client)\n    print(f\"Retrieved secret '{secret_name}': {retrieved_secret}\")\n\n    # Update the secret with a new version (auto-increment example)\n    stash.putSecret(name=secret_name, secret='new_supersecret_value', autoversion=True, kms_key='alias/credstash', kms_client=kms_client)\n    print(f\"Secret '{secret_name}' updated with new version.\")\n    updated_secret = stash.getSecret(name=secret_name, kms_client=kms_client)\n    print(f\"Retrieved updated secret '{secret_name}': {updated_secret}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure you have configured AWS credentials and run `credstash setup` and created a KMS key 'alias/credstash'.\")\n","lang":"python","description":"This quickstart demonstrates how to programmatically store and retrieve a secret using the `credstash` Python API. It assumes AWS credentials are configured (e.g., via environment variables or an IAM role) and that a KMS key aliased 'credstash' and a DynamoDB table named 'credential-store' have been created. It uses explicit `boto3` clients for clarity, though `credstash` can often infer them from the environment."},"warnings":[{"fix":"Upgrade `credstash` to the latest version and ensure `cryptography` is within compatible bounds. For very old secret stores (prior to v1.15.0) that used removed hashing methods, consider re-encrypting secrets with a supported method or migrating data. On Linux, ensure C compiler and development libraries for `cryptography` are installed (e.g., `build-essential libssl-dev libffi-dev python-dev` for Debian/Ubuntu).","message":"Credstash migrated from PyCrypto to Cryptography, and in v1.15.0, unsupported hashing methods were removed. Users with older secret stores (pre-v1.15.0) or custom hashing methods may experience decryption failures. Additionally, v1.13.4 introduced an upper bound on `cryptography` due to incompatibilities, which might cause installation issues with newer `cryptography` versions.","severity":"breaking","affected_versions":"<=1.15.0"},{"fix":"Upgrade to `credstash` v1.17.0 or higher. For older versions, explicitly configure logging to prevent disk writes, or be aware of potential local log files.","message":"Prior to v1.17.0, `credstash` might have logged sensitive information to local disk when imported as a library, potentially exposing secrets or causing issues in read-only environments. As of v1.17.0, logging is disabled by default when used as a library.","severity":"gotcha","affected_versions":"<1.17.0"},{"fix":"Always use keyword arguments when calling `credstash` functions, especially for optional parameters like `kms_region`, to avoid positional argument conflicts. Upgrade to `v1.17.1` or newer.","message":"In `v1.17.1`, a bug was fixed where `kms_region` as an optional parameter could cause issues when other parameters were passed positionally. While fixed, relying solely on positional arguments for optional parameters can lead to unexpected behavior.","severity":"gotcha","affected_versions":"1.17.0"},{"fix":"If you have a legacy secret store created before December 2015 and used auto-versioning, you must run the `credstash-migrate-autoversion.py` script provided in the repository to reformat version numbers to be lexicographically sortable. Newer versions of `credstash` automatically left-pad integer versions.","message":"Older versions of `credstash` (prior to December 2015) used unpadded integers for auto-versioning secrets, which could lead to incorrect sorting and retrieval of the latest secret once versions reached 10 or more. This is a significant issue for legacy secret stores.","severity":"breaking","affected_versions":"<~2015-12 (specific version not tagged)"},{"fix":"Before using `credstash`, ensure a KMS key named `alias/credstash` exists in your AWS account and region, and run `credstash setup` from the command line (or manually create the `credential-store` DynamoDB table with `name` and `version` as primary keys).","message":"Credstash requires an initial setup: a KMS master key (default alias `credstash`) must be created manually in AWS KMS, and the `credstash setup` command must be run to create the default DynamoDB table (`credential-store`). The library will not function without these prerequisites.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Implement additional security measures on EC2 instances, such as restricting access to the Instance Metadata Service (IMDS) using `iptables` or configuring IMDSv2. Be aware that Python process memory dumps can expose secrets, a fundamental limitation when handling sensitive data in memory.","message":"The default security model for `credstash` assumes the EC2 instance boundary as the security boundary. If an attacker gains sufficient access to an EC2 instance (e.g., to the instance metadata service or process memory), they may be able to retrieve credentials.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}