sayanarijit/cottageСовременный менеджер секретов на основе git с шифрованием age для команд.
cottage — это GitOps-инструмент для команд, позволяющий управлять секретами, зашифрованными с помощью age, в git-репозиториях.
Он предоставляет простой рабочий процесс для шифрования/расшифровки секретов, управления получателями и хранения секретов вне репозитория, при этом обеспечивая удобный обмен ими через VCS. cottage также генерирует отредактированные (redacted) превью зашифрованных секретов для лучшей видимости и поддерживает как постоянные, так и временные рабочие процессы расшифровки, гарантируя, что секреты никогда не попадут в коммиты в открытом виде.
.gitignore, чтобы незашифрованные секреты не попадали в репозиторий.ctg diff показывает различия локально изменённых секретов с отслеживаемыми зашифрованными аналогами.ctg decrypt/sync сохраняет расшифрованные секреты на диске.ctg run (сокращение ctgx) и ctg edit расшифровывают секреты перед операцией, сохраняя их на диске, если они уже были там, или автоматически очищая их после, если их не было.ctg encrypt --clean, и гарантируют, что расшифрованные файлы будут удалены с диска, даже если они существовали ранее.# 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.
Используйте расширение Cottage для VS Code, чтобы установить ctg, добавить хуки безопасности Copilot, шифровать файлы из проводника и открывать файлы .cott.age через рабочий процесс редактора.
Установите его из Visual Studio Marketplace или соберите и установите локально из vscode-plugin-cottage.
Скачайте VSX-файл и установите его в вашу IDE Cursor или Eclipse. Он работает аналогично расширению для VS Code.
Используйте плагин cottage.vim для шифрования/расшифровки секретов из Vim или Neovim.
Все интеграции ниже не позволяют AI-агентам запускать ctg/ctgx напрямую, а также просматривать или редактировать файлы секретов: всё внутри .cottage/, любые файлы *.cott.* (зашифрованные блобы *.cott.age и отредактированные превью *.cott.toml), а также любые расшифрованные файлы, у которых всё ещё есть аналог *.cott.age на диске.
Если вы используете Claude Code, добавьте .claude/settings.json и .claude/hooks/deny-secrets.py в ваши репозитории с секретами, чтобы сессии Claude Code безопасно обрабатывали секреты, или установите плагин claude-plugin-cottage.
Если вы используете 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/hooks.json и .codex/hooks/deny-ctg.py в ваши репозитории с секретами, чтобы сессии Codex безопасно обрабатывали секреты, или установите плагин codex-plugin-cottage.
Codex требует, чтобы локальные хуки были проверены перед запуском. После добавления файлов запустите Codex в репозитории и используйте /hooks, чтобы проверить и довериться хукам проекта.
Если вы используете Antigravity (agy), добавьте .agents/hooks.json и .agents/scripts/deny-ctg.py в ваши репозитории с секретами, чтобы сессии Antigravity безопасно обрабатывали секреты, или установите плагин agy-plugin-cottage.
Если вы используете 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.
Чтобы поделиться секретами с членами команды, просто запушьте изменения в 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 последних изменений и расшифровать секреты для себя.
Вы можете использовать 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
С помощью 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:
Используйте Cottage Sync для синхронизации ваших секретов между устройствами и просмотра без необходимости использования CLI.
Смотрите директорию examples для получения дополнительных примеров использования.
# Смотрите отладочные логи с -v, -vv или -vvv
ctg run -vvv -- ./deploy.sh
age использует современный, простой алгоритм, оптимизированный для безопасного шифрования файлов, с акцентом на удобство использования и минимальную поверхность атаки. Он также поддерживает SSH RSA и Ed25519 ключи, хотя рекомендуется использовать разные ключи для разных целей и областей применения.
Хотя SOPS и cottage имеют много пересекающихся функций, cottage имеет следующие преимущества:
cottage заимствует API ctg env из dotenvx.
agebox очень похож на cottage по основной философии, но ему не хватает многих возможностей.
ctg run --cleanctg edit --cleanctg env внедряет расшифрованные секреты как переменные окружения для запуска команды, вообще не записывая их на диск.ctg clean удаляет все расшифрованные секреты из локального репозитория, позволяя запускать ваших AI-агентов с чуть меньшим беспокойством.ctg init превращает любую директорию в хранилище секретов.ctg pull/diff/push как git pull/diff/push.