rotator

README

Rotator

Rotator is a tool for rotating credentials on a regular schedule. It works by reading a YAML configuration file with a list of secret. Each secret consists of a source from which rotator will read new credentials, and one or more destinations (from here on referred to as sinks) to write the new credentials to.

Currently, rotator supports the following sources...

• AWS IAM

... and sinks:

• Travis CI
• AWS Systems Manager Parameter Store
• AWS Secrets Manager

Table of contents

• Installation
• Usage
  • Flags
• Monitoring
• Sources
  • AWS IAM
  • Env
• Sinks
  • Travis CI
  • AWS Systems Manager Parameter Store
  • AWS Secrets Manager
• Contributing
• License

Installation

go get

If you have a functional go environment, you can install with:

$ go get github.com/chanzuckerberg/rotator

Homebrew

$ brew tap chanzuckerberg/tap
$ brew install rotator

Usage

Execute rotator with the rotate command, passing the --file/-f flag to specify the configuration file:

$ rotator rotate -f config.yaml

Below is an example of a configuration file config.yaml to rotate credentials for the AWS IAM user example-user and write them to the Travis CI repository example-repo:

version: 1
secrets:
  - name: example_secret
    source:
      kind: aws
      max_age: 1h40m0s
      role_arn: arn:aws:iam::123456789101:role/admin
      username: example-user
      external_id: ""
    sinks:
      - kind: TravisCI
        key_to_name:
          accessKeyId: EXAMPLE_AWS_ACCESS_KEY_ID
          secretAccessKey: EXAMPLE_AWS_SECRET_ACCESS_KEY
        repo_slug: example-repo

Flags

-f, --file config file to read from
-y, --yes assume "yes" to all prompts and run non-interactively

Monitoring

Configure Sentry for rotator by setting the ENV, SENTRY_DSN environment variables.

Sources

All sources must have the following fields in addition to any source-specific fields:

Name	Description
kind	The kind of source. Acceptable values: aws.
max_age	The max age for a credential before it will be rotated by rotator. The duration string should follow the same format as for time.ParseDuration() e.g. "2h45m".

Env (env)

Name	Description	Required
name	The name of the environment variable to read	yes

AWS IAM (aws)

Name	Description	Required
role_arn	The ARN of the AWS IAM role that rotator should assume.	yes
username	The name of the AWS IAM user for rotator to rotate their AWS access keys.	yes
external_id	If set, the external ID is passed to the AWS STS AssumeRole API to assume the IAM Role specified by role_arn e.g. if deploying rotator on EC2.	no

AWS credentials must be specified using a shared credentials file or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

Sinks

All sinks must have the following fields in addition to any sink-specific fields:

Name	Description
kind	The kind of sink. Acceptable values: TravisCI, AWSParameterStore, AWSSecretsManager.
key_to_name	A map of source keys to their sink names.*

*Rotator parses the credentials from any source as key-value pairs. For example, the credentials for an AWS IAM source will consist of a AWS_ACCESS_KEY_ID key and a AWS_SECRET_ACCESS_KEY key and their associated values. The key_to_name mapping then maps each key to the name of the credential in the sink that rotator should update the value of. This gives users more control over the rotation, and is also necessary as we might have multiple credentials from the source kind written to the same sink instance. For example, the same AWS Parameter Store sink might store AWS credentials from multiple AWS IAM users; the key_to_name mapping allows us to specify the names of the parameters rotator should update the value of for each source so that we don't overwrite the parameters for another source.

Travis CI (TravisCI)

Name	Description	Required
repo_slug	The target Travis CI repository slug. Same as {repository.owner.name}/{repository.name}.	yes

TRAVIS_API_AUTH_TOKEN should be set.

Circle CI (CircleCI)

Name	Description	Required
account	The CircleCI account to write this env var to.	yes
repo	The CircleCI repo to write this env var to.	yes

CIRCLECI_AUTH_TOKEN must be set.

GitHub Actions Secret (GitHubActionsSecret)

Name	Description	Required
owner	The GitHub repo owner to write this env var to.	yes
repo	The GitHub repo to write this env var to.	yes

GITHUB_ACTIONS_AUTH_TOKEN must be set.

AWS Systems Manager Parameter Store (AWSParameterStore)

Name	Description	Required
role_arn	The ARN of the AWS IAM role that rotator should assume.	yes
region	The [AWS Regional endpoint[(https://docs.aws.amazon.com/general/latest/gr/rande.html)	yes
external_id	If set, the external ID is passed to the AWS STS AssumeRole API to assume the IAM Role specified by role_arn e.g. if deploying rotator on Kubernetes.	no

AWS credentials must be specified using a shared credentials file or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

AWS Secrets Manager (AWSSecretsManager)

Name	Description	Required
role_arn	The ARN of the AWS IAM role that rotator should assume.	yes
region	The [AWS Regional endpoint[(https://docs.aws.amazon.com/general/latest/gr/rande.html)	yes
external_id	If set, the external ID is passed to the AWS STS AssumeRole API to assume the IAM Role specified by role_arn e.g. if deploying rotator on Kubernetes.	no

AWS credentials must be specified using a shared credentials file or AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

Contributing

Contributions and ideas are welcome! Please see our contributing guide and don't hesitate to open an issue or send a pull request to improve the functionality of this gem.

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to opensource@chanzuckerberg.com.

License

MIT