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

Das cottage-Logo

cottage ist ein GitOps-Tool für Teams, um age-verschlüsselte Geheimnisse in Git-Repositories zu verwalten.

Es bietet einen einfachen Workflow, um Geheimnisse zu verschlüsseln/entschlüsseln, Empfänger zu verwalten und Geheimnisse aus dem Repo herauszuhalten, während der Austausch über VCS weiterhin leicht möglich ist. 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, wobei sichergestellt wird, dass Geheimnisse niemals im Klartext committet werden.

Intro-Demo

Funktionen
Installation
Editor-Integrationen
1. VS-Code-Erweiterung
KI-Agent-Integrationen
Schnellstart
GitOps
Git-Hooks
Zugriffskontrolle
1. Regeln
2. Verifizierung
Beliebiger Anbieter als Upstream
1. Beispiel-Plugins
Mit beliebigem Gerät synchronisieren
Mehr erfahren
Fehlerbehebung
Vergleich

Funktionen

Expositionssicher: Nutzt das Typsystem von Rust, um sicherzustellen, dass Bugs niemals versehentlich Geheimnisse offenlegen können.
Teamfreundlich: Öffentliche Schlüssel (Empfänger) im Repo teilen, private Schlüssel (Identitäten) lokal behalten.
Zugriffskontrolle: Einfache Allow-/Deny-Regeln, um zu steuern, welche Geheimnisse für welche Empfänger verschlüsselt werden.
Verwaltet .gitignore: Aktualisiert automatisch .gitignore, um unverschlüsselte Geheimnisse aus dem Repo herauszuhalten.
Vorschauen: Erzeugt mit Zeitstempel versehene, geschwärzte Vorschauen verschlüsselter Geheimnisse für bessere Sichtbarkeit.
Aussagekräftige Diffs: Hält den Git-Diff sauber und überprüfbar, während ctg diff den Diff lokal geänderter Geheimnisse mit den versionierten verschlüsselten Gegenstücken zeigt.
Checksummen-Prüfung: Verhindert Manipulation, indem überprüft wird, dass verschlüsselte Geheimnisse und Empfängerlisten mit den Metadaten übereinstimmen.
Git-Hooks: Richten Sie Git-Hooks einfach ein, um Geheimnisse vor dem Commit automatisch zu prüfen/verschlüsseln und nach dem Checkout zu entschlüsseln.
Persistenter Geheimnis-Workflow: ctg decrypt/edit/sync hält entschlüsselte Geheimnisse auf der Festplatte.
Temporärer Geheimnis-Workflow: ctg run (Kurzform ctgx) entschlüsselt Geheimnisse vorübergehend, um einen Befehl auszuführen, und löscht sie danach, unabhängig davon, ob der Befehl erfolgreich war oder fehlschlug.
Umgebungsvariablen-Injektions-Workflow: ctg env injiziert entschlüsselte Geheimnisse als Umgebungsvariablen, um einen Befehl auszuführen, ohne sie überhaupt auf die Festplatte zu schreiben.
Aufräumen: ctg clean löscht alle entschlüsselten Geheimnisse aus dem lokalen Repo, damit Sie Ihre KI-Agenten mit ein bisschen weniger Sorge ausführen können.
Unterstützt jj und Nicht-Git-Verzeichnisse: ctg init verwandelt jedes Verzeichnis in einen Geheimnisspeicher.
Synchronisierung mit beliebigem Anbieter: Ermöglicht die Konfiguration jedes Anbieters mit einer API als Upstream und die Nutzung von ctg pull/diff/push wie git pull/diff/push.
Synchronisierung mit beliebigem Gerät: Mit cottage verschlüsselte und in einem Git-Repo verwaltete Geheimnisse können mit Cottage Sync geräteübergreifend synchronisiert werden.

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

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.

Editor-Integrationen

VS-Code-Erweiterung

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 es über den Visual Studio Marketplace oder bauen und installieren Sie es lokal aus vscode-plugin-cottage.

KI-Agent-Integrationen

Alle unten aufgeführten 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.

Claude-Code-Integration

Wenn Sie Claude Code verwenden, fügen Sie .claude/settings.json und .claude/hooks/deny-secrets.py zu Ihren Repos mit Geheimnissen hinzu, damit Claude-Code-Sitzungen Geheimnisse sicher behandeln, oder installieren Sie das Plugin claude-plugin-cottage.

GitHub-Copilot-Integration

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 Repos mit Geheimnissen hinzu, damit Copilot-Sitzungen entschlüsselte Dateien bereinigen, direkte ctg-Shell-Befehle blockieren und den Zugriff auf Geheimnisdateien blockieren. Alternativ installieren Sie die Erweiterung vscode-plugin-cottage, um dies aus VS Code einzurichten.

VS Code lädt auch die Hook-Definitionen aus .claude/settings.json. Wenn Sie sowohl Claude- als auch Copilot-Hook-Dateien im selben Repo aufbewahren, stellen Sie sicher, dass Sie nicht versehentlich denselben Bereinigungs-Hook zweimal ausführen.

Codex-Integration

Wenn Sie Codex verwenden, fügen Sie .codex/hooks.json und .codex/hooks/deny-ctg.py zu Ihren Repos mit Geheimnissen hinzu, damit Codex-Sitzungen Geheimnisse sicher behandeln, oder installieren Sie das Plugin codex-plugin-cottage.

Codex verlangt, dass lokale Hooks vor ihrer Ausführung überprüft werden. Starten Sie Codex nach dem Hinzufügen der Dateien im Repo und verwenden Sie /hooks, um die Projekt-Hooks zu überprüfen und ihnen zu vertrauen.

Antigravity (agy)-Integration

Wenn Sie Antigravity (agy) verwenden, fügen Sie .agents/hooks.json und .agents/scripts/deny-ctg.py zu Ihren Repos mit Geheimnissen hinzu, damit Antigravity-Sitzungen Geheimnisse sicher behandeln, oder installieren Sie das Plugin agy-plugin-cottage.

Cursor-Integration

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 Repos mit Geheimnissen hinzu, damit Cursor-Sitzungen Geheimnisse sicher behandeln.

Cursor verlangt, dass Hooks zuerst aktiviert werden. Öffnen Sie Cursor-Einstellungen > Hooks und aktivieren Sie die Hooks. Starten Sie dann die Agent-Sitzung neu, damit die Projekt-Hooks wirksam werden. .cursorignore hält Geheimnisdateien zusätzlich aus der Indizierung von Cursor und dem Kontext des Agents heraus.

Schnellstart

Projekt initialisieren:

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 export-ignore 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.

Ein Geheimnis erstellen oder bearbeiten.

ctg edit secret.yml --clean    # Opens secret.yml in $EDITOR
ctg encrypt secret.yml --clean # Another way to encrypt secrets
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml
#    edit .gitignore
# delete secret.yml

Einen Befehl mit temporär entschlüsselten Geheimnissen ausführen:

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

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

Oder verwenden Sie die Kurzform:

ctgx ./deploy.sh  # same as ctg run -- ./deploy.sh

Einen Befehl mit Geheimnissen ausführen, die als Umgebungsvariablen injiziert werden, ohne sie überhaupt auf die Festplatte zu schreiben:

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

Um Ihre Geheimnisse mit Teammitgliedern zu teilen, pushen Sie einfach in das Git-Repo.

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 pullen und für sie neu verschlüsseln.

git pull origin main

ctg sync  # or `ctg decrypt && ctg encrypt`
# 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

Jetzt können Ihre Teammitglieder die neuesten Änderungen pullen und Geheimnisse selbst entschlüsseln.

Git-Hooks

Sie können prek oder pre-commit verwenden, um Git-Hooks einzurichten, die Geheimnisse vor dem Commit automatisch prüfen/verschlüsseln und sie nach dem Checkout entschlüsseln.

Siehe die Beispielkonfiguration für prek hier.

Führen Sie nach dem Hinzufügen der Datei prek.toml Folgendes aus:

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

Zugriffskontrolle

Regeln

In der Metadatendatei können Sie angeben, für welche Empfänger das Geheimnis verschlüsselt werden soll. So können Sie verschiedene Geheimnisse für verschiedene Umgebungen haben (z. B. Staging vs. Produktion) und diese nur für die relevanten Empfänger verschlüsseln.

# 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

Deny-Regeln haben Vorrang vor Allow-Regeln.

Siehe Metadaten-Spezifikation für weitere Details.

Verifizierung

Sie können ctg verify in CI ausführen, um zu überprüfen, dass die verschlüsselten Geheimnisse und Empfängerlisten den Metadatenregeln entsprechen, und so Manipulationen 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

Beliebiger Anbieter als Upstream

Mit cottage können Sie Geheimnisse mit jedem Anbieter synchronisieren, der eine API hat, nicht nur mit git.

Erstellen Sie dazu im Projektstamm eine Datei namens cottage.toml 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 ist ähnlich wie bei 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:

# 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

Siehe Upstream-Konfigurationsspezifikation für weitere Details.

Beispiel-Plugins

Cottage unterstützt verschiedene Plugin-Anbieter zum Synchronisieren Ihrer Geheimnisse. Gebrauchsfertige Plugin-Skripte sind im Verzeichnis examples/plugins verfügbar:

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

Mit beliebigem Gerät synchronisieren

Verwenden Sie Cottage Sync, um Ihre Geheimnisse geräteübergreifend zu synchronisieren und ohne die CLI zu durchsuchen.

Mehr erfahren

Siehe das Verzeichnis examples für weitere Anwendungsbeispiele.

Fehlerbehebung

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

Vergleich

age vs andere Verschlüsselung

age verwendet einen modernen, einfachen Algorithmus, der für die sichere Dateiverschlüsselung optimiert ist, mit Fokus auf Benutzerfreundlichkeit und minimaler Angriffsfläche. Es unterstützt auch SSH-RSA- und Ed25519-Schlüssel, wobei empfohlen wird, für getrennte Zwecke und Anwendungsbereiche unterschiedliche Schlüssel zu verwenden.

cottage vs SOPS

Während SOPS und cottage viele überlappende Funktionen haben, bietet cottage die folgenden Vorteile:

Verwaltet .gitignore automatisch, um sicherzustellen, dass unverschlüsselte Geheimnisse nie in git committet werden.
Da verschlüsselte Geheimnisse reine age-verschlüsselte .age-Dateien sind, ist eine bessere Interoperabilität mit einem breiteren Ökosystem von Tools möglich.
Sauberere Diffs - anders als SOPS, das für jeden Wert jedes Geheimnisses Diffs erzeugt, selbst wenn die eigentliche Änderung nur das Hinzufügen/Entfernen eines Empfängers ist, erzeugt cottage nur einen Diff pro Datei, der die Änderung der Empfänger-Checksumme ausdrücklich hervorhebt.

cottage vs dotenvx

cottage übernimmt die ctg env-API von dotenvx.

Unterstützt jeden Dateityp, nicht nur dotenv-Dateien.
Verwaltet mehrere Geheimnisse in einem Repo.
Zugriffskontrollregeln, um Geheimnisse für bestimmte Empfänger zu verschlüsseln.
Sauberere Diffs - siehe cottage vs SOPS.

cottage vs agebox

agebox ist in der Kernphilosophie cottage sehr ähnlich, es fehlen jedoch viele Funktionen.