sayanarijit/cottageEin moderner Git-basierter age-verschlüsselter Geheimnisverwalter für Teams.
cottage ist ein GitOps-Tool für Teams, um age-verschlüsselte Geheimnisse in Git-Repositories zu verwalten.
Es bietet einen einfachen Workflow zum Verschlüsseln/Entschlüsseln von Geheimnissen, zur Verwaltung von Empfängern und hält Geheimnisse aus dem Repository heraus, während es dennoch eine einfache Weitergabe über VCS ermöglicht. cottage generiert außerdem geschwärzte Vorschauen verschlüsselter Geheimnisse für bessere Sichtbarkeit und unterstützt sowohl persistente als auch temporäre Entschlüsselungs-Workflows, während sichergestellt wird, dass Geheimnisse niemals im Klartext committet werden.
.gitignore, um unverschlüsselte Geheimnisse aus dem Repository herauszuhalten.ctg diff den Diff lokal geänderter Geheimnisse mit den nachverfolgten verschlüsselten Gegenstücken zeigt.ctg decrypt/sync hält entschlüsselte Geheimnisse auf der Festplatte.ctg run (Kurzform ctgx) und ctg edit entschlüsseln Geheimnisse vor der Operation und halten sie auf der Festplatte, wenn sie bereits vorher vorhanden waren, oder räumen sie danach automatisch auf, wenn sie es nicht waren.# 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
Auch als Docker-Images verfügbar:
# Docker
docker run --rm -v $PWD:/app sayanarijit/cottage --version
# Podman
podman run --rm -v $PWD:/app quay.io/sayanarijit/cottage --version
Oder laden Sie die neueste Version von GitHub herunter.
Verwenden Sie die Cottage VS Code-Erweiterung, um ctg zu installieren, Copilot-Sicherheits-Hooks hinzuzufügen, Dateien aus dem Explorer zu verschlüsseln und .cott.age-Dateien über den Editor-Workflow zu öffnen.
Installieren Sie sie aus dem Visual Studio Marketplace oder bauen und installieren Sie sie lokal aus vscode-plugin-cottage.
Laden Sie die VSX-Datei herunter und installieren Sie sie in Ihrer Cursor- oder Eclipse-IDE. Sie funktioniert ähnlich wie die VS Code-Erweiterung.
Verwenden Sie das cottage.vim-Plugin, um Geheimnisse aus Vim oder Neovim zu verschlüsseln/entschlüsseln.
Alle untenstehenden Integrationen hindern KI-Agenten daran, ctg/ctgx direkt auszuführen und Geheimnisdateien anzusehen oder zu bearbeiten: alles innerhalb von .cottage/, jede *.cott.*-Datei (verschlüsselte *.cott.age-Blobs und geschwärzte *.cott.toml-Vorschauen) sowie jede entschlüsselte Datei, die noch ein *.cott.age-Gegenstück auf der Festplatte hat.
Wenn Sie Claude Code verwenden, fügen Sie .claude/settings.json und .claude/hooks/deny-secrets.py zu Ihren Repositories mit Geheimnissen hinzu, damit Claude Code-Sitzungen Geheimnisse sicher behandeln, oder installieren Sie das claude-plugin-cottage-Plugin.
Wenn Sie GitHub Copilot in VS Code verwenden, fügen Sie .github/hooks/ctg-policy.json und .github/hooks/scripts/deny_ctg_command.py zu Ihren Repositories mit Geheimnissen hinzu, damit Copilot-Sitzungen entschlüsselte Dateien bereinigen, direkte ctg-Shell-Befehle blockieren und den Zugriff auf Geheimnisdateien blockieren, oder installieren Sie die vscode-plugin-cottage-Erweiterung, um dies aus VS Code einzurichten.
VS Code lädt auch .claude/settings.json-Hook-Definitionen. Wenn Sie sowohl Claude- als auch Copilot-Hook-Dateien im selben Repository aufbewahren, stellen Sie sicher, dass Sie nicht versehentlich denselben Bereinigungs-Hook zweimal ausführen.
Wenn Sie Codex verwenden, fügen Sie .codex/hooks.json und .codex/hooks/deny-ctg.py zu Ihren Repositories mit Geheimnissen hinzu, damit Codex-Sitzungen Geheimnisse sicher behandeln, oder installieren Sie das codex-plugin-cottage-Plugin.
Codex erfordert, dass lokale Hooks überprüft werden, bevor sie ausgeführt werden. Nach dem Hinzufügen der Dateien starten Sie Codex im Repository und verwenden /hooks, um die Projekt-Hooks zu überprüfen und zu vertrauen.
Wenn Sie Antigravity (agy) verwenden, fügen Sie .agents/hooks.json und .agents/scripts/deny-ctg.py zu Ihren Repositories mit Geheimnissen hinzu, damit Antigravity-Sitzungen Geheimnisse sicher behandeln, oder installieren Sie das agy-plugin-cottage-Plugin.
Wenn Sie Cursor verwenden, fügen Sie .cursor/hooks.json, .cursor/hooks/deny-ctg.py, .cursor/hooks/deny-read-secrets.py, .cursor/rules/deny-ctg.mdc und .cursorignore zu Ihren Repositories mit Geheimnissen hinzu, damit Cursor-Sitzungen Geheimnisse sicher behandeln.
Cursor erfordert, dass Hooks zuerst aktiviert werden. Öffnen Sie Cursor-Einstellungen > Hooks und aktivieren Sie Hooks, starten Sie dann die Agent-Sitzung neu, damit die Projekt-Hooks wirksam werden. .cursorignore hält Geheimnisdateien zusätzlich aus dem Cursor-Index und dem Kontext des Agents heraus.
Projekt initialisieren:
mkdir project && cd project
git init # Optional, cottage funktioniert besser mit git, ist aber nicht erforderlich
ctg init # Richtet das .cottage-Verzeichnis und notwendige Dateien ein
tree -a
# .
# ├ .cottage/ <- Automatisch von `ctg init` generiert
# │ ├ identity <- Ihr privater Schlüssel, bewahren Sie ihn sicher auf. Verschieben Sie ihn nach `~/.config/cottage/identity`, um ihn global zu verwenden, oder ersetzen Sie ihn durch einen symbolischen Link zu einem Ihrer vorhandenen privaten Schlüssel.
# │ └ recipients/ <- Hier bewahrt Ihr Team die öffentlichen Schlüssel aller Empfänger auf.
# │ └ sayanarijit <- Ihr öffentlicher Schlüssel. Committen Sie ihn. Um einen vorhandenen öffentlichen Schlüssel zu verwenden, kopieren Sie (nicht symbolisch verlinken) diesen Schlüssel hierher.
# ├ .git/...
# ├ .gitattributes <- `*.cott.age binary linguist-generated filter=cottage-encrypted -diff` hinzugefügt, um den Git-Diff nicht zu verschmutzen
# └ .gitignore <- `/.cottage/identity` aus offensichtlichen Gründen hinzugefügt
# Sie können jederzeit `ctg clean --all` ausführen, um alles aufzuräumen, was cottage jemals getan hat.
Ein Geheimnis erstellen oder bearbeiten:
# `ctg edit` entschlüsselt die Datei, bevor sie in $EDITOR geöffnet wird, und verschlüsselt sie beim Speichern erneut.
# Wenn die entschlüsselte Datei vor der Ausführung von `ctg edit` nicht auf der Festplatte vorhanden war, wird sie danach bereinigt.
# Wenn sie bereits vorhanden war, wird sie auf der Festplatte behalten.
ctg edit secret.yml
# Verwenden Sie `--clean` mit `ctg edit` oder `ctg encrypt`, um sicherzustellen, dass entschlüsselte Dateien gelöscht werden, auch wenn sie vorher vorhanden waren
ctg edit secret.yml --clean # Öffnet in $EDITOR, verschlüsselt beim Speichern und räumt auf
ctg encrypt secret.yml --clean # Verschlüsselt secret.yml und räumt auf
# encrypt secret.yml
# into secret.yml.cott.age
# edit secret.yml.cott.toml
# edit .gitignore
# delete secret.yml
Einen Befehl mit entschlüsselten Geheimnissen ausführen:
cat secret.yml
# cat: secret.yml: No such file or directory
# `ctg run` (oder die Kurzform `ctgx`) entschlüsselt Geheimnisse vor der Ausführung des Befehls.
# Wenn die entschlüsselten Dateien vorher nicht auf der Festplatte vorhanden waren, werden sie nach Abschluss des Befehls automatisch bereinigt.
# Wenn sie bereits vorher vorhanden waren, werden sie auf der Festplatte behalten.
ctg run -- kubectl apply -f secret.yml # entschlüsselt secret.yml.cott.age zu secret.yml und führt den Befehl aus
ctg run -- kubectl apply -f secret.yml.cott.age # ersetzt auch das Pfadargument durch den Pfad der entschlüsselten Datei
ctg run -- kubectl apply -f . # entschlüsselt alle .cott.age-Dateien in . und führt den Befehl aus
ctg run -- ./deploy.sh # entschlüsselt alle .cott.age-Dateien im Repository und führt den Befehl aus
cat secret.yml
# cat: secret.yml: No such file or directory
# Verwenden Sie `--clean`, um sicherzustellen, dass entschlüsselte Dateien bereinigt werden, auch wenn sie vorher vorhanden waren
ctg run --clean ./deploy.sh
Oder verwenden Sie die Kurzform:
ctgx -- ./deploy.sh
ctgx --clean -- ./deploy.sh
Einen Befehl mit Geheimnissen ausführen, die als Umgebungsvariablen injiziert werden, ohne überhaupt auf die Festplatte zu schreiben:
ctg env -- ./deploy.sh # Exportiert Geheimnisse aus .env.cott.age (Standard), ohne sie auf die Festplatte zu schreiben, und führt dann deploy.sh aus
ctg env -F .env.prod.cott.age -- ./deploy.sh # exportiert aus .env.prod.cott.age statt .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # Unterstützt auch Nicht-Dotenv-Dateien.
Um Ihre Geheimnisse mit Teammitgliedern zu teilen, pushen Sie einfach in das Git-Repository.
git add .
git commit -m "Add secret.yml"
git push origin main
Bitten Sie Ihre Teammitglieder, ihre öffentlichen Schlüssel zu .cottage/recipients hinzuzufügen und die Änderungen zu pushen. Dann können Sie die Geheimnisse für sie pullen und neu verschlüsseln.
git pull origin main
ctg decrypt --skip-verify-recipients # Entschlüsselt fehlende Geheimnisse zur Neuverschlüsselung
ctg encrypt # Verschlüsselt alle Geheimnisse neu
# encrypt secret.yml
# into secret.yml.cott.age
# edit secret.yml.cott.toml
ctg clean # optional
# delete secret.yml
# Änderungen überprüfen, committen und pushen
git add .
git commit -m "Add new recipient to secrets"
git push origin main
Jetzt können Ihre Teammitglieder die neuesten Änderungen pullen und Geheimnisse für sich selbst entschlüsseln.
Sie können prek oder pre-commit verwenden, um Git-Hooks einzurichten, die Geheimnisse vor dem Commit automatisch prüfen/verschlüsseln und nach dem Checkout entschlüsseln.
Siehe die Beispiel-prek-Konfiguration hier.
Nach dem Hinzufügen der prek.toml-Datei führen Sie Folgendes aus:
prek install
prek install --hook-type post-checkout
prek install --hook-type post-merge
prek install --hook-type post-rewrite
In der Metadatendatei können Sie annotieren, für welche Empfänger das Geheimnis verschlüsselt werden soll. Dies ermöglicht es Ihnen, verschiedene Geheimnisse für verschiedene Umgebungen (z. B. Staging vs. Produktion) zu haben und sie nur für die relevanten Empfänger zu verschlüsseln.
# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"] # Nur für sayanarijit verschlüsseln
# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"] # Für alle außer sayanarijit verschlüsseln
# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"] # Unterstützt Glob-Muster, nur für Empfänger in env/staging verschlüsseln
deny = ["env/staging/badservice"] # Für alle in env/staging außer badservice verschlüsseln
Verweigern-Regeln haben Vorrang vor Erlauben-Regeln.
Siehe die Metadatenspezifikation für weitere Details.
Sie können ctg verify in CI ausführen, um zu verifizieren, dass die verschlüsselten Geheimnisse und Empfängerlisten den Metadatenregeln entsprechen, um Manipulation zu verhindern.
# .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
Mit cottage können Sie Geheimnisse mit jedem Anbieter synchronisieren, der eine API hat, nicht nur mit git.
Erstellen Sie dafür eine Datei namens cottage.toml im Projektstamm und konfigurieren Sie die Upstream-Einstellungen.
Siehe die Beispiel-cottage.toml hier und die geheimnisspezifische Upstream-Konfiguration hier.
Siehe eine Beispiel-Plugin-Implementierung hier.
Der Workflow ähnelt git, aber statt git pull und git push führen Sie ctg pull und ctg push aus, um Geheimnisse mit dem konfigurierten Upstream zu synchronisieren.
Beispiel:
# Neueste Änderungen in lokale verschlüsselte Geheimnisse pullen
# Ähnlich wie `git pull origin`
ctg pull myvault
# Diff mit lokalen entschlüsselten Geheimnissen vergleichen
ctg diff
# Lokale entschlüsselte Geheimnisse mit lokalen verschlüsselten Geheimnissen synchronisieren
ctg sync
# Änderungen von lokalen verschlüsselten Geheimnissen zum Upstream pushen
# Ähnlich wie `git push origin main`
ctg push myvault
Siehe die Upstream-Konfigurationsspezifikation für weitere Details.
Cottage unterstützt verschiedene Plugin-Anbieter zur Synchronisierung Ihrer Geheimnisse. Gebrauchsfertige Plugin-Skripte sind im Verzeichnis examples/plugins verfügbar:
Verwenden Sie Cottage Sync, um Ihre Geheimnisse geräteübergreifend zu synchronisieren und ohne CLI zu durchsuchen.
Siehe das Verzeichnis examples für weitere Verwendungsbeispiele.
# Debug-Logs mit -v, -vv oder -vvv anzeigen
ctg run -vvv -- ./deploy.sh
age verwendet einen modernen, einfachen Algorithmus, der für sichere Dateiverschlüsselung optimiert ist, mit einem Fokus auf Benutzerfreundlichkeit und minimaler Angriffsfläche. Es unterstützt auch SSH-RSA- und Ed25519-Schlüssel, obwohl empfohlen wird, verschiedene Schlüssel für getrennte Zwecke und Bereiche zu verwenden.
Während SOPS und cottage viele überlappende Funktionen haben, bietet cottage die folgenden Vorteile:
cottage übernimmt die ctg env-API von dotenvx.
agebox ist cottage in der Kernphilosophie sehr ähnlich, es fehlen jedoch viele Funktionen.
ctg encrypt --cleanctg run --cleanctg edit --cleanctg env injiziert entschlüsselte Geheimnisse als Umgebungsvariablen, um einen Befehl auszuführen, ohne sie überhaupt auf die Festplatte zu schreiben.ctg clean löscht alle entschlüsselten Geheimnisse aus dem lokalen Repository, damit Sie Ihre KI-Agenten mit etwas weniger Sorge ausführen können.ctg init verwandelt jedes Verzeichnis in einen Geheimnisspeicher.ctg pull/diff/push wie git pull/diff/push.