• Stars
    star
    334
  • Rank 126,264 (Top 3 %)
  • Language
    Ruby
  • License
    Mozilla Public Li...
  • Created over 9 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Rails plugin for easily integrating Vault secrets

Vault Rails Build Status

Vault is the official Rails plugin for interacting with Vault by HashiCorp.

If you're viewing this README from GitHub on the master branch, know that it may contain unreleased features or different APIs than the most recently released version. Please see the Git tag that corresponds to your version of the Vault Rails plugin for the proper documentation.

Table of Contents

  1. Quick Start
  2. Advanced Configuration
  3. Caveats
  4. Development

Quick Start

β†₯ back to top

  1. Add to your Gemfile:

    gem "vault-rails", require: false

    and then run the bundle command to install.

  2. Create an initializer:

    require "vault/rails"
    
    Vault::Rails.configure do |vault|
      # Use Vault in transit mode for encrypting and decrypting data. If
      # disabled, vault-rails will encrypt data in-memory using a similar
      # algorithm to Vault. The in-memory store uses a predictable encryption
      # which is great for development and test, but should _never_ be used in
      # production. Default: ENV["VAULT_RAILS_ENABLED"].
      vault.enabled = Rails.env.production?
    
      # The name of the application. All encrypted keys in Vault will be
      # prefixed with this application name. If you change the name of the
      # application, you will need to migrate the encrypted data to the new
      # key namespace. Default: ENV["VAULT_RAILS_APPLICATION"].
      vault.application = "my_app"
    
      # The address of the Vault server. Default: ENV["VAULT_ADDR"].
      vault.address = "https://vault.corp"
    
      # The token to communicate with the Vault server.
      # Default: ENV["VAULT_TOKEN"].
      vault.token = "abcd1234"
    end

    For more customization, such as custom SSL certificates, please see the Vault Ruby documentation.

  3. Add Vault to the model you want to encrypt:

    class Person < ActiveRecord::Base
      include Vault::EncryptedModel
      vault_attribute :ssn
    end

    Each attribute you want to encrypt must have a corresponding attribute_encrypted column in the database. For the above example:

    class AddEncryptedSSNToPerson < ActiveRecord::Migration
      add_column :people, :ssn_encrypted, :string
    end

    That is it! The plugin will transparently handle the encryption and decryption of secrets with Vault:

    person = Person.new
    person.ssn = "123-45-6789"
    person.save #=> true
    person.ssn_encrypted #=> "vault:v0:EE3EV8P5hyo9h..."
  • Note The unencrypted value will still be saved if the attribute referenced has a corresponding column. (i.e. ssn in the case above)

Advanced Configuration

β†₯ back to top

The following section details some of the more advanced configuration options for vault-rails. As a general rule, you should try to use vault-rails without these options until absolutely necessary.

Specifying the encrypted column

By default, the name of the encrypted column is #{column}_encrypted. This is customizable by setting the :encrypted_column option when declaring the attribute:

vault_attribute :credit_card,
  encrypted_column: :cc_encrypted
  • Note Changing this value for an existing application will make existing values no longer decryptable!
  • Note This value cannot be the same name as the vault attribute!

Specifying a custom key

By default, the name of the key in Vault is #{app}_#{table}_#{column}. This is customizable by setting the :key option when declaring the attribute:

vault_attribute :credit_card,
  key: "pci-data"
  • Note Changing this value for an existing application will make existing values no longer decryptable!

Specifying a context (key derivation)

Vault Transit supports key derivation, which allows the same key to be used for multiple purposes by deriving a new key based on a context value.

The context can be specified as a string, symbol, or proc. Symbols (an instance method on the model) and procs are called for each encryption or decryption request, and should return a string.

  • Note Changing the context or context generator for an attribute will make existing values no longer decryptable!
String

With a string, all records will use the same context for this attribute:

vault_attribute :credit_card,
  context: "user-cc"
Symbol

When using a symbol, a method will be called on the record to compute the context:

belongs_to :user

vault_attribute :credit_card,
  context: :encryption_context

def encryption_context
  "user_#{user.id}"
end
Proc

Given a proc, it will be called each time to compute the context:

belongs_to :user

vault_attribute :credit_card,
  context: ->(record) { "user_#{record.user.id}" }

The proc must take a single argument for the record.

Specifying a default value

An attribute can specify a default value, which will be set on initialization (.new) or after loading the value from the database. The default will be set if the value is nil.

vault_attribute :access_level,
  default: "readonly"

vault_attribute :metadata,
  serialize: :json,
  default: {}

Specifying a different Vault path

By default, the path to the transit backend in Vault is transit/. This is customizable by setting the :path option when declaring the attribute:

vault_attribute :credit_card,
  path: "transport"
  • Note Changing this value for an existing application will make existing values no longer decryptable!

Lazy attribute decryption

By default, vault-rails will decrypt a record’s encrypted attributes on that record’s initialization. You can configure an encrypted model to decrypt attributes lazily, which will prevent communication with Vault until an encrypted attribute’s getter method is called, at which point all of the record’s encrypted attributes will be decrypted. This is useful if you do not always need access to encrypted attributes. For example:

class Person < ActiveRecord::Base
  include Vault::EncryptedModel
  vault_lazy_decrypt!

  vault_attribute :ssn
end

# Without vault_lazy_decrypt:
person = Person.find(id) # Vault communication happens here
person.ssn
# => "123-45-6789"

# With vault_lazy_decrypt:
person = Person.find(id)
person.ssn # Vault communication happens here
# => "123-45-6789"

Single, lazy attribute decryption

By default, vault-rails will decrypt all encrypted attributes on that record’s initialization on a class by class basis. You can configure an encrypted model to decrypt attributes lazily and and individually. This will prevent vault from loading all vault_attributes defined on a class the moment one attribute is requested.

class Person < ActiveRecord::Base
  include Vault::EncryptedModel
  vault_lazy_decrypt!
  vault_single_decrypt!

  vault_attribute :ssn
  vault_attribute :email
end

# Without vault_single_decrypt:
person = Person.find(id) # Vault communication happens here
person.ssn # Vault communication happens here, fetches both ssn and email
# => "123-45-6789"

# With vault_single_decrypt:
person = Person.find(id)
person.ssn # Vault communication happens here, fetches only ssn
# => "123-45-6789"
person.email # Vault communication happens here, fetches only email
# => "[email protected]"

Serialization

By default, all values are assumed to be "text" fields in the database. Sometimes it is beneficial for your application to work with a more flexible data structure (such as a Hash or Array). Vault-rails can automatically serialize and deserialize these structures for you:

vault_attribute :details,
  serialize: :json,
  default: {}

It is recommended to set a default matching type that you're serializing.

  • Note You can view the source for the exact serialization and deserialization options, but they are intentionally not customizable and cannot be used for a full object marshal/unmarshal.
Custom Serializers

For customized solutions, you can also pass a module to the :serializer key. This module must have the following API:

module MySerializer
  # @param [String, nil] raw
  # @return [String, nil]
  def self.encode(raw); end

  # @param [String, nil] raw
  # @return [String, nil]
  def self.decode(raw); end
end

Your class must account for nil and "empty" values if necessary. Then specify the class as the serializer:

vault_attribute :details,
  serialize: MySerializer
  • Note It is possible to encode and decode entire Ruby objects using a custom serializer. Please do not do that. You will have a bad time.

Custom encoding/decoding

If a custom serializer seems too heavy, you can declare an :encode and :decode proc when declaring the attribute. Both options must be given:

vault_attribute :address,
  encode: ->(raw) { raw.to_s.upcase },
  decode: ->(raw) { raw.to_s }
  • Note Changing the algorithm for encoding/decoding for an existing application will probably make the application crash when attempting to retrieve existing values!

Caveats

β†₯ back to top

Mounting/Creating Keys in Vault

The Vault Rails plugin does not automatically mount a backend. It is assumed the proper backend is mounted and accessible by the given token. You can mount a transit backend like this:

$ vault mount transit

If you are running Vault 0.2.0 or later, the Vault Rails plugin will automatically create keys in the transit backend if it has permission. Here is an example policy to grant permissions:

# Allow renewal of leases for secrets
path "sys/renew/*" {
  policy = "write"
}

# Allow renewal of token leases
path "auth/token/renew/*" {
  policy = "write"
}

path "transit/encrypt/myapp_*" {
  policy = "write"
}

path "transit/decrypt/myapp_*" {
  policy = "write"
}

Note that you will need to have an out-of-band process to renew your Vault token.

For lower versions of Vault, the Vault Rails plugin does not automatically create transit keys in Vault. Instead, you should create keys for each column you plan to encrypt using a different policy, out-of-band from the Rails application. For example:

$ vault write transit/keys/<key> create=1

Unless customized, the name of the key will always be:

<app>_<table>_<column>

So for the example above, the key would be:

my_app_people_ssn

Searching Encrypted Attributes

Because each column is uniquely encrypted, it is not possible to search for a particular plain-text value. For example, if the ssn attribute is encrypted, the following will NOT work:

Person.where(ssn: "123-45-6789")

This is because the database is unaware of the plain-text data (which is part of the security model).

Development

β†₯ back to top

  1. Clone the project on GitHub
  2. Create a feature branch
  3. Submit a Pull Request

Important Notes:

  • All new features must include test coverage. At a bare minimum, Unit tests are required. It is preferred if you include acceptance tests as well.
  • The tests must be be idempotent. The HTTP calls made during a test should be able to be run over and over.
  • Tests are order independent. The default RSpec configuration randomizes the test order, so this should not be a problem.

More Repositories

1

terraform

Terraform enables you to safely and predictably create, change, and improve infrastructure. It is a source-available tool that codifies APIs into declarative configuration files that can be shared amongst team members, treated as code, edited, reviewed, and versioned.
Go
42,550
star
2

vault

A tool for secrets management, encryption as a service, and privileged access management
Go
30,858
star
3

consul

Consul is a distributed, highly available, and data center aware solution to connect and configure applications across dynamic, distributed infrastructure.
Go
28,256
star
4

vagrant

Vagrant is a tool for building and distributing development environments.
Ruby
26,132
star
5

packer

Packer is a tool for creating identical machine images for multiple platforms from a single source configuration.
Go
15,086
star
6

nomad

Nomad is an easy-to-use, flexible, and performant workload orchestrator that can deploy a mix of microservice, batch, containerized, and non-containerized applications. Nomad is easy to operate and scale and has native Consul and Vault integrations.
Go
14,809
star
7

terraform-provider-aws

The AWS Provider enables Terraform to manage AWS resources.
Go
9,761
star
8

raft

Golang implementation of the Raft consensus protocol
Go
7,383
star
9

serf

Service orchestration and management tool.
Go
5,692
star
10

hcl

HCL is the HashiCorp configuration language.
Go
5,236
star
11

go-plugin

Golang plugin system over RPC.
Go
4,874
star
12

terraform-cdk

Define infrastructure resources using programming constructs and provision them using HashiCorp Terraform
TypeScript
4,868
star
13

waypoint

A tool to build, deploy, and release any application on any platform.
Go
4,789
star
14

consul-template

Template rendering, notifier, and supervisor for @HashiCorp Consul and Vault data.
Go
4,750
star
15

terraform-provider-azurerm

Terraform provider for Azure Resource Manager
Go
4,528
star
16

otto

Development and deployment made easy.
HTML
4,282
star
17

golang-lru

Golang LRU cache
Go
4,221
star
18

boundary

Boundary enables identity-based access management for dynamic infrastructure.
Go
3,850
star
19

memberlist

Golang package for gossip based membership and failure detection
Go
3,303
star
20

go-memdb

Golang in-memory database built on immutable radix trees
Go
2,937
star
21

next-mdx-remote

Load mdx content from anywhere through getStaticProps in next.js
TypeScript
2,405
star
22

terraform-provider-google

Terraform Provider for Google Cloud Platform
Go
2,325
star
23

go-multierror

A Go (golang) package for representing a list of errors as a single error.
Go
2,029
star
24

yamux

Golang connection multiplexing library
Go
2,003
star
25

envconsul

Launch a subprocess with environment variables using data from @HashiCorp Consul and Vault.
Go
1,967
star
26

go-retryablehttp

Retryable HTTP client in Go
Go
1,702
star
27

terraform-provider-kubernetes

Terraform Kubernetes provider
Go
1,580
star
28

go-getter

Package for downloading things from a string URL using a variety of protocols.
Go
1,541
star
29

best-practices

HCL
1,490
star
30

go-version

A Go (golang) library for parsing and verifying versions and version constraints.
Go
1,459
star
31

go-metrics

A Golang library for exporting performance and runtime metrics to external metrics systems (i.e. statsite, statsd)
Go
1,453
star
32

setup-terraform

Sets up Terraform CLI in your GitHub Actions workflow.
JavaScript
1,352
star
33

terraform-guides

Example usage of HashiCorp Terraform
HCL
1,324
star
34

mdns

Simple mDNS client/server library in Golang
Go
1,020
star
35

terraform-provider-helm

Terraform Helm provider
Go
997
star
36

vault-guides

Example usage of HashiCorp Vault secrets management
Shell
990
star
37

go-immutable-radix

An immutable radix tree implementation in Golang
Go
926
star
38

vault-helm

Helm chart to install Vault and other associated components.
Shell
904
star
39

terraform-ls

Terraform Language Server
Go
896
star
40

vscode-terraform

HashiCorp Terraform VSCode extension
TypeScript
870
star
41

levant

An open source templating and deployment tool for HashiCorp Nomad jobs
Go
825
star
42

vault-k8s

First-class support for Vault and Kubernetes.
Go
697
star
43

terraform-exec

Terraform CLI commands via Go.
Go
675
star
44

consul-k8s

First-class support for Consul Service Mesh on Kubernetes
Go
665
star
45

terraform-aws-vault

A Terraform Module for how to run Vault on AWS using Terraform and Packer
HCL
659
star
46

terraform-github-actions

Terraform GitHub Actions
Shell
624
star
47

terraform-provider-vsphere

Terraform Provider for VMware vSphere
Go
617
star
48

raft-boltdb

Raft backend implementation using BoltDB
Go
585
star
49

nextjs-bundle-analysis

A github action that provides detailed bundle analysis on PRs for next.js apps
JavaScript
562
star
50

go-discover

Discover nodes in cloud environments
Go
562
star
51

consul-replicate

Consul cross-DC KV replication daemon.
Go
504
star
52

next-mdx-enhanced

A Next.js plugin that enables MDX pages, layouts, and front matter
JavaScript
500
star
53

docker-vault

Official Docker images for Vault
Shell
492
star
54

terraform-provider-kubernetes-alpha

A Terraform provider for Kubernetes that uses dynamic resource types and server-side apply. Supports all Kubernetes resources.
Go
490
star
55

vault-secrets-operator

The Vault Secrets Operator (VSO) allows Pods to consume Vault secrets natively from Kubernetes Secrets.
Go
466
star
56

terraform-k8s

Terraform Cloud Operator for Kubernetes
Go
454
star
57

puppet-bootstrap

A collection of single-file scripts to bootstrap your machines with Puppet.
Shell
444
star
58

cap

A collection of authentication Go packages related to OIDC, JWKs, Distributed Claims, LDAP
Go
443
star
59

terraform-provider-vault

Terraform Vault provider
Go
431
star
60

damon

A terminal UI (TUI) for HashiCorp Nomad
Go
427
star
61

nomad-autoscaler

Nomad Autoscaler brings autoscaling to your Nomad workloads.
Go
424
star
62

consul-helm

Helm chart to install Consul and other associated components.
Shell
422
star
63

terraform-provider-azuread

Terraform provider for Azure Active Directory
Go
419
star
64

vault-ssh-helper

Vault SSH Agent is used to enable one time keys and passwords
Go
404
star
65

terraform-provider-scaffolding

Quick start repository for creating a Terraform provider
Go
402
star
66

terraform-aws-consul

A Terraform Module for how to run Consul on AWS using Terraform and Packer
HCL
401
star
67

docker-consul

Official Docker images for Consul.
Dockerfile
399
star
68

nomad-pack

Go
393
star
69

hil

HIL is a small embedded language for string interpolations.
Go
392
star
70

vault-action

A GitHub Action that simplifies using HashiCorp Vaultβ„’ secrets as build variables.
JavaScript
391
star
71

learn-terraform-provision-eks-cluster

HCL
389
star
72

terraform-plugin-sdk

Terraform Plugin SDK enables building plugins (providers) to manage any service providers or custom in-house solutions
Go
383
star
73

terraform-config-inspect

A helper library for shallow inspection of Terraform configurations
Go
380
star
74

hcl2

Former temporary home for experimental new version of HCL
Go
375
star
75

errwrap

Errwrap is a Go (golang) library for wrapping and querying errors.
Go
373
star
76

go-cleanhttp

Go
366
star
77

design-system

Helios Design System
TypeScript
358
star
78

logutils

Utilities for slightly better logging in Go (Golang).
Go
356
star
79

vault-ruby

The official Ruby client for HashiCorp's Vault
Ruby
336
star
80

next-remote-watch

Decorated local server for next.js that enables reloads from remote data changes
JavaScript
325
star
81

waypoint-examples

Example Apps that can be deployed with Waypoint
PHP
325
star
82

go-hclog

A common logging package for HashiCorp tools
Go
319
star
83

vault-csi-provider

HashiCorp Vault Provider for Secret Store CSI Driver
Go
308
star
84

nomad-guides

Example usage of HashiCorp Nomad
HCL
281
star
85

consul-haproxy

Consul HAProxy connector for real-time configuration
Go
279
star
86

terraform-provider-google-beta

Terraform Provider for Google Cloud Platform (Beta)
Go
265
star
87

consul-esm

External service monitoring for Consul
Go
262
star
88

http-echo

A tiny go web server that echos what you start it with!
Makefile
257
star
89

terraform-provider-awscc

Terraform AWS Cloud Control provider
HCL
256
star
90

terraform-aws-nomad

A Terraform Module for how to run Nomad on AWS using Terraform and Packer
HCL
254
star
91

faas-nomad

OpenFaaS plugin for Nomad
Go
252
star
92

go-sockaddr

IP Address/UNIX Socket convenience functions for Go
Go
250
star
93

terraform-foundational-policies-library

Sentinel is a language and framework for policy built to be embedded in existing software to enable fine-grained, logic-based policy decisions. This repository contains a library of Sentinel policies, developed by HashiCorp, that can be consumed directly within the Terraform Cloud platform.
HCL
233
star
94

nomad-driver-podman

A nomad task driver plugin for sandboxing workloads in podman containers
Go
226
star
95

vagrant-vmware-desktop

Official provider for VMware desktop products: Fusion, Player, and Workstation.
Go
225
star
96

go-tfe

HCP Terraform/Enterprise API Client/SDK in Golang
Go
224
star
97

nomad-pack-community-registry

A repo for Packs written and maintained by Nomad community members
HCL
221
star
98

boundary-reference-architecture

Example reference architecture for a high availability Boundary deployment on AWS.
HCL
211
star
99

terraform-plugin-framework

A next-generation framework for building Terraform providers.
Go
204
star
100

vault-plugin-auth-kubernetes

Vault authentication plugin for Kubernetes Service Accounts
Go
192
star