{"id":13531168,"url":"https://github.com/chef/chef-vault","last_synced_at":"2025-06-25T22:33:09.760Z","repository":{"id":7917943,"uuid":"9303203","full_name":"chef/chef-vault","owner":"chef","description":"Securely manage passwords, certs, and other secrets in Chef","archived":false,"fork":false,"pushed_at":"2025-03-27T15:43:48.000Z","size":891,"stargazers_count":406,"open_issues_count":31,"forks_count":160,"subscribers_count":50,"default_branch":"main","last_synced_at":"2025-04-01T18:59:49.299Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/chef.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2013-04-08T18:05:36.000Z","updated_at":"2025-03-27T15:43:52.000Z","dependencies_parsed_at":"2024-04-15T20:41:51.443Z","dependency_job_id":"137f3828-1c1e-4737-bdb3-c85d314f7661","html_url":"https://github.com/chef/chef-vault","commit_stats":{"total_commits":472,"total_committers":68,"mean_commits":"6.9411764705882355","dds":0.8559322033898304,"last_synced_commit":"1f807cd4dfa5b7bed6da5e41d7f3155211a8cb10"},"previous_names":["nordstrom/chef-vault"],"tags_count":66,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fchef-vault","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fchef-vault/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fchef-vault/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chef%2Fchef-vault/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chef","download_url":"https://codeload.github.com/chef/chef-vault/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246700426,"owners_count":20819871,"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-08-01T07:01:00.602Z","updated_at":"2025-04-01T19:31:38.293Z","avatar_url":"https://github.com/chef.png","language":"Ruby","readme":"# Chef-Vault\n\n[![Gem Version](https://badge.fury.io/rb/chef-vault.svg)](http://badge.fury.io/rb/chef-vault)\n\n[![Build status](https://badge.buildkite.com/12995d1511cba167621634791600aa4b1156a42ef557452d07.svg)](https://buildkite.com/chef-oss/chef-chef-vault-master-verify)\n\n[![Inline docs](http://inch-ci.org/github/chef/chef-vault.svg?branch=master)](http://inch-ci.org/github/chef/chef-vault)\n\n## DESCRIPTION:\n\nGem that allows you to encrypt a Chef Data Bag Item using the public keys of\na list of chef nodes. This allows only those chef nodes to decrypt the\nencrypted values.\n\nFor a more detailed explanation of how chef-vault works, please refer to this blog post [Chef Vault – what is it and what can it do for you?](https://www.chef.io/blog/2016/01/21/chef-vault-what-is-it-and-what-can-it-do-for-you/) by Nell Shamrell-Harrington.\n\n## INSTALLATION:\n\nBe sure you are running the latest version Chef. Versions earlier than\n0.10.0 don't support plugins:\n\n    gem install chef\n\nThis plugin is distributed as a Ruby Gem. To install it, run:\n\n    gem install chef-vault\n\nDepending on your system's configuration, you may need to run this command\nwith root privileges.\n\n## DEVELOPMENT:\n\n### Git Hooks\n\nThere is a git pre-commit hook to help you keep your chefstyle up to date.\nIf you wish to use it, simply:\n\n```\nmv hooks/pre-commit .git/hooks/\nchmod +x .git/hooks/pre-commit\n```\n\n### Running Your Changes\n\nTo run your changes locally:\n\n```\nbundle install\nbundle exec knife vault\n```\n\n### Testing\n\n#### Rspec Tests\n\nThere are some unit tests that can be run with:\n\n```\nbundle exec rspec spec/\n```\n\n#### Cucumber Testing\n\nThere are cucumber tests. Run the whole suite with:\n\n```\nbundle exec rake features\n```\n\nIf you get any failures, you can run the specific feature that failed with:\n\n```\nbundle exec cucumber features/\u003cfailed\u003e.feature\n```\n\nIf you want to test things out directly, after a failure you can go into the test\ndirectory and try out the commands that failed:\n\n```\ncd tmp/aruba\nbundle exec knife \u003cyour command that failed from test with -c config.rb\u003e\n```\n\nOptionally add `-VV` to the above to get a full stacktrace.\n\n### Rubocop Errors\n\nIf you are seeing rubocop errors in travis for your pull request, run:\n\n`bundle exec chefstyle -a`\n\nThis will fix up your rubocop errors automatically, and warn you about any it can't.\n\n## KNIFE COMMANDS:\n\nSee KNIFE_EXAMPLES.md for examples of commands\n\n### config.rb (aka knife.rb)\n\nTo set 'client' as the default mode, add the following line to the config.rb file.\n\n    knife[:vault_mode] = 'client'\n\nTo set the default list of admins for creating and updating vaults, add the\nfollowing line to the config.rb file.\n\n    knife[:vault_admins] = [ 'example-alice', 'example-bob', 'example-carol' ]\n\n(These values can be overridden on the command line by using -A)\n\nNOTE: chef-vault 1.0 knife commands are not supported! Please use chef-vault\n2.0 commands.\n\n### Vault\n\n    knife vault create VAULT ITEM VALUES\n    knife vault edit VAULT ITEM\n    knife vault refresh VAULT ITEM\n    knife vault update VAULT ITEM VALUES [--clean]\n    knife vault remove VAULT ITEM VALUES\n    knife vault delete VAULT ITEM\n    knife vault rotate keys VAULT ITEM\n    knife vault rotate all keys\n    knife vault show VAULT [ITEM] [VALUES]\n    knife vault download VAULT ITEM PATH\n    knife vault isvault VAULT ITEM\n    knife vault itemtype VAULT ITEM\n\n    Note: Creating a VAULT ITEM with an ITEM name ending in \"_keys\" causes the VAULT to treat it as an ordinary `data_bag` instead of as a vault.\n\n#### Global Options\n\nShort | Long | Description | Default | Valid Values | Sub-Commands\n------|------|-------------|---------|--------------|-------------\n-M MODE | --mode MODE | Chef mode to run in. Can be set in config.rb | solo | solo, client | all\n-S SEARCH | --search SEARCH | Chef Server SOLR Search Of Nodes | | | create, remove , update\n-C CLIENTS | --clients CLIENTS | Chef clients to be added as clients, can be comma list | | | create, remove , update\n-A ADMINS | --admins ADMINS | Chef clients or users to be vault admins, can be comma list | | | create, remove, update\n-J FILE | --json FILE | JSON file to be used for values, will be merged with VALUES if VALUES is passed | | | create, update\n| --file FILE | File that chef-vault should encrypt.  It adds \"file-content\" \u0026 \"file-name\" keys to the vault item | | | create, update\n-p DATA | --print DATA | Print extra vault data | | search, clients, admins, all | show\n-F FORMAT | --format FORMAT | Format for decrypted output | summary | summary, json, yaml, pp | show\n| --clean-unknown-clients | Remove unknown clients during key rotation | | | refresh, remove, rotate\n| --clean | Clean clients list before performing search | | | refresh, update\n| --keys-mode | | method to use to manage keys | default | default, sparse | create\n\n## USAGE IN RECIPES\n\nTo use this gem in a recipe to decrypt data you must first install the gem\nvia a chef_gem resource. Once the gem is installed require the gem and then\nyou can create a new instance of ChefVault.\n\nNOTE: chef-vault 1.0 style decryption is supported, however it has been\ndeprecated and chef-vault 2.0 decryption should be used instead\n\n### Example Code\n\n    chef_gem 'chef-vault' do\n      compile_time true if respond_to?(:compile_time)\n    end\n\n    require 'chef-vault'\n\n    item = ChefVault::Item.load(\"passwords\", \"root\")\n    item[\"password\"]\n\nNote that in this case, the gem needs to be installed at compile time\nbecause the require statement is at the top-level of the recipe.  If\nyou move the require of chef-vault and the call to `::load` to\nlibrary or provider code, you can install the gem in the converge phase\ninstead.\n\n### Specifying an alternate node name or client key path\n\nNormally, the value of `Chef::Config[:node_name]` is used to find the\nper-node encrypted secret in the keys data bag item, and the value of\n`Chef::Config[:client_key]` is used to locate the private key to decrypt\nthis secret. If `Chef::Config[:client_key_contents]` is defined, it takes\nprecedence over the file path specified in `Chef::Config[:client_key]`.\n\nThese can be overridden by passing a hash with the keys `:node_name` or\n`:client_key_path` to `ChefVault::Item.load`:\n\n    item = ChefVault::Item.load(\n      'passwords', 'root',\n      node_name: 'service_foo',\n      client_key_path: '/secure/place/service_foo.pem'\n    )\n    item['password']\n\nThe above example assumes that you have transferred\n`/secure/place/service_foo.pem` to your system via a secure channel.\n\nThis usage allows you to decrypt a vault using a key shared among several\nnodes, which can be helpful when working in cloud environments or other\nconfigurations where nodes are created dynamically.\n\n### chef_vault_item helper\n\nThe [chef-vault cookbook](https://supermarket.chef.io/cookbooks/chef-vault)\ncontains a recipe to install the chef-vault gem and a helper method\n`chef_vault_helper` which makes it easier to test cookbooks that use\nchef-vault using Test Kitchen.\n\n## DETERMINING IF AN ITEM IS A VAULT\n\nChefVault provides a helper method to determine if a data bag item is a vault,\nwhich can be helpful if you produce a recipe for community consumption and want\nto support both normal data bags and vaults:\n\n    if ChefVault::Item.vault?('passwords', 'root')\n      item = ChefVault::Item.load('passwords', 'root')\n    else\n      item = Chef::DataBagItem.load('passwords', 'root')\n    end\n\nThis functionality is also available from the command line as `knife vault isvault VAULT ITEM`.\n\n## DETERMINING THE TYPE OF A DATA BAG ITEM\n\nChefVault provides a helper method to determine the type of a data bag item.\nIt returns one of the symbols :normal, :encrypted or :vault\n\n    case ChefVault::Item.data_bag_item_type('passwords', 'root')\n    when :normal\n      ...\n    when :encrypted\n      ...\n    when :vault\n      ...\n    end\n\nThis functionality is also available from the command line as `knife vault itemtype VAULT ITEM`.\n\n## USAGE STAND ALONE\n\n`chef-vault` can be used as a stand alone binary to decrypt values stored in\nChef. It requires that Chef is installed on the system and that you have a\nvalid config.rb. This is useful if you want to mix `chef-vault` into non-Chef\nrecipe code, for example some other script where you want to protect a\npassword.\n\nIt does still require that the data bag has been encrypted for the user's or\nclient's pem and pushed to the Chef server. It mixes Chef into the gem and\nuses it to go grab the data bag.\n\nUse `chef-vault --help` to see all all available options\n\n### Example usage (password)\n\n    chef-vault -v passwords -i root -a password -k /etc/chef/config.rb\n\n## SCALING\nAs more nodes use a shared key, some operations like refresh or update can execute more efficiently using sparse mode (see [issue #237](https://github.com/chef/chef-vault/issues/237)).\n\nTo create a vault item using sparse mode, pass the value `sparse` to the `--keys-mode` option to `knife vault create`.\n\n## TESTING\n\nTo use Chef Vault in Test Kitchen, ensure that the `chef-vault` recipe\nis in your `run_list`, and then add the following to your\nsuite in `.kitchen.yml`:\n\n```yaml\ndata_bags_path: 'path/to/data_bags'\nattributes:\n  chef_vault:\n    databags_fallback: true\n```\n\nYou can then use the `chef_vault_item` helper in the aforementioned chef-vault cookbook.\n\nTo stub vault items in ChefSpec, use the\n[chef-vault-testfixtures](https://rubygems.org/gems/chef-vault-testfixtures)\ngem.\n\n## Contributing\n\nFor information on contributing to this project see \u003chttps://github.com/chef/chef/blob/master/CONTRIBUTING.md\u003e\n\n## Authors\n\nAuthor:: Kevin Moser - @moserke\u003cbr\u003e\nAuthor:: Eli Klein - @eliklein\u003cbr\u003e\nAuthor:: Joey Geiger - @jgeiger\u003cbr\u003e\nAuthor:: Joshua Timberman - @jtimberman\u003cbr\u003e\nAuthor:: James FitzGibbon - @jf647\u003cbr\u003e\nAuthor:: Thom May - @thommay\u003cbr\u003e\n\n## Contributors\n\nContributor:: Matt Brimstone - @brimstone\u003cbr\u003e\nContributor:: Thomas Gschwind - @thg65\u003cbr\u003e\nContributor:: Reto Hermann\u003cbr\u003e\n\n## License\n\nCopyright:: Copyright (c) 2013-15 Nordstrom, Inc.\u003cbr\u003e\nCopyright:: Copyright (c) 2016 Chef Software, Inc.\u003cbr\u003e\nLicense:: Apache License, Version 2.0\n\n```text\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```\n","funding_links":[],"categories":["Tools","Secrets management","Ruby"],"sub_categories":["Secrets Management"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchef%2Fchef-vault","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchef%2Fchef-vault","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchef%2Fchef-vault/lists"}