{"id":18779319,"url":"https://github.com/zostay/garotate","last_synced_at":"2026-04-17T01:32:12.028Z","repository":{"id":57693357,"uuid":"465401073","full_name":"zostay/garotate","owner":"zostay","description":"Small tool for performing secret rotation","archived":false,"fork":false,"pushed_at":"2023-01-11T23:23:57.000Z","size":199,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-21T06:11:33.643Z","etag":null,"topics":["aws","docker","github"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zostay.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE-OF-CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-03-02T17:18:19.000Z","updated_at":"2022-04-23T22:32:30.000Z","dependencies_parsed_at":"2023-02-09T08:45:28.100Z","dependency_job_id":null,"html_url":"https://github.com/zostay/garotate","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/zostay/garotate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Fgarotate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Fgarotate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Fgarotate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Fgarotate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zostay","download_url":"https://codeload.github.com/zostay/garotate/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zostay%2Fgarotate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31911473,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"ssl_error","status_checked_at":"2026-04-16T18:21:47.142Z","response_time":69,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","docker","github"],"created_at":"2024-11-07T20:19:36.788Z","updated_at":"2026-04-17T01:32:12.001Z","avatar_url":"https://github.com/zostay.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# garotate\n\nThis project provides tooling for automated secret rotation and\ndisablement. The rotation of secrets is an important task to perform for service\naccounts and other related assets, especially in the cloud, in situations where\nyour provided can't provide such services for you (either because they just\ndon't or because you need to use the service in such a way that makes those\nservices unavailable). \n\n# Getting Started\n\n## Downloadable Release Binaries\n\nPrecompiled binaries are provided through the github release system:\n\n1. Go to the [Releases](https://github.com/zostay/garotate/releases) page.\n2. Find the latest release.\n3. Click on heading labeled \"Assets\".\n4. Click on the file that matches your operating system and architecture.\n5. Put it in an appropriate directory for running it (on a local Linux or Apple\n   laptop, this is usually `/usr/local/bin`). You may want to rename it to just\n   `garotate` in the process:\n\n```bash\nsudo cp ~/Downloads/garotate-darwin-amd64 /usr/local/bin/garotate\n```\n\n## Build From Source\n\nYou will need to have Golang installed. Installing it from Go just requires:\n\n```bash\ngo install github.com/zostay/garotate@latest\n```\n\nTo install from source:\n\n```bash\ngit clone git@github.com:zostay/garotate.git\ncd garotate\nmake test \u0026\u0026 make install\n```\n\n# Configuration\n\nConfiguration of garotate requires a YAML configuration file and environment\nvariables to configure the plugins.\n\n## Configuration File\n\nHere's an example configuration file:\n\n```yaml\n---\n# plugins lists the configurations to use for rotation, disablement, and\n# storage. For now, every configuration must define this section exactly like\n# this. The names \"CircleCI\", \"github\", and \"IAM\" could be changed, but nothing\n# else. These plugins must be configured exactly this way.\nplugins:\n  github:\n    package: github.com/zostay/garotate/pkg/plugin/github/action/secret\n  IAM:\n    package: github.com/zostay/garotate/pkg/plugin/aws/iam/user/access\n  CircleCI:\n    package: github.com/zostay/garotate/pkg/plugin/circleci/project/env\n\n# The rotations section configures rotation policies. Each item in the list has\n# the following keys:\n# \n# client: This names the plugin to use, which must match the name in the plugins\n#   section.\n# rotate_after: The duration setting that determines how long to wait before\n#   rotating the secret. The first run of the rotation tool after this amount of\n#   time has passed since last rotation will trigger rotation.\n# secret_set: This is the list of secrets that will be rotated according to this\n#   policy.\nrotations:\n  - client: IAM\n    rotate_after: \"168h\"\n    secret_set: main\n\n# The disablements section configures disablement policies. Each item in the\n# list has the following keys:\n#\n# client: This names the plugin to use, which must match the name in the plugins\n#   section.\n# disable_after: The duration setting that determines how long to wait before\n#   disabling the secret. The first run of the disablement tool after this\n#   amount of time has passed since the secret was created will trigger\n#   disablement. You will want this to be longer than the rotation policy time\n#   unless you want inactive secrets to be disabled immediately after rotation.\n# secret_set: This is the list of secrets that will be rotated according to this\n#   policy.\ndisablements:\n  - client: IAM\n    disable_after: \"216h\"\n    secret_set: main\n\n# The secret_sets section configures the list of secrets that should have a\n# policy applied to them.\n#\n# Each secret item in the list of secrets must have the following keys:\n# \n# secret: The name of the secret to change, whatever names accounts that can be\n#   rotated in the plugin. For AWS, this is IAM user name.\n# storages: This lists configuration for each of the places that need to be\n#   updated after the secret is rotated.\n#\n# Each storage item in the list of storages must have the following keys:\n#\n# storage: This is the name of the storage plugin to use. This must exactly\n#   match the name of a storage plugin defined in the plugins section.\n# name: This is the name of the service that will be receiving a fresh copy of\n#   the rotated secret following rotation. This is whatever value the plugin\n#   needs. For github, this is the github project name in owner/repo form.\n# keys: This is a map that remaps the keys provided by the rotation plugin to\n#   the keys to use when storing. The AWS plugin provides two keys,\n#   \"AWS_ACCESS_KEY_ID\" and \"AWS_SECRET_ACCESS_KEY\". If no keys section is\n#   provided, then the keys used are the keys provided by the rotation plugin.\nsecret_sets:\n  - name: main\n    secrets:\n      - secret: s3sync-builder\n        storages:\n          - storage: github\n            name: zostay/periodic-s3-sync\n            keys:\n              AWS_ACCESS_KEY_ID: access_key\n              AWS_SECRET_ACCESS_KEY: secret_key\n      - secret: postfix-builder\n        storages:\n          - storage: github\n            name: zostay/postfix\n          - storage: CircleCI\n            name: gh/zostay/postfix\n```\n\n## AWS Plugin Configuration\n\nYou must provide AWS configuration using the usual means. This can mean files in\nan `~/.aws` folder as used by the AWS CLI or environment variables to provide\nthe required credentials.\n\nSee the [Specifying\nCredentials](https://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials)\nsection of the Go SDK for full details.\n\nFor the IAM plugin to work, these credentials must provide garotate with the\nfollowing permissions:\n\n* iam:ListAccessKeys\n* iam:CreateAccessKey\n* iam:DeleteAccessKey\n* iam:UpdateAccessKey\n\n## CircleCI Plugin Configuration\n\nYou must provide a `CIRCLECI_TOKEN` in environment. This must be set to a\nCircleCI API token.\n\nCircleCI provides instructions on [Managing API\nTokens](https://circleci.com/docs/2.0/managing-api-tokens/) on their web site.\n\n## Github Plugin Configuration.\n\nYou must provide a `GITHUB_TOKEN` environment variable. This must be set to a\nGithub token with `repo` permissions for the github plugin to work.\n\nGithub provides instructions on [creating a personal access\ntoken](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).\n\n# Running\n\nOnce configured, running it is straightforward:\n\n```bash\ngarotate --config-file garotate.yaml\n```\n\nUse `-h` to retrieve a list and description of options. There are a few options\nwhich can be specified on the command-line. The rest of the configuration is\nperformed either via environment or configuration file.\n\n# Supported Plugins\n\nCurrently, the service supports these plugins:\n\n* Rotation of [AWS IAM users](https://github.com/zostay/garotate/pkg/plugin/aws/iam/user/access)\n* Storage in [CircleCI project environment variables](https://github.com/zostay/garotate/pkg/plugin/circleci/project/env)\n* Storage in [github action secrets](https://github.com/zostay/garotate/pkg/plugin/github/action/secret)\n\nThe plugins are divided into three types, rotation, disablement, and storage.\nTypically, the rotation and disablement plugins are going to be the same plugin.\nThey're split up logically because the process for each operation is slightly\ndifferent and the policies that operate on these rotations is different.\n\nThe terms plugin and client are almost interchangeable here. Generally, though,\nthe term plugin refers to the implementation and client refers to the interface.\n\n## Rotation Clients\n\nRotation clients are responsible for rotating each configured secret. They must\nprovide the following capabilities:\n\n* Checking the timestamp of the most recent rotation of a given secret.\n* Performing the rotation of a secret on request and returning all secret\n  details associated with the newly rotated secret.\n\n## Disablement Clients\n\nDisablement clients are responsible for disabling the inactive secrets\nassociated with an account. Each disablement client must provide the following\ncapabilities:\n\n* Checking the timestamp of the newst inactive secret associated with an\n  account.\n* Performing the disablement of all inactive secrets associated with an acount.\n\n## Storage Clients\n\nStorage clients are responsible for storing freshly rotated secrets in some\nclient-side store. Each storage client must provide the following capabiities:\n\n* Report on the last updated timestamp for each secret associated with a rotated\n  account.\n* Replace all the secrets associated with a rotated account.\n\n## Rotation/Disablement Plugins\n\n### AWS IAM Users\n\nThe AWS IAM users plugin provides an implementation of both the rotation and\ndisablement clients for rotating AWS IAM user accounts.\n\n## Storage Plugins\n\n### CircleCI Project Environment Variables\n\nThe CircleCI project environment variables plugin provides an implementation of\nthe storage client. It stores the keys following rotation into the environment\nvariables of a named project.\n\n### Github Action Secrets\n\nThe github action secrets plugin provides an implementation of the storage\nclient for storing the key associated with rotated accounts.\n\n# The Origin Story\n\nThe original use case for this was to help with AWS IAM service accounts that I\nprovide to some of my Github projects. I have created IAM user accounts,\ngenerate AWS access keys for those accounts, and then save those secrets in the\naction secret store for each project. Then the github actions for those projects\ncan make use of those secrets to perform operations on my AWS account. However,\nvery shortly, all of my access keys were being flagged as being old, so I wanted\na tool to perform rotation.\n\nI could have found some tool that already does that, but a quick search didn't\nfind one. (It was so quick, I might not have read the results or maybe even hit\nthe search button in DuckDuckGo. I don't remember at this point.) It seemed like\na fun project to do while I was between jobs. It took a bit longer than expected\n(of course), so I'm just finishing up writing this a month into the new job.\n\n# COPYRIGHT\n\nCopyright 2022 Andrew Sterling Hanenkamp\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of\nthis software and associated documentation files (the \"Software\"), to deal in\nthe Software without restriction, including without limitation the rights to\nuse, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\nthe Software, and to permit persons to whom the Software is furnished to do so,\nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\nFOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\nCOPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\nIN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\nCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzostay%2Fgarotate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzostay%2Fgarotate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzostay%2Fgarotate/lists"}