Install & Compatibility
Where this runs
tested against v1.17.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.822s · 70.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.6s · import 0.762s · 72MB
70MB installed
● package 70MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
credstash
✓ import credstash
✗ from credstash import getSecret
The common pattern is to import the `credstash` module directly and call methods like `credstash.getSecret()` or `credstash.putSecret()`.
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.
import os
import credstash
import boto3
# Ensure AWS credentials are set up (e.g., via environment variables like AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION)
# Or configure a Boto3 session explicitly
# For demonstration, assume credentials are in env or IAM role is attached
# Set a specific region if not relying on AWS_DEFAULT_REGION or instance metadata
aws_region = os.environ.get('AWS_DEFAULT_REGION', 'us-east-1')
# Initialize Boto3 clients if custom sessions or specific clients are needed
kms_client = boto3.client('kms', region_name=aws_region)
dynamodb_client = boto3.client('dynamodb', region_name=aws_region)
# Instantiate Credstash (optional, can also call functions directly)
stash = credstash.Credstash(table='credential-store', region=aws_region)
secret_name = "my_test_secret"
secret_value = "supersecretpassword123"
try:
# Put a secret
# By default, uses the 'credential-store' table and 'alias/credstash' KMS key
# ensure these are set up (credstash setup and KMS key creation)
stash.putSecret(name=secret_name, secret=secret_value, version='1', kms_key='alias/credstash', kms_client=kms_client)
print(f"Secret '{secret_name}' version 1 stored successfully.")
# Get the secret
retrieved_secret = stash.getSecret(name=secret_name, kms_client=kms_client)
print(f"Retrieved secret '{secret_name}': {retrieved_secret}")
# Update the secret with a new version (auto-increment example)
stash.putSecret(name=secret_name, secret='new_supersecret_value', autoversion=True, kms_key='alias/credstash', kms_client=kms_client)
print(f"Secret '{secret_name}' updated with new version.")
updated_secret = stash.getSecret(name=secret_name, kms_client=kms_client)
print(f"Retrieved updated secret '{secret_name}': {updated_secret}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure you have configured AWS credentials and run `credstash setup` and created a KMS key 'alias/credstash'.")
credstash --version
Debug
Known issues
breakingCredstash 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.fixUpgrade `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).
affects: <=1.15.0
gotchaPrior 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.fixUpgrade 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.
affects: <1.17.0
gotchaIn `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.fixAlways 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.
affects: 1.17.0
breakingOlder 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.fixIf 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.
affects: <~2015-12 (specific version not tagged)
gotchaCredstash 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.fixBefore 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).
affects: All versions
gotchaThe 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.fixImplement 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'credstash'
The 'credstash' Python package is not installed in the current Python environment or is not accessible in the execution path.
fixInstall the credstash package using pip: `pip install credstash`
AttributeError: 'module' object has no attribute 'get'
When using the credstash Python API, developers often incorrectly try to call `credstash.get()` instead of the correct method, `credstash.getSecret()`.
fixUse `credstash.getSecret('your-secret-name')` to retrieve a secret via the Python API. bash: credstash: command not found
The `credstash` command-line executable's installation location is not included in your system's PATH environment variable, or the package was installed in an isolated environment not linked to your shell.
fixEnsure that the directory where pip installs scripts (e.g., `~/.local/bin` or your virtual environment's `bin` directory) is in your system's PATH. Alternatively, execute it directly via Python: `python -m credstash [command]`.
botocore.exceptions.ClientError: An error occurred (ExpiredToken) when calling the GetItem operation: The security token included in the request is expired.
Credstash requires valid AWS credentials to interact with KMS and DynamoDB, and this error indicates that the temporary security credentials being used have expired. Other similar `ClientError` messages often point to missing or invalid AWS credentials or insufficient IAM permissions (e.g., `AccessDeniedException`, `Unable to locate credentials`).
fixRefresh your AWS temporary credentials (e.g., by re-authenticating with your SSO provider or regenerating them). Ensure your environment (or EC2 instance profile) has valid AWS credentials configured and that the associated IAM role/user has necessary permissions (`kms:Decrypt`, `kms:GenerateDataKey`, `dynamodb:GetItem`, `dynamodb:PutItem`) for the credstash DynamoDB table and KMS key.
credstash put: error: argument value: Unable to read file ...
The `credstash put` command interprets a secret value that starts with the `@` symbol as a file path to read the secret content from, rather than the literal secret string.
fixPipe the secret to `credstash` via standard input using `echo -n 'your@secret' | credstash put 'secret-name' -`.
Upgrade
Version history
1.17.1latest on PyPI · released Apr 11, 2020
Audit
Dependencies
boto3requiredRequired for interacting with AWS KMS and DynamoDB services.
cryptographyrequiredRequired for cryptographic operations (encryption/decryption of secrets).
PyYAMLoptionalOptional dependency for YAML configuration support.