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 Secrets in Git-Repositories zu verwalten.

Es bietet einen einfachen Workflow zum Ver- und Entschlüsseln von Secrets, zur Verwaltung von Empfängern und hält Secrets aus dem Repository heraus, während sie dennoch einfach über VCS geteilt werden können. cottage erzeugt außerdem geschwärzte Vorschauen verschlüsselter Secrets für bessere Sichtbarkeit und unterstützt sowohl persistente als auch temporäre Entschlüsselungs-Workflows, wobei sichergestellt wird, dass Secrets niemals im Klartext committet werden.

Intro-Demo

Funktionen
Installation
Editor-Integrationen
KI-Agenten-Integrationen
Schnellstart
GitOps
Git-Hooks
Zugriffskontrolle
1. Regeln
2. Verifizierung
Jeder Anbieter als Upstream
1. Beispiel-Plugins
Mit jedem Gerät synchronisieren
Mehr erfahren
Fehlerbehebung
Vergleich

Funktionen

Sicher vor Offenlegung: Nutzt Rusts Typsystem, um sicherzustellen, dass Fehler niemals versehentlich Secrets offenlegen können.
Teamfreundlich: Teile öffentliche Schlüssel (Empfänger) im Repository, halte private Schlüssel (Identitäten) lokal.
Zugriffskontrolle: Einfache Allow/Deny-Regeln, um zu steuern, welche Secrets für welche Empfänger verschlüsselt werden.
Verwaltet .gitignore: Aktualisiert .gitignore automatisch, um unverschlüsselte Secrets aus dem Repository herauszuhalten.
Vorschauen: Erzeugt mit Zeitstempel versehene geschwärzte Vorschauen verschlüsselter Secrets für bessere Sichtbarkeit.
Aussagekräftige Diffs: Hält Git-Diffs sauber und überprüfbar, während ctg diff den Diff lokal geänderter Secrets mit den getrackten verschlüsselten Gegenstücken anzeigt.
Checksummen-Verifizierung: Verhindert Manipulation, indem überprüft wird, dass verschlüsselte Secrets und Empfängerlisten mit den Metadaten übereinstimmen.
Git-Hooks: Einfaches Einrichten von Git-Hooks, um Secrets vor dem Commit automatisch zu prüfen/verschlüsseln und nach dem Checkout zu entschlüsseln.
Persistenter Secrets-Workflow: ctg decrypt/sync behält entschlüsselte Secrets auf der Festplatte.
Intelligenter Aufräum-Lebenszyklus: ctg run (Kurzform ctgx) und ctg edit entschlüsseln Secrets vor der Operation und behalten sie auf der Festplatte, wenn sie bereits vorher vorhanden waren, oder räumen sie danach automatisch auf, wenn sie es nicht waren.
Sauber nach Abschluss: ctg encrypt --clean, ctg run --clean und ctg edit --clean stellen sicher, dass entschlüsselte Dateien von der Festplatte entfernt werden, selbst wenn sie vorher vorhanden waren.
Umgebungsinjektions-Workflow: ctg env injiziert entschlüsselte Secrets als Umgebungsvariablen, um einen Befehl auszuführen, ohne sie überhaupt auf die Festplatte zu schreiben.
Sicheres Secret-Piping: ctg cat PATH entschlüsselt im Speicher und gibt auf stdout aus, um direkt per stdin an andere Tools weitergeleitet zu werden.
Aufräumen: ctg clean löscht alle entschlüsselten Secrets aus dem lokalen Repository, damit du deine KI-Agenten mit etwas weniger Sorgen laufen lassen kannst.
Unterstützt jj und Nicht-Git-Verzeichnisse: ctg init verwandelt jedes Verzeichnis in einen Secret-Store.
Mit jedem Anbieter synchronisieren: Ermöglicht dir, jeden Anbieter mit einer API als Upstream zu konfigurieren und ctg pull/diff/push wie git pull/diff/push zu verwenden.
Mit jedem Gerät synchronisieren: Mit cottage verschlüsselte und in einem Git-Repository verwaltete Secrets 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 lade die neueste Version von GitHub herunter.

Editor-Integrationen

VS Code-Erweiterung

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

Installiere sie aus dem Visual Studio Marketplace oder baue und installiere sie lokal aus vscode-plugin-cottage.

Cursor- und Eclipse-Erweiterung

Lade die VSX-Datei herunter und installiere sie in deiner Cursor- oder Eclipse-IDE. Sie funktioniert ähnlich wie die VS Code-Erweiterung.

Vim-Plugin

Verwende das cottage.vim-Plugin, um Secrets aus Vim oder Neovim zu ver- und entschlüsseln.

KI-Agenten-Integrationen

Alle unten aufgeführten Integrationen hindern KI-Agenten daran, ctg/ctgx direkt auszuführen und Secret-Dateien anzuzeigen oder zu bearbeiten: alles innerhalb von .cottage/, jede *.cott.*-Datei (verschlüsselte *.cott.age-Blobs und geschwärzte *.cott.toml-Vorschauen) und jede entschlüsselte Datei, die noch ein *.cott.age-Gegenstück auf der Festplatte hat.

Claude Code-Integration

Wenn du Claude Code verwendest, füge .claude/settings.json und .claude/hooks/deny-secrets.py zu deinen Repositories mit Secrets hinzu, damit Claude Code-Sitzungen Secrets sicher handhaben, oder installiere das claude-plugin-cottage-Plugin.

GitHub Copilot-Integration

Wenn du GitHub Copilot in VS Code verwendest, füge .github/hooks/ctg-policy.json und .github/hooks/scripts/deny_ctg_command.py zu deinen Repositories mit Secrets hinzu, damit Copilot-Sitzungen entschlüsselte Dateien bereinigen, direkte ctg-Shell-Befehle blockieren und den Zugriff auf Secret-Dateien blockieren, oder installiere die vscode-plugin-cottage-Erweiterung, um das aus VS Code heraus einzurichten.

VS Code lädt auch Hook-Definitionen aus .claude/settings.json. Wenn du sowohl Claude- als auch Copilot-Hook-Dateien im selben Repository behältst, stelle sicher, dass du nicht versehentlich denselben Aufräum-Hook zweimal ausführst.

Codex-Integration

Wenn du Codex verwendest, füge .codex/hooks.json und .codex/hooks/deny-ctg.py zu deinen Repositories mit Secrets hinzu, damit Codex-Sitzungen Secrets sicher handhaben, oder installiere das codex-plugin-cottage-Plugin.

Codex erfordert, dass lokale Hooks vor ihrer Ausführung überprüft werden. Nachdem du die Dateien hinzugefügt hast, starte Codex im Repository und verwende /hooks, um die Projekt-Hooks zu überprüfen und ihnen zu vertrauen.

Antigravity (agy)-Integration

Wenn du Antigravity (agy) verwendest, füge .agents/hooks.json und .agents/scripts/deny-ctg.py zu deinen Repositories mit Secrets hinzu, damit Antigravity-Sitzungen Secrets sicher handhaben, oder installiere das agy-plugin-cottage-Plugin.

Cursor-Integration

Wenn du Cursor verwendest, füge .cursor/hooks.json, .cursor/hooks/deny-ctg.py, .cursor/hooks/deny-read-secrets.py, .cursor/rules/deny-ctg.mdc und .cursorignore zu deinen Repositories mit Secrets hinzu, damit Cursor-Sitzungen Secrets sicher handhaben.

Cursor erfordert, dass Hooks zuerst aktiviert werden. Öffne Cursor Settings > Hooks und aktiviere Hooks, dann starte die Agenten-Sitzung neu, damit die Projekt-Hooks wirksam werden. .cursorignore hält Secret-Dateien zusätzlich aus Cursors Indexierung und dem Kontext des Agenten 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 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.

Ein Secret erstellen oder bearbeiten:

# `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

Einen Befehl mit entschlüsselten Secrets ausführen:

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

Oder verwende die Kurzform:

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

Ein entschlüsseltes Secret lesen und weiterleiten, ohne es auf die Festplatte zu schreiben:

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

Einen Befehl mit als Umgebungsvariablen injizierten Secrets ausführen, ohne ü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 deine Secrets mit Teammitgliedern zu teilen, pushe einfach in das Git-Repository.

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

Bitte deine Teamkollegen, ihre öffentlichen Schlüssel zu .cottage/recipients hinzuzufügen und die Änderungen zu pushen. Dann kannst du pullen und die Secrets für sie neu verschlüsseln.

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

Jetzt können deine Teamkollegen die neuesten Änderungen pullen und die Secrets für sich selbst entschlüsseln.

Git-Hooks

Du kannst prek oder pre-commit verwenden, um Git-Hooks einzurichten, die Secrets vor dem Commit automatisch prüfen/verschlüsseln und nach dem Checkout entschlüsseln.

Siehe die Beispiel-prek-Konfiguration hier.

Nachdem du die prek.toml-Datei hinzugefügt hast, führe 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 kannst du annotieren, für welche Empfänger das Secret verschlüsselt werden soll. Dadurch kannst du unterschiedliche Secrets für unterschiedliche Umgebungen haben (z. B. Staging vs. Produktion) und sie 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

Du kannst ctg verify in CI ausführen, um zu überprüfen, dass die verschlüsselten Secrets und Empfängerlisten mit den Metadatenregeln übereinstimmen, 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

Jeder Anbieter als Upstream

Mit cottage kannst du Secrets mit jedem Anbieter synchronisieren, der eine API hat, nicht nur mit Git.

Erstelle dazu eine Datei namens cottage.toml im Projektstammverzeichnis und konfiguriere die Upstream-Einstellungen.

Siehe die Beispiel-cottage.toml hier und die secret-spezifische Upstream-Konfiguration hier.

Siehe eine Beispiel-Plugin-Implementierung hier.

Der Workflow ähnelt Git, aber statt git pull und git push führst du ctg pull und ctg push aus, um Secrets 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, um deine Secrets zu synchronisieren. Gebrauchsfertige Plugin-Skripte sind im Verzeichnis examples/plugins verfügbar:

1Password
AWS Secrets Manager
Azure Key Vault
Bitwarden
Dashlane
Doppler
ejson
GitHub Secrets
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 jedem Gerät synchronisieren

Verwende Cottage Sync, um deine Secrets geräteübergreifend zu synchronisieren und sie ohne 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 sichere Dateiverschlüsselung optimiert ist, mit Fokus auf Benutzerfreundlichkeit und minimale Angriffsfläche. Es unterstützt auch SSH RSA- und Ed25519-Schlüssel, obwohl es empfohlen wird, unterschiedliche Schlüssel für getrennte Zwecke und Geltungsbereiche zu verwenden.

cottage vs. SOPS

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

Automatische Verwaltung von .gitignore, um sicherzustellen, dass unverschlüsselte Secrets niemals in Git committet werden.
Verschlüsselte Secrets sind reine age-verschlüsselte .age-Dateien, was eine bessere Interoperabilität mit einem breiteren Ökosystem von Tools ermöglicht.
Sauberere Diffs – anders als SOPS, das Diffs für jeden Wert jedes Secrets erzeugt, selbst wenn die tatsächliche Änderung nur das Hinzufügen/Entfernen eines Empfängers ist, erzeugt cottage nur einen Diff pro Datei, der explizit die Änderung in der Checksumme der Empfänger aufzeigt.

cottage vs. dotenvx

cottage übernimmt die ctg env-API von dotenvx.

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

cottage vs. agebox

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