cottage

cottage es una herramienta GitOps para equipos que gestionan 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, permitiendo al mismo tiempo compartirlos fácilmente mediante VCS. cottage también genera vistas previas redactadas 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.

1. Características
2. Instalación
3. Integraciones con editores
   1. Extensión para VS Code
   2. Extensión para Cursor y Eclipse
   3. Plugin para Vim
4. Integraciones con agentes de IA
   1. Integración con Claude Code
   2. Integración con GitHub Copilot
   3. Integración con Codex
   4. Integración con Antigravity (agy)
   5. Integración con Cursor
5. Inicio rápido
6. GitOps
7. Git Hooks
8. Control de acceso
   1. Reglas
   2. Verificación
9. Cualquier proveedor como upstream
   1. Plugins de ejemplo
10. Sincroniza con cualquier dispositivo
11. Aprende más
12. Solución de problemas
13. Comparación
    1. age vs Otros cifrados
    2. cottage vs SOPS
    3. cottage vs dotenvx
    4. cottage vs agebox

Características

• Seguro frente a 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, 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 redactadas 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 frente a sus contrapartes cifradas rastreadas.
• Verificación de checksum: 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 verificar/cifrar secretos automáticamente antes del commit y descifrarlos después del checkout.
• Flujo de trabajo de secretos persistentes: ctg decrypt/sync mantiene los secretos descifrados en el disco.
• Ciclo de vida de limpieza inteligente: ctg run (atajo ctgx) y ctg edit descifran los secretos antes de la operación, manteniéndolos en el disco si ya estaban presentes previamente o limpiándolos automáticamente después si no lo estaban.
• Limpieza al finalizar: , y garantizan que los archivos descifrados se eliminen del disco incluso si estaban presentes antes.

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 está 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 con editores

Extensión para VS Code

Usa la extensión de Cottage para VS Code para instalar ctg, añadir hooks de seguridad para 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.

Extensión para Cursor y Eclipse

Descarga el archivo VSX e instálalo en tu IDE Cursor o Eclipse. Funciona de forma similar a la extensión de VS Code.

Plugin para Vim

Usa el plugin cottage.vim para cifrar/descifrar secretos desde Vim o Neovim.

Integraciones con agentes de IA

Todas las integraciones siguientes evitan que los agentes de IA ejecuten ctg/ctgx directamente y que vean o editen archivos de secretos: cualquier cosa dentro de .cottage/, cualquier archivo *.cott.* (blobs cifrados *.cott.age y vistas previas redactadas *.cott.toml), y cualquier archivo descifrado que aún 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 shell ctg 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 los archivos de hooks de Claude y 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 estén habilitados 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 del indexado de Cursor y del contexto del Agente.

Inicio rápido

Inicia el proyecto:

mkdir project && cd project

git init  # Opcional, cottage funciona mejor con git pero no es obligatorio
ctg init  # Configura el directorio .cottage y los archivos necesarios

tree -a
# .
# ├ .cottage/           <- Generado automáticamente por `ctg init`
# │ ├ identity        <- Tu clave privada, mantenla segura. Muévela a `~/.config/cottage/identity` para usarla globalmente, o reemplázala con un enlace simbólico a una de tus claves privadas existentes.
# │ └ recipients/     <- Aquí es donde tu equipo mantiene las claves públicas de todos los destinatarios.
# │     └ sayanarijit <- Tu clave pública. Confírmala. Para usar una clave pública existente, simplemente copia (no uses enlace simbólico) esa clave aquí.
# ├ .git/...
# ├ .gitattributes      <- Se añadió `*.cott.age binary linguist-generated filter=cottage-encrypted -diff` para evitar contaminar el diff de git
# └ .gitignore          <- Se añadió `/.cottage/identity` por razones obvias

# Puedes ejecutar `ctg clean --all` en cualquier momento para limpiar todo lo que cottage haya hecho.

Crea o edita un secreto:

# `ctg edit` descifra el archivo antes de abrirlo en $EDITOR y lo vuelve a cifrar al guardar.
# Si el archivo descifrado no estaba presente en el disco antes de ejecutar `ctg edit`, se limpia después.
# Si ya estaba presente, se mantiene en el disco.
ctg edit secret.yml

# Usa `--clean` con `ctg edit` o `ctg encrypt` para garantizar que los archivos descifrados se eliminen incluso si estaban presentes antes
ctg edit secret.yml --clean    # Se abre en $EDITOR, se cifra al guardar y se limpia
ctg encrypt secret.yml --clean # Cifra secret.yml y limpia
# cifra secret.yml
#    en secret.yml.cott.age
#    edita secret.yml.cott.toml
#    edita .gitignore
# elimina secret.yml

Ejecuta un comando con secretos descifrados:

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

# `ctg run` (o el atajo `ctgx`) descifra los secretos antes de ejecutar el comando.
# Si los archivos descifrados no estaban presentes en el disco previamente, se limpian automáticamente después de que el comando termine.
# Si ya estaban presentes previamente, se mantienen en el disco.
ctg run -- kubectl apply -f secret.yml          # descifra secret.yml.cott.age a secret.yml y ejecuta el comando
ctg run -- kubectl apply -f secret.yml.cott.age # también reemplaza el argumento de la ruta con la ruta del archivo descifrado
ctg run -- kubectl apply -f .                   # descifra todos los archivos .cott.age en . y ejecuta el comando
ctg run -- ./deploy.sh                          # descifra todos los archivos .cott.age del repositorio y ejecuta el comando

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

# Usa `--clean` para garantizar que los archivos descifrados se limpien incluso si estaban presentes antes
ctg run --clean ./deploy.sh

O usa el atajo:

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

Ejecuta un comando con secretos inyectados como variables de entorno, sin escribir nada en el disco:

ctg env -- ./deploy.sh # Exporta los secretos de .env.cott.age (por defecto) sin escribirlos en el disco, luego ejecuta deploy.sh
ctg env -F .env.prod.cott.age -- ./deploy.sh # exporta desde .env.prod.cott.age en lugar de .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # También admite archivos que no son dotenv.

GitOps

Para compartir tus secretos con los miembros del equipo, simplemente haz push al repositorio git.

git add .
git commit -m "Añadir 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 decrypt --skip-verify-recipients  # Descifra los secretos que faltan para volver a cifrarlos
ctg encrypt                           # Vuelve a cifrar todos los secretos
# cifra secret.yml
#    en secret.yml.cott.age
#    edita secret.yml.cott.toml

ctg clean  # opcional
# elimina secret.yml

# revisa los cambios, haz commit y push
git add .
git commit -m "Añadir nuevo destinatario a los secretos"
git push origin main

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

Git Hooks

Puedes usar prek o pre-commit para configurar git hooks que verifiquen/cifren secretos automáticamente antes del commit y los descifren después del checkout.

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

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 vs producción) y cifrarlos solo para los destinatarios relevantes.

# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"]  # Solo cifrar para sayanarijit

# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # Cifrar para todos excepto sayanarijit

# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # Admite patrones glob, solo cifrar para destinatarios en env/staging
deny = ["env/staging/badservice"]  # Cifrar para todos en env/staging excepto badservice

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

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 coincidan con las reglas de metadatos, para 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 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 los secretos con el upstream configurado.

Ejemplo:

# Trae los últimos cambios a los secretos cifrados locales
# Similar a `git pull origin`
ctg pull myvault

# Compara el diff con los secretos descifrados locales
ctg diff

# Sincroniza los secretos descifrados locales con los secretos cifrados locales
ctg sync

# Envía los cambios de los secretos cifrados locales al upstream
# Similar a `git push origin main`
ctg push myvault

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

Plugins de ejemplo

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

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

Sincroniza con cualquier dispositivo

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

Aprende más

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

Solución de problemas

# Consulta los registros de depuración con -v, -vv o -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

Si bien SOPS y cottage tienen muchas características superpuestas, 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, 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 el checksum 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.