CredStash

Quick Installation (Linux only)

(Install dependencies)

Security Notes

• Any IAM principal who can get items from the credential store DDB table and call KMS Decrypt can read stored credentials.
• The target deployment story for CredStash is an EC2 instance running with an IAM role that has permissions to read the credential store and use the master key. Since IAM role credentials are vended by the instance metadata service, by default, any user on the system can fetch creds and use them to retrieve credentials.
• If you're worried about unauthorized users on your instance, take steps to secure access to the Instance Metadata Service (e.g., using iptables to block connections to 169.254.169.254 except for privileged users).
• Since CredStash is written in Python, if an attacker can dump the memory of the CredStash process, they may be able to recover credentials. This is a known issue, but in the target deployment case, the security boundary is assumed to be the instance boundary.

Developing CredStash

Running the tests

python -m unittest discover -v tests "*.py"

Running the integration tests using BATS

1. The integration tests require a working install of CredStash. I recommend not using your primary development/production install.
2. Download and install BATS: https://github.com/sstephenson/bats
3. Run the tests: bats integration_tests/

New integration test PRs are welcome!

Frequently Asked Questions (FAQ)

1. Where is the master key stored?

The master key is stored in AWS Key Management Service (KMS), where it is stored in secure HSM-backed storage. The Master Key never leaves the KMS service.

2. How is credential rotation handled?

Every credential in the store has a version number. Whenever you want to update a credential to a new value, you have to do a put with a new credential version. For example, if you have foo version 1 in the database, then to update foo, you can put version 2. You can either specify the version manually (i.e., credstash put foo bar -v 2), or you can use the -a flag, which will attempt to autoincrement the version number (for example, credstash put foo baz -a). Whenever you do a get operation, CredStash will fetch the most recent (highest version) version of that credential. So, to do credential rotation, simply put a new version of the credential, and clients fetching the credential will get the new version.

3. How much do the AWS services needed to run CredStash cost?

tl;dr: If you are using less than 25 reads/sec and 25 writes per second on DDB today, it will cost ~$1/month to use CredStash.

• The master key in KMS costs $1 per month.
• The credential store DDB table uses 1 provisioned read and 1 provisioned write throughput, along with a small amount of actual storage. This falls well below the free tier for DDB (25 reads and 25 writes per second). If you are already a heavy DDB user and exceed the free tier, the credential store table will cost about $0.53 per month (mostly from the write throughput).
• If you are using CredStash heavily and need to increase the provisioned reads/writes, you may incur additional charges. You can estimate your bill using the AWS Simple Monthly Calculator (http://calculator.s3.amazonaws.com/index.html#s=DYNAMODB).

> Visit credstash Website <