sidecred

README

sidecred

Sidecred handles the lifecycle of your credentials "on the side". It supports multiple credential providers and secret stores, and handles the lifecycle from creation, to rotations and eventual deletion.

Supported Credential Stores

Credential stores are used to store credentials generated by providers. The following credential stores are supported:

• In-process
• AWS Secrets Manager
• AWS Systems Manager (SSM)

Supported Providers

Credential providers are used to generate provider specific credentials. For example, the GitHub provider is responsible for generating GitHub access tokens and deploy keys. The following credential providers are supported:

• Github (access tokens and deploy keys)
• AWS STS
• Random
• Artifactory

Supported Backends

Backends are where sidecred stores internal state. This state is used for various purposes, such as storing credential expiry.

The following backends are supported:

• File
• AWS S3

Development

Local

# Enable the STS provider
export AWS_REGION=eu-west-1
export SIDECRED_STS_PROVIDER_ENABLED=true
export SIDECRED_STS_PROVIDER_SESSION_DURATION=20m

# Enable the Github provider
export SIDECRED_GITHUB_PROVIDER_ENABLED=true
export SIDECRED_GITHUB_PROVIDER_KEY_ROTATION_INTERVAL=20m

# Chose a secret store and configure it
export SIDECRED_SECRET_STORE_BACKEND=ssm
export SIDECRED_SSM_STORE_PATH_TEMPLATE="/sidecred/{{ .Namespace }}/{{ .Name }}"

# Chose a state backend and configure it
export SIDECRED_STATE_BACKEND=file

# Enable debug logging
export SIDECRED_DEBUG=true

After setting the above you can execute sidecred as follows:

# The Github App credentials (integration ID and private key) and AWS STS credentials
# should be populated using e.g. vaulted or aws-vault:
go run ./cmd/sidecred --namespace e2e --config ./cmd/sidecred/testdata/config.yml

Documentation

Index

• func BuildSecretPath(pathTemplate, namespace, name string) (string, error)
• type Credential
• type CredentialType
  • func (c CredentialType) Provider() ProviderType
• type Metadata
• type Provider
• type ProviderType
• type Request
  • func (r *Request) UnmarshalConfig(target interface{}) error
• type Resource
• type Secret
• type SecretStore
• type Sidecred
  • func New(providers []Provider, store SecretStore, rotationWindow time.Duration, ...) (*Sidecred, error)
  • func (s *Sidecred) Process(namespace string, requests []*Request, state *State) error
• type State
  • func NewState() *State
  • func (s *State) AddResource(t ProviderType, resource *Resource)
  • func (s *State) AddSecret(t StoreType, secret *Secret)
  • func (s *State) GetResourcesByID(t ProviderType, id string) []*Resource
  • func (s *State) ListOrphanedSecrets(t StoreType) []*Secret
  • func (s *State) RemoveResource(t ProviderType, resource *Resource)
  • func (s *State) RemoveSecret(t StoreType, secret *Secret)
• type StateBackend
• type StoreType

Functions

func BuildSecretPath

func BuildSecretPath(pathTemplate, namespace, name string) (string, error)

BuildSecretPath is a convenience function for building path templates.

Types

type Credential

type Credential struct {
	// Name is the identifier for the credential.
	Name string `json:"name,omitempty"`

	// Value is the credential value (typically a secret).
	Value string `json:"-"`

	// Description returns a short description of the credential.
	Description string `json:"-"`

	// Expiration is the time at which the credential will have expired.
	Expiration time.Time `json:"expiration"`
}

Credential is a key/value pair returned by a sidecred.Provider.

type CredentialType

type CredentialType string

CredentialType ...

const (
	Randomized             CredentialType = "random"
	AWSSTS                 CredentialType = "aws:sts"
	GithubDeployKey        CredentialType = "github:deploy-key"
	GithubAccessToken      CredentialType = "github:access-token"
	ArtifactoryAccessToken CredentialType = "artifactory:access-token"
)

Enumeration of known credential types.

func (CredentialType) Provider

func (c CredentialType) Provider() ProviderType

Provider returns the sidecred.ProviderType for the credential.

type Metadata

type Metadata map[string]string

Metadata allows providers to pass additional information to be stored in the sidecred.ResourceState after successfully creating credentials.

type Provider

type Provider interface {
	// Type returns the provider type.
	Type() ProviderType

	// Create the requested credentials. Any sidecred.Resource
	// returned will be stored in state and used to determine
	// when credentials need to be rotated.
	Create(request *Request) ([]*Credential, *Metadata, error)

	// Destroy the specified resource. This is scheduled if
	// a resource in the state has expired. For providers that
	// are not stateful this should be a no-op.
	Destroy(resource *Resource) error
}

Provider is the interface that has to be satisfied by credential providers.

type ProviderType

type ProviderType string

ProviderType ...

const (
	Random      ProviderType = "random"
	AWS         ProviderType = "aws"
	Github      ProviderType = "github"
	Artifactory ProviderType = "artifactory"
)

Enumeration of known provider types.

type Request

type Request struct {
	// Type identifies the type of credential (and provider) for a request.
	Type CredentialType `json:"type"`

	// Name is an indentifier that can be used for naming resources and
	// credentials created by a sidecred.Provider. The exact usage for
	// name is up to the individual provider.
	Name string `json:"name"`

	// Config holds the specific configuration for the requested credential
	// type, and must be deserialized by the provider when Create is called.
	Config json.RawMessage `json:"config"`
}

Request is the root datastructure used to request credentials in Sidecred.

func (*Request) UnmarshalConfig

func (r *Request) UnmarshalConfig(target interface{}) error

UnmarshalConfig is a convenience method for unmarshalling the JSON config into a config structure for a sidecred.Provider. When no config has been passed in the request, no operation is performed by this function.

type Resource

type Resource struct {
	ID         string          `json:"id"`
	Expiration time.Time       `json:"expiration"`
	Deposed    bool            `json:"deposed"`
	Config     json.RawMessage `json:"config,omitempty"`
	Metadata   *Metadata       `json:"metadata,omitempty"`
	InUse      bool            `json:"-"`
}

Resource represents a resource provisioned by a sidecred.Provider as part of creating the requested credentials.

type Secret

type Secret struct {
	ResourceID string    `json:"resource_id"`
	Path       string    `json:"path"`
	Expiration time.Time `json:"expiration"`
}

Secret is used to hold state about secrets stored in a secret backend.

type SecretStore

type SecretStore interface {
	// Type returns the store type.
	Type() StoreType

	// Write a sidecred.Credential to the secret store.
	Write(namespace string, secret *Credential) (string, error)

	// Read the specified secret by reference.
	Read(path string) (string, bool, error)

	// Delete the specified secret. Should not return an error
	// if the secret does not exist or has already been deleted.
	Delete(path string) error
}

SecretStore is implemented by store backends for secrets.

type Sidecred

type Sidecred struct {
	// contains filtered or unexported fields
}

Sidecred is the underlying datastructure for the service.

func New

func New(providers []Provider, store SecretStore, rotationWindow time.Duration, logger *zap.Logger) (*Sidecred, error)

New returns a new instance of sidecred.Sidecred with the desired configuration.

func (*Sidecred) Process

func (s *Sidecred) Process(namespace string, requests []*Request, state *State) error

Process a single sidecred.Request.

type State

type State struct {
	Providers []*providerState `json:"providers,omitempty"`
	Stores    []*storeState    `json:"stores,omitempty"`
}

State is responsible for keeping track of when credentials need to be rotated because they are expired, the configuration has changed, or they have been deposed and need to clean up resources and secrets.

func NewState

func NewState() *State

NewState returns a new sidecred.State.

func (*State) AddResource

func (s *State) AddResource(t ProviderType, resource *Resource)

AddResource stores a resource state for the given provider. The provider will be added to state if it does not already exist. Any existing resources with the same ID will be marked as deposed.

func (*State) AddSecret

func (s *State) AddSecret(t StoreType, secret *Secret)

AddSecret adds state for the specified sidecred.SecretStore. The store will be added to state if it does not already exist, and any existing state for the same secret path will be overwritten.

func (*State) GetResourcesByID

func (s *State) GetResourcesByID(t ProviderType, id string) []*Resource

GetResourcesByID returns all resources with the given ID from state, and also marks the resources as being in use.

func (*State) ListOrphanedSecrets

func (s *State) ListOrphanedSecrets(t StoreType) []*Secret

ListOrphanedSecrets lists all secrets tied to missing resource IDs that should be considered orhpaned.

func (*State) RemoveResource

func (s *State) RemoveResource(t ProviderType, resource *Resource)

RemoveResource from the state.

func (*State) RemoveSecret

func (s *State) RemoveSecret(t StoreType, secret *Secret)

RemoveSecret from the state.

type StateBackend

type StateBackend interface {
	// Load state from the backend. If no state exists it should be created.
	Load(path string) (*State, error)

	// Save a state to the backend.
	Save(path string, state *State) error
}

StateBackend is implemented by things that know how to store sidecred.State.

type StoreType

type StoreType string

StoreType ...

const (
	Inprocess      StoreType = "inprocess"
	SecretsManager StoreType = "secretsmanager"
	SSM            StoreType = "ssm"
)

Enumeration of known backends.