{"id":20364346,"url":"https://github.com/bandwidth/vault-shim","last_synced_at":"2026-03-09T13:02:29.848Z","repository":{"id":257343775,"uuid":"830610855","full_name":"Bandwidth/vault-shim","owner":"Bandwidth","description":"Hashicorp Vault sidecar libraries","archived":false,"fork":false,"pushed_at":"2025-03-25T19:59:12.000Z","size":71,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-07-20T17:05:05.717Z","etag":null,"topics":["sdlc-enforced"],"latest_commit_sha":null,"homepage":null,"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/Bandwidth.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-07-18T15:52:22.000Z","updated_at":"2025-05-28T19:25:16.000Z","dependencies_parsed_at":"2024-09-16T05:55:06.001Z","dependency_job_id":"14c8ddb4-1183-460b-a399-35d17a8c0ed0","html_url":"https://github.com/Bandwidth/vault-shim","commit_stats":null,"previous_names":["bandwidth/vault-shim"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/Bandwidth/vault-shim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bandwidth%2Fvault-shim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bandwidth%2Fvault-shim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bandwidth%2Fvault-shim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bandwidth%2Fvault-shim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Bandwidth","download_url":"https://codeload.github.com/Bandwidth/vault-shim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Bandwidth%2Fvault-shim/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30297111,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T11:12:22.024Z","status":"ssl_error","status_checked_at":"2026-03-09T11:10:54.577Z","response_time":61,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["sdlc-enforced"],"created_at":"2024-11-15T00:11:22.685Z","updated_at":"2026-03-09T13:02:29.814Z","avatar_url":"https://github.com/Bandwidth.png","language":"Go","readme":"# vault-shim\nInject secrets from HashiCorp Vault into the environment\n\n- [Usage](#usage)\n    - [Installation](#installation)\n    - [Inputs and Outputs](#inputs-and-outputs)\n        - [Generic Secrets](#generic-secrets)\n- [Examples](#examples)\n    - [Simple Example](#simple-example)\n    - [Application Container Example](#application-container-example)\n    - [Shared AWS Account Example](#shared-aws-account-example)\n    - [AWS Credentials From Openshift](#aws-credentials-from-openshift)\n- [FAQ](#faq)\n    - [Where can I download vault-shim?](#where-can-i-download-vault-shim)\n    - [How do my workloads get access to vault?](#how-do-my-workloads-get-access-to-vault)\n    - [How does vault-shim auth with vault?](#how-does-vault-shim-auth-with-vault)\n\n## Usage\nReads secrets from vault then runs a specified command with the commands environment populated with the retrieved secrets.\n`\u003ccommand\u003e` must be a fully qualified or relative path to some executable. No shell is assumed.\n```\nvault-shim run-cmd -- \u003ccommand\u003e\n```\n\n### Installation\nTo install vault-shim, download the installer from GitHub and execute it.\n```shell\ncurl -H 'Accept: application/vnd.github.v3.raw' -L -o vault-shim-installer.sh https://raw.githubusercontent.com/Bandwidth/vault-shim/\u003cVERSION\u003e/vault-shim-installer.sh\nchmod +x vault-shim-installer.sh\n./vault-shim-installer.sh \"\u003cVERSION\u003e\"\n\nvault-shim --help\n```\n\n### Inputs and Outputs\nWhat secrets are read from vault and passed to the run command are determined by what environmental variables are set that contain the `VAULT__` prefix.\n\n#### Generic Secrets\nEnvironmental variable input format for reading generic secrets.\n```\nexport VAULT__\u003cSECRET_NAME\u003e=\u003cnamespace\u003e::\u003cmount\u003e:\u003cpath\u003e:\u003ckey\u003e[@\u003cversion][::\u003cexport_name\u003e]\n```\nEnvironmental variable output when a generic secret environmental variable input is set.\n```\n\u003cSECRET_NAME\u003e=\u003cVALUE_IN_VAULT\u003e\n```\n\n#### AWS Credentials\nReading AWS credentials from vault using vault-shim is similar to reading generic secrets but has a few caveats. Because AWS credentials issued from vault are short lived they can not just be exported to the environment of the running process.\nInstead for every AWS credential required an aws profile will be created by vault-shim with the [credential_process](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html) setting set in an AWS configuration file. vault-shim will set an appropriate value for `credential_process`.\nThis will ensure long running processes will have access to active AWS credentials.\nThe various AWS SDKs will work as is with this process as long as the correct AWS profile is specified. Multiple AWS credentials can be generated.\n\nEnvironmental variable input format for reading AWS credentials.\n```\nexport VAULT__\u003cDESIRED_AWS_PROFILE_NAME\u003e=AWS:/aws_deploy_role:\u003caccount-id\u003e:\u003cvault-sts-role\u003e:\u003caws-assume-role\u003e\n```\n\nThe following profile would be created. The profile will be appended to the AWS configuration file or a new configuration file will be created if one does not exist.\n```\n[profile \u003cDESIRED_AWS_PROFILE_NAME\u003e]\ncredential_process = vault-shim aws-credentials --namespace=\"\" --secret-path=\"\u003csecret-path\u003e\" --account-id=\"\u003caccount-id\u003e\" --vault-sts-role-name=\"\u003cvault-sts-role\u003e\" --aws-assume-role-name=\"\u003caws-assume-role\u003e\"\n```\n\nThe only environmental variable exported is the aws config file location. This tells the AWS SDK where the aws config file is located. This will default to an auto generated location but can be specified with the `aws-config-file` flag.\n```\nAWS_CONFIG_FILE=/tmp/\u003crandom_16_char_string\u003e_aws_config\n```\n\n## Examples\n### Simple Example\nThis small example demonstrates that vault-shim reads the environment for any variables that are prefixed with `VAULT__` and uses their values to read the secret in vault then pass them to the run command specified.\n```\nexport VAULT__SECRETONE=workloads/foo/bar::secret:secret_one:FIRST_KEY\nexport VAULT__SECRETTWO=workloads/foo/bar::secret:secret_two:SECOND_KEY\n./vault-shim run-cmd --vault-addr \"vaultlocation:8200\" -- /usr/bin/env | grep SECRET\nSECRETONE=whateversecretvaluewassetforsecretoneFIRST_KEY # the run-cmd here was /usr/bin/env so all of the env is printed and we grep for just our secrets so they are the only output in the example.\nSECRETTWO=whateversecretvaluewassetforsecrettwoSECOND_KEY\n```\n### Application Container Example\nThe following shows building a container that uses vault-shim to run and pass secrets to an application. These should not get passed to the final image. The multi-stage build is used to avoid this.\n\nDockerfile\n```dockerfile\nFROM python:3.12 as vault-shim\n\nRUN curl -H 'Accept: application/vnd.github.v3.raw' -L -o vault-shim-installer.sh https://raw.githubusercontent.com/Bandwidth/vault-shim/\u003cVERSION\u003e/vault-shim-installer.sh\nRUN chmod +x \"vault-shim-installer.sh\" \nRUN ./vault-shim-installer.sh \"\u003cVERSION\u003e\"\n\n########## Second Stage ##########\nFROM python:3.12\nCOPY example.py .\nCOPY --from=vault-shim /usr/local/bin/vault-shim /usr/local/bin/vault-shim\nCMD [\"vault-shim\", \"run-cmd\", \"--vault-addr\", \"vaultlocation:8200\", \"--\", \"/usr/local/bin/python\", \"example.py\"]\n```\nexample.py\n```python\nimport os\nprint(os.environ['BAR'])\n```\n\nRunning our container\n```bash\ndocker run -it -e VAULT__BAR=workloads/someenv/somedomain::secret:test_secret:FOO example\n```\nSetting the environmental variable `VAULT__BAR` when running the container sets the environmental variable `BAR` with the value of what ever is stored in vault at `workloads/someenv/somedomain::secret:test_secret:FOO` for our app.\n\nNote: This is just an example using `docker run` to highlight that the `VAULT__BAR` environmental variable needs to be passed to the container but the concepts would still work with ECS and Kubernetes.\n\n### AWS Credentials From Openshift\nThe following shows an example running a container that receives AWS credentials in an openshift cluster.\n\nThis assumes our example.jar uses a standard AWS SDK for interacting with AWS.\n\nDockerfile\n```dockerfile\nFROM python:3.12 as vault-shim\n\nRUN curl -H 'Accept: application/vnd.github.v3.raw' -L -o vault-shim-installer.sh https://raw.githubusercontent.com/Bandwidth/vault-shim/\u003cVERSION\u003e/vault-shim-installer.sh\nRUN chmod +x \"vault-shim-installer.sh\"\nRUN ./vault-shim-installer.sh \"\u003cVERSION\u003e\"\n\n########## Second Stage ##########\nFROM example.jfrog.io/eclipse-temurin:19.0.2_7-jre\n\nCOPY --from=vault-shim /usr/local/bin/vault-shim /usr/local/bin/vault-shim\n\nCOPY example.jar .\n\nENTRYPOINT [\"vault-shim\", \"run-cmd\", \"--vault-addr\", \"vaultlocation:8200\", \"--\", \"/opt/java/openjdk/bin/java\", \"-jar\", \"example.jar\"]\n```\n\nAtlas Application Deployment (The important part for this example is setting the AWS_PROFILE and VAULT__EXAMPLE env vars).\n```yaml\napiVersion: proj.io/v1alpha1\nkind: Application\nmetadata:\n  name: example\nspec:\n  project: atlas\n  source:\n    chart: 'component'\n    targetRevision: '0.5.*'\n    helm:\n      values: |\n        image:\n          uri: example.jfrog.io/example:1.0.0\n\n          extraEnvVars:\n            - name: AWS_PROFILE\n              value: EXAMPLE\n            - name: VAULT__EXAMPLE\n              value: AWS:/aws_deploy_role:123456789101:123456789101_deploy:example-aws-role-to-assume\n```\n## FAQ\n### Where can I download vault-shim?\nYou will want to download the installer from GitHub and run the script during the build process.\n### Why do I need to download an installer?\nThe installer downloads the right version of vault-shim for the platform you are running on.\n### How does vault-shim auth with vault?\nIt will try to auth to vault in the following order:\n1) Checks for vault token on disk at $HOME/.vault-token\n2) Checks for kubernetes jwt on disk\n3) Uses AWS IAM.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbandwidth%2Fvault-shim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbandwidth%2Fvault-shim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbandwidth%2Fvault-shim/lists"}