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

The cottage logo

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 os segredos fora do repositório, permitindo ainda o compartilhamento fácil via VCS. O cottage também gera pré-visualizações censuradas de segredos criptografados para melhor visibilidade e suporta fluxos de trabalho de descriptografia persistentes e temporários, garantindo que os segredos nunca sejam commitados em texto simples.

Intro Demo

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

Recursos

Seguro contra 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 (destinatários) no repositório, mantenha chaves privadas (identidades) locais.
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é-visualizações: Gera pré-visualizações censuradas com timestamp de 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 que 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 de segredos persistentes: ctg decrypt/sync mantém segredos descriptografados no disco.
Ciclo de vida de limpeza inteligente: ctg run (atalho ctgx) e ctg edit descriptografam segredos antes da operação, mantendo-os no disco se já estavam presentes antes ou limpando-os automaticamente depois, caso não estivessem.
Limpeza ao concluir: ctg encrypt --clean, ctg run --clean e ctg edit --clean garantem que arquivos descriptografados sejam removidos do disco mesmo se já estavam presentes antes.
Fluxo de trabalho de injeção de ambiente: ctg env injeta segredos descriptografados como variáveis de ambiente para executar um comando, sem gravá-los no disco.
Piping seguro de segredos: ctg cat PATH descriptografa em memória e imprime na stdout para piping direto via stdin para outras ferramentas.
Limpeza: ctg clean exclui todos os segredos descriptografados do repositório local para que você possa 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 uma API como upstream e começar a 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 o 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 para 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 pelo Visual Studio Marketplace, ou compile e instale localmente a partir de vscode-plugin-cottage.

Extensão para Cursor e Eclipse

Baixe o arquivo VSX e instale-o no seu Cursor ou Eclipse IDE. Funciona de forma semelhante à extensão para VS Code.

Plugin para Vim

Use o plugin cottage.vim para criptografar/descriptografar segredos no Vim ou Neovim.

Integrações com Agentes de IA

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

Integração com Claude Code

Se você usa o 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 o 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 shell diretos do ctg e bloqueiem o 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 de .claude/settings.json. Se você mantiver os 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 o 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 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 o 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 o 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, depois reinicie a sessão do agente para que os hooks do projeto entrem em vigor. O .cursorignore também mantém arquivos de segredos fora da indexação do Cursor e do contexto do Agente.

Início Rápido

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

Crie ou edite um segredo:

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

Execute um comando com segredos descriptografados:

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

Ou use o atalho:

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

Leia e faça pipe de um segredo descriptografado sem gravá-lo no disco:

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

Execute um comando com segredos injetados como variáveis de ambiente, sem gravar 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 para o 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 últimas alterações e descriptografar os segredos por conta própria.

Git Hooks

Você pode usar prek ou pre-commit para configurar git hooks que verificam/criptografam segredos automaticamente antes do commit e os descriptografam após o checkout.

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

Após 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 (por exemplo, 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.

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

Verificação

Você pode executar ctg verify na CI para verificar que os segredos criptografados e as listas de destinatários correspondem às regras de metadados, para prevenir 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 o 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 de segredo aqui.

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

O fluxo de trabalho é semelhante ao do 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

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

Plugins de exemplo

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
GitHub Secrets
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

Veja 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

O 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 o SOPS e o cottage tenham muitos recursos sobrepostos, o cottage tem as seguintes vantagens:

Gerencia automaticamente o .gitignore para garantir que segredos não criptografados nunca sejam commitados no git.
Segredos criptografados sendo arquivos .age puros criptografados com age, permite 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 que a alteração real seja apenas adicionar/remover um destinatário, o cottage gera apenas um diff por arquivo, apontando explicitamente a mudança no checksum dos destinatários.

cottage vs dotenvx

O cottage empresta a API ctg env do dotenvx.

Suporta qualquer tipo de arquivo, não apenas arquivos dotenv.
Gerencia múltiplos 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

O agebox é muito semelhante ao cottage em filosofia central, mas carece de muitos recursos.

Ler mais