pegase 0.2.0

Cli to generate secret config files from yaml recipe
Documentation
# 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
```