lambda

README

AWS Lambda to rotate Secret in AWS Secretsmanager

AWS Lambda function to rotate secret's version, e.g. database access credentials, stored in AWS Secretsmanager.

• How it works
  • The Lambda Module
    • Plugins
    • List of Plugins
    • Plugin Codebase Structure
• Contribution
• Development
  • Requirements
  • Commands

How it works

[C4 Container] Architecture Diagram.

The diagram illustrates the process of secret's rotation.

Upon invocation, the AWS Lambda's logic executes the following steps:

1. Create Secret: new version of the "Secret User" secret is generated and stored in the staging label AWSPENDING;
2. Set Secret: newly generated secret's version is set in the "System delegated credentials store";
3. Test Secret: newly generated secret's version is tested against the "System delegated credentials store";
4. Finish Secret: newly generated secret's version is moved from the stage AWSPENDING to AWSCURRENT.

Note that the secret is expected to be JSON-encoded.

The Lambda Module

The AWS Lambda's logic defined in the Go module is encapsulated in two interfaces:

• SecretsmanagerClient: defines communication with the secrets vault, i.e. AWS Secretsmanager;
• ServiceClient: defines communication with the system which credentials are stored in the vault. The interface's methods define the logic to perform the rotation steps 1-3. The client uses the secret "Secret Admin" to pass authentication and authorization in order to reset the credentials "Secret User".

The AWS Lambda handler is defined as the function Start configured with the object of the type Config. The config includes the following attributes:

• Clients, i.e. instances of SecretsmanagerClient and ServiceClient;
• SecretObj: the type defining the structure of the secret "Secret User";
• Debug: flag to activate debug level logs.

Plugins

The lambda module defines the interfaces and abstract methods only. The implementation for specific "System delegated credentials store" is done as a plugin which defines the signatures of ServiceClient according to the system's specs. Every plugin is distributed as a separate Go module.

List of Plugins

• neon: plugin to change user's password in the Neon SaaS Postgres service.
• confluent: plugin to rotate Confluent Cloud API keys.

Plugin Codebase Structure

Every plugin is stored in the directory plugin.

It is recommended to use the template to develop and distribute plugin's codebase:

.
|-- README.md
|-- go.mod                <- Definition of Go module: github.com/kislerdm/aws-lambda-secret-rotation/plugin/{{.PluginName}}
|-- go.sum
|-- models.go             <- Types defining structure of "Secret User" and "Secret Admin"         
|-- serviceclient.go      <- Implementation of `ServiceClient` interface
|-- serviceclient_test.go
|-- .release_notes        <- release notes following https://keepachangelog.com/en/1.0.0/
|   |-- v0.0.1.md
|   |-- ...   
|   `-- vx.y.z.md
|-- cmd
|   `-- lambda
|       `-- main.go       <- AWS Lambda handler's definition
`-- example               <- (optional) terraform example to provision resources to rotate "Secret User" secret

Contribution

The codebase is distributed under the MIT license. Please feel free to open an issue ticket, or PR to contribute.

Development

Requirements

• go ~> 1.19
• gnuMake

Commands

Run to see available commands:

make help

Run to test the lambda module:

make tests

Run to test a plugin module:

make test-plugin PLUGIN=##name-of-the-plugin##

For example, to run unit tests for the Neon plugin:

make test-plugin PLUGIN=neon

Run to build lambda binary for selected plugin:

make build PLUGIN=##name-of-the-plugin##

For example, to run unit tests for the Neon plugin:

make build PLUGIN=neon

Documentation

Index

• func ExtractSecretObject(v *secretsmanager.GetSecretValueOutput, secret any) error
• func NewHandler(cfg Config) (func(ctx context.Context, event secretsmanagerTriggerPayload) error, error)
• func StrToBool(s string) bool
• type Config
• type SecretsmanagerClient
• type ServiceClient

Functions

func ExtractSecretObject

func ExtractSecretObject(v *secretsmanager.GetSecretValueOutput, secret any) error

ExtractSecretObject deserializes secret value to a Go object of the secret type.

func NewHandler

func NewHandler(cfg Config) (func(ctx context.Context, event secretsmanagerTriggerPayload) error, error)

NewHandler initialises lambda handler.

func StrToBool

func StrToBool(s string) bool

StrToBool converts string to bool.

Types

type Config

type Config struct {
	// SecretsmanagerClient the client's instance to communicate with the secretsmanager.
	SecretsmanagerClient SecretsmanagerClient

	// ServiceClient the client's instance to communicate with the service delegated credentials storage.
	ServiceClient ServiceClient

	// SecretObj defines the interface of the secret to rotate.
	SecretObj any

	// Debug set to `true` to activate debug level logs.
	Debug bool
}

Config defines the rotation lambda's configuration.

type SecretsmanagerClient

type SecretsmanagerClient interface {
	GetSecretValue(
		ctx context.Context, input *secretsmanager.GetSecretValueInput, optFns ...func(*secretsmanager.Options),
	) (*secretsmanager.GetSecretValueOutput, error)

	PutSecretValue(
		ctx context.Context, input *secretsmanager.PutSecretValueInput, optFns ...func(*secretsmanager.Options),
	) (*secretsmanager.PutSecretValueOutput, error)

	DescribeSecret(
		ctx context.Context, input *secretsmanager.DescribeSecretInput, optFns ...func(*secretsmanager.Options),
	) (
		*secretsmanager.DescribeSecretOutput, error,
	)

	UpdateSecretVersionStage(
		ctx context.Context, input *secretsmanager.UpdateSecretVersionStageInput,
		optFns ...func(*secretsmanager.Options),
	) (*secretsmanager.UpdateSecretVersionStageOutput, error)
}

SecretsmanagerClient client to communicate with the secretsmanager.

type ServiceClient

type ServiceClient interface {
	// Create generates the secret and mutates the `secret` value.
	Create(ctx context.Context, secret any) error

	// Set sets newly generated credentials in the system delegated credentials storage.
	Set(ctx context.Context, secretCurrent, secretPending, secretPrevious any) error

	// Test tries to connect to the system delegated credentials storage using newly generated secret.
	Test(ctx context.Context, secret any) error
}

ServiceClient defines the interface to communicate with the service (e.g. database) to rotate the access credentials.