Un moderno gestor de secretos cifrados con age basado en git para equipos.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://s13.gifyu.com/images/b7mxd.webp">
<source media="(prefers-color-scheme: light)" srcset="https://s13.gifyu.com/images/b7mxl.webp">
<img alt="El logotipo de cottage" width="600" src="https://assets.kitploit.com/production/public/readmes/7490/2c8e4c6f8fa352cb9dcf2d8f22c3d84926c09a69fca9a6632d008c61b5417c28.webp">
</picture>
</p>
[](https://github.com/sayanarijit/cottage/actions/workflows/cottage-verify.yml)
[](https://crates.io/crates/cottage)
[](https://pypi.org/project/cottage/)
[](https://www.npmjs.com/package/@sayanarijit/cottage)
[](https://hub.docker.com/r/sayanarijit/cottage)
**cott*age*** es una herramienta GitOps para que los equipos gestionen secretos [cifrados con age](https://age-encryption.org/) 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 a través de 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.
1. [Características](#features)
2. [Instalación](#installation)
3. [Integraciones con editores](#editor-integrations)
1. [Extensión de VS Code](#vs-code-extension)
2. [Extensión para Cursor y Eclipse](#cursor-and-eclipse-extension)
3. [Plugin de Vim](#vim-plugin)
4. [Integraciones con agentes de IA](#ai-agent-integrations)
1. [Integración con Claude Code](#claude-code-integration)
2. [Integración con GitHub Copilot](#github-copilot-integration)
3. [Integración con Codex](#codex-integration)
4. [Integración con Antigravity (agy)](https://github.com/sayanarijit/cottage/blob/main/%3C#antigravity-(agy)-integration>)
5. [Integración con Cursor](#cursor-integration)
5. [Inicio rápido](#quick-start)
6. [GitOps](#gitops)
7. [Git Hooks](#git-hooks)
8. [Control de acceso](#access-control)
1. [Reglas](#rules)
2. [Verificación](#verification)
9. [Cualquier proveedor como upstream](#any-provider-as-upstream)
1. [Plugins de ejemplo](#example-plugins)
10. [Sincronizar con cualquier dispositivo](#sync-with-any-device)
11. [Más información](#learn-more)
12. [Solución de problemas](#troubleshooting)
13. [Comparación](#comparison)
1. [age vs otros cifrados](#age-vs-other-encryption)
2. [cottage vs SOPS](#cottage-vs-sops)
3. [cottage vs dotenvx](#cottage-vs-dotenvx)
4. [cottage vs agebox](#cottage-vs-agebox)
## Características
- **A prueba de exposiciones**: Utiliza el sistema de tipos de Rust para asegurar que los errores nunca puedan exponer secretos accidentalmente.
- **Apto para equipos**: Comparte claves públicas (destinatarios) en el repositorio, mantén las claves privadas (identidades) en local.
- **Control de acceso**: Reglas sencillas 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 git diff limpio y revisable, mientras que `ctg diff` muestra el diff de los secretos modificados localmente con sus contrapartes cifradas rastreadas.
- **Verificación de checksum**: Evita manipulaciones 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/sync` mantiene los secretos descifrados en 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 disco si ya estaban presentes de antemano o limpiándolos automáticamente después si no lo estaban.
- **Limpieza al finalizar**: `ctg encrypt --clean`, `ctg run --clean` y `ctg edit --clean` garantizan que los archivos descifrados se limpien del disco incluso si ya estaban presentes antes.
- **Flujo de trabajo de inyección de entorno**: `ctg env` inyecta los secretos descifrados como variables de entorno para ejecutar un comando, sin escribirlos en disco en absoluto.
- **Tubería segura de secretos**: `ctg cat PATH` descifra en memoria e imprime a stdout para canalizar directamente por stdin a otras herramientas.
- **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.
- **Compatible con jj y directorios no 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](https://cottage-sync.github.io).
## Instalación
```bash
# 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:
```bash
# 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](https://github.com/sayanarijit/cottage/releases).
## Integraciones con editores
### Extensión de VS Code
Usa la [extensión Cottage para VS Code](https://github.com/sayanarijit/vscode-plugin-cottage) para instalar `ctg`, añadir hooks de seguridad para Copilot, cifrar archivos desde el Explorador y abrir archivos `.cott.age` a través del flujo de trabajo del editor.
[](https://marketplace.visualstudio.com/items?itemName=sayanarijit.vscode-plugin-cottage)
Instálala desde el [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=sayanarijit.vscode-plugin-cottage), o constrúyela e instálala localmente desde [`vscode-plugin-cottage`](https://github.com/sayanarijit/vscode-plugin-cottage).
### Extensión para Cursor y Eclipse
Descarga el [archivo VSX](https://open-vsx.org/extension/sayanarijit/vscode-plugin-cottage) e instálalo en tu IDE Cursor o Eclipse. Funciona de forma similar a la extensión de VS Code.
### Plugin de Vim
Usa el plugin [cottage.vim](https://github.com/sayanarijit/cottage.vim) para cifrar/descifrar secretos desde Vim o Neovim.
[](https://asciinema.org/a/1264076)
## 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 censuradas `*.cott.toml`), y cualquier archivo descifrado que aún tenga una contraparte `*.cott.age` en disco.
### Integración con Claude Code
Si usas Claude Code, añade [`.claude/settings.json`](https://github.com/sayanarijit/cottage/blob/main/.claude/settings.json) y [`.claude/hooks/deny-secrets.py`](https://github.com/sayanarijit/cottage/blob/main/.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](https://github.com/sayanarijit/claude-plugin-cottage).
### Integración con GitHub Copilot
Si usas GitHub Copilot en VS Code, añade [`.github/hooks/ctg-policy.json`](https://github.com/sayanarijit/cottage/blob/main/.github/hooks/ctg-policy.json) y [`.github/hooks/scripts/deny_ctg_command.py`](https://github.com/sayanarijit/cottage/blob/main/.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 de shell `ctg` directos y bloqueen el acceso a los archivos de secretos, o instala la extensión [vscode-plugin-cottage](https://github.com/sayanarijit/vscode-plugin-cottage) para configurarlo desde VS Code.
VS Code también carga las definiciones de hooks de [`.claude/settings.json`](https://github.com/sayanarijit/cottage/blob/main/.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`](https://github.com/sayanarijit/cottage/blob/main/.codex/hooks.json) y [`.codex/hooks/deny-ctg.py`](https://github.com/sayanarijit/cottage/blob/main/.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](https://github.com/sayanarijit/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`](https://github.com/sayanarijit/cottage/blob/main/.agents/hooks.json) y [`.agents/scripts/deny-ctg.py`](https://github.com/sayanarijit/cottage/blob/main/.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](https://github.com/sayanarijit/agy-plugin-cottage).
### Integración con Cursor
Si usas Cursor, añade [`.cursor/hooks.json`](https://github.com/sayanarijit/cottage/blob/main/.cursor/hooks.json), [`.cursor/hooks/deny-ctg.py`](https://github.com/sayanarijit/cottage/blob/main/.cursor/hooks/deny-ctg.py), [`.cursor/hooks/deny-read-secrets.py`](https://github.com/sayanarijit/cottage/blob/main/.cursor/hooks/deny-read-secrets.py), [`.cursor/rules/deny-ctg.mdc`](https://github.com/sayanarijit/cottage/blob/main/.cursor/rules/deny-ctg.mdc) y [`.cursorignore`](https://github.com/sayanarijit/cottage/blob/main/.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:
```bash
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`
# │ └ 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 that key here.
# ├ .git/...
# └ .gitattributes <- Added `*.cott.age binary linguist-generated filter=cottage-encrypted -diff` to avoid polluting git diff
# Your private key is stored safely in `~/.config/cottage/identity/<dirname>/<timestamp>.key`.
# You can run `ctg clean --all` anytime to clean up everything cottage ever did.
```
Crear o editar un secreto:
```bash
# `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
```
Ejecutar un comando con secretos descifrados:
```bash
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
```
O usa el atajo:
```bash
ctgx -- ./deploy.sh
ctgx --clean -- ./deploy.sh
```
Leer y canalizar un secreto descifrado sin escribirlo en disco:
```bash
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
```
Ejecutar un comando con secretos inyectados como variables de entorno, sin escribirlos en disco en absoluto:
```bash
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.
```bash
git add .
git commit -m "Add secret.yml"
git push origin main
```
Pide a tus compañeros de equipo 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.
```bash
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
```
Ahora tus compañeros de equipo pueden hacer pull de los últimos cambios y descifrar los secretos por sí mismos.
## Git Hooks
Puedes usar [prek](https://github.com/j178/prek) o [pre-commit](https://pre-commit.com/) para configurar git hooks que comprueben/cifren secretos automáticamente antes del commit y los descifren después del checkout.
Consulta la [configuración de ejemplo de prek aquí](https://github.com/sayanarijit/cottage/blob/main/examples/prek.toml).
Después de añadir el archivo `prek.toml`, ejecuta:
```bash
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.
```toml
# secret.yml.cott.toml
[secret]
allow = ["sayanarijit"] # Only encrypt for sayanarijit
```
```toml
# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"] # Encrypt for everyone except sayanarijit
```
```toml
# 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](https://github.com/sayanarijit/cottage/blob/main/SPECIFICATION.md#secretmetadata) 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.
```yaml
# .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 de upstream.
Consulta el [ejemplo de `cottage.toml` aquí](https://github.com/sayanarijit/cottage/blob/main/cottage.toml) y la [configuración de upstream específica de secretos aquí](https://github.com/sayanarijit/cottage/blob/main/examples/secrets/secret.json.cott.toml).
Consulta un [ejemplo de implementación de plugin aquí](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-vault-in-kubernetes.py).
El flujo de trabajo es similar a git, pero en lugar de `git pull` y `git push`, ejecutas `ctg pull` y `ctg push` para sincronizar secretos con el upstream configurado.
Ejemplo:
```bash
# 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](https://github.com/sayanarijit/cottage/blob/main/SPECIFICATION.md#upstreamconfig) para más detalles.
### Plugins de ejemplo
Cottage admite varios proveedores de plugins para sincronizar tus secretos. Hay scripts de plugins listos para usar disponibles en el directorio [examples/plugins](https://github.com/sayanarijit/cottage/blob/main/examples/plugins):
- [1Password](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-onepassword.py)
- [AWS Secrets Manager](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-aws-secretsmanager.py)
- [Azure Key Vault](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-azure-keyvault.py)
- [Bitwarden](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-bitwarden.py)
- [Dashlane](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-dashlane.py)
- [Doppler](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-doppler.py)
- [ejson](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-ejson.py)
- [GitHub Secrets](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-github-secrets.py)
- [Google Cloud Secret Manager](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-gcp-secretmanager.py)
- [HashiCorp Vault](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-vault.py) (también consulta [Vault en Kubernetes](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-vault-in-kubernetes.py))
- [Keeper Security](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-keeper.py)
- [KeePass (Passhole)](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-passhole.py)
- [LastPass](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-lastpass.py)
- [pass (password-store)](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-pass.py)
- [Proton Pass](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-protonpass.py)
- [System Keyring](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-keyring.py)
- [Zoho Vault](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-zoho-vault.py)
## Sincronizar con cualquier dispositivo
Usa [Cottage Sync](https://cottage-sync.github.io) para sincronizar tus secretos entre tus dispositivos y navegar sin necesidad de la CLI.
## Más información
Consulta el directorio [examples](https://github.com/sayanarijit/cottage/blob/main/examples) para más ejemplos de uso.
## Solución de problemas
```bash
# See debug logs with -v, -vv or -vvv
ctg run -vvv -- ./deploy.sh
```
## Comparación
### age vs otros cifrados
[age](https://age-encryption.org) utiliza un algoritmo moderno y sencillo 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](https://words.filippo.io/using-ed25519-keys-for-encryption/), aunque se recomienda usar claves diferentes para propósitos y ámbitos separados.
### cottage vs SOPS
Aunque [SOPS](https://getsops.io/) 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 puros 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 destinatarios.
### cottage vs dotenvx
cottage toma prestada la API `ctg env` de [dotenvx](https://dotenvx.com).
- 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-sops).
### cottage vs agebox
[agebox](https://github.com/slok/agebox) es muy similar a cottage en su filosofía central pero carece de muchas [características](#features).