{"id":20812303,"url":"https://github.com/ukayani/kms-env","last_synced_at":"2025-05-07T10:37:32.637Z","repository":{"id":143882606,"uuid":"83520943","full_name":"ukayani/kms-env","owner":"ukayani","description":"A tool to encrypt and decrypt environment variables using KMS","archived":false,"fork":false,"pushed_at":"2023-04-18T23:31:09.000Z","size":41,"stargazers_count":17,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-27T03:03:19.634Z","etag":null,"topics":["aws","decryption","docker","ecs","encryption","kms"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/ukayani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-03-01T06:37:07.000Z","updated_at":"2024-01-31T11:01:19.000Z","dependencies_parsed_at":null,"dependency_job_id":"f4dcf983-1c0a-4f25-bc9a-db14fe9598e8","html_url":"https://github.com/ukayani/kms-env","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukayani%2Fkms-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukayani%2Fkms-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukayani%2Fkms-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukayani%2Fkms-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ukayani","download_url":"https://codeload.github.com/ukayani/kms-env/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252860791,"owners_count":21815568,"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":["aws","decryption","docker","ecs","encryption","kms"],"created_at":"2024-11-17T20:52:46.423Z","updated_at":"2025-05-07T10:37:32.616Z","avatar_url":"https://github.com/ukayani.png","language":"JavaScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# KMS Env ![Build Status](https://travis-ci.org/ukayani/kms-env.svg?branch=master)\n\nA tool used to encrypt environment and decrypt environment variables\nusing KMS to support passing of encrypted environment variables to\ndocker containers.\n\nIf you are looking for a way to pass environment variables to a\ndocker container in a secure manner, this tool aims to help.\n\n# Requirements\n\n- NodeJS v7.x\n- A AWS Customer Master Key in KMS\n- Docker\n\n# How it works\n\n## AWS Setup\n\n1. Create a CMK in AWS. IAM \u003e Encryption Keys\n2. Give a user or role access to this key via the key's policy\n\nBy default, the tool will use the default credential chain for AWS.\n\nYou can specify Access Keys and Secret Access keys via Environment variables, or cli arguments.\nIf you are running the tool on an EC2 instance, the instance profile will be used.\n\n### Usage\n\n```bash\nUsage: kms-env [options] [command]\n\n\n  Commands:\n\n    init [keyId] [file]      Initialize an environment variable file with provided CMK Id\n    add [file] [entries...]  Adds environment variable to file after encrypting the value\n    decrypt                  Decrypts secure environment variables and generates a bash export for each. Can be used with bash eval command to do in place decryption of env variables\n    show [file]              Show the contents of the env file decrypting all secure vars. Warning: Only use for debugging!\n\n  Options:\n\n    -h, --help                        output usage information\n    -V, --version                     output the version number\n    -k, --access-key-id \u003cid\u003e          AWS Access key ID. Env: $AWS_ACCESS_KEY_ID\n    -s, --secret-access-key \u003csecret\u003e  AWS Secret Access Key. Env: $AWS_SECRET_ACCESS_KEY\n    -r, --region \u003cregion\u003e             AWS Region. Env: $AWS_REGION\n    -p, --profile \u003cname\u003e              AWS Credential profile to use\n```\n\n**Exporting AWS Region**\n\nAn AWS Region must be specified when running `kms-env`. It can be provided via the `--region` parameter or with the following export:\n\n```bash\nexport AWS_REGION=us-east-1\n```\n\nThe above command will set your region to `us-east-1`\n\n## Initializing an env file\n\nTo get started, you must run the `init` command and specify\nyour KMS CMK ID or alias. You can find this in the AWS console: IAM \u003e Encryption Keys\n\n```bash\n$ kms-env init [keyid] [filename]\n```\n\nLet's initialize a file called `test.env` using a CMK with alias `mykey`\n\n```bash\n$ kms-env init alias/mykey test.env\n```\n\nAfter running the `init` command, a `test.env` file will be created in your\n working directory.\n\nIt will contain the following:\n\n```bash\nKMS_DATA_KEY = [encrypted value]\n```\n\nYou can now start adding secure environment variables to this file\n\n## Adding secure variables\n\nTo add secure environment variables to your file you can use:\n\n```bash\n$ kms-env add [filename] [entries...]\n```\n\nLet's add the following environment variables:\n\n- DATABASE_PASS = test123\n- DATABASE_USER = alice\n\n```bash\n$ kms-env add test.env DATABASE_PASS=test123 DATABASE_USER=alice\n```\n\nThe new environment variables should be added to your `test.env`:\n\n```bash\nKMS_DATA_KEY = [encrypted value]\nDATABASE_PASS = secure:[encrypted value]\nDATABASE_USER = secure:[encrypted value]\n```\n\n## Decrypting secure variables\n\nOnce you have exported the above environment variables in your an environment,\nyou can easily have them decrypted\n\n```bash\n$ export KMS_DATA_KEY = ...\n$ export DATABASE_PASS = secure:...\n$ export DATABASE_USER = secure:...\n\n\n$ eval $(kms-env decrypt)\n$ echo $DATABASE_PASS\n$ test123\n$ echo $DATABASE_USER\n$ alice\n```\n\nThe `decrypt` command will output export statements which you can run through `eval`\nto have the secure environment variables replaced in place.\n\n## Example: Secure environment variables to Docker container\n\nThe motivation behind creating kms-env was to securely pass sensitive environment\nvariables to an application running in a docker container in AWS\n\nThe `env` file created by `kms-env` can be used with the `docker run` command using the `--env-file [file]` argument.\n\n### Step 1: Create a docker image with kms-env installed\n\nTo use `kms-env` to securely pass env vars to a docker container, the container needs kms-env installed.\n\n**Example Dockerfile with node + kms-env**\n\nAn example docker file which has kms-env installed is provided at [Dockerfile](examples/Dockerfile)\n\nYou can use this docker file as your base image for your application image if you are building a NodeJs application.\nIf you are using a different platform (eg JVM) then you will also need to install the necessary dependencies for that platform.\n\n**How it works**\nThe docker file uses an `env-decrypt` bash entrypoint script, so it will first run `kms-env decrypt` and then run whatever is supplied as a command to `docker run`\n\nSo, for example:\n\n```\ndocker run [image] npm start\n```\n\nAssuming your image has the working directory set to a node project, the `npm start` command will run after the `kms-env decrypt`\n\n### Step 2: Permissions to the CMK\n\nIn order for your container to decrypt environment variables, it will need read access to the CMK used to\nencrypt the env vars.\n\nTo set up permissions, you will need to attach a policy to the role which is assumed by your AWS EC2 instance\nor the task role (if you are using AWS ECS)\n\n**Example IAM Policy Granting Access to a CMK**\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Action\": [\n                \"kms:Decrypt\"\n            ],\n            \"Resource\": [\n                \"arn:aws:kms:us-east-1:xxxxxxxxxz:key/xxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx\"\n            ],\n            \"Effect\": \"Allow\"\n        }\n    ]\n}\n```\n\nThe above policy, when attached to a role will give decrypt access for the CMK. You must supply the ARN for your specific key.\n\n**ECS Task Role**\nIf you are running docker containers using AWS ECS, you would attach the above policy to the [Task Role](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) associated with your ECS Task Definition\n\n\n### Step 3: Supplying an env file to your container\n\nOnce you have a container image that has `kms-env` installed and the container is running on an EC2 instance or ECS Task with\nthe correct permissions, you can supply your `env` files to your container.\n\n**Supplying env via docker run**\n\nIf you are running docker on EC2 directly, you can use supply your `env` file via:\n\n```docker\ndocker run --env-file [filepath] [image] [command]\n```\n\nThe above command will run your container with the supplied env file as environment variables. If the container is using the example base image,\nit will automatically decrypt the secure env vars in place for your application to read.\n\n**Supplying env via ECS Task Definition**\n\nTo supply environment variables to a container running on ECS you will need to supply them via the task definition JSON\n\nThe following is an example task def (with some fields left blank) where we supply the environment variables which would be present in\na `.env` file generated by `kms-env`\n\n**Example Task Def**\n```json\n{\n    \"family\": \"\",\n    \"taskRoleArn\": \"\",\n    \"networkMode\": \"\",\n    \"containerDefinitions\": [\n        {\n            \"name\": \"\",\n            \"image\": \"\",\n            \"cpu\": 0,\n            \"memory\": 0,\n            \"memoryReservation\": 0,\n            \"essential\": true,\n            \"environment\": [\n                {\n                    \"name\": \"MY_VAR\",\n                    \"value\": \"secure:xxxxxxxxx\"\n                }\n            ]\n        }\n    ]\n}\n```\n\nWhen the above task runs, it would supply the env vars to the docker container similar to the `--env` or `-e` argument for the `docker run` command.\n\n# Optional Parameters\n\n### AWS Credentials\n\nTo supply credentials manually you can use the following parameters:\n\n- **--access-key-id** - To specify your access key ID\n- **--secret-access-key** - To specify your secret\n- **--region** - To specify the AWS Region\n\n**Using Profiles**\n\nAlternatively you can supply an AWS credential profile to use via:\n\n- **--profile** - To use a credential profile instead of supplying access key and secret\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fukayani%2Fkms-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fukayani%2Fkms-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fukayani%2Fkms-env/lists"}