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

Логотип cottage

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

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

Демонстрация

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

Возможности

Защита от утечек: использует систему типов Rust, чтобы ошибки никогда не могли случайно раскрыть секреты.
Удобство для команды: публичные ключи (получатели) храните в репозитории, а приватные ключи (идентичности) — локально.
Контроль доступа: простые правила allow/deny для управления тем, какие секреты шифруются для каких получателей.
Управление .gitignore: автоматически обновляет .gitignore, чтобы незашифрованные секреты не попадали в репозиторий.
Превью: создаёт превью зашифрованных секретов со скрытыми данными и отметками времени для лучшей наглядности.
Информативные диффы: поддерживает git diff чистым и удобным для ревью, а ctg diff показывает различия между локально изменёнными секретами и отслеживаемыми зашифрованными аналогами.
Проверка контрольных сумм: предотвращает подмену, проверяя, что зашифрованные секреты и списки получателей соответствуют метаданным.
Git-хуки: легко настраивайте git-хуки для автоматической проверки/шифрования секретов перед коммитом и их дешифрования после checkout.
Рабочий процесс с постоянными секретами: ctg decrypt/edit/sync хранит расшифрованные секреты на диске.
Рабочий процесс с временными секретами: ctg run (сокращение ctgx) временно расшифровывает секреты для выполнения команды, а затем удаляет их независимо от успеха или неудачи команды.
Внедрение в окружение: ctg env внедряет расшифрованные секреты как переменные окружения для выполнения команды, вообще не записывая их на диск.
Очистка: ctg clean удаляет все расшифрованные секреты из локального репозитория, чтобы вы могли запускать ИИ-агентов с чуть меньшим беспокойством.
Поддержка jj и каталогов без git: ctg init превращает любой каталог в хранилище секретов.
Синхронизация с любым провайдером: позволяет настроить любого провайдера с API в качестве апстрима и использовать 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, шифровать файлы из Explorer и открывать файлы .cott.age через редактор.

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

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

Все приведённые ниже интеграции не позволяют ИИ-агентам запускать 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 export-ignore 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 secret.yml --clean    # Opens secret.yml in $EDITOR
ctg encrypt secret.yml --clean # Another way to encrypt secrets
# 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 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

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

ctgx ./deploy.sh  # same as ctg run -- ./deploy.sh

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

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

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

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

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

git pull origin main

ctg sync  # or `ctg decrypt && ctg encrypt`
# 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

Правила 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 и настройте параметры апстрима.

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

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

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

Пример:

# 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

Подробнее см. в спецификации конфигурации апстрима.

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

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

1Password
AWS Secrets Manager
Azure Key Vault
Bitwarden
Dashlane
Doppler
ejson
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.

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

# 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 по своей основной философии, но ему не хватает многих возможностей.