• Stars
    star
    608
  • Rank 73,735 (Top 2 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 7 years ago
  • Updated over 1 year ago

Reviews

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

Repository Details

Secure Secret management for Kubernetes (with gpg, Google Cloud KMS and AWS KMS backends)

kubesec Latest Version Build Status

Secure secret management for Kubernetes (with gpg, Google Cloud KMS and AWS KMS backends).

asciicast

In short, it allows you to encrypt Secrets so that they can be stored in VCS along with the rest of resources.
An example of encrypted Secret is shown below (note that only the "data" is encrypted (and that keys are left untouched)):

apiVersion: v1
kind: Secret
metadata:
  name: myapp-default-0
type: Opaque
data:
  KEY: TUFkWD1iuKs=.O....D...=
  ANOTHER_KEY: iOy1nf90+M6FrrEIoymN6cOSUYM=.E...=.q...=
# ...  

The nice thing about this approach (compared to complete file encryption) is that git diff and git merge become so much more user-friendly (+ you can ascertain that specific entry is present even if you don't have the key to decrypt the secret).

kubesec is written in Go, works with (or without) Yubikey โค.

For general-purpose secret management, take a look at mozilla/sops
(kubesec's drawn a lot of inspiration from it).

Installation

macOS

curl -sSL https://github.com/shyiko/kubesec/releases/download/0.9.2/kubesec-0.9.2-darwin-amd64 \
  -o kubesec && chmod a+x kubesec && sudo mv kubesec /usr/local/bin/  

Verify PGP signature (optional but recommended):

curl -sSL https://github.com/shyiko/kubesec/releases/download/0.9.2/kubesec-0.9.2-darwin-amd64.asc \
  -o kubesec.asc
curl -sS https://keybase.io/shyiko/pgp_keys.asc | gpg --import
gpg --verify kubesec.asc /usr/local/bin/kubesec

gpg can be installed with brew install gnupg

... with Homebrew
brew install shyiko/kubesec/kubesec
brew install shyiko/kubesec/kubesec --with-short-name # install as "ksec"

brew install shyiko/kubesec/kubesec is equivalent to brew tap shyiko/kubesec && brew install kubesec.

Linux

curl -sSL https://github.com/shyiko/kubesec/releases/download/0.9.2/kubesec-0.9.2-linux-amd64 \
  -o kubesec && chmod a+x kubesec && sudo mv kubesec /usr/local/bin/  

Verify PGP signature (optional but recommended):

curl -sSL https://github.com/shyiko/kubesec/releases/download/0.9.2/kubesec-0.9.2-linux-amd64.asc \
  -o kubesec.asc
curl -sS https://keybase.io/shyiko/pgp_keys.asc | gpg --import
gpg --verify kubesec.asc /usr/local/bin/kubesec

Windows

Download executable from the Releases page.

Usage

If you plan to use gpg:
... but don't have a valid PGP key, see GitHub Help - Generating a new GPG key on how to generate one.
gpg (tested: 2.0+; recommended: 2.1+) must be available on the PATH.
It's also highly recommended to set up gpg-agent to avoid constant passphrase re-entry.

Encryption

# encrypt existing Secret (see `kubesec create` below on how to create encrypted secret from scratch)
kubesec encrypt secret.yml
# same as above but output is written back to secret.yml (instead of stdout)
kubesec encrypt -i secret.yml

# NOTE: if you don't specify --key - default PGP key will be used
# in other words, `kubesec encrypt secret.yml` is identical to 
kubesec encrypt --key=pgp:default secret.yml

# NOTE: multiple --key|s can be specified if needed 
# (and they don't have to be of the same type, i.e. `--key=pgp:... --key=arn:...` 
# is perfectly valid)

# encrypt with PGP key ("pgp:" prefix is optional)
kubesec encrypt --key=pgp:6206C32E111611688694CF5530BDA87E3E71C268 secret.yml

# avoid gpgagent for pgp passprhase when encrypting with PGP key ("pgp:" prefix is optional)
kubesec encrypt --passphrase=<supersecret> --key=pgp:6206C32E111611688694CF5530BDA87E3E71C268 secret.yml

# encrypt with Google Cloud KMS key ("gcp:" prefix is optional)
#
# NOTE: you'll need either to `gcloud auth application-default login` or set
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json 
# before attempting secret encryption/decryption
#
# https://developers.google.com/identity/protocols/application-default-credentials#howtheywork
kubesec encrypt --key=gcp:<resource-id of Google Cloud KMS key> secret.yml
kubesec encrypt \ 
  --key=gcp:projects/project-0/locations/global/keyRings/keyring-0/cryptoKeys/key-0 secret.yml

# encrypt with AWS KMS key ("aws:" prefix is optional)
#
# NOTE: you might need to `aws configure` (if you don't have ~/.aws/credentials already)
#
# http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html
kubesec encrypt --key=aws:<ARN of AWS KMS key> secret.yml
kubesec encrypt \
  --key=aws:arn:aws:kms:us-west-1:000000000000:key/00000000-0000-0000-0000-000000000000 secret.yml

# add ...D89 key & drop ...310 key (leave all other keys untouched)
kubesec encrypt --key=+pgp:160A7A9CF46221A56B06AD64461A804F2609FD89 \
  --key=-pgp:6206C32E111611688694CF5530BDA87E3E71C268 secret.yml
# NOTE: removal of a key will automatically result in data encryption key rotation
# you will also need to change all the secrets as whoever you removed from the chain of trust might 
# still have access to the previous version of a file   

# encrypt content of stdin
cat secret.yml | kubesec encrypt -

# create encrypted Secret from key=value pair(s) / file(s)
kubesec create secret-name \
  --data key=value \
  --data file:pki/ca.crt \
  --data file:hostname.key=pki/private/server.key \
  -o secret.enc.yml

Decryption

# decrypt a Secret 
# (usually combined with kubectl (`kubesec decrypt secret.enc.yml | kubectl apply -f -`))
kubesec decrypt secret.enc.yml 

# decrypt without invoking gpgagent - useful for unattended interaction or for alternate keyrings 
#
# You can prevent these lines ending up in history with a space 
# see https://www.linuxjournal.com/content/using-bash-history-more-efficiently-histcontrol or https://superuser.com/questions/352788/how-to-prevent-a-command-in-the-zshell-from-being-saved-into-history 
kubesec decrypt --keyring alternate.keyring --passphrase=<supersecret> secret.yml

# decrypt to a custom Go Template (http://golang.org/pkg/text/template) string
kubesec decrypt secret.enc.yml --cleartext --template='KEY={{ .data.KEY }}'
kubesec decrypt secret.enc.yml --cleartext \
  --template=$'{{ range $k, $v := .data }}{{ $k }}={{ $v }}\n{{ end }}' > .env

Modification

# open decrypted Secret in $EDITOR (it will be automatically re-encrypted upon save)
kubesec edit -i secret.enc.yml
kubesec edit -i --key=<a-different-key-to-re-encrypt-with> secret.enc.yml
# same as above but secret.enc.yml will be created if it doesn't exist 
kubesec edit -if secret.enc.yml

# batch editing (noninteractive)
kubesec patch -i secret.enc.yml --data key1=secret_string --data file:key2=path/to/file

# "decrypt, modify-in-any-way-you-like, re-encrypt" 
kubesec decrypt --cleartext secret.enc.yml -o secret.yml
# edit secret.yml using your favourite editor / tool
kubesec encrypt --cleartext secret.yml -o secret.enc.yml --parent=secret.enc.yml
# --parent=path/to/encrypted/secret.enc.yml above is used to preserve keys, DEK and IVs (when safe)

Introspection

# show information about the Secret (who has access to the "data", last modification date, etc)
kubesec introspect secret.enc.yml

Tab completion

# bash
source <(kubesec completion bash)

# zsh
source <(kubesec completion zsh)

- can be used anywhere (where a file is expected) to reference stdin.
(for more information see kubesec --help)

Example(s)

#1 (basic)

kubesec create secret-name -d key=value -d file:path/to/file -o secret.enc.yml  
kubesec decrypt secret.enc.yml | kubectl apply -f -

Playground

If you have docker installed you don't need to download kubesec binary just to try it out.
Instead, launch a container and start playing:

docker run -it --rm shyiko/kubesec-playground:0.9.2 /bin/bash
$ kubesec encrypt secret.yml

shyiko/kubesec-playground image contains gpg 2.1+, kubesec, vim (as a default $EDITOR) and secret PGP key of Jean-Luc Picard (PGP fingerprint - 6206C32E111611688694CF5530BDA87E3E71C268).

Dockerfile is included within this repo.

Encryption Protocol

  • "data" values are encrypted with AES-GCM (each value is padded to a block-size (48 bytes by default) and then encrypted using a shared (resource-unique, randomly generated) 256-bit DEK & a 96-bit random IV).
  • DEK is encrypted (and signed in case of PGP) with --key(s) before being stored in a Secret as # kubesec:<key type>:<key id>:... (one entry for each --key).

In addition to the above, kubesec also generates MAC (AES-GMAC, with AAD constructed from both the "data" and the --key(s)). If MAC is missing or invalid - decryption will fail (kubesec edit -i --recompute-mac <file> can be used to recompute MAC when necessary (e.g. after git merge)).

Reporting Security Issues

Please reach me at https://keybase.io/shyiko.

Development

PREREQUISITE: go1.9+.

git clone https://github.com/shyiko/kubesec $GOPATH/src/github.com/shyiko/kubesec 
cd $GOPATH/src/github.com/shyiko/kubesec
make fetch

go run kubesec.go

Legal

All code, unless specified otherwise, is licensed under the Apache-2.0 license.
Copyright (c) 2018 Stanley Shyiko.

More Repositories

1

jabba

(cross-platform) Java Version Manager
Go
2,778
star
2

mysql-binlog-connector-java

MySQL Binary Log connector
Java
2,212
star
3

commacd

A faster way to move around (Bash 3+/Zsh)
Shell
353
star
4

kubetpl

Kubernetes templates made easy #keep-it-simple #no-server-component
Go
209
star
5

skedule

A human-friendly alternative to cron. Designed after GAE's schedule for Kotlin and/or Java 8+.
Kotlin
84
star
6

gitlab-ci-build-on-merge-request

Missing "build on Merge Request" feature of Gitlab CI
Go
68
star
7

electron-har

A command-line tool for generating HTTP Archive (HAR) (based on Electron)
JavaScript
46
star
8

kubensx

Simpler Cluster/User/Namespace switching for Kubernetes (featuring interactive mode and wildcard/fuzzy matching)
Go
44
star
9

dotenv

A twelve-factor configuration (12factor.net/config) library for Java 8+
Java
42
star
10

docker-vm

A simple and transparent alternative to boot2docker (backed by Vagrant)
Shell
38
star
11

tsdm

No worries TypeScript definition manager
JavaScript
34
star
12

lorem

Filler text generator compatible with Node.js, Require.js and plain-old <script/>
JavaScript
33
star
13

bower-shrinkwrap-resolver

Missing shrinkwrap for Bower
JavaScript
33
star
14

dockry

Docker Registry V2 CLI (compatible with Docker Hub, GitLab Container Registry, etc; public or private)
Go
25
star
15

rook

Change Data Capture (CDC) toolkit for keeping system layers in sync with the database
Java
23
star
16

servers-maven-extension

Maven extension for exposing settings.xml/servers to ${}
Java
22
star
17

canvas-text-opentypejs-shim

Consistent text rendering for <canvas> (backed by opentype.js)
JavaScript
20
star
18

neutrino-preset-vue-static

A minimalistic starter kit for building static sites using Vue.js
JavaScript
16
star
19

levelkt

LevelDB client for Kotlin and/or Java 8+
Kotlin
14
star
20

dotfiles

Personal ~/*
Shell
13
star
21

k8sovpn

OpenVPN tunnel "to see the world the way pods see it" in Kubernetes
11
star
22

klob

A .gitgnore-pattern-based glob library for Kotlin and/or Java 8+
Kotlin
10
star
23

urxvt-clipboard-paste-on-right-click

rxvt-unicode extension that allows to paste the contents of your clipboard with the right click
Perl
10
star
24

bower-dependency-tree

Bower dependency tree visualizer
JavaScript
9
star
25

amqplib-auto-recovery

Automatic connection recovery for amqplib (squaremo/amqp.node)
JavaScript
9
star
26

vue-document

A 1kb document manager for Vue.js
JavaScript
6
star
27

hubot-starter-kit

Everything you need to get started with Hubot (Dockerfile included).
CoffeeScript
5
star
28

node-chrome-extension-id

A way to get Chromium / Google Chrome Extension ID
JavaScript
4
star
29

node-chrome-user-data-dir

An easy way to generate custom Chromium / Google Chrome profile (user data directory)
JavaScript
4
star
30

usage-maven-plugin

Maven Plugin for printing project Usage information
Java
3
star
31

jabba-autodiscovery

A simple mechanism for keeping jabba's index up-to-date
JavaScript
3
star
32

urxvt-selection-open

rxvt-unicode extension that allows to execute custom actions based on selection
Perl
2
star
33

node-finalize-addon

Object finalization based on N-API for Node.js v8.6.0+
C++
2
star
34

cucumber-js-caffeinator

Cucumber.js supercharged with Mocha reporters.
JavaScript
1
star
35

node-crx-parser

CRX parser
JavaScript
1
star
36

mappify

Dead-simple object mapping in Java
Java
1
star
37

native2asciiplug

Intellij IDEA native2ascii plugin
Java
1
star
38

hadoop-maven-plugin

Maven Plugin for Apache Hadoop
Java
1
star
39

checkstyle-nonstandard

Additional Checkstyle checks
Java
1
star
40

hubot-skype-over-phantomjs

Skype adapter for Hubot (the one that can be actually used on Raspberry Pi)
CoffeeScript
1
star
41

node-minimal-viable-pool

Minimal viable pool for Node.js
JavaScript
1
star
42

ijignore

.ijignore-controlled selective indexing for IntelliJยฎ Platform-based products (IDEA, WebStorm, ...).
Java
1
star
43

rcfg

Configurable package.json-aware sync/async .${app}rc loader
JavaScript
1
star