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

El logotipo de cottage

cottage es una herramienta GitOps para que los equipos gestionen secretos cifrados con age en repositorios git.

Proporciona un flujo de trabajo sencillo para cifrar/descifrar secretos, gestionar destinatarios y mantener los secretos fuera del repositorio, a la vez que permite compartirlos fácilmente mediante VCS. cottage también genera vistas previas censuradas de los secretos cifrados para una mejor visibilidad y admite flujos de trabajo de descifrado tanto persistentes como temporales, garantizando que los secretos nunca se confirmen en texto plano.

Demo de introducción

Características
Instalación
Integraciones de Editor
1. Extensión de VS Code
Integraciones con Agentes de IA
Inicio Rápido
GitOps
Git Hooks
Control de Acceso
1. Reglas
2. Verificación
Cualquier Proveedor como Upstream
1. Plugins de ejemplo
Sincronización con cualquier dispositivo
Más Información
Solución de problemas
Comparación

Características

Seguro contra exposiciones: Utiliza el sistema de tipos de Rust para garantizar que los errores nunca puedan exponer secretos accidentalmente.
Pensado para equipos: Comparte claves públicas (destinatarios) en el repositorio y mantén las claves privadas (identidades) de forma local.
Control de Acceso: Reglas simples de permitir/denegar para controlar qué secretos se cifran para qué destinatarios.
Gestiona .gitignore: Actualiza automáticamente .gitignore para mantener los secretos sin cifrar fuera del repositorio.
Vistas previas: Genera vistas previas censuradas con marca de tiempo de los secretos cifrados para una mejor visibilidad.
Diffs enriquecidos: Mantiene el diff de git limpio y revisable, mientras que ctg diff muestra el diff de los secretos modificados localmente con sus contrapartes cifradas rastreadas.
Verificación de suma de comprobación: Evita la manipulación verificando que los secretos cifrados y las listas de destinatarios coincidan con los metadatos.
Git hooks: Configura fácilmente git hooks para comprobar/cifrar secretos automáticamente antes del commit y descifrarlos después del checkout.
Flujo de trabajo de secretos persistentes: ctg decrypt/edit/sync mantiene los secretos descifrados en el disco.
Flujo de trabajo de secretos temporales: ctg run (atajo ctgx) descifra secretos temporalmente para ejecutar un comando y luego los elimina, independientemente de que el comando tenga éxito o falle.
Flujo de trabajo de inyección de entorno: ctg env inyecta secretos descifrados como variables de entorno para ejecutar un comando, sin escribirlos en el disco en absoluto.
Limpieza: ctg clean elimina todos los secretos descifrados del repositorio local para que puedas ejecutar tus agentes de IA con un poco menos de preocupación.
Compatibilidad con jj y directorios que no son git: ctg init convierte cualquier directorio en un almacén de secretos.
Sincronización con cualquier proveedor: Te permite configurar cualquier proveedor con una API como upstream y empezar a usar ctg pull/diff/push como git pull/diff/push.
Sincronización con cualquier dispositivo: Los secretos cifrados con cottage y gestionados en un repositorio git se pueden sincronizar entre dispositivos con Cottage Sync.

Instalación

# 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

También disponible como imágenes docker:

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

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

O descarga la última versión desde GitHub.

Integraciones de Editor

Extensión de VS Code

Utiliza la extensión Cottage para VS Code para instalar ctg, añadir hooks de seguridad de Copilot, cifrar archivos desde el Explorador y abrir archivos .cott.age mediante el flujo de trabajo del editor.

Instálala desde el Visual Studio Marketplace, o compílala e instálala localmente desde vscode-plugin-cottage.

Integraciones con Agentes de IA

Todas las integraciones siguientes impiden que los agentes de IA ejecuten ctg/ctgx directamente y que vean o editen archivos de secretos: cualquier elemento dentro de .cottage/, cualquier archivo *.cott.* (blobs cifrados *.cott.age y vistas previas censuradas *.cott.toml), y cualquier archivo descifrado que todavía tenga una contraparte *.cott.age en el disco.

Integración con Claude Code

Si usas Claude Code, añade .claude/settings.json y .claude/hooks/deny-secrets.py a tus repositorios con secretos para que las sesiones de Claude Code gestionen los secretos de forma segura, o instala el plugin claude-plugin-cottage.

Integración con GitHub Copilot

Si usas GitHub Copilot en VS Code, añade .github/hooks/ctg-policy.json y .github/hooks/scripts/deny_ctg_command.py a tus repositorios con secretos para que las sesiones de Copilot limpien los archivos descifrados, bloqueen los comandos directos de ctg en el shell y bloqueen el acceso a los archivos de secretos, o instala la extensión vscode-plugin-cottage para configurarlo desde VS Code.

VS Code también carga las definiciones de hooks de .claude/settings.json. Si mantienes tanto los archivos de hooks de Claude como los de Copilot en el mismo repositorio, asegúrate de no ejecutar accidentalmente el mismo hook de limpieza dos veces.

Integración con Codex

Si usas Codex, añade .codex/hooks.json y .codex/hooks/deny-ctg.py a tus repositorios con secretos para que las sesiones de Codex gestionen los secretos de forma segura, o instala el plugin codex-plugin-cottage.

Codex requiere que los hooks locales se revisen antes de ejecutarse. Después de añadir los archivos, inicia Codex en el repositorio y usa /hooks para revisar y confiar en los hooks del proyecto.

Integración con Antigravity (agy)

Si usas Antigravity (agy), añade .agents/hooks.json y .agents/scripts/deny-ctg.py a tus repositorios con secretos para que las sesiones de Antigravity gestionen los secretos de forma segura, o instala el plugin agy-plugin-cottage.

Integración con Cursor

Si usas Cursor, añade .cursor/hooks.json, .cursor/hooks/deny-ctg.py, .cursor/hooks/deny-read-secrets.py, .cursor/rules/deny-ctg.mdc y .cursorignore a tus repositorios con secretos para que las sesiones de Cursor gestionen los secretos de forma segura.

Cursor requiere que los hooks se habiliten primero. Abre Cursor Settings > Hooks y habilita los hooks, luego reinicia la sesión del agente para que los hooks del proyecto surtan efecto. .cursorignore además mantiene los archivos de secretos fuera de la indexación de Cursor y del contexto del Agente.

Inicio Rápido

Inicializar proyecto:

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.

Crear o editar un secreto.

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

Ejecutar un comando con secretos descifrados temporales:

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

O usar el atajo:

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

Ejecutar un comando con secretos inyectados como variables de entorno, sin escribir nada en el 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 compartir tus secretos con los miembros del equipo, simplemente haz push al repositorio git.

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

Pide a tus compañeros que añadan sus claves públicas a .cottage/recipients y hagan push de los cambios. Luego puedes hacer pull y volver a cifrar los secretos para ellos.

git pull origin main

ctg sync  # or `ctg decrypt && ctg encrypt`
# 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

Ahora tus compañeros pueden hacer pull de los últimos cambios y descifrar los secretos ellos mismos.

Git Hooks

Puedes usar prek o pre-commit para configurar git hooks y comprobar/cifrar secretos automáticamente antes del commit y descifrarlos después del checkout.

Consulta aquí la configuración de ejemplo de prek.

Después de añadir el archivo prek.toml, ejecuta:

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

Control de Acceso

Reglas

En el archivo de metadatos, puedes anotar para qué destinatarios debe cifrarse el secreto. Esto te permite tener diferentes secretos para diferentes entornos (por ejemplo, staging frente a producción) y cifrarlos solo para los destinatarios 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

Las reglas de denegación tienen prioridad sobre las reglas de permiso.

Consulta la especificación de metadatos para más detalles.

Verificación

Puedes ejecutar ctg verify en CI para verificar que los secretos cifrados y las listas de destinatarios coinciden con las reglas de metadatos, y así evitar manipulaciones.

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

Cualquier Proveedor como Upstream

Con cottage, puedes sincronizar secretos con cualquier proveedor que tenga una API, no solo con git.

Para ello, crea un archivo llamado cottage.toml en la raíz del proyecto y configura los ajustes del upstream.

Consulta el ejemplo de cottage.toml aquí y la configuración de upstream específica para secretos aquí.

Consulta una implementación de plugin de ejemplo aquí.

El flujo de trabajo es similar al de git, pero en lugar de git pull y git push, ejecutas ctg pull y ctg push para sincronizar secretos con el upstream configurado.

Ejemplo:

# 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

Consulta la especificación de configuración de upstream para más detalles.

Plugins de ejemplo

Cottage admite varios proveedores de plugins para sincronizar tus secretos. Hay scripts de plugin listos para usar disponibles en el directorio examples/plugins:

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

Sincronización con cualquier dispositivo

Usa Cottage Sync para sincronizar tus secretos entre tus dispositivos y navegar sin necesidad de la CLI.

Más Información

Consulta el directorio examples para más ejemplos de uso.

Solución de problemas

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

Comparación

age vs Otros Cifrados

age utiliza un algoritmo moderno y simple optimizado para el cifrado seguro de archivos, con un enfoque en la usabilidad y una superficie de ataque mínima. También admite claves SSH RSA y Ed25519, aunque se recomienda usar claves diferentes para propósitos y ámbitos separados.

cottage vs SOPS

Aunque SOPS y cottage comparten muchas características, cottage tiene las siguientes ventajas:

Gestiona automáticamente .gitignore para garantizar que los secretos sin cifrar nunca se confirmen en git.
Al ser los secretos cifrados archivos .age puramente cifrados con age, se permite una mejor interoperabilidad con un ecosistema más amplio de herramientas.
Diffs más limpios: a diferencia de SOPS, que genera diffs para cada valor de cada secreto, incluso si el cambio real es solo añadir/eliminar un destinatario, cottage solo genera un diff por archivo, señalando explícitamente el cambio en la suma de comprobación de los destinatarios.

cottage vs dotenvx

cottage toma prestada la API ctg env de dotenvx.

Admite cualquier tipo de archivo, no solo archivos dotenv.
Gestiona múltiples secretos en un repositorio.
Reglas de control de acceso para cifrar secretos para destinatarios específicos.
Diffs más limpios: consulta cottage vs SOPS.

cottage vs agebox

agebox es muy similar a cottage en su filosofía central, pero carece de muchas características.