{"id":13531190,"url":"https://github.com/fugue/credstash","last_synced_at":"2025-10-21T04:54:14.512Z","repository":{"id":30715752,"uuid":"34271922","full_name":"fugue/credstash","owner":"fugue","description":"A little utility for managing credentials in the cloud","archived":false,"fork":false,"pushed_at":"2022-02-09T00:08:30.000Z","size":348,"stargazers_count":2063,"open_issues_count":56,"forks_count":215,"subscribers_count":66,"default_branch":"master","last_synced_at":"2025-10-21T04:54:09.222Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fugue.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null}},"created_at":"2015-04-20T16:20:15.000Z","updated_at":"2025-10-13T11:34:02.000Z","dependencies_parsed_at":"2022-07-28T03:39:04.653Z","dependency_job_id":null,"html_url":"https://github.com/fugue/credstash","commit_stats":null,"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"purl":"pkg:github/fugue/credstash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fcredstash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fcredstash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fcredstash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fcredstash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fugue","download_url":"https://codeload.github.com/fugue/credstash/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fugue%2Fcredstash/sbom","scorecard":{"id":413233,"data":{"date":"2025-08-11","repo":{"name":"github.com/fugue/credstash","commit":"df24f9189e843e0cdc700c015ee4f37fbd35dc40"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":2.6,"checks":[{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Code-Review","score":3,"reason":"Found 5/15 approved changesets -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Security-Policy","score":9,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Warn: One or no descriptive hints of disclosure, vulnerability, and/or timelines in security policy","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v1.17.1 not signed: https://api.github.com/repos/fugue/credstash/releases/25417172","Warn: release artifact v1.17.0 not signed: https://api.github.com/repos/fugue/credstash/releases/25203585","Warn: release artifact v1.16.2 not signed: https://api.github.com/repos/fugue/credstash/releases/23505186","Warn: release artifact v1.17.1 does not have provenance: https://api.github.com/repos/fugue/credstash/releases/25417172","Warn: release artifact v1.17.0 does not have provenance: https://api.github.com/repos/fugue/credstash/releases/25203585","Warn: release artifact v1.16.2 does not have provenance: https://api.github.com/repos/fugue/credstash/releases/23505186"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":0,"reason":"10 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2021-142 / GHSA-8q59-q68h-6hv4","Warn: Project is vulnerable to: PYSEC-2018-49","Warn: Project is vulnerable to: GHSA-3ww4-gg4f-jr7f","Warn: Project is vulnerable to: GHSA-5cpq-8wj7-hf2v","Warn: Project is vulnerable to: GHSA-9v9h-cgj8-h64p","Warn: Project is vulnerable to: PYSEC-2018-52 / GHSA-fcf9-3qw3-gxmj","Warn: Project is vulnerable to: PYSEC-2021-62 / GHSA-hggm-jpg3-v476","Warn: Project is vulnerable to: GHSA-jm77-qphf-c4w8","Warn: Project is vulnerable to: GHSA-w7pp-m8wf-vj6r","Warn: Project is vulnerable to: GHSA-x4qr-2fvf-3mr5"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-18T23:12:59.260Z","repository_id":30715752,"created_at":"2025-08-18T23:12:59.260Z","updated_at":"2025-08-18T23:12:59.260Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280207203,"owners_count":26290616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T07:01:00.787Z","updated_at":"2025-10-21T04:54:14.483Z","avatar_url":"https://github.com/fugue.png","language":"Python","funding_links":[],"categories":["Datastores","Tools","Python","Secret Management"],"sub_categories":["Online resources","Secrets Management"],"readme":"# CredStash\n\n## Quick Installation\n0. (Linux only) Install dependencies \n1. `pip install credstash`\n2. Set up a key called credstash in KMS (found in the IAM console)\n3. Make sure you have AWS creds in a place that boto/botocore can read them\n4. `credstash setup`\n\n### Linux install-time dependencies\nCredstash recently moved from PyCrypto to `cryptography`. `cryptography` uses pre-built binary wheels on OSX and Windows, but does not on Linux. That means that you need to install some dependencies if you want to run credstash on linux. \n\nFor Debian and Ubuntu, the following command will ensure that the required dependencies are installed:\n```\n$ sudo apt-get install build-essential libssl-dev libffi-dev python-dev\n```\nFor Fedora and RHEL-derivatives, the following command will ensure that the required dependencies are installed:\n```\n$ sudo yum install gcc libffi-devel python-devel openssl-devel\n```\n\nIn either case, once you've installed the dependencies, you can do `pip install credstash` as usual.\n\nSee https://cryptography.io/en/latest/installation/ for more information.\n\n\n## What is this?\nSoftware systems often need access to some shared credential. For example, your web application needs access to a database password, or an API key for some third party service.\n\nSome organizations build complete credential-management systems, but for most of us, managing these credentials is usually an afterthought. In the best case, people use systems like ansible-vault, which does a pretty good job, but leads to other management issues (like where/how to store the master key). A lot of credential management schemes amount to just SCP'ing a `secrets` file out to the fleet, or in the worst case, burning secrets into the SCM (do a github search on `password`).\n\nCredStash is a very simple, easy to use credential management and distribution system that uses AWS Key Management Service (KMS) for key wrapping and master-key storage, and DynamoDB for credential storage and sharing.\n\n## Compatibility with Other Languages \nA number of great projects exist to provide credstash compatability with other languages. Here are the ones that we know about (feel free to open a pull request if you know of another):\n\n- https://github.com/klamouri/jcredstash (Java)\n- https://github.com/adorechic/rcredstash (Ruby)\n- https://github.com/kdrakon/scala-credstash (Scala)\n- https://github.com/gmo/credstash-php (PHP)\n- https://github.com/DavidTanner/nodecredstash (Node.js)\n- https://github.com/winebarrel/gcredstash (Go)\n- https://github.com/Narochno/Narochno.Credstash (C#)\n- https://github.com/republicwireless-open/erlcredstash (Erlang)\n- https://github.com/psibi/rucredstash (Rust)\n- https://github.com/ouzi-dev/credstash-operator (Kubernetes)\n\n## How does it work?\nAfter you complete the steps in the `Setup` section, you will have an encryption key in KMS (in this README, we will refer to that key as the `master key`), and a credential storage table in DDB.\n\n### Stashing Secrets\nWhenever you want to store/share a credential, such as a database password, you simply run `credstash put [credential-name] [credential-value]`. For example, `credstash put myapp.db.prod supersecretpassword1234`. credstash will go to the KMS and generate a unique data encryption key, which itself is encrypted by the master key (this is called key wrapping). credstash will use the data encryption key to encrypt the credential value. It will then store the encrypted credential, along with the wrapped (encrypted) data encryption key in the credential store in DynamoDB.\n\nYou can also store a credential either by referencing a file or by passing the secret in via `stdin`. To add a secret from a file, instead of passing the secret as an argument pass the filename of the file containing the secret prefixed by the `@` sign. For example, `credstash put myapp.db.prod @secret.txt`. You can also pass the credential via `stdin` by passing the `-` character as the secret argument. For example, `tr -dc '[:alnum:]' \u003c /dev/urandom | fold -w 32 | head -n 1 | credstash put myapp.db.prod -`.\n\n### Getting Secrets\nWhen you want to fetch the credential, for example as part of the bootstrap process on your web-server, you simply do `credstash get [credential-name]`. For example, `export DB_PASSWORD=$(credstash get myapp.db.prod)`. When you run `get`, credstash will go and fetch the encrypted credential and the wrapped encryption key from the credential store (DynamoDB). It will then send the wrapped encryption key to KMS, where it is decrypted with the master key. credstash then uses the decrypted data encryption key to decrypt the credential. The credential is printed to `stdout`, so you can use it in scripts or assign it to environment variables.\n\n### Controlling and Auditing Secrets\nOptionally, you can include any number of [Encryption Context](http://docs.aws.amazon.com/kms/latest/developerguide/encrypt-context.html) key value pairs to associate with the credential. The exact set of encryption context key value pairs that were associated with the credential when it was `put` in DynamoDB must be provided in the `get` request to successfully decrypt the credential. These encryption context key value pairs are useful to provide auditing context to the encryption and decryption operations in your CloudTrail logs. They are also useful for constraining access to a given credstash stored credential by using KMS Key Policy conditions and KMS Grant conditions. Doing so allows you to, for example, make sure that your database servers and web-servers can read the web-server DB user password but your database servers can not read your web-servers TLS/SSL certificate's private key. A `put` request with encryption context would look like `credstash put myapp.db.prod supersecretpassword1234 app.tier=db environment=prod`. In order for your web-servers to read that same credential they would execute a `get` call like `export DB_PASSWORD=$(credstash get myapp.db.prod environment=prod app.tier=db)`\n\n### Versioning Secrets\nCredentials stored in the credential-store are versioned and immutable. That is, if you `put` a credential called `foo` with a version of `1` and a value of `bar`, then foo version 1 will always have a value of bar, and there is no way in `credstash` to change its value (although you could go fiddle with the bits in DDB, but you shouldn't do that). Credential rotation is handed through versions. Suppose you do `credstash put foo bar`, and then decide later to rotate `foo`, you can put version 2 of `foo` by doing `credstash put foo baz -v `. The next time you do `credstash get foo`, it will return `baz`. You can get specific credential versions as well (with the same `-v` flag). You can fetch a list of all credentials in the credential-store and their versions with the `list` command.\n\nIf you use incrementing integer version numbers (for example, `[1, 2, 3, ...]`), then you can use the `-a` flag with the `put` command to automatically increment the version number. However, because of the lexicographical sorting in DynamoDB, `credstash` will left-pad the version representation with zeros (for example, `[001, 025, 103, ...]`, except to 19 characters, enough to handle `sys.maxint` on 64-bit systems).\n\n#### Special Note for Those Using Credstash Auto-Versioning Before December 2015\nPrior to December 2015, `credstash` auto-versioned with unpadded integers. This resulted in a sorting error once a key hit ten versions. To ensure support for versions that were not numbers (such as dates, build versions, names, etc.), the lexicographical sorting behavior was retained, but the auto-versioning behavior was changed to left-pad integer representations.\n\nIf you've used auto-versioning so far, you should run the `credstash-migrate-autoversion.py` script included in the root of the repository. If you are supplying your own version numbers, you should ensure a lexicographic sort of your versions produces the result you desire.\n\n## Dependencies\ncredstash uses the following AWS services:\n* AWS Key Management Service (KMS) - for master key management and key wrapping\n* AWS Identity and Access Management - for access control\n* Amazon DynamoDB - for credential storage\n\n## Setup\n### tl;dr\n1. Set up a key called `credstash` in KMS\n2. Install credstash's python dependencies (or just use pip)\n3. Make sure you have AWS creds in a place that boto/botocore can read them\n4. Run `credstash setup`\n\n### Setting up KMS\n`credstash` will not currently set up your KMS master key. To create a KMS master key,\n\n1. Go to the AWS Console and make sure you are in `us-east-1`. If you want to use a key in a different region, you can pass it in using the `--kms-region` argument.\n2. Go to the KMS Console\n3. Click \"Customer managed keys\" in the left sidebar\n4. Click \"Next\" to configure a Symmetric key\n5. For alias, put \"credstash\" and click \"Next\". If you want to use a different name, be sure to pass it to credstash with the `-k` flag. \n6. Decide what IAM principals, if any, you want to be able to manage the key. Click \"Next\".\n6. On the \"Key Usage Permissions\" screen, pick the IAM users/roles that will be using credstash (you can change your mind later). Click \"Next\".\n7. Review the key policy and click \"Finish\".\n8. Done!\n\n### Setting up credstash\nThe easiest thing to do is to just run `pip install credstash`. That will download and install credstash and its dependencies (boto and PyCypto). You can also install credstash with optional YAML support by running `pip install credstash[YAML]` instead.\n\nThe second easiest thing to do is to do `python setup.py install` in the `credstash` directory.\n\nThe python dependencies for credstash are in the `requirements.txt` file. You can install them with `pip install -r requirements.txt`.\n\nIn all cases, you will need a C compiler for building `PyCrypto` (you can install `gcc` by doing `apt-get install gcc` or `yum install gcc`).\n\nYou will need to have AWS credentials accessible to boto/botocore. The easiest thing to do is to run credstash on an EC2 instance with an IAM role. Alternatively, you can put AWS credentials in the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. Or, you can put them in a file (see http://boto.readthedocs.org/en/latest/boto_config_tut.html).\n\nYou can specify the region in which `credstash` should operate by using the `-r` flag, or by setting the `AWS_DEFAULT_REGION` environment variable. Note that the command line flag takes precedence over the environment variable. If you set neither, then `credstash` will operate against us-east-1.\n\nOnce credentials are in place, run `credstash setup`. This will create the DDB table needed for credential storage.\n\n### Working with multiple AWS accounts (profiles)\n\nIf you need to work with multiple AWS accounts, an easy thing to do is to set up multiple profiles in your `~/.aws/credentials` file. For example,\n\n```\n[dev]\naws_access_key_id = AKIDEXAMPLEASDFASDF\naws_secret_access_key = SKIDEXAMPLE2103429812039423\n[prod]\naws_access_key_id= AKIDEXAMPLEASDFASDF\naws_secret_access_key= SKIDEXAMPLE2103429812039423\n```\n\nThen, by setting the `AWS_PROFILE` environment variable to the name of the profile, (dev or prod, in this case), you can point credstash at the appropriate account.\n\nFor example:\nexport AWS_PROFILE=dev ( or AWS_PROFILE=prod )\n\nSee https://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs for more information.\n\n## Usage\n```\nusage: credstash [-h] [-r REGION] [--kms-region KMS_REGION] [-t TABLE]\n                 [--log-level LOG_LEVEL] [--log-file LOG_FILE]\n                 [-p PROFILE | -n ARN]\n                 {delete,get,getall,keys,list,put,putall,setup} ...\n\nA credential/secret storage system\n\npositional arguments:\n  {delete,get,getall,keys,list,put,putall,setup}\n                        Try commands like \"/Users/Mike/.pyenv/versions/3.6.5/e\n                        nvs/rm/bin/credstash get -h\" or \"/Users/Mike/.pyenv/ve\n                        rsions/3.6.5/envs/rm/bin/credstash put --help\" to get\n                        each sub command's options\n    delete              Delete a credential from the store\n    get                 Get a credential from the store\n    getall              Get all credentials from the store\n    keys                List all keys in the store\n    list                list credentials and their versions\n    put                 Put a credential into the store\n    putall              Put credentials from json into the store\n    setup               setup the credential store\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -r REGION, --region REGION\n                        the AWS region in which to operate. If a region is not\n                        specified, credstash will use the value of the\n                        AWS_DEFAULT_REGION env variable, or if that is not\n                        set, the value in `~/.aws/config`. As a last resort,\n                        it will use us-east-1\n  --kms-region KMS_REGION\n                        Region the credstash KMS key will be read from,\n                        independent of the region the DDB table is in. If not\n                        specified, the KMS region will follow the same\n                        resolution path as --region. To save the KMS region,\n                        use `credstash setup --save-kms-region KMS_REGION`.\n                        The value in this argument takes precedence any saved\n                        value.\n  -t TABLE, --table TABLE\n                        DynamoDB table to use for credential storage. If not\n                        specified, credstash will use the value of the\n                        CREDSTASH_DEFAULT_TABLE env variable, or if that is\n                        not set, the value `credential-store` will be used\n  --log-level LOG_LEVEL\n                        Set the log level, default WARNING\n  --log-file LOG_FILE   Set the log output file, default credstash.log. Errors\n                        are printed to stderr and stack traces are logged to\n                        file\n  -p PROFILE, --profile PROFILE\n                        Boto config profile to use when connecting to AWS\n  -n ARN, --arn ARN     AWS IAM ARN for AssumeRole\n\ndelete\n    usage: credstash delete [-h] [-r REGION] [-t TABLE] [-p PROFILE | -n ARN] credential\n\n    positional arguments:\n      credential  the name of the credential to delete\n\nget\n    usage: credstash get [-h] [-n] [-v VERSION] [-f {json,csv,dotenv,yaml}]\n                        credential [context [context ...]]\n\n    positional arguments:\n      credential            the name of the credential to get. Using the wildcard\n                            character '*' will search for credentials that match\n                            the pattern\n      context               encryption context key/value pairs associated with the\n                            credential in the form of \"key=value\"\n\n    optional arguments:\n      -h, --help            show this help message and exit\n      -n, --noline          Don't append newline to returned value (useful in\n                            scripts or with binary files)\n      -v VERSION, --version VERSION\n                            Get a specific version of the credential (defaults to\n                            the latest version)\n      -f {json,csv,dotenv,yaml}, --format {json,csv,dotenv,yaml}\n                            Output format. json(default) yaml csv or dotenv.\n\ngetall\n    usage: credstash getall [-h] [-r REGION] [-t TABLE] [-p PROFILE | -n ARN] [-v VERSION] [-f {json,yaml,csv,dotenv}]\n                            [context [context ...]]\n\n    positional arguments:\n      context               encryption context key/value pairs associated with the\n                            credential in the form of \"key=value\"\n\n    optional arguments:\n      -v VERSION, --version VERSION\n                            Get a specific version of the credential (defaults to\n                            the latest version).\n      -f {json,yaml,csv,dotenv}, --format {json,yaml,csv,dotenv}\n                            Output format. json(default), yaml, csv or dotenv.\n\n\nlist\n    usage: credstash list [-h] [-r REGION] [-t TABLE] [-p PROFILE | -n ARN]\n\nput\n    usage: credstash put [-h] [-k KEY] [-c COMMENT] [-v VERSION] [-a]\n                        [-d {SHA,SHA224,SHA256,SHA384,SHA512,MD5}] [-P]\n                        credential [value] [context [context ...]]\n\n    positional arguments:\n      credential            the name of the credential to store\n      value                 the value of the credential to store or, if beginning\n                            with the \"@\" character, the filename of the file\n                            containing the value, or pass \"-\" to read the value\n                            from stdin\n      context               encryption context key/value pairs associated with the\n                            credential in the form of \"key=value\"\n\n    optional arguments:\n      -h, --help            show this help message and exit\n      -k KEY, --key KEY     the KMS key-id of the master key to use. See the\n                            README for more information. Defaults to\n                            alias/credstash\n      -c COMMENT, --comment COMMENT\n                            Include reference information or a comment about value\n                            to be stored.\n      -v VERSION, --version VERSION\n                            Put a specific version of the credential (update the\n                            credential; defaults to version `1`).\n      -a, --autoversion     Automatically increment the version of the credential\n                            to be stored. This option causes the `-v` flag to be\n                            ignored. (This option will fail if the currently\n                            stored version is not numeric.)\n      -d {SHA,SHA224,SHA256,SHA384,SHA512,MD5}, --digest {SHA,SHA224,SHA256,SHA384,SHA512,MD5}\n                            the hashing algorithm used to to encrypt the data.\n                            Defaults to SHA256\n      -P, --prompt          Prompt for secret\n\n\nsetup\n    usage: credstash setup [-h] [--save-kms-region SAVE_KMS_REGION]\n                          [--tags [TAGS [TAGS ...]]]\n\n    optional arguments:\n      -h, --help            show this help message and exit\n      --save-kms-region SAVE_KMS_REGION\n                            Save the region the credstash KMS key will be read\n                            from, independent of the region the DDB table is in.\n                            This value is saved in ~/.credstash\n      --tags [TAGS [TAGS ...]]\n                            Tags to apply to the Dynamodb Table passed in as a\n                            space sparated list of Key=Value\n```\n## IAM Policies\n\n### Secret Writer\nYou can put or write secrets to credstash by either using KMS Key Grants, KMS Key Policies, or IAM Policies. If you are using IAM Policies, the following IAM permissions are the minimum required to be able to put or write secrets:\n```\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Action\": [\n        \"kms:GenerateDataKey\"\n      ],\n      \"Effect\": \"Allow\",\n      \"Resource\": \"arn:aws:kms:us-east-1:AWSACCOUNTID:key/KEY-GUID\"\n    },\n    {\n      \"Action\": [\n        \"dynamodb:PutItem\"\n      ],\n      \"Effect\": \"Allow\",\n      \"Resource\": \"arn:aws:dynamodb:us-east-1:AWSACCOUNTID:table/credential-store\"\n    }\n  ]\n}\n```\nIf you are using Key Policies or Grants, then the `kms:GenerateDataKey` is not required in the policy for the IAM user/group/role. Replace `AWSACCOUNTID` with the account ID for your table, and replace the KEY-GUID with the identifier for your KMS key (which you can find in the KMS console).\n\n### Secret Reader\nYou can read secrets from credstash with the get or getall actions by either using KMS Key Grants, KMS Key Policies, or IAM Policies. If you are using IAM Policies, the following IAM permissions are the minimum required to be able to get or read secrets:\n```\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Action\": [\n        \"kms:Decrypt\"\n      ],\n      \"Effect\": \"Allow\",\n      \"Resource\": \"arn:aws:kms:us-east-1:AWSACCOUNTID:key/KEY-GUID\"\n    },\n    {\n      \"Action\": [\n        \"dynamodb:GetItem\",\n        \"dynamodb:Query\",\n        \"dynamodb:Scan\"\n      ],\n      \"Effect\": \"Allow\",\n      \"Resource\": \"arn:aws:dynamodb:us-east-1:AWSACCOUNTID:table/credential-store\"\n    }\n  ]\n}\n```\nIf you are using Key Policies or Grants, then the `kms:Decrypt` is not required in the policy for the IAM user/group/role. Replace `AWSACCOUNTID` with the account ID for your table, and replace the KEY-GUID with the identifier for your KMS key (which you can find in the KMS console). Note that the `dynamodb:Scan` permission is not required if you do not use wildcards in your `get`s.\n\n### Setup Permissions\nIn order to run `credstash setup`, you will also need to be able to perform the following DDB operations:\n```\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Action\": [\n                \"dynamodb:CreateTable\",\n                \"dynamodb:DescribeTable\"\n            ],\n            \"Effect\": \"Allow\",\n            \"Resource\": \"arn:aws:dynamodb:us-west-2:\u003cACCOUNT NUMBER\u003e:table/credential-store\"\n        },\n        {\n            \"Action\": [\n                \"dynamodb:ListTables\"\n            ],\n            \"Effect\": \"Allow\",\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\n## Security Notes\nAny IAM principal who can get items from the credential store DDB table, and can call KMS.Decrypt, can read stored credentials.\n\nThe 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. That means that by default, the instance boundary is the security boundary for this system. If you are worried about unauthorized users on your instance, you should take steps to secure access to the Instance Metadata Service (for example, use iptables to block connections to 169.254.169.254 except for privileged users). Also, because 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 again, in the target deployment case, the security boundary is assumed to be the instance boundary.\n\n## Developing credstash\n\n### Running the tests\n\n```\npython -m unittest discover -v tests \"*.py\"\n```\n\n### Running the integration tests using BATS\n1. The integration tests require a working install of credstash. I recommend not using your primary development/production install.\n2. Download and install BATS: https://github.com/sstephenson/bats \n3. Run the tests: `bats integration_tests/`\n\nNew integration test PRs are welcome!\n\n## Frequently Asked Questions (FAQ)\n\n### 1. Where is the master key stored?\nThe 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.\n\n### 2. How is credential rotation handled?\nEvery credential in the store has a version number. Whenever you want to 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.\n\n### 3. How much do the AWS services needed to run credstash cost?\ntl;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.\n\nThe master key in KMS costs $1 per month.\n\nThe 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).\n\nIf 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).\n\n### 4. Why DynamoDB for the credential store? Why not S3?\nDDB fits the application really well. Having very low latency fetches are really nice if credstash is in the critical path of spinning up an application. Being able to turn throughput up or down based on load and requirements are also great things to have in a config management tool. Also, as credstash gets into more complex credential management functions, the query capabilities of DDB get super handy.\n\nThat said, S3 support may happen someday.\n\n### 5. Where can I learn more about use cases and context for something like credstash?\nCheck out this blog post: http://blog.fugue.it/2015-04-21-aws-kms-secrets.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffugue%2Fcredstash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffugue%2Fcredstash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffugue%2Fcredstash/lists"}