1# Vault [![CircleCI](https://circleci.com/gh/hashicorp/vault.svg?style=svg)](https://circleci.com/gh/hashicorp/vault) [![vault enterprise](https://img.shields.io/badge/vault-enterprise-yellow.svg?colorB=7c8797&colorA=000000)](https://www.hashicorp.com/products/vault/?utm_source=github&utm_medium=banner&utm_campaign=github-vault-enterprise) 2 3---- 4 5**Please note**: We take Vault's security and our users' trust very seriously. If you believe you have found a security issue in Vault, _please responsibly disclose_ by contacting us at [security@hashicorp.com](mailto:security@hashicorp.com). 6 7---- 8 9- Website: https://www.vaultproject.io 10- IRC: `#vault-tool` on Freenode 11- Announcement list: [Google Groups](https://groups.google.com/group/hashicorp-announce) 12- Discussion forum: [Discuss](https://discuss.hashicorp.com/c/vault) 13- Documentation: [https://www.vaultproject.io/docs/](https://www.vaultproject.io/docs/) 14- Tutorials: [HashiCorp's Learn Platform](https://learn.hashicorp.com/vault) 15- Certification Exam: [Vault Associate](https://www.hashicorp.com/certification/#hashicorp-certified-vault-associate) 16 17<img width="300" alt="Vault Logo" src="https://github.com/hashicorp/vault/blob/f22d202cde2018f9455dec755118a9b84586e082/Vault_PrimaryLogo_Black.png"> 18 19Vault is a tool for securely accessing secrets. A secret is anything that you want to tightly control access to, such as API keys, passwords, certificates, and more. Vault provides a unified interface to any secret, while providing tight access control and recording a detailed audit log. 20 21A modern system requires access to a multitude of secrets: database credentials, API keys for external services, credentials for service-oriented architecture communication, etc. Understanding who is accessing what secrets is already very difficult and platform-specific. Adding on key rolling, secure storage, and detailed audit logs is almost impossible without a custom solution. This is where Vault steps in. 22 23The key features of Vault are: 24 25* **Secure Secret Storage**: Arbitrary key/value secrets can be stored 26 in Vault. Vault encrypts these secrets prior to writing them to persistent 27 storage, so gaining access to the raw storage isn't enough to access 28 your secrets. Vault can write to disk, [Consul](https://www.consul.io), 29 and more. 30 31* **Dynamic Secrets**: Vault can generate secrets on-demand for some 32 systems, such as AWS or SQL databases. For example, when an application 33 needs to access an S3 bucket, it asks Vault for credentials, and Vault 34 will generate an AWS keypair with valid permissions on demand. After 35 creating these dynamic secrets, Vault will also automatically revoke them 36 after the lease is up. 37 38* **Data Encryption**: Vault can encrypt and decrypt data without storing 39 it. This allows security teams to define encryption parameters and 40 developers to store encrypted data in a location such as SQL without 41 having to design their own encryption methods. 42 43* **Leasing and Renewal**: All secrets in Vault have a _lease_ associated 44 with it. At the end of the lease, Vault will automatically revoke that 45 secret. Clients are able to renew leases via built-in renew APIs. 46 47* **Revocation**: Vault has built-in support for secret revocation. Vault 48 can revoke not only single secrets, but a tree of secrets, for example 49 all secrets read by a specific user, or all secrets of a particular type. 50 Revocation assists in key rolling as well as locking down systems in the 51 case of an intrusion. 52 53Documentation, Getting Started, and Certification Exams 54------------------------------- 55 56Documentation is available on the [Vault website](https://www.vaultproject.io/docs/). 57 58If you're new to Vault and want to get started with security automation, please 59check out our [Getting Started guides](https://learn.hashicorp.com/collections/vault/getting-started) 60on HashiCorp's learning platform. There are also [additional guides](https://learn.hashicorp.com/vault) 61to continue your learning. 62 63Show off your Vault knowledge by passing a certification exam. Visit the 64[certification page](https://www.hashicorp.com/certification/#hashicorp-certified-vault-associate) 65for information about exams and find [study materials](https://learn.hashicorp.com/collections/vault/certification) 66on HashiCorp's learning platform. 67 68Developing Vault 69-------------------- 70 71If you wish to work on Vault itself or any of its built-in systems, you'll 72first need [Go](https://www.golang.org) installed on your machine. Go version 731.16.7+ is *required*. 74 75For local dev first make sure Go is properly installed, including setting up a 76[GOPATH](https://golang.org/doc/code.html#GOPATH). Ensure that `$GOPATH/bin` is in 77your path as some distributions bundle old version of build tools. Next, clone this 78repository. Vault uses [Go Modules](https://github.com/golang/go/wiki/Modules), 79so it is recommended that you clone the repository ***outside*** of the GOPATH. 80You can then download any required build tools by bootstrapping your environment: 81 82```sh 83$ make bootstrap 84... 85``` 86 87To compile a development version of Vault, run `make` or `make dev`. This will 88put the Vault binary in the `bin` and `$GOPATH/bin` folders: 89 90```sh 91$ make dev 92... 93$ bin/vault 94... 95``` 96 97To compile a development version of Vault with the UI, run `make static-dist dev-ui`. This will 98put the Vault binary in the `bin` and `$GOPATH/bin` folders: 99 100```sh 101$ make static-dist dev-ui 102... 103$ bin/vault 104... 105``` 106 107To run tests, type `make test`. Note: this requires Docker to be installed. If 108this exits with exit status 0, then everything is working! 109 110```sh 111$ make test 112... 113``` 114 115If you're developing a specific package, you can run tests for just that 116package by specifying the `TEST` variable. For example below, only 117`vault` package tests will be run. 118 119```sh 120$ make test TEST=./vault 121... 122``` 123 124### Acceptance Tests 125 126Vault has comprehensive [acceptance tests](https://en.wikipedia.org/wiki/Acceptance_testing) 127covering most of the features of the secret and auth methods. 128 129If you're working on a feature of a secret or auth method and want to 130verify it is functioning (and also hasn't broken anything else), we recommend 131running the acceptance tests. 132 133**Warning:** The acceptance tests create/destroy/modify *real resources*, which 134may incur real costs in some cases. In the presence of a bug, it is technically 135possible that broken backends could leave dangling data behind. Therefore, 136please run the acceptance tests at your own risk. At the very least, 137we recommend running them in their own private account for whatever backend 138you're testing. 139 140To run the acceptance tests, invoke `make testacc`: 141 142```sh 143$ make testacc TEST=./builtin/logical/consul 144... 145``` 146 147The `TEST` variable is required, and you should specify the folder where the 148backend is. The `TESTARGS` variable is recommended to filter down to a specific 149resource to test, since testing all of them at once can sometimes take a very 150long time. 151 152Acceptance tests typically require other environment variables to be set for 153things such as access keys. The test itself should error early and tell 154you what to set, so it is not documented here. 155 156For more information on Vault Enterprise features, visit the [Vault Enterprise site](https://www.hashicorp.com/products/vault/?utm_source=github&utm_medium=referral&utm_campaign=github-vault-enterprise). 157