Современный менеджер секретов на основе git с шифрованием age для команд.
<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="The cottage logo" 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*** — это GitOps-инструмент для команд, позволяющий управлять секретами, зашифрованными с помощью [age](https://age-encryption.org/), в git-репозиториях.
Он предоставляет простой рабочий процесс для шифрования/расшифровки секретов, управления получателями и
хранения секретов вне репозитория, при этом позволяя легко делиться ими через VCS. cottage также
генерирует отредактированные превью зашифрованных секретов для лучшей видимости и поддерживает как
постоянные, так и временные рабочие процессы расшифровки, гарантируя, что секреты никогда не коммитятся
в открытом виде.
1. [Возможности](#features)
2. [Установка](#installation)
3. [Интеграции с редакторами](#editor-integrations)
1. [Расширение для VS Code](#vs-code-extension)
2. [Расширение для Cursor и Eclipse](#cursor-and-eclipse-extension)
3. [Плагин для Vim](#vim-plugin)
4. [Интеграции с AI-агентами](#ai-agent-integrations)
1. [Интеграция с Claude Code](#claude-code-integration)
2. [Интеграция с GitHub Copilot](#github-copilot-integration)
3. [Интеграция с Codex](#codex-integration)
4. [Интеграция с Antigravity (agy)](https://github.com/sayanarijit/cottage/blob/main/%3C#antigravity-(agy)-integration>)
5. [Интеграция с Cursor](#cursor-integration)
5. [Быстрый старт](#quick-start)
6. [GitOps](#gitops)
7. [Git-хуки](#git-hooks)
8. [Контроль доступа](#access-control)
1. [Правила](#rules)
2. [Проверка](#verification)
9. [Любой провайдер в качестве upstream](#any-provider-as-upstream)
1. [Примеры плагинов](#example-plugins)
10. [Синхронизация с любым устройством](#sync-with-any-device)
11. [Узнать больше](#learn-more)
12. [Устранение неполадок](#troubleshooting)
13. [Сравнение](#comparison)
1. [age против других методов шифрования](#age-vs-other-encryption)
2. [cottage против SOPS](#cottage-vs-sops)
3. [cottage против dotenvx](#cottage-vs-dotenvx)
4. [cottage против agebox](#cottage-vs-agebox)
## Возможности
- **Безопасность от утечек**: Использует систему типов 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](https://cottage-sync.github.io).
## Установка
```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
```
Также доступен в виде docker-образов:
```bash
# Docker
docker run --rm -v $PWD:/app sayanarijit/cottage --version
# Podman
podman run --rm -v $PWD:/app quay.io/sayanarijit/cottage --version
```
Или скачайте последний релиз с [GitHub](https://github.com/sayanarijit/cottage/releases).
## Интеграции с редакторами
### Расширение для VS Code
Используйте [расширение Cottage для VS Code](https://github.com/sayanarijit/vscode-plugin-cottage), чтобы установить `ctg`, добавить хуки безопасности для Copilot, шифровать файлы из Проводника и открывать файлы `.cott.age` через рабочий процесс редактора.
[](https://marketplace.visualstudio.com/items?itemName=sayanarijit.vscode-plugin-cottage)
Установите его из [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=sayanarijit.vscode-plugin-cottage) или соберите и установите локально из [`vscode-plugin-cottage`](https://github.com/sayanarijit/vscode-plugin-cottage).
### Расширение для Cursor и Eclipse
Скачайте [VSX-файл](https://open-vsx.org/extension/sayanarijit/vscode-plugin-cottage) и установите его в вашей Cursor или Eclipse IDE. Оно работает аналогично расширению для VS Code.
### Плагин для Vim
Используйте плагин [cottage.vim](https://github.com/sayanarijit/cottage.vim) для шифрования/расшифровки секретов из Vim или Neovim.
[](https://asciinema.org/a/1264076)
## Интеграции с AI-агентами
Все приведённые ниже интеграции не позволяют AI-агентам запускать `ctg`/`ctgx` напрямую и просматривать или редактировать файлы секретов: всё внутри `.cottage/`, любые файлы `*.cott.*` (зашифрованные блобы `*.cott.age` и отредактированные превью `*.cott.toml`), а также любые расшифрованные файлы, у которых всё ещё есть аналог `*.cott.age` на диске.
### Интеграция с Claude Code
Если вы используете Claude Code, добавьте [`.claude/settings.json`](https://github.com/sayanarijit/cottage/blob/main/.claude/settings.json) и [`.claude/hooks/deny-secrets.py`](https://github.com/sayanarijit/cottage/blob/main/.claude/hooks/deny-secrets.py) в ваши репозитории с секретами, чтобы сессии Claude Code безопасно обрабатывали секреты, или установите плагин [claude-plugin-cottage](https://github.com/sayanarijit/claude-plugin-cottage).
### Интеграция с GitHub Copilot
Если вы используете GitHub Copilot в VS Code, добавьте [`.github/hooks/ctg-policy.json`](https://github.com/sayanarijit/cottage/blob/main/.github/hooks/ctg-policy.json) и [`.github/hooks/scripts/deny_ctg_command.py`](https://github.com/sayanarijit/cottage/blob/main/.github/hooks/scripts/deny_ctg_command.py) в ваши репозитории с секретами, чтобы сессии Copilot очищали расшифрованные файлы, блокировали прямые shell-команды `ctg` и блокировали доступ к файлам секретов, или установите расширение [vscode-plugin-cottage](https://github.com/sayanarijit/vscode-plugin-cottage), чтобы настроить это из VS Code.
VS Code также загружает определения хуков из [`.claude/settings.json`](https://github.com/sayanarijit/cottage/blob/main/.claude/settings.json). Если вы храните файлы хуков и Claude, и Copilot в одном репозитории, убедитесь, что вы случайно не запускаете один и тот же хук очистки дважды.
### Интеграция с Codex
Если вы используете Codex, добавьте [`.codex/hooks.json`](https://github.com/sayanarijit/cottage/blob/main/.codex/hooks.json) и [`.codex/hooks/deny-ctg.py`](https://github.com/sayanarijit/cottage/blob/main/.codex/hooks/deny-ctg.py) в ваши репозитории с секретами, чтобы сессии Codex безопасно обрабатывали секреты, или установите плагин [codex-plugin-cottage](https://github.com/sayanarijit/codex-plugin-cottage).
Codex требует, чтобы локальные хуки были проверены перед запуском. После добавления файлов запустите Codex в репозитории и используйте `/hooks`, чтобы проверить и довериться проектным хукам.
### Интеграция с Antigravity (agy)
Если вы используете Antigravity (`agy`), добавьте [`.agents/hooks.json`](https://github.com/sayanarijit/cottage/blob/main/.agents/hooks.json) и [`.agents/scripts/deny-ctg.py`](https://github.com/sayanarijit/cottage/blob/main/.agents/scripts/deny-ctg.py) в ваши репозитории с секретами, чтобы сессии Antigravity безопасно обрабатывали секреты, или установите плагин [agy-plugin-cottage](https://github.com/sayanarijit/agy-plugin-cottage).
### Интеграция с Cursor
Если вы используете Cursor, добавьте [`.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) и [`.cursorignore`](https://github.com/sayanarijit/cottage/blob/main/.cursorignore) в ваши репозитории с секретами, чтобы сессии Cursor безопасно обрабатывали секреты.
Cursor требует сначала включить хуки. Откройте Cursor Settings > Hooks и включите хуки, затем перезапустите сессию агента, чтобы проектные хуки вступили в силу. `.cursorignore` дополнительно не позволяет файлам секретов попадать в индексацию Cursor и контекст Агента.
## Быстрый старт
Инициализация проекта:
```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.
```
Создание или редактирование секрета:
```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
```
Запуск команды с расшифрованными секретами:
```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
```
Или используйте сокращение:
```bash
ctgx -- ./deploy.sh
ctgx --clean -- ./deploy.sh
```
Чтение и передача расшифрованного секрета без записи на диск:
```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
```
Запуск команды с секретами, внедрёнными как переменные окружения, без записи на диск вообще:
```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
Чтобы поделиться секретами с членами команды, просто отправьте изменения в git-репозиторий.
```bash
git add .
git commit -m "Add secret.yml"
git push origin main
```
Попросите коллег добавить свои публичные ключи в `.cottage/recipients` и отправить
изменения. Затем вы можете получить изменения и повторно зашифровать секреты для них.
```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
```
Теперь ваши коллеги могут получить последние изменения и расшифровать секреты для себя.
## Git-хуки
Вы можете использовать [prek](https://github.com/j178/prek) или [pre-commit](https://pre-commit.com/) для настройки git-хуков, чтобы автоматически проверять/шифровать секреты перед коммитом и расшифровывать их после checkout.
Смотрите [пример конфигурации prek здесь](https://github.com/sayanarijit/cottage/blob/main/examples/prek.toml).
После добавления файла `prek.toml` выполните:
```bash
prek install
prek install --hook-type post-checkout
prek install --hook-type post-merge
prek install --hook-type post-rewrite
```
## Контроль доступа
### Правила
В файле метаданных вы можете указать, для каких получателей должен быть зашифрован секрет.
Это позволяет иметь разные секреты для разных окружений (например, staging и production) и шифровать их только для соответствующих получателей.
```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
```
Правила запрета имеют приоритет над правилами разрешения.
Смотрите [спецификацию метаданных](https://github.com/sayanarijit/cottage/blob/main/SPECIFICATION.md#secretmetadata) для подробностей.
### Проверка
Вы можете запустить `ctg verify` в CI, чтобы проверить, что зашифрованные секреты и списки получателей соответствуют правилам метаданных, для предотвращения подмены.
```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
```
## Любой провайдер в качестве upstream
С cottage вы можете синхронизировать секреты с любым провайдером, у которого есть API, не только с git.
Для этого создайте файл с именем `cottage.toml` в корне проекта и настройте параметры upstream.
Смотрите [пример `cottage.toml` здесь](https://github.com/sayanarijit/cottage/blob/main/cottage.toml) и [конфигурацию upstream для конкретного секрета здесь](https://github.com/sayanarijit/cottage/blob/main/examples/secrets/secret.json.cott.toml).
Смотрите [пример реализации плагина здесь](https://github.com/sayanarijit/cottage/blob/main/examples/plugins/cottage-plugin-vault-in-kubernetes.py).
Рабочий процесс аналогичен git, но вместо `git pull` и `git push` вы запускаете `ctg pull` и `ctg push` для синхронизации секретов с настроенным upstream.
Пример:
```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
```
Смотрите [спецификацию конфигурации upstream](https://github.com/sayanarijit/cottage/blob/main/SPECIFICATION.md#upstreamconfig) для подробностей.
### Примеры плагинов
Cottage поддерживает различные провайдеры-плагины для синхронизации ваших секретов. Готовые к использованию скрипты плагинов доступны в директории [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) (также смотрите [Vault in 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)
## Синхронизация с любым устройством
Используйте [Cottage Sync](https://cottage-sync.github.io) для синхронизации секретов между устройствами и просмотра без необходимости в CLI.
## Узнать больше
Смотрите директорию [examples](https://github.com/sayanarijit/cottage/blob/main/examples) для дополнительных примеров использования.
## Устранение неполадок
```bash
# See debug logs with -v, -vv or -vvv
ctg run -vvv -- ./deploy.sh
```
## Сравнение
### age против других методов шифрования
[age](https://age-encryption.org) использует современный, простой алгоритм, оптимизированный для безопасного шифрования файлов, с акцентом на удобство использования и минимальную поверхность атаки. Он также [поддерживает SSH RSA и Ed25519 ключи](https://words.filippo.io/using-ed25519-keys-for-encryption/), хотя рекомендуется использовать разные ключи для разных целей и областей применения.
### cottage против SOPS
Хотя [SOPS](https://getsops.io/) и cottage имеют много пересекающихся функций, cottage имеет следующие преимущества:
- Автоматическое управление .gitignore, чтобы незашифрованные секреты никогда не попадали в git.
- Зашифрованные секреты, будучи чистыми age-зашифрованными файлами .age, обеспечивают лучшую совместимость с более широкой экосистемой инструментов.
- Более чистые диффы — в отличие от SOPS, который генерирует диффы для каждого значения каждого секрета, даже если фактическое изменение заключается лишь в добавлении/удалении получателя, cottage генерирует только один дифф на файл, явно указывая изменение контрольной суммы получателей.
### cottage против dotenvx
cottage заимствует API `ctg env` из [dotenvx](https://dotenvx.com).
- Поддерживает любой тип файлов, не только dotenv-файлы.
- Управляет несколькими секретами в репозитории.
- Правила контроля доступа для шифрования секретов для конкретных получателей.
- Более чистые диффы — смотрите [cottage против SOPS](#cottage-vs-sops).
### cottage против agebox
[agebox](https://github.com/slok/agebox) очень похож на cottage по основной философии, но ему не хватает многих [возможностей](#features).