cottage v0.6.7 — A modern git based age-encrypted secrets manager for teams.

Le logo cottage

cottage est un outil GitOps permettant aux équipes de gérer des secrets chiffrés avec age dans des dépôts git.

Il fournit un workflow simple pour chiffrer/déchiffrer des secrets, gérer les destinataires et garder les secrets hors du dépôt tout en permettant un partage facile via un VCS. cottage génère également des aperçus expurgés des secrets chiffrés pour une meilleure visibilité et prend en charge les workflows de déchiffrement persistants et temporaires, tout en garantissant que les secrets ne sont jamais commités en clair.

Démo d'introduction

Fonctionnalités
Installation
Intégrations d'éditeurs
Intégrations d'agents IA
Démarrage rapide
GitOps
Hooks Git
Contrôle d'accès
1. Règles
2. Vérification
N'importe quel fournisseur comme upstream
1. Plugins d'exemple
Synchronisation avec n'importe quel appareil
En savoir plus
Dépannage
Comparaison

Fonctionnalités

Sûr face à l'exposition : Utilise le système de types de Rust pour garantir que les bugs ne puissent jamais exposer accidentellement des secrets.
Adapté aux équipes : Partagez les clés publiques (destinataires) dans le dépôt, gardez les clés privées (identités) en local.
Contrôle d'accès : Règles simples d'autorisation/refus pour contrôler quels secrets sont chiffrés pour quels destinataires.
Gère .gitignore : Met automatiquement à jour .gitignore pour garder les secrets non chiffrés hors du dépôt.
Aperçus : Génère des aperçus expurgés horodatés des secrets chiffrés pour une meilleure visibilité.
Diffs riches : Garde les diffs git propres et faciles à relire, tandis que ctg diff affiche le diff des secrets modifiés localement avec leurs équivalents chiffrés suivis.
Vérification par somme de contrôle : Empêche toute altération en vérifiant que les secrets chiffrés et les listes de destinataires correspondent aux métadonnées.
Hooks Git : Configurez facilement des hooks git pour vérifier/chiffrer automatiquement les secrets avant commit et les déchiffrer après checkout.
Workflow de secrets persistants : ctg decrypt/sync conserve les secrets déchiffrés sur le disque.
Cycle de nettoyage intelligent : ctg run (raccourci ctgx) et ctg edit déchiffrent les secrets avant l'opération, les conservant sur le disque s'ils étaient déjà présents au préalable ou les nettoyant automatiquement ensuite s'ils ne l'étaient pas.
Nettoyage à la fin : ctg encrypt --clean, ctg run --clean et ctg edit --clean garantissent que les fichiers déchiffrés sont nettoyés du disque même s'ils étaient présents au préalable.
Workflow d'injection d'environnement : ctg env injecte les secrets déchiffrés comme variables d'environnement pour exécuter une commande, sans jamais les écrire sur le disque.
Pipe sécurisé de secrets : ctg cat PATH déchiffre en mémoire et affiche sur stdout pour un pipe direct vers stdin d'autres outils.
Nettoyage : ctg clean supprime tous les secrets déchiffrés du dépôt local pour vous permettre d'exécuter vos agents IA avec un peu moins d'inquiétude.
Prend en charge jj et les répertoires non-git : ctg init transforme n'importe quel répertoire en coffre de secrets.
Synchronisation avec n'importe quel fournisseur : Permet de configurer n'importe quel fournisseur disposant d'une API comme upstream, et d'utiliser ctg pull/diff/push comme git pull/diff/push.
Synchronisation avec n'importe quel appareil : Les secrets chiffrés avec cottage et gérés dans un dépôt git peuvent être synchronisés entre appareils avec Cottage Sync.

Installation

# rust: cargo-binstall/cargo
cargo binstall --locked cottage
cargo install --locked cottage

# python: pip/uv/uvx
pip install cottage
uv pip install cottage
uvx --from cottage ctg --version

# node: yarn/pnpm/npx
yarn global add @sayanarijit/cottage
pnpm add -g @sayanarijit/cottage
npx -p @sayanarijit/cottage ctg --version

Également disponible sous forme d'images docker :

# Docker
docker run --rm -v $PWD:/app sayanarijit/cottage --version

# Podman
podman run --rm -v $PWD:/app quay.io/sayanarijit/cottage --version

Ou téléchargez la dernière version depuis GitHub.

Intégrations d'éditeurs

Extension VS Code

Utilisez l'extension Cottage pour VS Code pour installer ctg, ajouter des hooks de sécurité Copilot, chiffrer des fichiers depuis l'Explorateur et ouvrir les fichiers .cott.age via le workflow de l'éditeur.

Installez-la depuis le Visual Studio Marketplace, ou compilez et installez-la localement depuis vscode-plugin-cottage.

Extension Cursor et Eclipse

Téléchargez le fichier VSX et installez-le dans votre IDE Cursor ou Eclipse. Il fonctionne de manière similaire à l'extension VS Code.

Plugin Vim

Utilisez le plugin cottage.vim pour chiffrer/déchiffrer des secrets depuis Vim ou Neovim.

Intégrations d'agents IA

Toutes les intégrations ci-dessous empêchent les agents IA d'exécuter directement ctg/ctgx et de consulter ou modifier les fichiers de secrets : tout ce qui se trouve dans .cottage/, tout fichier *.cott.* (blobs chiffrés *.cott.age et aperçus expurgés *.cott.toml), et tout fichier déchiffré qui possède encore un équivalent *.cott.age sur le disque.

Intégration Claude Code

Si vous utilisez Claude Code, ajoutez .claude/settings.json et .claude/hooks/deny-secrets.py à vos dépôts contenant des secrets afin que les sessions Claude Code manipulent les secrets en toute sécurité, ou installez le plugin claude-plugin-cottage.

Intégration GitHub Copilot

Si vous utilisez GitHub Copilot dans VS Code, ajoutez .github/hooks/ctg-policy.json et .github/hooks/scripts/deny_ctg_command.py à vos dépôts contenant des secrets afin que les sessions Copilot nettoient les fichiers déchiffrés, bloquent les commandes shell ctg directes et bloquent l'accès aux fichiers de secrets, ou installez l'extension vscode-plugin-cottage pour configurer cela depuis VS Code.

VS Code charge également les définitions de hooks de .claude/settings.json. Si vous conservez à la fois les fichiers de hooks Claude et Copilot dans le même dépôt, assurez-vous de ne pas exécuter accidentellement le même hook de nettoyage deux fois.

Intégration Codex

Si vous utilisez Codex, ajoutez .codex/hooks.json et .codex/hooks/deny-ctg.py à vos dépôts contenant des secrets afin que les sessions Codex manipulent les secrets en toute sécurité, ou installez le plugin codex-plugin-cottage.

Codex exige que les hooks locaux soient examinés avant leur exécution. Après avoir ajouté les fichiers, démarrez Codex dans le dépôt et utilisez /hooks pour examiner et approuver les hooks du projet.

Intégration Antigravity (agy)

Si vous utilisez Antigravity (agy), ajoutez .agents/hooks.json et .agents/scripts/deny-ctg.py à vos dépôts contenant des secrets afin que les sessions Antigravity manipulent les secrets en toute sécurité, ou installez le plugin agy-plugin-cottage.

Intégration Cursor

Si vous utilisez Cursor, ajoutez .cursor/hooks.json, .cursor/hooks/deny-ctg.py, .cursor/hooks/deny-read-secrets.py, .cursor/rules/deny-ctg.mdc et .cursorignore à vos dépôts contenant des secrets afin que les sessions Cursor manipulent les secrets en toute sécurité.

Cursor exige que les hooks soient d'abord activés. Ouvrez Cursor Settings > Hooks et activez les hooks, puis redémarrez la session de l'agent pour que les hooks du projet prennent effet. .cursorignore empêche en outre les fichiers de secrets d'être indexés par Cursor et d'apparaître dans le contexte de l'Agent.

Démarrage rapide

Initialiser le projet :

mkdir project && cd project

git init  # Optional, cottage works better with git but it's not required
ctg init  # Sets up the .cottage directory and necessary files

tree -a
# .
# ├ .cottage/           <- Auto-generated by `ctg init`
# │ ├ identity        <- Your private key, keep it safe. Move it to `~/.config/cottage/identity` to use it globally, or replace it with a soft link to one of your existing private keys.
# │ └ recipients/     <- This is where your team keeps the public keys of all the recipients.
# │     └ sayanarijit <- Your public key. Commit it. To use an existing public key, just copy (don't softlink) that key here.
# ├ .git/...
# ├ .gitattributes      <- Added `*.cott.age binary linguist-generated filter=cottage-encrypted -diff` to avoid polluting git diff
# └ .gitignore          <- Added `/.cottage/identity` for obvious reasons

# You can run `ctg clean --all` anytime to clean up everything cottage ever did.

Créer ou modifier un secret :

# `ctg edit` decrypts the file before opening in $EDITOR and re-encrypts upon save.
# If the decrypted file was not present on disk before running `ctg edit`, it is cleaned up afterwards.
# If it was already present, it is kept on disk.
ctg edit secret.yml

# Use `--clean` with `ctg edit` or `ctg encrypt` to ensure decrypted files are deleted even if present before
ctg edit secret.yml --clean    # Opens in $EDITOR, encrypts on save, and cleans up
ctg encrypt secret.yml --clean # Encrypts secret.yml and cleans up
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml
#    edit .gitignore
# delete secret.yml

Exécuter une commande avec des secrets déchiffrés :

cat secret.yml
# cat: secret.yml: No such file or directory

# `ctg run` (or shortcut `ctgx`) decrypts secrets before running the command.
# If the decrypted files were not present on disk beforehand, they are automatically cleaned up after the command finishes.
# If they were already present beforehand, they are kept on disk.
ctg run -- kubectl apply -f secret.yml          # decrypts secret.yml.cott.age to secret.yml and runs the command
ctg run -- kubectl apply -f secret.yml.cott.age # also replaces the path argument with the decrypted file path
ctg run -- kubectl apply -f .                   # decrypts all .cott.age files in . and runs the command
ctg run -- ./deploy.sh                          # decrypts all .cott.age files in repo and runs the command

cat secret.yml
# cat: secret.yml: No such file or directory

# Use `--clean` to ensure decrypted files are cleaned up even if they were present before
ctg run --clean ./deploy.sh

Ou utilisez le raccourci :

ctgx -- ./deploy.sh
ctgx --clean -- ./deploy.sh

Lire et piper un secret déchiffré sans l'écrire sur le disque :

ctg cat secret.yml.cott.age
ctg cat secret.yml | kubectl apply -f -
ctg cat .env.prod | docker run --rm --env-file /dev/stdin my-image:latest

Exécuter une commande avec des secrets injectés comme variables d'environnement, sans jamais écrire sur le disque :

ctg env -- ./deploy.sh # Export secrets from .env.cott.age (default) without writing them to disk, then run deploy.sh
ctg env -F .env.prod.cott.age -- ./deploy.sh # exports from .env.prod.cott.age instead of .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # Also supports non-dotenv files.

GitOps

Pour partager vos secrets avec les membres de l'équipe, poussez simplement vers le dépôt git.

git add .
git commit -m "Add secret.yml"
git push origin main

Demandez à vos coéquipiers d'ajouter leurs clés publiques dans .cottage/recipients et de pousser les changements. Vous pourrez ensuite tirer et rechiffrer les secrets pour eux.

git pull origin main

ctg decrypt --skip-verify-recipients  # Decrypt missing secrets for re-encryption
ctg encrypt                           # Re-encrypt all secrets
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml

ctg clean  # optional
# delete secret.yml

# review changes, commit and push
git add .
git commit -m "Add new recipient to secrets"
git push origin main

Vos coéquipiers peuvent maintenant tirer les derniers changements et déchiffrer les secrets pour eux-mêmes.

Hooks Git

Vous pouvez utiliser prek ou pre-commit pour configurer des hooks git afin de vérifier/chiffrer automatiquement les secrets avant commit et de les déchiffrer après checkout.

Voir l'exemple de configuration prek ici.

Après avoir ajouté le fichier prek.toml, exécutez :

prek install
prek install --hook-type post-checkout
prek install --hook-type post-merge
prek install --hook-type post-rewrite

Contrôle d'accès

Règles

Dans le fichier de métadonnées, vous pouvez indiquer pour quels destinataires le secret doit être chiffré. Cela vous permet d'avoir différents secrets pour différents environnements (par ex. staging vs production) et de ne les chiffrer que pour les destinataires concernés.

# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"]  # Only encrypt for sayanarijit

# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # Encrypt for everyone except sayanarijit

# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # Supports glob patterns, only encrypt for recipients in env/staging
deny = ["env/staging/badservice"]  # Encrypt for everyone in env/staging except badservice

Les règles de refus ont la priorité sur les règles d'autorisation.

Voir la spécification des métadonnées pour plus de détails.

Vérification

Vous pouvez exécuter ctg verify en CI pour vérifier que les secrets chiffrés et les listes de destinataires correspondent aux règles des métadonnées, afin de prévenir toute altération.

# .github/workflows/cottage-verify.yml
name: Cottage Verify
on: [push, pull_request]
permissions:
  contents: read
jobs:
  verify-secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Verify secrets
        run: docker run --rm -v "${{ github.workspace }}:/app" ghcr.io/sayanarijit/cottage verify

N'importe quel fournisseur comme upstream

Avec cottage, vous pouvez synchroniser des secrets avec n'importe quel fournisseur disposant d'une API, pas seulement git.

Pour cela, créez un fichier nommé cottage.toml à la racine du projet et configurez les paramètres upstream.

Voir l'exemple de cottage.toml ici et la configuration upstream spécifique aux secrets ici.

Voir un exemple d'implémentation de plugin ici.

Le workflow est similaire à git, mais au lieu de git pull et git push, vous exécutez ctg pull et ctg push pour synchroniser les secrets avec l'upstream configuré.

Exemple :

# Pull latest changes into local encrypted secrets
# Similar to `git pull origin`
ctg pull myvault

# Compare diff with local decrypted secrets
ctg diff

# Sync local decrypted secrets with local encrypted secrets
ctg sync

# Push changes from local encrypted secrets to upstream
# Similar to `git push origin main`
ctg push myvault

Voir la spécification de configuration upstream pour plus de détails.

Plugins d'exemple

Cottage prend en charge divers fournisseurs de plugins pour synchroniser vos secrets. Des scripts de plugins prêts à l'emploi sont disponibles dans le répertoire examples/plugins :

1Password
AWS Secrets Manager
Azure Key Vault
Bitwarden
Dashlane
Doppler
ejson
GitHub Secrets
Google Cloud Secret Manager
HashiCorp Vault (voir aussi Vault in Kubernetes)
Keeper Security
KeePass (Passhole)
LastPass
pass (password-store)
Proton Pass
System Keyring
Zoho Vault

Synchronisation avec n'importe quel appareil

Utilisez Cottage Sync pour synchroniser vos secrets entre vos appareils et les parcourir sans avoir besoin de la CLI.

En savoir plus

Voir le répertoire examples pour plus d'exemples d'utilisation.

Dépannage

# See debug logs with -v, -vv or -vvv
ctg run -vvv -- ./deploy.sh

Comparaison

age vs autres chiffrements

age utilise un algorithme moderne et simple optimisé pour le chiffrement sécurisé de fichiers, avec un accent sur la facilité d'utilisation et une surface d'attaque minimale. Il prend également en charge les clés SSH RSA et Ed25519, bien qu'il soit recommandé d'utiliser des clés différentes pour des usages et périmètres distincts.

cottage vs SOPS

Bien que SOPS et cottage partagent de nombreuses fonctionnalités, cottage présente les avantages suivants :

Gestion automatique du .gitignore pour garantir que les secrets non chiffrés ne soient jamais commités dans git.
Les secrets chiffrés étant de purs fichiers .age chiffrés avec age, cela permet une meilleure interopérabilité avec un écosystème d'outils plus large.
Des diffs plus propres - contrairement à SOPS, qui génère des diffs pour chaque valeur de chaque secret, même si le changement réel n'est que l'ajout/la suppression d'un destinataire, cottage ne génère qu'un seul diff par fichier, en pointant explicitement le changement dans la somme de contrôle des destinataires.

cottage vs dotenvx

cottage emprunte l'API ctg env à dotenvx.

Prend en charge n'importe quel type de fichier, pas seulement les fichiers dotenv.
Gère plusieurs secrets dans un dépôt.
Règles de contrôle d'accès pour chiffrer les secrets pour des destinataires spécifiques.
Des diffs plus propres - voir cottage vs SOPS.

cottage vs agebox

agebox est très similaire à cottage dans sa philosophie de base mais il lui manque de nombreuses fonctionnalités.

Lire plus