cottage v0.7.0 — 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 os segredos fora do repositório, ao mesmo tempo que permite compartilhamento fácil via VCS. O cottage também gera visualizações redigidas 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.

Demo de Introdução

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.
Visualizações: Gera visualizações redigidas 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: Previne 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 de segredos persistentes: ctg decrypt/sync mantém segredos descriptografados no disco.
Ciclo de vida inteligente de limpeza: ctg run (atalho ctgx) e ctg edit descriptografam segredos antes da operação, mantendo-os no disco se já estivessem presentes anteriormente ou limpando-os automaticamente depois se 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 estivessem 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.
Limpeza: ctg clean exclui todos os segredos descriptografados do repositório local para permitir que você execute 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 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 VS Code do Cottage para instalar 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 Cursor e Eclipse

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

Plugin Vim

Use o plugin cottage.vim para criptografar/descriptografar segredos a partir do Vim ou Neovim.

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 visualizações redigidas *.cott.toml), e qualquer arquivo descriptografado que ainda tenha uma contraparte *.cott.age no disco.

Integração 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 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 shell ctg diretos 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 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 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 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 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 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 Configurações do Cursor > Hooks e habilite os hooks, depois reinicie a sessão do agente para que os hooks do projeto entrem em vigor. O .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  # Opcional, cottage funciona melhor com git, mas não é obrigatório
ctg init  # Configura o diretório .cottage e os arquivos necessários

tree -a
# .
# ├ .cottage/           <- Gerado automaticamente por `ctg init`
# │ ├ identity        <- Sua chave privada, mantenha-a segura. Mova-a para `~/.config/cottage/identity` para usá-la globalmente, ou substitua-a por um link simbólico para uma de suas chaves privadas existentes.
# │ └ recipients/     <- É aqui que sua equipe mantém as chaves públicas de todos os destinatários.
# │     └ sayanarijit <- Sua chave pública. Faça commit dela. Para usar uma chave pública existente, basta copiar (não usar link simbólico) essa chave aqui.
# ├ .git/...
# ├ .gitattributes      <- Adicionado `*.cott.age binary linguist-generated filter=cottage-encrypted -diff` para evitar poluir o git diff
# └ .gitignore          <- Adicionado `/.cottage/identity` por razões óbvias

# Você pode executar `ctg clean --all` a qualquer momento para limpar tudo que o cottage já fez.

Crie ou edite um segredo:

# `ctg edit` descriptografa o arquivo antes de abrir no $EDITOR e re-criptografa ao salvar.
# Se o arquivo descriptografado não estava presente no disco antes de executar `ctg edit`, ele é limpo depois.
# Se já estava presente, ele é mantido no disco.
ctg edit secret.yml

# Use `--clean` com `ctg edit` ou `ctg encrypt` para garantir que arquivos descriptografados sejam excluídos mesmo se presentes antes
ctg edit secret.yml --clean    # Abre no $EDITOR, criptografa ao salvar e limpa
ctg encrypt secret.yml --clean # Criptografa secret.yml e limpa
# criptografa secret.yml
#    em secret.yml.cott.age
#    edita secret.yml.cott.toml
#    edita .gitignore
# exclui secret.yml

Execute um comando com segredos descriptografados:

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

# `ctg run` (ou o atalho `ctgx`) descriptografa segredos antes de executar o comando.
# Se os arquivos descriptografados não estavam presentes no disco antes, eles são automaticamente limpos após o comando terminar.
# Se já estavam presentes antes, eles são mantidos no disco.
ctg run -- kubectl apply -f secret.yml          # descriptografa secret.yml.cott.age para secret.yml e executa o comando
ctg run -- kubectl apply -f secret.yml.cott.age # também substitui o argumento do caminho pelo caminho do arquivo descriptografado
ctg run -- kubectl apply -f .                   # descriptografa todos os arquivos .cott.age em . e executa o comando
ctg run -- ./deploy.sh                          # descriptografa todos os arquivos .cott.age no repositório e executa o comando

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

# Use `--clean` para garantir que arquivos descriptografados sejam limpos mesmo se estivessem presentes antes
ctg run --clean ./deploy.sh

Ou use o atalho:

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

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

ctg env -- ./deploy.sh # Exporta segredos de .env.cott.age (padrão) sem gravá-los no disco, depois executa deploy.sh
ctg env -F .env.prod.cott.age -- ./deploy.sh # exporta de .env.prod.cott.age em vez de .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # Também suporta arquivos que não são dotenv.

GitOps

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

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

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

git pull origin main

ctg decrypt --skip-verify-recipients  # Descriptografa segredos ausentes para re-criptografia
ctg encrypt                           # Re-criptografa todos os segredos
# criptografa secret.yml
#    em secret.yml.cott.age
#    edita secret.yml.cott.toml

ctg clean  # opcional
# exclui secret.yml

# revise as alterações, faça commit e push
git add .
git commit -m "Adicionar novo destinatário aos segredos"
git push origin main

Agora seus colegas de equipe podem fazer pull das alterações mais recentes e descriptografar os segredos para si mesmos.

Git Hooks

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

Veja a configuração de exemplo 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 (ex.: staging vs produção) e criptografá-los apenas para os destinatários relevantes.

# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"]  # Criptografa apenas para sayanarijit

# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # Criptografa para todos exceto sayanarijit

# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # Suporta padrões glob, criptografa apenas para destinatários em env/staging
deny = ["env/staging/badservice"]  # Criptografa para todos em env/staging exceto 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 no CI para verificar se os segredos criptografados e as listas de destinatários correspondem às regras de metadados, prevenindo 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 configurações de upstream.

Veja o exemplo de cottage.toml aqui e a configuração de upstream específica de segredo 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:

# Baixa as alterações mais recentes para segredos criptografados locais
# Semelhante a `git pull origin`
ctg pull myvault

# Compara o diff com segredos descriptografados locais
ctg diff

# Sincroniza segredos descriptografados locais com segredos criptografados locais
ctg sync

# Envia alterações de segredos criptografados locais para o upstream
# Semelhante a `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 plugin 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 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

# Veja logs de depuração com -v, -vv ou -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 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 puramente 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 alteração 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

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

Ler mais