# PEGASE
> PleasE Generate A Secret Easily
[![Build Status]][actions]
[![Dependencies Status]][deps.rs]
[![Docs Status]][docs.rs]
[![Latest Version]][crates.io]
[![Licence]](LICENCE)
[Build Status]: https://codeberg.org/CorentinGuillerme/pegase/badges/workflows/pr.yaml/badge.svg?label=build
[actions]: https://codeberg.org/CorentinGuillerme/pegase/actions
[Dependencies Status]: https://img.shields.io/deps-rs/pegase/latest
[deps.rs]: https://deps.rs/crate/pegase
[Docs Status]: https://img.shields.io/docsrs/pegase
[docs.rs]: https://docs.rs/crate/pegase
[Latest Version]: https://img.shields.io/crates/v/pegase
[crates.io]: https://crates.io/crates/pegase
[Licence]: https://img.shields.io/crates/l/pegase
Cli to generate secret config files from yaml recipe
It can generate encrypted files using [SOPS](https://github.com/getsops/sops)
The goal is to simplify the generation of secrets inside config files and avoid generating them manually
## Usage
```bash
pegase <recipe.yaml>
```
## Recipe format
The input recipe is a YAML file with a top-level `files` list. Each entry must include:
- `path`: the target output file path
- `content`: a secret generation tree
- `format`: (optional) format of the output file (`env`, `json`, `toml`, `yaml`), use file extension if not set
- `sops`: (optional) SOPS configuration (see [#SOPS](#sops))
Example recipe:
```yaml
files:
- path: "aa.yaml"
content:
my_key:
generator: pass
charset: hex
at_least_bits: 128
my_hosts:
host_a: pass
host_b: hash
```
generates
```yaml
my_hosts:
host_a: d7KR5hrh6NVVnL4CqrrKtiFtWsEPGi99jt89p6SK
host_b:
plain: G8mKrPSCrEEGi3UgJCJINeQzZW7mC87THohO77Zw
hash: >-
$argon2id$v=19$m=19456,t=2,p=1$kEoot3ENxhTKjviPED2QXA$sSsefTbkUifpjZEezmhn6tJ2WbIZRHv2fh48/Tk99FA
my_key: 2384A66C4BF4E379DB5469BC16E5947A
```
(See other examples in tests/recipes)
The format supports YAML anchors and aliases:
```yaml
_: &token
generator: pass
charset: hex
at_least_bits: 256
files:
- path: "aa.yaml"
content:
my_key: *token
my_hosts:
host_a: *token
host_b: *token
```
## Supported generators
Generator can have long or short form
Short form:
```yaml
my_key: pass
```
Long form:
```yaml
my_key:
generator: pass
charset: hex
length: 32
```
(generator is a reserved keyword)
### `pass`
Generates a password-like secret string.
Configuration options:
- `length`: fixed output length (optional, defaults to `40`, cannot be used with `at_least_bits`)
- `at_least_bits`: minimum entropy in bits (optional, cannot be used with `length`)
- `charset`: (optional, defaults to `alnum`) one of:
- `num`
- `hex`
- `alnum`
- `rfc3986`
- `alnumspec`
- `custom`: a string of length >=2 containing unique characters
### `ssh`
Generates a ssh key (private and public keys).
Configuration options:
- `kind`: (optional, defaults to `ed25519`) one of:
- `rsa`
- `ed25519`
- `bits`: size in bits of the key (rsa only, optional, defaults to `4096`)
### `hash`
Generates a password-like secret string and its hash.
Configuration options:
- `kind`: (optional, defaults to `argon2`) one of:
- `argon2`
- `pbkdf2`
- `yescrypt` / `linux_passwd`
- `length`: fixed output length (optional, defaults to `40`, cannot be used with `at_least_bits`)
- `at_least_bits`: minimum entropy in bits (optional, cannot be used with `length`)
- `charset`: (optional, defaults to `alnum`) one of:
- `num`
- `hex`
- `alnum`
- `rfc3986`
- `alnumspec`
- `custom`: a string of length >=2 containing unique characters
Each hash kind have specific additional options:
argon2:
- `params`: (optional, defaults to recommanded parameters)
- `m_cost`
- `t_cost`
- `p_cost`
pbkdf2:
- `params`: (optional, defaults to recommanded parameters)
- `rounds`
yescrypt / linux_passwd:
- `params`: (optional, defaults to recommanded parameters)
- `n_cost`
- `r_cost`
- `p_cost`
## References
References allows to share secrets or parts of secrets across multiple files.
Exemple :
```yaml
shared:
my_key: ssh
a_group_of_secrets:
secret1: pass
secret2: hash
secret3: ssh
files:
- path: "public.yaml"
content:
my_key:
ref: my_key.public
- path: "private.yaml"
content:
my_key:
ref: my_key.private
my_secrets:
ref: a_group_of_secrets
- path: "private_bis.yaml"
content:
my_secrets:
ref: a_group_of_secrets
```
## SOPS
> [!IMPORTANT]
> SOPS must be installed
>
The SOPS options are :
- `enable`: (defaults to `false`) enable encryption with sops,
- `kms`: (optional) list of KMS ARNs,
- `aws_profile`: (optional) The AWS profile to use for requests to AWS,
- `age`: (optional) list of age recipients,
- `pgp`: (optional) list of PGP fingerprints,
- `gcp_kms`: (optional) list of GCP KMS resource IDs,
- `hckms`: (optional) list of HuaweiCloud KMS key IDs,
- `azure_keyvault`: (optional) list of Azure Key Vault URLs,
- `hc_vault_transit`: (optional) list of vault's key URI,
- `shamir_threshold`: (optional) the number of master keys required to retrieve the data key with shamir,
- `unencrypted_suffix`: (optional) override the unencrypted key suffix,
- `encrypted_suffix`: (optional) override the encrypted key suffix,
- `unencrypted_regex`: (optional) set the unencrypted key regex,
- `encrypted_regex`: (optional) set the encrypted key regex,
(see SOPS documentation for more details)
Recipe example with SOPS enabled:
```yaml
files:
- path: "aa.yaml"
sops:
enable: true
age:
- age1cspxn98ah526gd886g55u7dakrdjuljmsf4ervalav3kfqrwv3js5w5405
content:
my_key:
generator: pass
charset: hex
at_least_bits: 128
my_hosts:
host_a: pass
host_b: pass
```
generates
```yaml
my_hosts:
host_a: ENC[AES256_GCM,data:GE9wG6En2TUgbQdt0QkjzYlLIUIoyuFq75tZeEKff1iaKPPN4e2I3g==,iv:TGVFla1I4eZoPLG1XOqNQh8j/PpUoPNQUANPHW6DdXg=,tag:R+eYsoCy6V/ga4yqsPQapg==,type:str]
host_b: ENC[AES256_GCM,data:BWXUMyYzE6KlpnPKiqqxHvbKpV/pbz+9SD7jzUGGdtqtty5pCaZQ7g==,iv:Wk9ucQEbh/siYuy9LzCvZhKABMaLGGNbhM+z1pEqqmk=,tag:LXCaR0ipiPrdrD3WOiPdHw==,type:str]
my_key: ENC[AES256_GCM,data:CkgqWXxmkRjEXHnRKgWaDsaRG6xX+UD2AyrH1HYpURg=,iv:7DOxIAXPO2F1ZryTgu9dHDHhHn4smoSTO2s8hm+G95M=,tag:RERLG6sJeEUXBL2dZsmYwg==,type:str]
sops:
age:
- enc: |
-----BEGIN AGE ENCRYPTED FILE-----
YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA2NDU2ZDFMdTNjbXZkUkFo
STZCdjMrRjBYamR5aW8rQUxoZGZuSTNwUlFvCklkM2FaRnZkREZNbURUQ0JuRWk3
KzloUVhjejE4L0dJVEVTUzhqa1BxL2cKLS0tIHNsRTNzcG1vYkZ5bHEvTnA5aEF2
VktTb2N4SVZmWUlJTWdoSTNUcEo0cHcK9nb65gP0RPo3L3d/aH0w/COysf/HIKxf
9F6SR+2dyoNLhmCEK7jSBZVXYY9istjXrnq1LJZiKEFg2qk8biZEsQ==
-----END AGE ENCRYPTED FILE-----
recipient: age1cspxn98ah526gd886g55u7dakrdjuljmsf4ervalav3kfqrwv3js5w5405
lastmodified: "2026-08-08T16:41:49Z"
mac: ENC[AES256_GCM,data:MaFbkJXwK6O5ARH7Sdtv3jDGnYjkDltFpV0DSGNhv4SmOnTy/7puOaHhixB2BoJPANvu1PXr6iwCJEYo07jeBULtv9azV66lOo/u3oCesj3VgvBtQ5XXU2yEP/9ewrYermbKtz5TDGUI/axjWw30Z+olifGC8fIZerNEqkiEMp8=,iv:YAE9gGmgsXNiBAfk1R0gY01dHLmU4vhSwDETVsGtHKM=,tag:aTmGGtjlj59OUfTGZ8O14w==,type:str]
unencrypted_suffix: _unencrypted
version: 3.13.1
```