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

The cottage logo

cottage — это GitOps-инструмент для команд, позволяющий управлять секретами, зашифрованными с помощью age, в git-репозиториях.

Он предоставляет простой рабочий процесс для шифрования/расшифровки секретов, управления получателями и хранения секретов вне репозитория, при этом позволяя легко делиться ими через VCS. cottage также генерирует отредактированные превью зашифрованных секретов для лучшей видимости и поддерживает как постоянные, так и временные рабочие процессы расшифровки, гарантируя, что секреты никогда не попадут в коммиты в открытом виде.

Intro Demo

Возможности
Установка
Интеграции с редакторами
Интеграции с AI-агентами
Быстрый старт
GitOps
Git-хуки
Контроль доступа
1. Правила
2. Проверка
Любой провайдер в качестве upstream
1. Примеры плагинов
Синхронизация с любым устройством
Узнать больше
Устранение неполадок
Сравнение

Возможности

Безопасность от утечек: Использует систему типов Rust, чтобы гарантировать, что ошибки никогда не приведут к случайной утечке секретов.
Удобство для команд: Делитесь публичными ключами (получателями) в репозитории, храните приватные ключи (идентификаторы) локально.
Контроль доступа: Простые правила разрешения/запрета для управления тем, какие секреты шифруются для каких получателей.
Управляет .gitignore: Автоматически обновляет .gitignore, чтобы незашифрованные секреты не попадали в репозиторий.
Превью: Генерирует отредактированные превью зашифрованных секретов с отметкой времени для лучшей видимости.
Наглядные диффы: Сохраняет git diff чистым и удобным для ревью, при этом ctg diff показывает различия локально изменённых секретов с отслеживаемыми зашифрованными аналогами.
Проверка контрольных сумм: Предотвращает подмену, проверяя, что зашифрованные секреты и списки получателей соответствуют метаданным.
Git-хуки: Легко настраивайте git-хуки для автоматической проверки/шифрования секретов перед коммитом и их расшифровки после checkout.
Рабочий процесс с постоянными секретами: ctg decrypt/sync сохраняет расшифрованные секреты на диске.
Умный жизненный цикл очистки: ctg run (сокращение ctgx) и ctg edit расшифровывают секреты перед операцией, оставляя их на диске, если они уже были там до этого, или автоматически удаляя их после, если их не было.
Очистка по завершении: ctg encrypt --clean, ctg run --clean и ctg edit --clean гарантируют, что расшифрованные файлы удаляются с диска, даже если они присутствовали ранее.
Рабочий процесс с внедрением переменных окружения: ctg env внедряет расшифрованные секреты как переменные окружения для запуска команды, вообще не записывая их на диск.
Безопасная передача секретов через pipe: ctg cat PATH расшифровывает в памяти и выводит в stdout для прямой передачи через stdin в другие инструменты.
Очистка: ctg clean удаляет все расшифрованные секреты из локального репозитория, чтобы вы могли запускать своих AI-агентов с чуть меньшим беспокойством.
Поддержка jj и директорий без git: ctg init превращает любую директорию в хранилище секретов.
Синхронизация с любым провайдером: Позволяет настроить любого провайдера с API в качестве upstream и начать использовать ctg pull/diff/push как git pull/diff/push.
Синхронизация с любым устройством: Секреты, зашифрованные с помощью cottage и управляемые в git-репозитории, можно синхронизировать между устройствами с помощью Cottage Sync.

Установка

# 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

Также доступен в виде docker-образов:

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

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

Или скачайте последний релиз с GitHub.

Интеграции с редакторами

Расширение для VS Code

Используйте расширение Cottage для VS Code, чтобы установить ctg, добавить хуки безопасности для Copilot, шифровать файлы из Проводника и открывать файлы .cott.age через рабочий процесс редактора.

Установите его из Visual Studio Marketplace или соберите и установите локально из vscode-plugin-cottage.

Расширение для Cursor и Eclipse

Скачайте файл VSX и установите его в вашей среде Cursor или Eclipse. Оно работает аналогично расширению для VS Code.

Плагин для Vim

Используйте плагин cottage.vim для шифрования/расшифровки секретов из Vim или Neovim.

Интеграции с AI-агентами

Все приведённые ниже интеграции не позволяют AI-агентам напрямую запускать ctg/ctgx и просматривать или редактировать файлы секретов: всё внутри .cottage/, любые файлы *.cott.* (зашифрованные блобы *.cott.age и отредактированные превью *.cott.toml), а также любые расшифрованные файлы, для которых на диске всё ещё есть аналог *.cott.age.

Интеграция с Claude Code

Если вы используете Claude Code, добавьте .claude/settings.json и .claude/hooks/deny-secrets.py в ваши репозитории с секретами, чтобы сессии Claude Code безопасно обращались с секретами, или установите плагин claude-plugin-cottage.

Интеграция с GitHub Copilot

Если вы используете GitHub Copilot в VS Code, добавьте .github/hooks/ctg-policy.json и .github/hooks/scripts/deny_ctg_command.py в ваши репозитории с секретами, чтобы сессии Copilot очищали расшифрованные файлы, блокировали прямые shell-команды ctg и блокировали доступ к файлам секретов, или установите расширение vscode-plugin-cottage, чтобы настроить это из VS Code.

VS Code также загружает определения хуков из .claude/settings.json. Если вы храните файлы хуков и для Claude, и для Copilot в одном репозитории, убедитесь, что вы случайно не запускаете один и тот же хук очистки дважды.

Интеграция с Codex

Если вы используете Codex, добавьте .codex/hooks.json и .codex/hooks/deny-ctg.py в ваши репозитории с секретами, чтобы сессии Codex безопасно обращались с секретами, или установите плагин codex-plugin-cottage.

Codex требует, чтобы локальные хуки были проверены перед запуском. После добавления файлов запустите Codex в репозитории и используйте /hooks, чтобы проверить и довериться проектным хукам.

Интеграция с Antigravity (agy)

Если вы используете Antigravity (agy), добавьте .agents/hooks.json и .agents/scripts/deny-ctg.py в ваши репозитории с секретами, чтобы сессии Antigravity безопасно обращались с секретами, или установите плагин agy-plugin-cottage.

Интеграция с Cursor

Если вы используете Cursor, добавьте .cursor/hooks.json, .cursor/hooks/deny-ctg.py, .cursor/hooks/deny-read-secrets.py, .cursor/rules/deny-ctg.mdc и .cursorignore в ваши репозитории с секретами, чтобы сессии Cursor безопасно обращались с секретами.

Cursor требует сначала включить хуки. Откройте Cursor Settings > Hooks и включите хуки, затем перезапустите сессию агента, чтобы проектные хуки вступили в силу. .cursorignore дополнительно не позволяет файлам секретов попадать в индексацию Cursor и контекст Агента.

Быстрый старт

Инициализация проекта:

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.

Создание или редактирование секрета:

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

Запуск команды с расшифрованными секретами:

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

Или используйте сокращение:

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

Чтение и передача расшифрованного секрета через pipe без записи на диск:

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

Запуск команды с секретами, внедрёнными как переменные окружения, вообще без записи на диск:

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

Чтобы поделиться секретами с членами команды, просто отправьте изменения в git-репозиторий.

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

Попросите коллег добавить свои публичные ключи в .cottage/recipients и отправить изменения. Затем вы можете получить изменения и повторно зашифровать секреты для них.

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

Теперь ваши коллеги могут получить последние изменения и расшифровать секреты для себя.

Git-хуки

Вы можете использовать prek или pre-commit для настройки git-хуков, чтобы автоматически проверять/шифровать секреты перед коммитом и расшифровывать их после checkout.

Смотрите пример конфигурации prek здесь.

После добавления файла prek.toml выполните:

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

Контроль доступа

Правила

В файле метаданных вы можете указать, для каких получателей должен быть зашифрован секрет. Это позволяет иметь разные секреты для разных сред (например, staging и production) и шифровать их только для соответствующих получателей.

# 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

Правила запрета имеют приоритет над правилами разрешения.

Смотрите спецификацию метаданных для подробностей.

Проверка

Вы можете запустить ctg verify в CI, чтобы проверить, что зашифрованные секреты и списки получателей соответствуют правилам метаданных, для предотвращения подмены.

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

Любой провайдер в качестве upstream

С cottage вы можете синхронизировать секреты с любым провайдером, у которого есть API, а не только с git.

Для этого создайте файл с именем cottage.toml в корне проекта и настройте параметры upstream.

Смотрите пример cottage.toml здесь и конфигурацию upstream для конкретного секрета здесь.

Смотрите пример реализации плагина здесь.

Рабочий процесс аналогичен git, но вместо git pull и git push вы запускаете ctg pull и ctg push для синхронизации секретов с настроенным upstream.

Пример:

# 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

Смотрите спецификацию конфигурации upstream для подробностей.

Примеры плагинов

Cottage поддерживает различные провайдеры-плагины для синхронизации ваших секретов. Готовые к использованию скрипты плагинов доступны в директории examples/plugins:

1Password
AWS Secrets Manager
Azure Key Vault
Bitwarden
Dashlane
Doppler
ejson
GitHub Secrets
Google Cloud Secret Manager
HashiCorp Vault (также смотрите Vault в Kubernetes)
Keeper Security
KeePass (Passhole)
LastPass
pass (password-store)
Proton Pass
System Keyring
Zoho Vault

Синхронизация с любым устройством

Используйте Cottage Sync для синхронизации ваших секретов между устройствами и просмотра без необходимости в CLI.

Узнать больше

Смотрите директорию examples для дополнительных примеров использования.

Устранение неполадок

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

Сравнение

age против других методов шифрования

age использует современный, простой алгоритм, оптимизированный для безопасного шифрования файлов, с акцентом на удобство использования и минимальную поверхность атаки. Он также поддерживает ключи SSH RSA и Ed25519, хотя рекомендуется использовать разные ключи для разных целей и областей применения.

cottage против SOPS

Хотя SOPS и cottage имеют много общих функций, cottage обладает следующими преимуществами:

Автоматически управляет .gitignore, чтобы незашифрованные секреты никогда не попадали в git.
Зашифрованные секреты, будучи чистыми .age-файлами, зашифрованными с помощью age, обеспечивают лучшую совместимость с более широкой экосистемой инструментов.
Более чистые диффы — в отличие от SOPS, который генерирует диффы для каждого значения каждого секрета, даже если фактическое изменение заключается лишь в добавлении/удалении получателя, cottage генерирует только один дифф на файл, явно указывая изменение в контрольной сумме получателей.

cottage против dotenvx

cottage заимствует API ctg env из dotenvx.

Поддерживает любой тип файлов, а не только dotenv-файлы.
Управляет несколькими секретами в репозитории.
Правила контроля доступа для шифрования секретов для конкретных получателей.
Более чистые диффы — смотрите cottage против SOPS.

cottage против agebox

agebox очень похож на cottage по основной философии, но ему не хватает многих возможностей.