{"id":19330732,"url":"https://github.com/versent/unicreds","last_synced_at":"2025-05-12T04:30:42.737Z","repository":{"id":57485455,"uuid":"47814197","full_name":"Versent/unicreds","owner":"Versent","description":"unicreds is a CLI which manages secrets in AWS using DynamoDB and KMS.","archived":false,"fork":false,"pushed_at":"2023-06-05T16:52:14.000Z","size":394,"stargazers_count":117,"open_issues_count":19,"forks_count":40,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-04-01T00:11:30.419Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://github.com/Versent/unicreds","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Versent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-12-11T08:23:20.000Z","updated_at":"2024-09-27T03:21:05.000Z","dependencies_parsed_at":"2024-06-18T15:24:30.552Z","dependency_job_id":"cb1ff719-82dd-4906-af79-ffa2a2f05a3a","html_url":"https://github.com/Versent/unicreds","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Funicreds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Funicreds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Funicreds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Versent%2Funicreds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Versent","download_url":"https://codeload.github.com/Versent/unicreds/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253675086,"owners_count":21945894,"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","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-11-10T02:37:45.997Z","updated_at":"2025-05-12T04:30:42.236Z","avatar_url":"https://github.com/Versent.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build Status](https://travis-ci.org/Versent/unicreds.svg?branch=master)](https://travis-ci.org/Versent/unicreds)\n\n# unicreds\n\nUnicreds is a command line tool to manage secrets within an AWS account, the aim is to keep securely stored\nwith your systems and data so you don't have to manage them externally. It uses [DynamoDB](https://aws.amazon.com/dynamodb/) and [KMS](https://aws.amazon.com/kms/) to store and\nencrypt these secrets. Access to these keys is controlled using [IAM](https://aws.amazon.com/iam/).\n\nUnicreds is written in [Go](https://golang.org/) and is based on [credstash](https://github.com/fugue/credstash).\n\n# setup\n\n1. Create a KMS key in IAM, using an aws profile you have configured in the aws CLI. You can ommit `--profile` if you use the Default profile.\n```\naws --region ap-southeast-2 --profile [yourawsprofile] kms create-key --query 'KeyMetadata.KeyId'\n```\n**Note:** You will also need to assign permission to users other than the root account to access and use the key see [How to Help Protect Sensitive Data with AWS KMS](https://blogs.aws.amazon.com/security/post/Tx79IILINW04DC/How-to-Help-Protect-Sensitive-Data-with-AWS-KMS).\n2. Assign the `credstash` alias to the key using the key id printed when you created the KMS key.\n```\naws --region ap-southeast-2 --profile [yourawsprofile] kms create-alias --alias-name 'alias/credstash' --target-key-id \"xxxx-xxxx-xxxx-xxxx-xxxx\"\n```\n3. Run unicreds setup to create the dynamodb table in your region, ensure you have your credentials configured using the [awscli](https://aws.amazon.com/cli/).\n```\nunicreds setup --region ap-southeast-2 --profile [yourawsprofile]\n```\n**Note:** It is really important to tune DynamoDB to your read and write requirements if you're using unicreds with automation!\n\n# demo\n\nTo illustrate how unicreds works I made a screen recording of list, put, get and delete.\n\n![Image of screencast](docs/images/unicreds_recording.gif)\n\n# usage\n\n```\nusage: unicreds [\u003cflags\u003e] \u003ccommand\u003e [\u003cargs\u003e ...]\n\nA credential/secret storage command line tool.\n\nFlags:\n      --help                     Show context-sensitive help (also try --help-long and\n                                 --help-man).\n  -c, --csv                      Enable csv output for table data.\n  -d, --debug                    Enable debug mode.\n  -j, --json                     Output results in JSON\n  -r, --region=REGION            Configure the AWS region\n  -p, --profile=PROFILE          Configure the AWS profile\n  -R, --role=ROLE                Specify an AWS role ARN to assume\n  -t, --table=\"credential-store\"\n                                 DynamoDB table.\n  -k, --alias=\"alias/credstash\"  KMS key alias.\n  -E, --enc-context=ENC-CONTEXT ...\n                                 Add a key value pair to the encryption context.\n      --version                  Show application version.\n\nCommands:\n  help [\u003ccommand\u003e...]\n    Show help.\n\n  setup\n    Setup the dynamodb table used to store credentials.\n\n  get \u003ccredential\u003e [\u003cversion\u003e]\n    Get a credential from the store.\n\n  getall [\u003cflags\u003e]\n    Get latest credentials from the store.\n\n  list [\u003cflags\u003e]\n    List latest credentials with names and version.\n\n  put \u003ccredential\u003e \u003cvalue\u003e [\u003cversion\u003e]\n    Put a credential into the store.\n\n  put-file \u003ccredential\u003e \u003cvalue\u003e [\u003cversion\u003e]\n    Put a credential from a file into the store.\n\n  delete \u003ccredential\u003e\n    Delete a credential from the store.\n\n  exec \u003ccommand\u003e...\n    Execute a command with all secrets loaded as environment variables.\n```\n\nUnicreds supports the `AWS_*` environment variables, and configuration in `~/.aws/credentials` and `~/.aws/config`\n\n# examples\n\n* List secrets using default profile:\n```\n$ unicreds list\n```\n\n* List secrets using the default profile, in a different region:\n```\n$ unicreds -r us-east-2 list\n$ AWS_REGION=us-east-2 unicreds list\n```\n\n* List secrets using profile MYPROFILE in `~/.aws/credentials` or `~/.aws/config`\n```\n$ unicreds -r us-west-2 -p MYPROFILE list\n$ AWS_PROFILE=MYPROFILE unicreds list\n```\n\n* List secrets using a profile, but also assuming a role:\n```\n$ unicreds -r us-west-2 -p MYPROFILE -R arn:aws:iam::123456789012:role/MYROLE list\n```\n\n* Store a login for `test123` from unicreds using the encryption context feature.\n```\n$ unicreds -r us-west-2 put test123 -E 'stack:123' testingsup\n   • stored                    name=test123 version=0000000000000000001\n```\n\n* Retrieve a login for `test123` from unicreds using the encryption context feature.\n```\n$ unicreds -r us-west-2 get test123 -E 'stack:123'\ntestingsup\n```\n\n* Example of a failed encryption context check.\n```\n$ unicreds -r us-west-2 get test123 -E 'stack:12'\n   ⨯ failed                    error=InvalidCiphertextException:\n\tstatus code: 400, request id: 0fed8a0b-5ea1-11e6-b359-fd8168c3c784\n```\n\n* Execute `env` command, all secrets are loaded as environment variables.\n```\n$ unicreds -r us-west-2 exec -- env\n```\n\n# references\n\n* [How to Protect the Integrity of Your Encrypted Data by Using AWS Key Management Service and EncryptionContext](https://blogs.aws.amazon.com/security/post/Tx2LZ6WBJJANTNW/How-to-Protect-the-Integrity-of-Your-Encrypted-Data-by-Using-AWS-Key-Management)\n\n# install\n\nIf you're on OSX you can install unicreds using homebrew now!\n\n```\nbrew tap versent/homebrew-taps\nbrew install unicreds\n```\n\nOtherwise grab an archive from the [github releases page](https://github.com/Versent/unicreds/releases).\n\n# development\n\nI use `scantest` to watch my code and run tests on save.\n\n```\ngo get github.com/smartystreets/scantest\n```\n\n# testing\nYou can run unit tests which mock out the KMS and DynamoDB backend using `make test`.\n\nThere is an integration test you can run using `make integration`. You must set the `AWS_REGION` (default `us-west-2`), `UNICREDS_KEY_ALIAS` (default `alias/unicreds`), and `UNICREDS_TABLE_NAME` (default `credential-store`) environment variables to point to valid AWS resources.\n\n# auto-versioning\n\nIf you've been using unicreds auto-versioning before September 2015, Unicreds had the [same](https://github.com/fugue/credstash/issues/51) [bug](https://github.com/Versent/unicreds/issues/34) as credstash when auto-versioning that results in a sorting error after ten versions. You should be able to run the [credstash-migrate-autoversion.py](https://github.com/fugue/credstash/blob/master/credstash-migrate-autoversion.py) script included in the root of the credstash repository to update your versions prior to using the latest version of unicreds.\n\n# Docker ENTRYPOINT\n\nIt is possible to use `unicreds exec` as an [entrypoint](https://docs.docker.com/engine/reference/builder/#/entrypoint) for loading safely your secrets as environment variables inside your container in AWS ECS.\n\n### Example\n```\nRUN curl -sL \\\n    https://github.com/Versent/unicreds/releases/download/v1.5.0/unicreds_1.5.0_linux_x86_64.tgz \\\n | tar zx -C /usr/local/bin \\\n \u0026\u0026 chmod +x /usr/local/bin/unicreds\nENTRYPOINT [\"/usr/local/bin/unicreds\", \"exec\", \"--\"]\n```\n\nWith [IAM roles for Amazon ECS tasks](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) you can give the necessary privileges to your container so that it can exploit `unicreds`.\n\n# todo\n\n* Add the ability to filter list / getall results using DynamoDB filters, at the moment I just use `| grep blah`.\n* Work on the output layout.\n* Make it easier to import files\n\n# license\n\nThis code is Copyright (c) 2015 Versent and released under the MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE.md file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversent%2Funicreds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fversent%2Funicreds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fversent%2Funicreds/lists"}