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

The cottage logo

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

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

Intro Demo

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

Возможности

Безопасность от раскрытия: Использует систему типов Rust, чтобы гарантировать, что ошибки никогда не смогут случайно раскрыть секреты.
Ориентирован на команду: Делитесь публичными ключами (получателями) в репозитории, храните приватные ключи (идентичности) локально.
Контроль доступа: Простые правила разрешения/запрета для управления тем, какие секреты шифруются для каких получателей.
Управление .gitignore: Автоматически обновляет .gitignore, чтобы незашифрованные секреты не попадали в репозиторий.
Превью: Генерирует отредактированные (redacted) превью с временными метками для зашифрованных секретов для лучшей видимости.
Богатые диффы: Поддерживает чистый и удобный для ревью 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 внедряет расшифрованные секреты как переменные окружения для запуска команды, вообще не записывая их на диск.
Очистка: 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-файл и установите его в вашу IDE 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  # Необязательно, cottage лучше работает с git, но это не обязательно
ctg init  # Настраивает директорию .cottage и необходимые файлы

tree -a
# .
# ├ .cottage/           <- Автоматически создаётся командой `ctg init`
# │ ├ identity        <- Ваш приватный ключ, храните его в безопасности. Переместите его в `~/.config/cottage/identity`, чтобы использовать глобально, или замените его символической ссылкой на один из ваших существующих приватных ключей.
# │ └ recipients/     <- Здесь ваша команда хранит публичные ключи всех получателей.
# │     └ sayanarijit <- Ваш публичный ключ. Закоммитьте его. Чтобы использовать существующий публичный ключ, просто скопируйте (не создавайте символическую ссылку) этот ключ сюда.
# ├ .git/...
# ├ .gitattributes      <- Добавлено `*.cott.age binary linguist-generated filter=cottage-encrypted -diff`, чтобы не загрязнять git diff
# └ .gitignore          <- Добавлено `/.cottage/identity` по очевидным причинам

# Вы можете запустить `ctg clean --all` в любое время, чтобы очистить всё, что когда-либо делал cottage.

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

# `ctg edit` расшифровывает файл перед открытием в $EDITOR и повторно шифрует при сохранении.
# Если расшифрованного файла не было на диске до запуска `ctg edit`, он будет удалён после.
# Если он уже был на диске, он будет сохранён.
ctg edit secret.yml

# Используйте `--clean` с `ctg edit` или `ctg encrypt`, чтобы гарантировать удаление расшифрованных файлов, даже если они существовали ранее
ctg edit secret.yml --clean    # Открывает в $EDITOR, шифрует при сохранении и очищает
ctg encrypt secret.yml --clean # Шифрует secret.yml и очищает
# 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` (или сокращение `ctgx`) расшифровывает секреты перед запуском команды.
# Если расшифрованных файлов не было на диске заранее, они автоматически удаляются после завершения команды.
# Если они уже были на диске заранее, они сохраняются.
ctg run -- kubectl apply -f secret.yml          # расшифровывает secret.yml.cott.age в secret.yml и запускает команду
ctg run -- kubectl apply -f secret.yml.cott.age # также заменяет аргумент пути на путь расшифрованного файла
ctg run -- kubectl apply -f .                   # расшифровывает все файлы .cott.age в . и запускает команду
ctg run -- ./deploy.sh                          # расшифровывает все файлы .cott.age в репозитории и запускает команду

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

# Используйте `--clean`, чтобы гарантировать удаление расшифрованных файлов, даже если они существовали ранее
ctg run --clean ./deploy.sh

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

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

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

ctg env -- ./deploy.sh # Экспортирует секреты из .env.cott.age (по умолчанию) без записи на диск, затем запускает deploy.sh
ctg env -F .env.prod.cott.age -- ./deploy.sh # экспортирует из .env.prod.cott.age вместо .env.cott.age
ctg env -F secrets.json.cott.age -- printenv COTTAGE_SECRET # Также поддерживает файлы, не являющиеся dotenv.

GitOps

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

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

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

git pull origin main

ctg decrypt --skip-verify-recipients  # Расшифровывает отсутствующие секреты для повторного шифрования
ctg encrypt                           # Повторно шифрует все секреты
# encrypt secret.yml
#    into secret.yml.cott.age
#    edit secret.yml.cott.toml

ctg clean  # необязательно
# delete secret.yml

# просмотрите изменения, закоммитьте и запушьте
git add .
git commit -m "Add new recipient to secrets"
git push origin main

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

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"]  # Шифровать только для sayanarijit

# secret.yml.cott.toml
[secret]
deny = ["sayanarijit"]  # Шифровать для всех, кроме sayanarijit

# secret.yml.cott.toml
[secret]
allow = ["env/staging/*"]  # Поддерживает glob-шаблоны, шифровать только для получателей в env/staging
deny = ["env/staging/badservice"]  # Шифровать для всех в env/staging, кроме badservice

Правила deny имеют приоритет над правилами allow.

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

Проверка

Вы можете запустить 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.

Пример:

# Получить последние изменения в локальные зашифрованные секреты
# Аналогично `git pull origin`
ctg pull myvault

# Сравнить diff с локальными расшифрованными секретами
ctg diff

# Синхронизировать локальные расшифрованные секреты с локальными зашифрованными секретами
ctg sync

# Отправить изменения из локальных зашифрованных секретов в upstream
# Аналогично `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 in Kubernetes)
Keeper Security
KeePass (Passhole)
LastPass
pass (password-store)
Proton Pass
System Keyring
Zoho Vault

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

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

Подробнее

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

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

# Смотрите отладочные логи с -v, -vv или -vvv
ctg run -vvv -- ./deploy.sh

Сравнение

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

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

cottage против SOPS

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

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

cottage против dotenvx

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

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

cottage против agebox

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