vaku

Documentation

Overview

Package vaku wraps an official Vault client with useful high-level functions.

Terminology

A 'path' in vault references a location. This location can either be a secret itself or a folder containing secrets. A clean path does not start or end with a '/'.

A 'key' is the same as a path except that it can end in a '/', signifying for certain that it is a folder. A trailing slash is a way of notifying that a path is a folder, but lack of a trailing slash does not imply the opposite.

A 'folder' is a key that ends in a '/'. Folders are not secrets, but they contain secrets and/or other folders.

Summary

Vaku is intended to provide useful functions for Vault that let users operate securely and efficiently. Using the official Vault API and CLI it is only possible to take CRUD actions on individual paths, however normal usage of vault will eventually lead to a desire for more advanced functions like the ability to copy or move paths or even entire folders. The functions in this package can be broken into the distinct categroies below.

Helpers

These exported functions provide useful ways to manage Vault paths in code. They provide utilities for cleaning, combining, and splitting Vault paths, keys, and folders. Many of these utilities exist unexported in the official Vault Golang API, but they are useful enough to provide to end users here.

Path Functions

Path functions act on vault paths under both versions of the key/value secrets engine. They should not be used on paths outside of those engines. The path functions in Vaku are opinionated and easy to use. However this means that they do not support many of the features in the Vault API. For example, PathRead() does not return any metadata or other information about a secret, only the data of the secret itself.

Folder Functions

Folder functions act on vault folders under both versions of the key/value secrets engine. They should not be used on folders outside of those engines. In general, a folder function acts on all paths found by listing the input path recursively. For example, FolderDelete() on "secret/test" will list all paths within "secret/test" and its subfolders and then call PathDelete() on each one. Folder functions are executed concurrently using a worker pool of goroutines and channels.

Index

• Variables
• func Version() string
• type Client
  • func NewClient() *Client
  • func NewClientFromVaultClient(vc *vapi.Client) *Client
  • func (c *Client) FolderCopy(s *PathInput, t *PathInput) error
  • func (c *Client) FolderDelete(i *PathInput) error
  • func (c *Client) FolderDestroy(i *PathInput) error
  • func (c *Client) FolderList(i *PathInput) ([]string, error)
  • func (c *Client) FolderMove(s *PathInput, t *PathInput) error
  • func (c *Client) FolderRead(i *PathInput) (map[string]map[string]interface{}, error)
  • func (c *Client) FolderReadOnce(i *PathInput) (map[string]map[string]interface{}, error)
  • func (c *Client) FolderSearch(i *PathInput, s string) ([]string, error)
  • func (c *Client) FolderWrite(d map[string]map[string]interface{}) error
  • func (c *Client) InitPathInput(i *PathInput) error
  • func (c *Client) KeyBase(k string) string
  • func (c *Client) KeyClean(k string) string
  • func (c *Client) KeyIsFolder(k string) bool
  • func (c *Client) KeyJoin(ks ...string) string
  • func (c *Client) MountInfo(p string) (*MountInfoOutput, error)
  • func (c *Client) PathBase(p string) string
  • func (c *Client) PathClean(p string) string
  • func (c *Client) PathCopy(s *PathInput, t *PathInput) error
  • func (c *Client) PathDelete(i *PathInput) error
  • func (c *Client) PathDestroy(i *PathInput) error
  • func (c *Client) PathDestroyVersions(i *PathInput, versions []int) error
  • func (c *Client) PathJoin(ps ...string) string
  • func (c *Client) PathList(i *PathInput) ([]string, error)
  • func (c *Client) PathMove(s *PathInput, t *PathInput) error
  • func (c *Client) PathRead(i *PathInput) (map[string]interface{}, error)
  • func (c *Client) PathSearch(i *PathInput, s string) (bool, error)
  • func (c *Client) PathUpdate(i *PathInput, d map[string]interface{}) error
  • func (c *Client) PathWrite(i *PathInput, d map[string]interface{}) error
  • func (c *Client) SliceAddKeyPrefix(ss []string, p string)
  • func (c *Client) SliceRemoveFolders(ss []string) []string
  • func (c *Client) SliceTrimKeyPrefix(ss []string, p string)
• type CopyClient
  • func NewCopyClient() *CopyClient
  • func (c *CopyClient) FolderCopy(s *PathInput, t *PathInput) error
  • func (c *CopyClient) PathCopy(s *PathInput, t *PathInput) error
• type MountInfoOutput
• type PathInput
  • func NewPathInput(p string) *PathInput

Variables

var MaxConcurrency = 10

MaxConcurrency is the maximum number of threads/workers to use when calling Folder-based functions that execute concurrently. The default value is 10, but a stable and well-tuned Vault server should be able to handle up to 100 without issues. Use with caution and tune specifically to your environment and storage backend.

Functions

func Version

func Version() string

Version returns the current Vaku API version

Types

type Client

type Client struct {
	*vapi.Client
}

Client is a simple wrapper around a real Vault API client. All Vaku functions are defined on Client as well, which lets anyone already using a Vault Client easily make use of Vaku.

func NewClient

func NewClient() *Client

NewClient returns a new empty Vaku Client. Using this function requires that you initialize and set the nested Vault client on your own before Vaku functions will work.

func NewClientFromVaultClient

func NewClientFromVaultClient(vc *vapi.Client) *Client

NewClientFromVaultClient takes in an official Vault Client that you have already created and returns a Vaku client that wraps your Vault client.

func (*Client) FolderCopy

func (c *Client) FolderCopy(s *PathInput, t *PathInput) error

FolderCopy takes in a source PathInput and target PathInput and copies every path in the source to the target. Note that this will copy the input path if it is a secret and all paths under the input path that result from calling FolderList() on that path. Also note that this will overwrite any existing keys at the target paths.

func (*Client) FolderDelete

func (c *Client) FolderDelete(i *PathInput) error

FolderDelete takes in a path and deletes every key in that folder and all sub-folders. Note that this calls PathDelete() on every path found in the folder, and for v2 secret mounts that means deleting the active version, but not all versions.

func (*Client) FolderDestroy

func (c *Client) FolderDestroy(i *PathInput) error

FolderDestroy takes in a path and destroys every key in that folder and all sub-folders. Note that this function only works on V2 mounts and that it destroys ALL versions of ALL keys

func (*Client) FolderList

func (c *Client) FolderList(i *PathInput) ([]string, error)

FolderList takes in a PathInput and walks the path by calling PathList on the input path and all folders within that path as well. Returns the results as a sorted slice of paths.

func (*Client) FolderMove

func (c *Client) FolderMove(s *PathInput, t *PathInput) error

FolderMove calls FolderCopy() with the same inputs followed by FolderDelete() on the source path if the copy was successful.

func (*Client) FolderRead

func (c *Client) FolderRead(i *PathInput) (map[string]map[string]interface{}, error)

FolderRead takes in a PathInput and calls PathRead() on all paths in that path and all nested paths. It outputs a map of paths (strings) to PathRead() outputs (map[string]interface{}).

func (*Client) FolderReadOnce

func (c *Client) FolderReadOnce(i *PathInput) (map[string]map[string]interface{}, error)

FolderReadOnce takes in a PathInput and calls PathRead() on all non-folders in that path. It outputs a map of paths (strings) to PathRead() outputs (map[string]interface{}). This function is different from FolderRead in that it reads the immediately nested keys, instead of all keys in the folder and its subfolders.

func (*Client) FolderSearch

func (c *Client) FolderSearch(i *PathInput, s string) ([]string, error)

FolderSearch takes in a PathInput and a search string. It then calls FolderList() on that path and concurrently runs PathSearch() on every returned path in the list. It returns a list of paths at which the search string was found. Note that running this function against a path that is not a folder will produce an error, to search a single path you should use PathSearch() instead.

func (*Client) FolderWrite

func (c *Client) FolderWrite(d map[string]map[string]interface{}) error

FolderWrite takes in a map of paths to data that should be written to that path. Users may find this function difficult to call on its own because the input can be large and specific, however the output of FolderRead matches the input of FolderWrite(), making them easy to use together. Note that mount/version information is determined only once using a random path in the map and cached for all future writes. Therefore this function cannot write to two mounts of different versions in the same call.

func (*Client) InitPathInput

func (c *Client) InitPathInput(i *PathInput) error

InitPathInput fills in missing values from PathInput with defaults and mount information. This function will rarely be useful by end-users, but could lead to performance gain if multiple actions are being taken on the same PathInput by preventing repeats of the relatively expensive task of determining mount information about the path

func (*Client) KeyBase

func (c *Client) KeyBase(k string) string

KeyBase returns the last element of path k and cleans it. If k is empty or all slashes, return an empty string

func (*Client) KeyClean

func (c *Client) KeyClean(k string) string

KeyClean simply calls KeyJoin() with one string. KeyJoin already cleans keys, so this helper exists only for naming simplicity.

func (*Client) KeyIsFolder

func (c *Client) KeyIsFolder(k string) bool

KeyIsFolder returns true if the string ends in a '/'.

func (*Client) KeyJoin

func (c *Client) KeyJoin(ks ...string) string

KeyJoin takes n strings and combines them into a clean Vault key. Vault keys (as opposed to paths) optionally have a trailing '/' to signify they are a folder.

func (*Client) MountInfo

func (c *Client) MountInfo(p string) (*MountInfoOutput, error)

MountInfo gets information about the mount at the specified path that can be used to determine what actions to take on that path.

func (*Client) PathBase

func (c *Client) PathBase(p string) string

PathBase calls KeyBase(p) and also trims the trailing '/' if necessary

func (*Client) PathClean

func (c *Client) PathClean(p string) string

PathClean just calls PathJoin() with one string. PathJoin already cleans paths, so this helper exists only for naming simplicity.

func (*Client) PathCopy

func (c *Client) PathCopy(s *PathInput, t *PathInput) error

PathCopy takes in a source PathInput and a target PathInput. It then copies the data from one path to another. Note that PathCopy can be used to copy data from one mount to another. Note also that this will overwrite any existing key at the target path.

func (*Client) PathDelete

func (c *Client) PathDelete(i *PathInput) error

PathDelete takes in a PathInput and calls the native Vault delete on it. For v2 mounts this function only "marks the path as deleted", it does nothing with the versions of the path

func (*Client) PathDestroy

func (c *Client) PathDestroy(i *PathInput) error

PathDestroy takes in a PathInput and calls the native delete on 'mount/metadata/path' This function only works on versioned (V2) key/value mounts. Note that this destroys ALL versions at the path, there is no current support for destroying specific versions.

func (*Client) PathDestroyVersions

func (c *Client) PathDestroyVersions(i *PathInput, versions []int) error

PathDestroyVersions takes in a PathInput and calls the destroy on 'mount/destroy/path' This function only works on versioned (V2) key/value mounts.

func (*Client) PathJoin

func (c *Client) PathJoin(ps ...string) string

PathJoin takes n strings and combines them into a clean Vault path. Paths in vault (unlike keys) never end with a '/'.

func (*Client) PathList

func (c *Client) PathList(i *PathInput) ([]string, error)

PathList takes in a PathInput, calls the native vault list on it, extracts the secret (list of keys), and returns it. Note that any metadata or other information returned by the list is thrown away.

func (*Client) PathMove

func (c *Client) PathMove(s *PathInput, t *PathInput) error

PathMove calls PathCopy() with the same inputs followed by PathDelete() on the source if the copy was successful. Note that this will overwrite any existing keys at the target Path.

func (*Client) PathRead

func (c *Client) PathRead(i *PathInput) (map[string]interface{}, error)

PathRead takes in a PathInput, calls the native vault read on it, extracts the secret, and returns it as a map of strings to values. Note that this is the way secrets are represented in Vault, as map[string]interface{} (JSON)

func (*Client) PathSearch

func (c *Client) PathSearch(i *PathInput, s string) (bool, error)

PathSearch takes in a PathInput and a search string, reads the path, and searches the read data for a match on the search string. Returns true if the string is found in the data. Note that this is a simple search that just checks if the secret contains the search string anywhere. Also note that if this is a KV version 2 mount and the input path has been deleted (but not destroyed) this returns false with no error.

func (*Client) PathUpdate

func (c *Client) PathUpdate(i *PathInput, d map[string]interface{}) error

PathUpdate takes in a path with existing data and new data to write to that path. It then merges the data at the existing path with the new data, with precedence given to the new data, and writes the merged data back to Vault

func (*Client) PathWrite

func (c *Client) PathWrite(i *PathInput, d map[string]interface{}) error

PathWrite takes in a PathInput and data to written to that path. It then calls the native vault write with that data at the specified path.

func (*Client) SliceAddKeyPrefix

func (c *Client) SliceAddKeyPrefix(ss []string, p string)

SliceAddKeyPrefix takes in a slice of keys (strings) and a prefix and adds that prefix to every key in the slice

func (*Client) SliceRemoveFolders

func (c *Client) SliceRemoveFolders(ss []string) []string

SliceRemoveFolders takes a list of keys and removes any folders (strings that end in a '/') and returns the new filtered list

func (*Client) SliceTrimKeyPrefix

func (c *Client) SliceTrimKeyPrefix(ss []string, p string)

SliceTrimKeyPrefix takes in a slice of keys (strings) and a prefix and trims that prefix from every key in the slice

type CopyClient

type CopyClient struct {
	Source *Client
	Target *Client
}

CopyClient is a client for copy operations where the source address/namespace/token is different from target address/namespace/token. The source is a client for the source of the copy, target is a client for the target of the copy

func NewCopyClient

func NewCopyClient() *CopyClient

NewCopyClient returns a new empty CopyClient. Using this function requires that caller initialize and set the source / target client.

func (*CopyClient) FolderCopy

func (c *CopyClient) FolderCopy(s *PathInput, t *PathInput) error

FolderCopy takes in a source PathInput and target PathInput and copies every path in the source to the target. Note that this will copy the input path if it is a secret and all paths under the input path that result from calling FolderList() on that path. Also note that this will overwrite any existing keys at the target paths.

func (*CopyClient) PathCopy

func (c *CopyClient) PathCopy(s *PathInput, t *PathInput) error

PathCopy takes in a source PathInput and a target PathInput. It then copies the data from one path to another. Note that PathCopy can be used to copy data from one mount to another. Note also that this will overwrite any existing key at the target path.

type MountInfoOutput

type MountInfoOutput struct {
	FullPath      string // The original input path
	MountPath     string // The path of the mount
	MountlessPath string // The FullPath with the MountPath removed
	MountVersion  string // The version of the mount, default "unknown"
}

MountInfoOutput holds output for MountInfo. This data can be useful for determining which key/value engine version a path is mounted on and acting accordingly.

type PathInput

type PathInput struct {
	Path           string
	TrimPathPrefix bool
	// contains filtered or unexported fields
}

PathInput is the standard way of representing a Vault path with Vaku. The only required input is the Path itself. You can also specify TrimPathPrefix which determines if returned paths include the full input Path or only the nested paths. This struct also holds unexported data about the version of the key/value mount that the path is in.

func NewPathInput

func NewPathInput(p string) *PathInput

NewPathInput takes in a Path and returns the default PathInput. This function can be used to easily take a path string and use it as input for a Vaku function. TrimPathPrefix is true by default, which produces behavior similar to the Vault API.