Serverless KMS Grants Plugin


A plugin for the Serverless Framework which creates
AWS KMS grants for an IAM role to give it permission to use a KMS key. The
plugin creates an AWS KMS grant as part of the serverless deploy function, and
revokes it as part of the serverless remove function. You can also run it from
the command line.

Table of Contents

- Install
- Usage
- Run Locally
- Support
- Contribute

Install

1. Add serverless-kms-grants plugin to your package.json:
npm install --save-dev serverless-kms-grants

2. Add the serverless-kms-grants plugin to the serverless.yml file:

``
plugins:
- serverless-kms-grants
`

3. To verify that the plugin was added successfully, run serverless in your
command line. The plugin should show up under the "Plugins" section as
ServerlessKmsGrants.

Usage

$3

As of version 1.0.0 a list of grants can be configured. For each grant you'd
like to make, configure the AWS KMS key id and role arn or role name for the
plugin in serverless.yml. Using the ARN of a resource is the safest as it is
guaranteed to be unique in AWS. If only a kmsKeyId is given and neither the
roleName or roleArn are specified, the plugin will try to find and use the
default lambda role generated by Serverless. The default serverless lambda role
name follows the convention: ---lambdaRole.

- kmsKeyId: the KeyId, Alias, or Arn used to identify the KMS key
(Required)
- roleName: the name of the AWS IAM role you wish to grant access to KMS key.
(Optional).
- roleArn: the Arn of the AWS IAM role you wish to grant access to the KMS key
(Optional).

Example:

`(yaml)
custom:
kmsGrants:
# Grant the default serverless lambda role access to a KMS key
- kmsKeyId:
# Grant a role with a unique name access to a KMS Key
- kmsKeyId:
roleName:
# Grant a role with a specific ARN access to a KMS Key
- kmsKeyId:
roleArn:
`

$3

Configure the AWS KMS key id and lambdaArn for the plugin in serverless.yml:

- kmsKeyId: the KeyId, Alias, or Arn used to identify the KMS key
(Required)
- lambdaRoleName: the name of the lambda role you wish to grant access to KMS
key. (Optional). If name is not specified the plugin will try with default
role name.
- lambdaRoleArn: the Arn of the lambda you wish to grant access to the KMS key
(Optional). If an arn is not specified, the plugin will look for the default
lambdaRole and obtain its arn. The default serverless lambda role follows the
convention: ---lambdaRole.

`
custom:
kmsGrants:
kmsKeyId:
lambdaRoleArn:
`

For example:

`
custom:
kmsGrants:
kmsKeyId: "alias/myKey"
lambdaRoleArn: "arn:aws:iam::000123456789:role/myservice-mystage-us-east-1-lambdaRole"
`

Run Locally

The plugin can be used locally via the command line to create or revoke an AWS
KMS Grant (using the specification in serverless.yml above)

`
serverless createKmsGrant
serverless revokeKmsGrant
`

You can specify the stage by adding --stage to the end as follows:

`
serverless createKmsGrant --stage myStage
serverless revokeKmsGrant --stage myStage
``

Support

This is an Open Source community project. Project contributors may be able to
help, depending on their time and availability. Please be specific about what
you're trying to do, your system, and steps to reproduce the problem.

For bug reports or feature requests, please
open an issue.
You are welcome to contribute.

Official support from Trend Micro is not available. Individual contributors may
be Trend Micro employees, but are not official support.

Contribute

We accept contributions from the community. To submit changes:

1. Fork this repository.
1. Create a new feature branch.
1. Make your changes.
1. Submit a pull request with an explanation of your changes or additions.

We will review and work with you to release the code.