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

The cottage logo

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 flux de travail 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 le VCS. cottage génère également des aperçus expurgés des secrets chiffrés pour une meilleure visibilité et prend en charge les flux de travail de déchiffrement persistants et temporaires, tout en garantissant que les secrets ne sont jamais commités en clair.

Intro Demo

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

Fonctionnalités

Sûr contre les expositions: Utilise le système de types de Rust pour garantir que les bogues ne peuvent jamais exposer accidentellement des secrets.
Adapté aux équipes: Partagez les clés publiques (destinataires) dans le dépôt, conservez les clés privées (identités) en local.
Contrôle d'accès: Des 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 le git diff propre et reviewable, tandis que ctg diff affiche le diff des secrets modifiés localement avec leurs contreparties chiffrées suivies.
Vérification des sommes de contrôle: Empêche la falsification en vérifiant que les secrets chiffrés et les listes de destinataires correspondent aux métadonnées.
Git hooks: Configurez facilement des git hooks pour vérifier/chiffrer automatiquement les secrets avant le commit et les déchiffrer après le checkout.
Flux de travail des secrets persistants: ctg decrypt/edit/sync conserve les secrets déchiffrés sur le disque.
Flux de travail des secrets temporaires: ctg run (raccourci ctgx) déchiffre temporairement les secrets pour exécuter une commande, puis les supprime quel que soit le succès ou l'échec de la commande.
Flux de travail d'injection d'environnement: ctg env injecte les secrets déchiffrés comme variables d'environnement pour exécuter une commande, sans les écrire sur le disque du tout.
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 un coffre-fort de secrets.
Synchronisation avec n'importe quel fournisseur: Permet de configurer n'importe quel fournisseur avec 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 en 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 éditeur

Extension VS Code

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

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

Intégrations d'agents IA

Toutes les intégrations ci-dessous empêchent les agents IA d'exécuter ctg/ctgx directement 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 a encore une contrepartie *.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 directes ctg 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 les fichiers de hooks Claude et Copilot dans le même dépôt, assurez-vous de ne pas exécuter accidentellement deux fois le même hook de nettoyage.

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 de s'exécuter. 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 activés au préalable. 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'entrer dans le contexte de l'Agent.

Démarrage rapide

Initialiser le projet :

mkdir project && cd project

git init  # Facultatif, cottage fonctionne mieux avec git mais ce n'est pas requis
ctg init  # Configure le répertoire .cottage et les fichiers nécessaires

tree -a
# .
# ├ .cottage/           <- Généré automatiquement par `ctg init`
# │ ├ identity        <- Votre clé privée, conservez-la en lieu sûr. Déplacez-la vers `~/.config/cottage/identity` pour l'utiliser globalement, ou remplacez-la par un lien symbolique vers l'une de vos clés privées existantes.
# │ └ recipients/     <- C'est ici que votre équipe conserve les clés publiques de tous les destinataires.
# │     └ sayanarijit <- Votre clé publique. Commitez-la. Pour utiliser une clé publique existante, copiez simplement (ne créez pas de lien symbolique) cette clé ici.
# ├ .git/...
# ├ .gitattributes      <- Ajout de `*.cott.age binary export-ignore filter=cottage-encrypted -diff` pour éviter de polluer le git diff
# └ .gitignore          <- Ajout de `/.cottage/identity` pour des raisons évidentes

# Vous pouvez exécuter `ctg clean --all` à tout moment pour nettoyer tout ce que cottage a pu faire.

Créer ou modifier un secret.

ctg edit secret.yml --clean    # Ouvre secret.yml dans $EDITOR
ctg encrypt secret.yml --clean # Autre façon de chiffrer des secrets
# 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 temporairement :

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

ctg run kubectl apply -f secret.yml          # déchiffre secret.yml.cott.age vers secret.yml et exécute la commande
ctg run kubectl apply -f secret.yml.cott.age # remplace également l'argument du chemin par le chemin du fichier déchiffré
ctg run kubectl apply -f .                   # déchiffre tous les fichiers .cott.age dans . et exécute la commande
ctg run ./deploy.sh                          # déchiffre tous les fichiers .cott.age du dépôt et exécute la commande

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

Ou utilisez le raccourci :

ctgx ./deploy.sh  # identique à ctg run -- ./deploy.sh

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

ctg env -- ./deploy.sh # Exporte les secrets de .env.cott.age (par défaut) sans les écrire sur le disque, puis exécute deploy.sh
ctg env -F .env.prod.cott.age -- ./deploy.sh # exporte depuis .env.prod.cott.age au lieu de .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # Prend également en charge les fichiers non-dotenv.

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 modifications. Ensuite, vous pouvez tirer et rechiffrer les secrets pour eux.

git pull origin main

ctg sync  # ou `ctg decrypt && ctg encrypt`
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml

ctg clean  # facultatif
# delete secret.yml

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

Maintenant, vos coéquipiers peuvent tirer les dernières modifications et déchiffrer les secrets eux-mêmes.

Git Hooks

Vous pouvez utiliser prek ou pre-commit pour configurer des git hooks afin de vérifier/chiffrer automatiquement les secrets avant le commit et de les déchiffrer après le 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 annoter pour quels destinataires le secret doit être chiffré. Cela vous permet d'avoir différents secrets pour différents environnements (par exemple staging vs production) et de ne les chiffrer que pour les destinataires concernés.

# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"]  # Ne chiffrer que pour sayanarijit

# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # Chiffrer pour tout le monde sauf sayanarijit

# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # Prend en charge les motifs glob, ne chiffrer que pour les destinataires dans env/staging
deny = ["env/staging/badservice"]  # Chiffrer pour tout le monde dans env/staging sauf badservice

Les règles de refus priment sur les règles d'autorisation.

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

Vérification

Vous pouvez exécuter ctg verify dans votre CI pour vérifier que les secrets chiffrés et les listes de destinataires correspondent aux règles de métadonnées, afin d'empêcher toute falsification.

# .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 au secret ici.

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

Le flux de travail 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 :

# Tire les derniers changements dans les secrets chiffrés locaux
# Similaire à `git pull origin`
ctg pull myvault

# Compare le diff avec les secrets déchiffrés locaux
ctg diff

# Synchronise les secrets déchiffrés locaux avec les secrets chiffrés locaux
ctg sync

# Pousse les changements des secrets chiffrés locaux vers l'upstream
# Similaire à `git push origin main`
ctg push myvault

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

Exemples de plugins

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
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 consulter sans avoir besoin de la CLI.

En savoir plus

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

Dépannage

# Voir les journaux de débogage avec -v, -vv ou -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 convivialité 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 des périmètres distincts.

cottage vs SOPS

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

Gère automatiquement .gitignore pour garantir que les secrets non chiffrés ne sont jamais commités dans git.
Le fait que les secrets chiffrés soient de purs fichiers .age chiffrés avec age permet une meilleure interopérabilité avec un écosystème plus large d'outils.
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 consiste simplement à ajouter/retirer un destinataire, cottage ne génère qu'un diff par fichier, en signalant explicitement le changement dans la somme de contrôle des destinataires.

cottage vs dotenvx

cottage emprunte l'API ctg env à dotenvx.

Prend en charge tout 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 fondamentale, mais manque de nombreuses fonctionnalités.

Lire plus