cottage v0.7.0 — 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 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.

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 amont
1. Exemples de plugins
Synchronisation avec n'importe quel appareil
En savoir plus
Dépannage
Comparaison

Fonctionnalités

Sûr contre l'exposition : Utilise le système de types de Rust pour garantir que les bugs 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 : 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 diff git propre et vérifiable, tandis que ctg diff affiche le diff des secrets modifiés localement avec leurs homologues chiffrés suivis.
Vérification de somme 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.
Hooks git : Configurez facilement des hooks git pour vérifier/chiffrer automatiquement les secrets avant le commit et les déchiffrer après le checkout.
Flux de travail de secrets persistants : ctg decrypt/sync conserve les secrets déchiffrés sur le disque.
Cycle de vie 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 auparavant 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 auparavant.
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 du tout sur le disque.
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 à secrets.
Synchronisation avec n'importe quel fournisseur : Vous permet de configurer n'importe quel fournisseur avec une API comme amont et de commencer à 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 d'éditeurs

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.

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 ctg/ctgx directement et de visualiser 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 un homologue *.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 gèrent 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 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 gèrent 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 gèrent 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 gèrent les secrets en toute sécurité.

Cursor exige que les hooks soient d'abord activés. Ouvrez Paramètres Cursor > 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 obligatoire
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 sécurité. 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é `*.cott.age binary linguist-generated filter=cottage-encrypted -diff` pour éviter de polluer le diff git
# └ .gitignore          <- Ajouté `/.cottage/identity` pour des raisons évidentes

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

Créer ou modifier un secret :

# `ctg edit` déchiffre le fichier avant de l'ouvrir dans $EDITOR et le rechiffre lors de l'enregistrement.
# Si le fichier déchiffré n'était pas présent sur le disque avant d'exécuter `ctg edit`, il est nettoyé ensuite.
# S'il était déjà présent, il est conservé sur le disque.
ctg edit secret.yml

# Utilisez `--clean` avec `ctg edit` ou `ctg encrypt` pour garantir que les fichiers déchiffrés sont supprimés même s'ils étaient présents auparavant
ctg edit secret.yml --clean    # Ouvre dans $EDITOR, chiffre lors de l'enregistrement et nettoie
ctg encrypt secret.yml --clean # Chiffre secret.yml et nettoie
# chiffre secret.yml
#    vers secret.yml.cott.age
#    modifie secret.yml.cott.toml
#    modifie .gitignore
# supprime 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` (ou le raccourci `ctgx`) déchiffre les secrets avant d'exécuter la commande.
# Si les fichiers déchiffrés n'étaient pas présents sur le disque auparavant, ils sont automatiquement nettoyés après la fin de la commande.
# S'ils étaient déjà présents auparavant, ils sont conservés sur le disque.
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

# Utilisez `--clean` pour garantir que les fichiers déchiffrés sont nettoyés même s'ils étaient présents auparavant
ctg run --clean ./deploy.sh

Ou utilisez le raccourci :

ctgx -- ./deploy.sh
ctgx --clean -- ./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 depuis .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 decrypt --skip-verify-recipients  # Déchiffre les secrets manquants pour le rechiffrement
ctg encrypt                           # Rechiffre tous les secrets
# chiffre secret.yml
#    vers secret.yml.cott.age
#    modifie secret.yml.cott.toml

ctg clean  # facultatif
# supprime secret.yml

# examinez les modifications, commitez et poussez
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.

Hooks Git

Vous pouvez utiliser prek ou pre-commit pour configurer des hooks git 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 la spécification des métadonnées pour plus de détails.

Vérification

Vous pouvez exécuter ctg verify dans 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 la 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 amont

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 amont.

Voir l'exemple cottage.toml ici et la configuration amont 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'amont configuré.

Exemple :

# Tire les dernières modifications 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 modifications des secrets chiffrés locaux vers l'amont
# Similaire à `git push origin main`
ctg push myvault

Voir la spécification de configuration amont 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
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 naviguer 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 objectifs et des portées 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.
Les secrets chiffrés étant de purs fichiers .age chiffrés avec age, cela permet une meilleure interopérabilité avec un écosystème plus large d'outils.
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/supprimer un destinataire, cottage ne génère qu'un seul 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.
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