artsy/citadel

Name: citadel

Owner: Artsy

Description: Chef cookbook to help store secrets in S3 in a secure fashion

Forked from: poise/citadel

Created: 2016-05-12 01:07:13.0

Updated: 2016-05-12 01:07:14.0

Pushed: 2016-05-25 20:43:40.0

Homepage: null

Size: 45

Language: Ruby

GitHub Committers

User	Most Recent Commit	# Commits

Other Committers

User	Email	Most Recent Commit	# Commits

README

Citadel cookbook

Using a combination of IAM roles, S3 buckets and EC2 it is possible to use AWS as a trusted-third-party for distributing secret or otherwise sensitive data.

Overview

IAM roles allow specifying snippets of IAM policies in a way that can be used from an EC2 virtual machine. This can be used to authorize specific hosts and decryption rights to specific files.

IAM Roles can be created in the AWS Console. While the policies applied to a role can be changed later, the name cannot so be careful when choosing them.

Requirements

This cookbook requires Chef 11.8 or newer.

IAM Policy

By default, your role will not be able to access any files in your private S3 bucket. You can create IAM policies that whitelist specific keys for each role:

ersion": "2008-10-17",
d": "<policy name>",
tatement": [
{
  "Sid": "<statement name>",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::<AWS account number>:role/<role name>"
  },
  "Action": "s3:GetObject",
  "Resource": "arn:aws:s3:::<bucket name>/<key pattern>"
}

The key pattern can include * and ? metacharacters, so for example arn:aws:s3:::myapp.citadel/deploy_keys/* to allow access to all files in the deploy_keys folder.

This policy can be attached to either the IAM role or the S3 bucket with equal effect.

Key management

This repo includes a set of Rake tasks to help you create, read, update, delete keys. First install the cli group dependencies with bundler

Set CITADEL_BUCKET and EDITOR if unset. Note that EDITOR must be an inline-editor such as vim

Run rake -T to see all available tasks

Limitations

Each EC2 VM can only be assigned a single IAM role. This can complicate situations where some secrets need to be shared by overlapping subsets of your servers. A possible improvement to this would be to make a script to create all needed composite IAM roles, possibly driven by Chef roles or other metadata.

Attributes

• node['citadel']['bucket'] ? The default S3 bucket to use.
• node['citadel']['region'] ? The default S3 region to use.

Recipe Usage

You must include the default recipe before running the citadel method.

include_recipe "citadel::default"

You can then access secret data via the citadel method.

 '/etc/secret' do
ner 'root'
oup 'root'
de '600'
ntent citadel['keys/secret.pem']

By default the node attribute node['citadel']['bucket'] is used to find the S3 bucket to query, however you can override this:

late '/etc/secret' do
ner 'root'
oup 'root'
de '600'
riables secret: citadel('mybucket')['id_rsa']

Developing with Vagrant

While developing in a local VM, you can use the node attributes node['citadel']['access_key_id'] and node['citadel']['secret_access_key'] to provide credentials. The recommended way to do this is via environment variables so that the Vagrantfile itself can still be kept in source control without leaking credentials:

ig.vm.provision :chef_solo do |chef|
ef.json = {
citadel: {
  access_key_id: ENV['ACCESS_KEY_ID'],
  secret_access_key: ENV['SECRET_ACCESS_KEY'],
},

WARNING: Use of these attributes in production should be considered a likely security risk as they will end up visible in the node data, or in the role/environment/cookbook that sets them. This can be mitigated using Enterprise Chef ACLs, however such configurations are generally error-prone due to the defaults being wide open.

Testing with Test-Kitchen

Similarly you can use the same attributes with Test-Kitchen

isioner:
me: chef_solo
tributes:
citadel:
  access_key_id: <%= ENV['AWS_ACCESS_KEY_ID'] %>
  secret_access_key: <%= ENV['AWS_SECRET_ACCESS_KEY'] %>

Recommended Folder Layout

Within your S3 bucket I recommend you create one folder for each group of secrets, and in your IAM policies have one statement per group. Each group of secrets is a set of data with identical security requirements. Many groups will start out only containing a single file, however having the flexibility to change this in the future allows for things like key rotation without rewriting all of your IAM policies.

Managing Secrets

Rake tasks are provided to manage secret keys. To get started, create a S3 bucket and KMS master key. Set the CITADEL_BUCKET and CITADEL_KEY_ID environment variables and create a key with rake citadel:create[new_key]. This will open your $EDITOR for editing, and encrypt / upload the contents to S3.

TLS verification

While citadel uses HTTPS, Chef does not verify certificates by default. You can enable verification by adding ssl_verify_mode :verify_peer to your client.rb.