serverless-plugin-sync-secrets

This is a Serverless Framework that simplifies secrets management by synchronizing encrypted EJSON files with AWS Secrets Manager.

Features

Enhanced Security: Decrypts EJSON secrets directly in memory, without writing secrets to temporary files.
AWS Integration: Automatically synchronizes secrets with AWS Secrets Manager.
Multi-environment Support: Manages different sets of secrets per environment (dev, prod, etc.).
Simulation Mode: Preview changes without applying them using "dry run" mode.

Requirements

EJSON

EJSON must be installed in your development environment.

AWS Policies

The following AWS permissions are required for this plugin to work:

secretsmanager:GetSecretValue
secretsmanager:UpdateSecret
secretsmanager:ListSecrets
secretsmanager:CreateSecret
secretsmanager:DeleteSecret
ssm:GetParameter (only if using SSM to store the EJSON key)

Installation

Install the plugin via npm:

npm install --save-dev serverless-plugin-sync-secrets

Add the plugin to your serverless.yml file:

plugins:
  - serverless-plugin-sync-secrets

Usage

Configuration

To configure this plugin, you need to add a syncSecrets section to the custom section of your serverless.yml file. Here is an example:

custom:
  syncSecrets:
    ejson_file_path: path/to/ejson/secrets.ejson
    ejson_key: <ejson-private-key>
    ssm_prefix: <ssm-prefix>
    secret_name: <secret-name>
    exclude: '^_'
    create_secret: true
    show_values: false
    delete_secret: false
    dry: false

Configuration Options

Option	Description
`ejson_file_path`	Path to the `EJSON` secrets file (default: `./secrets/{stage}.ejson`).
`ejson_key`	The `EJSON` private key (optional if `ssm_prefix` is set).
`ssm_prefix`	Prefix in `AWS SSM Parameter Store` to retrieve the `EJSON` private key (optional if `ejson_key` is provided).
`secret_name`	Name of the secret in `AWS Secrets Manager` (default: service name).
`exclude`	Regex pattern to exclude specific keys from synchronization (default: `'^_'`).
`create_secret`	If `true`, creates the secret in AWS Secrets Manager if it does not exist (default: `false`).
`show_values`	If `true`, shows the secret values in logs instead of markers (default: `false`).
`delete_secret`	If `true`, deletes the secret instead of creating or updating it (default: `false`).
`dry`	If `true`, runs in simulation mode without applying changes (default: `false`).

Execution

The plugin will runs automatically when executing the serverless deploy command. It is triggered during the before:package:initialize phase of the serverless deployment process.

Example 1

service: my-service

provider:
  name: aws
  architecture: arm64
  runtime: provided.al2
  region: ${opt:region, "us-east-2"}
  stage: ${opt:stage, "dev"}

custom:
  syncSecrets:
    ejson_file_path: ./secrets/${self:provider.stage}.ejson
    ssm_prefix: "/ejson/keys/${self:provider.stage}/EJSON_KEY"
    secret_name: "my-service"
    create_secret: true

plugins:
  - serverless-secret-sync-plugin

Example 2

service: my-service

provider:
  name: aws
  architecture: arm64
  runtime: provided.al2
  region: ${opt:region, "us-east-2"}
  stage: ${opt:stage, "dev"}

custom:
  syncSecrets:
    ejson_key: ${env:EJSON_KEY}

plugins:
  - serverless-secret-sync-plugin