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

O logotipo do cottage

cottage é uma ferramenta GitOps para equipes gerenciarem segredos criptografados com age em repositórios git.

Ela fornece um fluxo de trabalho simples para criptografar/descriptografar segredos, gerenciar destinatários e manter segredos fora do repositório enquanto ainda permite compartilhamento fácil via VCS. cottage também gera prévias redigidas dos segredos criptografados para melhor visibilidade e suporta fluxos de trabalho de descriptografia persistente e temporária, garantindo que segredos nunca sejam commitados em texto puro.

Demonstração de Introdução

Recursos
Instalação
Integrações com Editores
1. Extensão VS Code
Integrações com Agentes de IA
Início Rápido
GitOps
Hooks do Git
Controle de Acesso
1. Regras
2. Verificação
Qualquer Provedor como Upstream
1. Exemplos de plugins
Sincronize com qualquer dispositivo
Saiba Mais
Solução de Problemas
Comparação

Recursos

À prova de exposição: Usa o sistema de tipos do Rust para garantir que bugs nunca exponham segredos acidentalmente.
Amigável para equipes: Compartilhe chaves públicas (recipients) no repositório, mantenha chaves privadas (identities) localmente.
Controle de Acesso: Regras simples de permitir/negar para controlar quais segredos são criptografados para quais destinatários.
Gerencia .gitignore: Atualiza automaticamente o .gitignore para manter segredos não criptografados fora do repositório.
Prévias: Gera prévias redigidas com carimbo de data/hora dos segredos criptografados para melhor visibilidade.
Diffs ricos: Mantém o git diff limpo e revisável, enquanto ctg diff mostra o diff de segredos modificados localmente com suas contrapartes criptografadas rastreadas.
Verificação de checksum: Impede adulteração verificando se os segredos criptografados e as listas de destinatários correspondem aos metadados.
Git hooks: Configure facilmente git hooks para verificar/criptografar segredos automaticamente antes do commit e descriptografá-los após o checkout.
Fluxo de trabalho com segredos persistentes: ctg decrypt/edit/sync mantém os segredos descriptografados no disco.
Fluxo de trabalho com segredos temporários: ctg run (atalho ctgx) descriptografa segredos temporariamente para executar um comando, depois os exclui, independentemente do sucesso ou falha do comando.
Fluxo de trabalho com injeção de ambiente: ctg env injeta segredos descriptografados como variáveis de ambiente para executar um comando, sem gravá-los no disco.
Limpeza: ctg clean exclui todos os segredos descriptografados do repositório local para você executar seus agentes de IA com um pouco menos de preocupação.
Suporta jj e diretórios não-git: ctg init transforma qualquer diretório em um armazenamento de segredos.
Sincronize com qualquer provedor: Permite configurar qualquer provedor com API como upstream e usar ctg pull/diff/push como git pull/diff/push.
Sincronize com qualquer dispositivo: Segredos criptografados com cottage e gerenciados em um repositório git podem ser sincronizados entre dispositivos com Cottage Sync.

Instalação

# 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

Também disponível como imagens docker:

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

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

Ou baixe a versão mais recente do GitHub.

Integrações com Editores

Extensão VS Code

Use a extensão Cottage para VS Code para instalar o ctg, adicionar hooks de segurança do Copilot, criptografar arquivos pelo Explorer e abrir arquivos .cott.age através do fluxo de trabalho do editor.

Instale-a pela Visual Studio Marketplace, ou compile e instale localmente a partir do vscode-plugin-cottage.

Integrações com Agentes de IA

Todas as integrações abaixo impedem que agentes de IA executem ctg/ctgx diretamente e visualizem ou editem arquivos de segredos: qualquer coisa dentro de .cottage/, qualquer arquivo *.cott.* (blobs criptografados *.cott.age e prévias redigidas *.cott.toml), e qualquer arquivo descriptografado que ainda tenha uma contraparte *.cott.age no disco.

Integração com Claude Code

Se você usa Claude Code, adicione .claude/settings.json e .claude/hooks/deny-secrets.py aos seus repositórios com segredos para que as sessões do Claude Code lidem com segredos com segurança, ou instale o plugin claude-plugin-cottage.

Integração com GitHub Copilot

Se você usa GitHub Copilot no VS Code, adicione .github/hooks/ctg-policy.json e .github/hooks/scripts/deny_ctg_command.py aos seus repositórios com segredos para que as sessões do Copilot limpem arquivos descriptografados, bloqueiem comandos ctg diretos no shell e bloqueiem acesso a arquivos de segredos, ou instale a extensão vscode-plugin-cottage para configurar isso pelo VS Code.

O VS Code também carrega as definições de hooks do .claude/settings.json. Se você mantiver arquivos de hooks do Claude e do Copilot no mesmo repositório, certifique-se de não executar acidentalmente o mesmo hook de limpeza duas vezes.

Integração com Codex

Se você usa Codex, adicione .codex/hooks.json e .codex/hooks/deny-ctg.py aos seus repositórios com segredos para que as sessões do Codex lidem com segredos com segurança, ou instale o plugin codex-plugin-cottage.

O Codex exige que os hooks locais sejam revisados antes de serem executados. Após adicionar os arquivos, inicie o Codex no repositório e use /hooks para revisar e confiar nos hooks do projeto.

Integração com Antigravity (agy)

Se você usa Antigravity (agy), adicione .agents/hooks.json e .agents/scripts/deny-ctg.py aos seus repositórios com segredos para que as sessões do Antigravity lidem com segredos com segurança, ou instale o plugin agy-plugin-cottage.

Integração com Cursor

Se você usa Cursor, adicione .cursor/hooks.json, .cursor/hooks/deny-ctg.py, .cursor/hooks/deny-read-secrets.py, .cursor/rules/deny-ctg.mdc e .cursorignore aos seus repositórios com segredos para que as sessões do Cursor lidem com segredos com segurança.

O Cursor exige que os hooks sejam habilitados primeiro. Abra Cursor Settings > Hooks e habilite os hooks; em seguida, reinicie a sessão do agente para que os hooks do projeto entrem em vigor. .cursorignore adicionalmente mantém arquivos de segredos fora da indexação do Cursor e do contexto do agente.

Início Rápido

Inicie o projeto:

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.

Crie ou edite um segredo.

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

Execute um comando com segredos descriptografados temporários:

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

Ou use o atalho:

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

Execute um comando com segredos injetados como variáveis de ambiente, sem gravar nada no disco:

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

Para compartilhar seus segredos com membros da equipe, basta fazer push no repositório git.

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

Peça aos seus colegas de equipe para adicionar suas chaves públicas em .cottage/recipients e fazer push das alterações. Depois você pode fazer pull e re-criptografar os segredos para eles.

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

Agora seus colegas de equipe podem fazer pull das alterações mais recentes e descriptografar os segredos por conta própria.

Hooks do Git

Você pode usar prek ou pre-commit para configurar git hooks e verificar/criptografar segredos automaticamente antes do commit e descriptografá-los após o checkout.

Veja a configuração de exemplo do prek aqui.

Depois de adicionar o arquivo prek.toml, execute:

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

Controle de Acesso

Regras

No arquivo de metadados, você pode anotar para quais destinatários o segredo deve ser criptografado. Isso permite ter segredos diferentes para ambientes diferentes (ex.: staging vs produção) e criptografá-los apenas para os destinatários relevantes.

# 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

Regras de negação têm precedência sobre regras de permissão.

Consulte a especificação de metadados para mais detalhes.

Verificação

Você pode executar ctg verify na CI para verificar se os segredos criptografados e as listas de destinatários correspondem às regras de metadados, a fim de impedir adulteração.

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

Qualquer Provedor como Upstream

Com cottage, você pode sincronizar segredos com qualquer provedor que tenha uma API, não apenas git.

Para isso, crie um arquivo chamado cottage.toml na raiz do projeto e configure as definições de upstream.

Veja o exemplo de cottage.toml aqui e a configuração de upstream específica para segredos aqui.

Veja uma implementação de plugin de exemplo aqui.

O fluxo de trabalho é semelhante ao git, mas em vez de git pull e git push, você executa ctg pull e ctg push para sincronizar segredos com o upstream configurado.

Exemplo:

# 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

Consulte a especificação de configuração de upstream para mais detalhes.

Exemplos de plugins

O cottage suporta vários provedores de plugins para sincronizar seus segredos. Scripts de plugins prontos para uso estão disponíveis no diretório examples/plugins:

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

Sincronize com qualquer dispositivo

Use o Cottage Sync para sincronizar seus segredos entre seus dispositivos e navegar sem precisar da CLI.

Saiba Mais

Consulte o diretório examples para mais exemplos de uso.

Solução de Problemas

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

Comparação

age vs Outras Criptografias

age usa um algoritmo moderno e simples, otimizado para criptografia segura de arquivos, com foco em usabilidade e superfície de ataque mínima. Ele também suporta chaves SSH RSA e Ed25519, embora seja recomendado usar chaves diferentes para propósitos e escopos separados.

cottage vs SOPS

Embora SOPS e cottage tenham muitos recursos em comum, cottage tem as seguintes vantagens:

Gerencia automaticamente o .gitignore para garantir que segredos não criptografados nunca sejam commitados no git.
Por serem arquivos .age criptografados puramente com age, os segredos criptografados permitem melhor interoperabilidade com um ecossistema mais amplo de ferramentas.
Diffs mais limpos - ao contrário do SOPS, que gera diffs para cada valor de cada segredo, mesmo se a mudança real for apenas adicionar/remover um destinatário, cottage gera apenas um diff por arquivo, apontando explicitamente a mudança no checksum dos destinatários.

cottage vs dotenvx

cottage aproveita a API ctg env do dotenvx.

Suporta qualquer tipo de arquivo, não apenas arquivos dotenv.
Gerencia vários segredos em um repositório.
Regras de controle de acesso para criptografar segredos para destinatários específicos.
Diffs mais limpos - veja cottage vs SOPS.

cottage vs agebox

agebox é muito semelhante ao cottage na filosofia central, mas não tem muitos recursos.

Ler mais