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

The cottage logo

cottage è uno strumento GitOps per team per gestire segreti crittografati con age nei repository git.

Fornisce un flusso di lavoro semplice per crittografare/decrittografare segreti, gestire i destinatari e mantenere i segreti fuori dal repository, consentendo comunque una facile condivisione tramite VCS. cottage genera anche anteprime oscurate dei segreti crittografati per una migliore visibilità e supporta sia flussi di lavoro di decrittografia persistenti che temporanei, garantendo che i segreti non vengano mai committati in chiaro.

Intro Demo

Funzionalità
Installazione
Integrazioni con Editor
Integrazioni con Agenti AI
Avvio Rapido
GitOps
Git Hooks
Controllo degli Accessi
1. Regole
2. Verifica
Qualsiasi Provider come Upstream
1. Plugin di esempio
Sincronizza con qualsiasi dispositivo
Scopri di Più
Risoluzione dei Problemi
Confronto

Funzionalità

Sicuro contro esposizioni: Usa il sistema di tipi di Rust per garantire che i bug non possano mai esporre accidentalmente i segreti.
Adatto ai team: Condividi le chiavi pubbliche (destinatari) nel repository, mantieni le chiavi private (identità) in locale.
Controllo degli Accessi: Semplici regole di consenso/negazione per controllare quali segreti vengono crittografati per quali destinatari.
Gestisce .gitignore: Aggiorna automaticamente .gitignore per mantenere i segreti non crittografati fuori dal repository.
Anteprime: Genera anteprime oscurate con timestamp dei segreti crittografati per una migliore visibilità.
Diff ricchi: Mantiene il git diff pulito e revisionabile, mentre ctg diff mostra il diff dei segreti modificati localmente rispetto alle controparti crittografate tracciate.
Verifica del checksum: Previene manomissioni verificando che i segreti crittografati e gli elenchi di destinatari corrispondano ai metadati.
Git hooks: Configura facilmente git hooks per controllare/crittografare automaticamente i segreti prima del commit e decrittografarli dopo il checkout.
Flusso di lavoro con segreti persistenti: ctg decrypt/sync mantiene i segreti decrittografati su disco.
Ciclo di vita intelligente della pulizia: ctg run (scorciatoia ctgx) e ctg edit decrittografano i segreti prima dell'operazione, mantenendoli su disco se già presenti in precedenza o pulendoli automaticamente dopo se non lo erano.
Pulizia al completamento: ctg encrypt --clean, ctg run --clean e ctg edit --clean garantiscono che i file decrittografati vengano rimossi dal disco anche se erano presenti prima.
Flusso di lavoro con iniezione di variabili d'ambiente: ctg env inietta i segreti decrittografati come variabili d'ambiente per eseguire un comando, senza scriverli affatto su disco.
Pulizia: ctg clean elimina tutti i segreti decrittografati dal repository locale per permetterti di eseguire i tuoi agenti AI con un po' meno preoccupazioni.
Supporta jj e directory non git: ctg init trasforma qualsiasi directory in un archivio di segreti.
Sincronizza con qualsiasi provider: Ti permette di configurare qualsiasi provider con un'API come upstream e iniziare a usare ctg pull/diff/push come git pull/diff/push.
Sincronizza con qualsiasi dispositivo: I segreti crittografati con cottage e gestiti in un repository git possono essere sincronizzati tra dispositivi con Cottage Sync.

Installazione

# 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

Disponibile anche come immagini docker:

# Docker
docker run --rm -v $PWD:/app sayanarijit/cottage --version

# Podman
podman run --rm -v $PWD:/app quay.io/sayanarijit/cottage --version

Oppure scarica l'ultima release da GitHub.

Integrazioni con Editor

Estensione VS Code

Usa l'estensione VS Code di Cottage per installare ctg, aggiungere hook di sicurezza per Copilot, crittografare file dall'Explorer e aprire file .cott.age tramite il flusso di lavoro dell'editor.

Installala dal Visual Studio Marketplace, oppure compila e installala localmente da vscode-plugin-cottage.

Estensione per Cursor ed Eclipse

Scarica il file VSX e installalo nel tuo IDE Cursor o Eclipse. Funziona in modo simile all'estensione VS Code.

Plugin Vim

Usa il plugin cottage.vim per crittografare/decrittografare segreti da Vim o Neovim.

Integrazioni con Agenti AI

Tutte le integrazioni seguenti impediscono agli agenti AI di eseguire direttamente ctg/ctgx e di visualizzare o modificare file segreti: qualsiasi cosa dentro .cottage/, qualsiasi file *.cott.* (blob crittografati *.cott.age e anteprime oscurate *.cott.toml) e qualsiasi file decrittografato che abbia ancora una controparte *.cott.age su disco.

Integrazione con Claude Code

Se usi Claude Code, aggiungi .claude/settings.json e .claude/hooks/deny-secrets.py ai tuoi repository con segreti affinché le sessioni di Claude Code gestiscano i segreti in modo sicuro, oppure installa il plugin claude-plugin-cottage.

Integrazione con GitHub Copilot

Se usi GitHub Copilot in VS Code, aggiungi .github/hooks/ctg-policy.json e .github/hooks/scripts/deny_ctg_command.py ai tuoi repository con segreti affinché le sessioni di Copilot puliscano i file decrittografati, blocchino i comandi shell diretti ctg e blocchino l'accesso ai file segreti, oppure installa l'estensione vscode-plugin-cottage per configurarlo da VS Code.

VS Code carica anche le definizioni degli hook di .claude/settings.json. Se mantieni sia i file hook di Claude che quelli di Copilot nello stesso repository, assicurati di non eseguire accidentalmente lo stesso hook di pulizia due volte.

Integrazione con Codex

Se usi Codex, aggiungi .codex/hooks.json e .codex/hooks/deny-ctg.py ai tuoi repository con segreti affinché le sessioni di Codex gestiscano i segreti in modo sicuro, oppure installa il plugin codex-plugin-cottage.

Codex richiede che gli hook locali vengano revisionati prima di essere eseguiti. Dopo aver aggiunto i file, avvia Codex nel repository e usa /hooks per revisionare e fidarti degli hook del progetto.

Integrazione con Antigravity (agy)

Se usi Antigravity (agy), aggiungi .agents/hooks.json e .agents/scripts/deny-ctg.py ai tuoi repository con segreti affinché le sessioni di Antigravity gestiscano i segreti in modo sicuro, oppure installa il plugin agy-plugin-cottage.

Integrazione con Cursor

Se usi Cursor, aggiungi .cursor/hooks.json, .cursor/hooks/deny-ctg.py, .cursor/hooks/deny-read-secrets.py, .cursor/rules/deny-ctg.mdc e .cursorignore ai tuoi repository con segreti affinché le sessioni di Cursor gestiscano i segreti in modo sicuro.

Cursor richiede che gli hook vengano prima abilitati. Apri Cursor Settings > Hooks e abilita gli hook, quindi riavvia la sessione dell'agente affinché gli hook del progetto abbiano effetto. .cursorignore inoltre mantiene i file segreti fuori dall'indicizzazione di Cursor e dal contesto dell'Agente.

Avvio Rapido

Inizializza il progetto:

mkdir project && cd project

git init  # Opzionale, cottage funziona meglio con git ma non è richiesto
ctg init  # Configura la directory .cottage e i file necessari

tree -a
# .
# ├ .cottage/           <- Generato automaticamente da `ctg init`
# │ ├ identity        <- La tua chiave privata, tienila al sicuro. Spostala in `~/.config/cottage/identity` per usarla globalmente, oppure sostituiscila con un link simbolico a una delle tue chiavi private esistenti.
# │ └ recipients/     <- È qui che il tuo team tiene le chiavi pubbliche di tutti i destinatari.
# │     └ sayanarijit <- La tua chiave pubblica. Committala. Per usare una chiave pubblica esistente, copia (non creare un link simbolico) quella chiave qui.
# ├ .git/...
# ├ .gitattributes      <- Aggiunto `*.cott.age binary linguist-generated filter=cottage-encrypted -diff` per evitare di inquinare il git diff
# └ .gitignore          <- Aggiunto `/.cottage/identity` per ovvi motivi

# Puoi eseguire `ctg clean --all` in qualsiasi momento per ripulire tutto ciò che cottage ha mai fatto.

Crea o modifica un segreto:

# `ctg edit` decrittografa il file prima di aprirlo in $EDITOR e lo ricrittografa al salvataggio.
# Se il file decrittografato non era presente su disco prima di eseguire `ctg edit`, viene pulito dopo.
# Se era già presente, viene mantenuto su disco.
ctg edit secret.yml

# Usa `--clean` con `ctg edit` o `ctg encrypt` per garantire che i file decrittografati vengano eliminati anche se presenti prima
ctg edit secret.yml --clean    # Apre in $EDITOR, crittografa al salvataggio e pulisce
ctg encrypt secret.yml --clean # Crittografa secret.yml e pulisce
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml
#    edit .gitignore
# delete secret.yml

Esegui un comando con segreti decrittografati:

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

# `ctg run` (o la scorciatoia `ctgx`) decrittografa i segreti prima di eseguire il comando.
# Se i file decrittografati non erano presenti su disco in precedenza, vengono puliti automaticamente dopo che il comando termina.
# Se erano già presenti in precedenza, vengono mantenuti su disco.
ctg run -- kubectl apply -f secret.yml          # decrittografa secret.yml.cott.age in secret.yml ed esegue il comando
ctg run -- kubectl apply -f secret.yml.cott.age # sostituisce anche l'argomento del percorso con il percorso del file decrittografato
ctg run -- kubectl apply -f .                   # decrittografa tutti i file .cott.age in . ed esegue il comando
ctg run -- ./deploy.sh                          # decrittografa tutti i file .cott.age nel repository ed esegue il comando

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

# Usa `--clean` per garantire che i file decrittografati vengano puliti anche se erano presenti prima
ctg run --clean ./deploy.sh

Oppure usa la scorciatoia:

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

Esegui un comando con segreti iniettati come variabili d'ambiente, senza scrivere affatto su disco:

ctg env -- ./deploy.sh # Esporta i segreti da .env.cott.age (predefinito) senza scriverli su disco, poi esegue deploy.sh
ctg env -F .env.prod.cott.age -- ./deploy.sh # esporta da .env.prod.cott.age invece di .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # Supporta anche file non dotenv.

GitOps

Per condividere i tuoi segreti con i membri del team, basta fare push nel repository git.

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

Chiedi ai tuoi colleghi di aggiungere le loro chiavi pubbliche in .cottage/recipients e di fare push delle modifiche. Poi puoi fare pull e ricrittografare i segreti per loro.

git pull origin main

ctg decrypt --skip-verify-recipients  # Decrittografa i segreti mancanti per la ricrittografia
ctg encrypt                           # Ricrittografa tutti i segreti
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml

ctg clean  # opzionale
# delete secret.yml

# revisiona le modifiche, committa e fai push
git add .
git commit -m "Add new recipient to secrets"
git push origin main

Ora i tuoi colleghi possono fare pull delle ultime modifiche e decrittografare i segreti per conto proprio.

Git Hooks

Puoi usare prek o pre-commit per configurare git hooks che controllino/crittografino automaticamente i segreti prima del commit e li decrittografino dopo il checkout.

Vedi la configurazione prek di esempio qui.

Dopo aver aggiunto il file prek.toml, esegui:

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

Controllo degli Accessi

Regole

Nel file dei metadati, puoi annotare per quali destinatari il segreto deve essere crittografato. Questo ti permette di avere segreti diversi per ambienti diversi (es. staging vs produzione) e di crittografarli solo per i destinatari pertinenti.

# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"]  # Crittografa solo per sayanarijit

# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # Crittografa per tutti tranne sayanarijit

# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # Supporta pattern glob, crittografa solo per i destinatari in env/staging
deny = ["env/staging/badservice"]  # Crittografa per tutti in env/staging tranne badservice

Le regole di negazione hanno precedenza sulle regole di consenso.

Vedi la specifica dei metadati per maggiori dettagli.

Verifica

Puoi eseguire ctg verify in CI per verificare che i segreti crittografati e gli elenchi di destinatari corrispondano alle regole dei metadati, per prevenire manomissioni.

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

Qualsiasi Provider come Upstream

Con cottage, puoi sincronizzare i segreti con qualsiasi provider che abbia un'API, non solo git.

Per farlo, crea un file chiamato cottage.toml nella radice del progetto e configura le impostazioni upstream.

Vedi la cottage.toml di esempio qui e la configurazione upstream specifica per segreto qui.

Vedi un'implementazione di plugin di esempio qui.

Il flusso di lavoro è simile a git, ma invece di git pull e git push, esegui ctg pull e ctg push per sincronizzare i segreti con l'upstream configurato.

Esempio:

# Scarica le ultime modifiche nei segreti crittografati locali
# Simile a `git pull origin`
ctg pull myvault

# Confronta il diff con i segreti decrittografati locali
ctg diff

# Sincronizza i segreti decrittografati locali con i segreti crittografati locali
ctg sync

# Invia le modifiche dai segreti crittografati locali all'upstream
# Simile a `git push origin main`
ctg push myvault

Vedi la specifica della configurazione upstream per maggiori dettagli.

Plugin di esempio

Cottage supporta vari provider di plugin per sincronizzare i tuoi segreti. Script di plugin pronti all'uso sono disponibili nella directory examples/plugins:

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

Sincronizza con qualsiasi dispositivo

Usa Cottage Sync per sincronizzare i tuoi segreti tra i tuoi dispositivi e navigarli senza bisogno della CLI.

Scopri di Più

Vedi la directory examples per ulteriori esempi di utilizzo.

Risoluzione dei Problemi

# Vedi i log di debug con -v, -vv o -vvv
ctg run -vvv -- ./deploy.sh

Confronto

age vs Altri Sistemi di Crittografia

age usa un algoritmo moderno e semplice ottimizzato per la crittografia sicura dei file, con un focus su usabilità e superficie d'attacco minima. Supporta anche chiavi SSH RSA ed Ed25519, anche se si consiglia di usare chiavi diverse per scopi e ambiti separati.

cottage vs SOPS

Sebbene SOPS e cottage abbiano molte funzionalità sovrapposte, cottage ha i seguenti vantaggi:

Gestione automatica di .gitignore per garantire che i segreti non crittografati non vengano mai committati in git.
I segreti crittografati essendo file .age puramente crittografati con age, consentono una migliore interoperabilità con un ecosistema più ampio di strumenti.
Diff più puliti - a differenza di SOPS, che genera diff per ogni valore di ogni segreto, anche se la modifica effettiva è solo l'aggiunta/rimozione di un destinatario, cottage genera solo un diff per file, indicando esplicitamente la modifica nel checksum dei destinatari.

cottage vs dotenvx

cottage prende in prestito l'API ctg env da dotenvx.

Supporta qualsiasi tipo di file, non solo file dotenv.
Gestisce più segreti in un repository.
Regole di controllo degli accessi per crittografare segreti per destinatari specifici.
Diff più puliti - vedi cottage vs SOPS.

cottage vs agebox

agebox è molto simile a cottage nella filosofia di base ma manca di molte funzionalità.