{"id":37212030,"url":"https://github.com/primait/biscuit","last_synced_at":"2026-01-15T00:23:07.324Z","repository":{"id":57548206,"uuid":"134236807","full_name":"primait/biscuit","owner":"primait","description":"Biscuit is a multi-region HA key-value store for your AWS infrastructure secrets.","archived":true,"fork":true,"pushed_at":"2023-08-30T14:04:01.000Z","size":88,"stargazers_count":0,"open_issues_count":4,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-06-20T15:55:25.823Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"dcoker/biscuit","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/primait.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-05-21T07:53:53.000Z","updated_at":"2024-05-15T07:33:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/primait/biscuit","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/primait/biscuit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primait%2Fbiscuit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primait%2Fbiscuit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primait%2Fbiscuit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primait%2Fbiscuit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/primait","download_url":"https://codeload.github.com/primait/biscuit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/primait%2Fbiscuit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28439685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T22:37:52.437Z","status":"ssl_error","status_checked_at":"2026-01-14T22:37:31.496Z","response_time":107,"last_error":"SSL_read: 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":[],"created_at":"2026-01-15T00:23:06.546Z","updated_at":"2026-01-15T00:23:07.310Z","avatar_url":"https://github.com/primait.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Biscuit\n\n[![Build Status](https://travis-ci.org/primait/biscuit.svg)](https://travis-ci.org/primait/biscuit)\n\nBiscuit is a simple key-value store for your infrastructure secrets.\n\n## Is Biscuit right for me?\n\nBiscuit is most useful to teams already using AWS and IAM to manage their \ninfrastructure. If that describes your team, then Biscuit might be useful to \nyou if you answer \"yes\" to any of these questions:\n\n* Do you live in constant fear of accidentally committing infrastructure secrets to source control?\n* Do you commit private keys to your source repository?\n* Do you share passwords with other developers?\n* Do you want to manage secrets securely across multiple regions?\n\n### Features\n\n* Provides a simple key/value CLI to secure storage.\n* Secrets can live alongside with your code in source control.\n* Operates with KMS keys across multiple regions.\n* Facilitates management of AWS IAM Policies, KMS Policies, and KMS Grants across multiple regions.\n* Local encryption using AES-GCM-256 or Secretbox (NaCL).\n* Offline mode: Using the \"testing\" key manager, you can use Biscuit in\n  test environments without changing your code and without network \n  dependencies.\n\n### Feature Comparison\n\n| Package                                             | Requires a server? | Multi-region | HA  | Rotation | Storage  | AWS KMS  | Principals | Web UI |\n|:----------------------------------------------------|:-------------------|:-------------|:----|:---------|:---------|:---------|:-----------|:-------|\n| Biscuit                                             | No                 | Yes          | Yes | No       | File     | Required | AWS Only   | No     |\n| [Credstash](https://github.com/fugue/credstash)     | No                 | No           | Yes | No       | DynamoDB | Required | AWS Only   | No     |\n| [Lyft Confidant](https://github.com/lyft/confidant) | Yes                | No           | No  | No       | DynamoDB | Required | AWS Only   | Yes    |\n| [Hashicorp Vault](https://www.vaultproject.io)      | Yes                | Yes          | Yes | Yes      | Varied   | Optional | Multiple   | No     |\n\n## Quick Start\n\n### Installing\n\n#### Downloading\n\nSee [releases](https://github.com/primait/biscuit/releases) for the latest release.\n\n#### Building from Source\n\nIf you have Golang 1.6+ installed, you can install with:\n\n```\ngo get -v github.com/primait/biscuit\n```\n\n### Setup\n\n```shell\n# Verify that your AWS credentials are readable.\nbiscuit kms get-caller-identity\n\n# Provision a KMS Key w/useful defaults in us-east-1, us-west-1, \n# and us-west-2 and create a secrets.yml file.\nbiscuit kms init -f secrets.yml\n\n# Store the launch codes.\nbiscuit put -f secrets.yml launch_codes 0000\n\n# Decrypt the launch codes.\nbiscuit get -f secrets.yml launch_codes\n```\n\nNext steps: examine `secrets.yml` in your favorite text editor, and run \n`biscuit --help` to learn about additional commands.\n\n### Updating glock deps\n\n```shell\ncd $GOPATH/src\ngo get -u -v ./...\nglock save github.com/primait/biscuit\n```\n\n### Uninstalling\n\nDone already?\n\nThe `biscuit kms init` step above may have created a KMS Key and some\nassociated policies using CloudFormation. You can remove those by\nrunning:\n\n```shell\nbiscuit kms deprovision\nrm secrets.yml\n```\n\nNote: any biscuit files you created before deprovisioning will no longer\nbe readable.\n\n### Glossary\n\nThe **secret** is the plaintext value which you wish to protect.\n\nA **label** is a short alphanumeric string that identifies a set of keys\nacross multiple AWS regions. It is present in CloudFormation stack names\n(`biscuit-label`) and in KMS key aliases (`alias/biscuit-label`).\n\nThe **key manager** is responsible for the provisioning of encryption\nkeys. The encryption keys generated by the key manager are used to\nencrypt the **secret**. An encrypted version of the encryption key -- \ndecryptable only by KMS -- is stored as the **key ciphertext**.\n\nSecret **values** consist of the information necessary for the **key\nmanager** to provide the plaintext encryption key to decrypt a\n**ciphertext** for a named secret. Values consist of a Key ID (a\nstring, meaningful to the key manager), an indicator of which key manager is\nin use (string), an algorithm (string), the key ciphertext (the\nencrypted key, base64), and the ciphertext (base 64). Here is an example\nof a value named `api_key`:\n\n```yaml\napi_key:\n- key_id: arn:aws:kms:us-west-1:123456789012:key/37793df5-ad32-4d06-b19f-bfb95cee4a35\n  key_manager: kms\n  algorithm: secretbox\n  key_ciphertext: CiA3edlKfUWXVgiDDuzbz95S/pkM8grwRsYkjRoURv0LGhKnAQEBAQB4N3nZSn1Fl1YIgw7s28/eUv6ZDPIK8EbGJI0aFEb9CxoAAAB+MHwGCSqGSIb3DQEHBqBvMG0CAQAwaAYJKoZIhvcNAQcBMB4GCWCGSAFlAwQBLjARBAw4OEtFZrisfC3xJHACARCAO+HJpH4bWD/MF9BYjBvl5ztcezTNxo5SPeAOKJ3Z8Pff2vh1uCZhEEjxnF7t1tqTma8oeESuu2vpPiZp\n  ciphertext: YsI/4Qnzpu+Vm+JP4LhnO8Y3dSoz61/vKHBXGVI1pVAUCjMhvjb9ohcdjA==\n```\n\n**Names** identify a value. When using AWS KMS, names are\nencoded into the **encryption context** and must be provided by the\nprocess that decrypts the value.\n\nA key **template** is a special entry in the .yml file which tells the\nbiscuit tool how to handle values that are added to that file. This is\nan example template:\n\n```yaml\n_keys:\n- key_id: arn:aws:kms:us-west-1:123456789012:key/37793df5-ad32-4d06-b19f-bfb95cee4a35\n  key_manager: kms\n  algorithm: secretbox\n- key_id: arn:aws:kms:us-west-2:123456789012:key/c0045b15-9880-4b17-84da-a35760e8a16f\n  key_manager: kms\n  algorithm: secretbox\n- key_id: arn:aws:kms:us-east-1:123456789012:key/d1c5a8e3-adfb-4f79-af0b-cde9f1a31292\n  key_manager: kms\n  algorithm: secretbox\n```\n\n## IAQ\n\n### How much does this cost?\n\nBiscuit requires one key in each region you wish to use. Most users can\nexpect to pay ~$1/mo per region per label, and additional usage charges\nfor heavy users. See\n[AWS Key Management Service Pricing](https://aws.amazon.com/kms/pricing/)\nfor pricing.\n\n### Can I use it in a single AWS region?\n\nYes. Use the `-r` flag or the `BISCUIT_REGIONS` environment variable to specify\nthe region.\n\nExample:\n\n```shell\nbiscuit kms init -r us-west-2 -f secrets.yml\n```\n\n### What do I do with the .yml file after it is created?\n\nThe .yml file is safe for committing to version control, your CI system,\nembedding in native binaries, copying to S3, publishing in a newspaper,\netc. You can deploy these to your production servers by whatever\nmechanism is most appropriate for your environment, but by far the\neasiest way to start is to simply include it in your deployments in the\nsame way you would a configuration file.\n\n### Once I've created a value, how do I let AWS resources decrypt it?\n\nYou can use KMS Grants, KMS Key Policies, or IAM Policies to manage access \nto the secrets.\n\n#### KMS Grants\n\nKMS Grants enable you to delegate access to specific KMS operations to some\nAWS principal. Often your AWS resources will be running with an IAM Role, and \nthus often the easiest thing to do is to use KMS Grants to allow your IAM Roles\nto decrypt the appropriate values.\n\nBiscuit will create and retire those grants for you.\n\nHere's how to grant role/webserver and user/gordon the ability to decrypt the launch codes:\n\n```shell\nbiscuit kms grants create --grantee-principal role/webserver -f secrets.yml launch_codes\nbiscuit kms grants create --grantee-principal user/gordon -f secrets.yml launch_codes\nbiscuit kms grants list -f secrets.yml launch_codes\n```\n\nIf you wish to allow a principal to decrypt all values encrypted under the same set of keys as\nthe launch codes, you can pass the `--all-names` flag:\n\n```shell\nbiscuit kms grants create -g role/webserver -f secrets.yml --all-names launch_codes\n```\n\nYou can also retire grants when they are no longer useful:\n\n```shell\nbiscuit kms grants list -f secrets.yml launch_codes\nbiscuit kms grants retire -f secrets.yml --grant-name biscuit-ff8102edc8 launch_codes\n```\n\nBiscuit manages grants using the KMS [CreateGrant](http://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html),\n[ListGrants](http://docs.aws.amazon.com/kms/latest/APIReference/API_ListGrants.html), and \n[RetireGrant](http://docs.aws.amazon.com/kms/latest/APIReference/API_RetireGrant.html) APIs.\n\n#### KMS Key Policies\n\nKMS Keys have their own policies. See \n[Key Policies](http://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) \nfor more details. If you have just a few users, this is possibly the easiest\nmechanism to use to control access. You can run `biscuit kms edit-key-policy` to \nedit the policy document across all of your regions at once.\n\nBiscuit manages Key Policies using the KMS [GetKeyPolicy](http://docs.aws.amazon.com/kms/latest/APIReference/API_GetKeyPolicy.html) \nand [SetKeyPolicy](http://docs.aws.amazon.com/kms/latest/APIReference/API_SetKeyPolicy.html) APIs.\n\n#### IAM Policies\n\nIAM Policies are attached to a myriad of AWS entities, and they can also be \nused to enable access to KMS operations. See \n[Key Policies](http://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html) for more details.\n\nExample: You have a server running with a static AWS access key and secret key. You can give that\nserver the ability to decrypt all values encrypted under a set of keys by attaching a standard user policy, \nspecifying `kms:Decrypt` as the Action and the full key ARNs in the Resource field.\n\nNote: IAM Policies are global entities, whereas KMS Keys are unique per region. Thus if you have a 3-region \nconfiguration, any IAM Policies that explicitly grant access to KMS Keys will need to list all 3 \nregion-specific key ARNs.\n\nBiscuit does not manage IAM Policies for you. \n\nIf you wish to disallow IAM Policies from controlling access to your keys,\nyou can do so by passing `--disable-iam-policies` to `kms init`. When IAM\nPolicies are disabled, the only way to control access to keys is via Grants and KMS Key \nPolicies. For more information on how this works, see the CloudFormation \ntemplate in the source repository and the Key Policies doc linked above.\n\n### How do I control which AWS region is used to decrypt the values?\n\nEach AWS region has its own isolated KMS instance. This means that KMS keys\nare per-region resources, and using a KMS key requires communicating with the KMS\nservice in the region that holds that key.\n\nWhen encrypting, Biscuit will attempt to encrypt the secrets by using all of\nthe KMS instances corresponding to the regions of the keys it is told to use.\nThis can incur cross-datacenter traffic and is slower than using only the\nclosest region.\n\nWhen decrypting, Biscuit only needs to decrypt under one of the keys. By\ndefault, Biscuit will prioritize using keys that are in the same region that\nthe caller is in. This is determined by the `AWS_REGION` environment variable.\nIf you do not have an `AWS_REGION` variable set, Biscuit will process keys in\nthe order that they appear in the .yaml file.\n\nYou can override this behavior by passing a `--aws-region-priority` flag to the\n`get` or `export` operations. Here is an example invocation which prioritizes\nkeys in ap-north-1 and us-west-2:\n\n```shell\nbiscuit get --aws-region-priority ap-north-1,us-west-2 -f secrets.yml launch_codes\n```\n\nWe recommend you make arrangements on your EC2 instances to either set the\n`AWS_REGION` flag, or pass a latency-ordered list of regions via the\n`--aws-region-priority` flag.\n\n\n### How do I keep my development and production keys separate?\n \nBiscuit tracks keys across regions by using a label. Labels are embedded \ninto the name of the CloudFormation stack and a KMS Key Alias in each region. \nThe default behavior is to use the `default` label, but you can change this \nby passing the `-l` flag. Example: `biscuit kms init -l development`\n \nLabels are not persisted with the values and are not visible in the .yml \nfiles. They are an organizational tool to facilitate managing keys across \nregions, and are passed as parameters to various commands.\n\nHere are some common scenarios:\n\n```shell\n# Create key in a single-region, and allow developers to do whatever they want. \nbiscuit kms init -r us-west-2 -l development -f development.yml --administrators role/developers --users role/developers\nbiscuit put -f development.yml ssl_key -i selfsigned.key\n\n# Create keys in three regions, and allow a limited set of people to administer it,\n# and allow developers (and gordon) to read and write the secrets.\nbiscuit kms init -l production -f production.yml --administrators role/prod-keymaster --users role/developers,user/gordon\nbiscuit put -f production.yml ssl_key -i wildcard.key\n\n# Create a file that doesn't use encryption at all.\nbiscuit put -f unittest.yml -a none database_password testing\n```\n\n### What's the difference between an \"administrator\" and a \"user\"?\n\nBiscuit installs a KMS Key Policy similar to the default policy \nrecommended by AWS. This creates a distinction between \n[\"administrators\"](http://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default-allow-administrators) \nand [\"users\"](http://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html#key-policy-default-allow-users).\n\nAdministrators can administer the key but not necessarily encrypt or decrypt \nwith that key. They could, if they wished, replace the key policy with one \nthat does allow them encrypt and decrypt, but that would be unusual.\n\nUsers can encrypt, decrypt, and generate ephemeral data keys. In most \ncases, you'll want to make your development team a \"user\" and \npossibly also \"administrators\". \n\nIf you use `biscuit kms init` to create your keys, you can use the \n`--administrators` and `--users` flag to set membership. If you have already\ncreated the keys but want to change the policy, use the interactive\n`biscuit kms edit-key-policy` to apply changes to all regions simultaneously.\n\n### What is the minimum IAM Policy needed to run `kms init`?\n\nThe IAM Policy below is the smallest set of permissions needed to get\nstarted with Biscuit using `kms init`. Be sure to replace the account \nnumber `123456789012` with your own.\n\n```json\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"AllowKmsListAliasesAndCreateKey\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"kms:ListAliases\",\n                \"kms:CreateKey\"\n            ],\n            \"Resource\": [\n                \"*\"\n            ]\n        },\n        {\n            \"Sid\": \"AllowKmsCreateAlias\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"kms:CreateAlias\"\n            ],\n            \"Resource\": [\n                \"arn:aws:kms:*:123456789012:alias/biscuit-*\"\n            ]\n        },\n        {\n            \"Sid\": \"AllowKmsDeleteAlias\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"kms:DeleteAlias\"\n            ],\n            \"Resource\": [\n                \"arn:aws:kms:*:123456789012:alias/biscuit-*\"\n            ]\n        },\n        {\n            \"Sid\": \"AllowCloudFormationCreate\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"cloudformation:DescribeStacks\",\n                \"cloudformation:CreateStack\",\n                \"cloudformation:DeleteStack\"\n            ],\n            \"Resource\": [\n                \"arn:aws:cloudformation:*:123456789012:stack/biscuit-*\"\n            ]\n        },\n        {\n            \"Sid\": \"AllowCloudFormationDelete\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"cloudformation:DeleteStack\"\n            ],\n            \"Resource\": [\n                \"arn:aws:cloudformation:*:123456789012:stack/biscuit-*\"\n            ]\n        }\n    ]\n}\n```\n\n### Does Biscuit support multi-factor authentication?\n\nYes. IAM Policies and the KMS Key Policies support the `aws:MultiFactorAuthPresent` condition.\n\nBiscuit does not enforce any access control on its own. All enforcement is\nimplemented by AWS. Any features that are available in the IAM Policies, KMS Key \nPolicy documents, or KMS Grants are available to you. \n\nBiscuit does not expose command line flags to use all of the features, but you \ncan edit the various policies after they are created, or override the default \nCloudFormation template.\n\nBiscuit is known to work well with [awsmfa](https://pypi.python.org/pypi/awsmfa).\n\n### I manually edited the .yaml file and changed the name of a value and now it won't decrypt. What's wrong?\n\nThe `kms` key manager annotates the ciphertext with an\n[EncryptionContext](http://docs.aws.amazon.com/kms/latest/developerguide/encryption-context.html)\ncontaining the name of the value. If you change the name of a value,\nthen the decrypting process will provide the wrong name to the decrypt\noperation and the decrypt will fail. If you wish to change the name of a\nsecret, re-encrypt it using the new name instead.\n\n### I want to change something about the CloudFormation template. What do I do?\n\nThe `biscuit kms init` command allows you to override the built-in\nCloudFormation template with your own via the\n`--cloudformation-template-url` parameter. \n\n### My account administrator does not let me create CloudFormation stacks, help!\n\nThe only expectations that Biscuit has about your KMS configuration is that the \nkeys have aliases of the form `alias/biscuit-{label}` and that you have sufficient \npermissions to operate on the KMS keys. You can create the keys using whatever\nprocess is compatible with your organization's policies.\n\n### How do I rotate the values?\n\nBiscuit considers the rotation of secrets (such as database passwords)\nto be application-specific features and thus does not have any native\nsupport for it. However, you can\nimplement a rotation scheme appropriate for your situation simply by\nserializing that state as the secret and then read it with your \napplication-specific rotation behaviors. \n\nHere is an example using JSON and [jq](https://stedolan.github.io/jq/):\n\n```shell\nbiscuit put -f secrets.yml database_passwords '{\"1\": \"pass1\", \"2\": \"pass2\"}'\nbiscuit get -f secrets.yml database_passwords | jq -r '.[to_entries | map(.key) | map(tonumber) | max | tostring]'\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimait%2Fbiscuit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprimait%2Fbiscuit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprimait%2Fbiscuit/lists"}