{"id":16978605,"url":"https://github.com/willdady/cdk-sops-secrets-management","last_synced_at":"2025-09-03T02:47:18.775Z","repository":{"id":192173742,"uuid":"662902277","full_name":"willdady/cdk-sops-secrets-management","owner":"willdady","description":"CDK app for securely storing secrets in Git and syncing to AWS Secrets Manager","archived":false,"fork":false,"pushed_at":"2023-09-02T04:08:00.000Z","size":107,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-19T09:43:25.628Z","etag":null,"topics":["aws","cdk","secops","secrets-management","sops","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willdady.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-07-06T06:18:46.000Z","updated_at":"2023-08-04T00:36:31.000Z","dependencies_parsed_at":"2023-09-03T05:23:06.002Z","dependency_job_id":"5957e9e9-48c3-405b-a20d-6a8893fe3f19","html_url":"https://github.com/willdady/cdk-sops-secrets-management","commit_stats":null,"previous_names":["willdady/cdk-sops-secrets-management"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/willdady/cdk-sops-secrets-management","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdady%2Fcdk-sops-secrets-management","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdady%2Fcdk-sops-secrets-management/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdady%2Fcdk-sops-secrets-management/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdady%2Fcdk-sops-secrets-management/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willdady","download_url":"https://codeload.github.com/willdady/cdk-sops-secrets-management/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willdady%2Fcdk-sops-secrets-management/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273381913,"owners_count":25095330,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","cdk","secops","secrets-management","sops","typescript"],"created_at":"2024-10-14T01:43:48.369Z","updated_at":"2025-09-03T02:47:18.744Z","avatar_url":"https://github.com/willdady.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CDK Sops Secrets Management\n\nThis a reference project using [Mozilla Sops][sops] and [AWS CDK][cdk] to securely store secrets in Git and sync to AWS Secrets Manager.\n\n## Setup\n\n### Install dependencies\n\nThis project requires Node v16.19.0 or greater.\n\n```bash\nnpm install\n```\n\n### Install sops\n\nIn order to add secrets to this repository you MUST [install sops locally](https://github.com/getsops/sops#download).\n\nOn Mac, sops can be easily installed via Homebrew:\n\n```\nbrew install sops\n```\n\n## Testing\n\n```\nnpm test\n```\n\n## Stacks\n\nThis project defines 2 CDK stacks.\nYou MUST edit `bin/secrets-management.ts` to provide configuration values.\nRefer to the comments in this file for the values you need to supply.\n\n### SopsKeyStack\n\nThis stack defines a single resource, a KMS key which is used by [sops][sops] to encrypt and decrypt secrets.\nThis stack is deployed into 2 regions. \nWe refer to each as the primary and secondary keys respectively. \nBoth keys are used when encrypting secrets. \nOnly one key, the primary, is used to decrypt secrets though either key can be used.\nTwo keys are used for redundancy in the event of the total destruction of an AWS region.\n\nEach key is created with a policy granting the `kms:Decrypt` action to requests originating withing the AWS Organisation.\n\nTypically, you should not need to touch this stack as it's unlikely to require changes once deployed.\n\n### SecretsManagementStack\n\nThis stack is used to contain several `SopsSecret` instances. \nThis stack has a dependency on the primary `SopsKeyStack` instance as it requires a reference to the primary KMS key in order to decrypt keys prior to storing in AWS Secrets Manager.\n\n## Encrypting a secret\n\nCreating a secret requires your local AWS credentials to have the appropriate permissions to access the primary and secondary KMS keys created by `SopsKeyStack`.\nThis can be achieved by simply assuming a role in the target Secrets account where the role has permissions to access the KMS key.\nIf you are assuming a role it will need permission to perform encrypt/decrypt operations using the keys. \n\nIt's recommended you define your primary and secondary key arns in a `.sops.yaml` file.\nRefer to the [sops README](https://github.com/getsops/sops#using-sops-yaml-conf-to-select-kms-pgp-for-new-files) on how to do this.\n\nRun the following to open a secret for editing in your shell's default editor.\nThe following example will store your encrypted secret in file named `my-secret.json` in the `secrets` directory in this repositories root.\n\n```bash\nsops secrets/my-secret.json\n```\n\nSecret file extension must be `.json`, `.yaml`, `.env` or `.txt`.\nPlease note any leading and trailing whitespace is trimmed before writing into Secrets Manager.\n\n## Adding secret to SecretsManagementStack\n\nFor each secret you create on-disk a `SopsSecret` construct MUST be instantiated in `lib/secrets-management-stack.ts`.\n\n```typescript\nnew SopsSecret(this, 'MySecret', {\n  path: path.join(__dirname, '..', 'secrets', 'my-secret.json'),\n  kmsKeyArn: props.sopsMasterKeyArn,\n  secretName: 'my-secret',\n});\n```\n\nThe secret's description and tags can optionally be defined with `secretDescription` and `secretTags` respectively.\n\n```typescript\nnew SopsSecret(this, 'MySecret', {\n  path: path.join(__dirname, '..', 'secrets', 'my-secret.json'),\n  kmsKeyArn: props.sopsMasterKeyArn,\n  secretName: 'my-secret',\n  secretDescription: 'My super-secret secret!',\n  secretTags: [\n    {\n      key: 'foo',\n      value: 'bar',\n    },\n  ]\n});\n```\n\nTo grant AWS principals access to the secret you must define `secretPolicy`. \nNote, the principal must *exist* or the deployment will fail.\n\n```typescript\nnew SopsSecret(this, 'MySecret', {\n  path: path.join(__dirname, '..', 'secrets', 'my-secret.json'),\n  kmsKeyArn: props.sopsMasterKeyArn,\n  secretName: 'my-secret',\n  secretDescription: 'My super-secret secret!',\n  secretPolicy: new iam.PolicyDocument({\n    statements: [\n      new iam.PolicyStatement({\n        actions: ['secretsmanager:GetSecretValue'],\n        principals: [new iam.AccountPrincipal(999999999999)],\n        resources: ['*'],\n      }),\n    ],\n  }),\n});\n```\n\nSecret replication can be configured via `secretReplicaRegions`.\n\n```typescript\nnew SopsSecret(this, 'MySecret', {\n  path: path.join(__dirname, '..', 'secrets', 'my-secret.json'),\n  kmsKeyArn: props.sopsMasterKeyArn,\n  secretName: 'my-secret',\n  secretReplicaRegions: [\n    {\n      region: 'us-east-2',\n    },\n    {\n      region: 'us-east-1',\n    },\n  ],\n});\n```\n\n## Known issues\n\n### Updating secrets\n\nUpdating secrets too-frequently MAY be problematic. \nThe custom resource used by `SopsSecret` calls the [UpdateSecret API][update-secret-api] which has the following limitation:\n\n\u003e We recommend you avoid calling UpdateSecret at a sustained rate of more than once every 10 minutes. When you call UpdateSecret to update the secret value, Secrets Manager creates a new version of the secret. Secrets Manager removes outdated versions when there are more than 100, but it does not remove versions created less than 24 hours ago. If you update the secret value more than once every 10 minutes, you create more versions than Secrets Manager removes, and you will reach the quota for secret versions.\n\n### Deleting secrets\n\nDeleting secrets is an asynchronous operation. \nThe custom resource used by `SopsSecret` calls the [DeleteSecret API][delete-secret-api] with `ForceDeleteWithoutRecovery = true`, despite this, deletion is *not* instant. \nThis should only be an issue if you delete a `SopsSecret` and then create a new `SopsSecret` with the same `secretName` a short time later.\n\n\u003e Secrets Manager performs the permanent secret deletion at the end of the waiting period as a background task with low priority. There is no guarantee of a specific time after the recovery window for the permanent delete to occur.\n\n[sops]: https://github.com/mozilla/sops\n[cdk]: https://docs.aws.amazon.com/cdk/v2/guide/home.html\n[update-secret-api]: https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_UpdateSecret.html\n[delete-secret-api]: https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_DeleteSecret.html\n\n## Related articles\n* https://aws.amazon.com/blogs/database/design-patterns-to-access-cross-account-secrets-stored-in-aws-secrets-manager/","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilldady%2Fcdk-sops-secrets-management","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilldady%2Fcdk-sops-secrets-management","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilldady%2Fcdk-sops-secrets-management/lists"}