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

شعار cottage

cottage هي أداة GitOps للفرق لإدارة الأسرار المشفّرة بـ age في مستودعات git.

توفّر سير عمل بسيطًا لتشفير/فك تشفير الأسرار، وإدارة المستلمين، وإبقاء الأسرار خارج المستودع مع السماح بمشاركتها بسهولة عبر VCS. كما تولّد cottage معاينات محجوبة للأسرار المشفّرة لتحسين الرؤية، وتدعم سير عمل فك التشفير الدائم والمؤقت، مع ضمان عدم إيداع الأسرار أبدًا بنص صريح.

عرض توضيحي تمهيدي

الميزات
التثبيت
تكاملات المحررات
تكاملات وكلاء الذكاء الاصطناعي
البدء السريع
GitOps
خطافات Git
التحكم في الوصول
1. القواعد
2. التحقق
أي مزوّد كـ Upstream
1. إضافات نموذجية
المزامنة مع أي جهاز
معرفة المزيد
استكشاف الأخطاء وإصلاحها
المقارنة

الميزات

آمن ضد التسريب: يستخدم نظام الأنواع في Rust لضمان عدم تمكن الأخطاء من كشف الأسرار عن طريق الخطأ.
صديق للفريق: شارك المفاتيح العامة (المستلمين) في المستودع، واحتفظ بالمفاتيح الخاصة (الهويات) محليًا.
التحكم في الوصول: قواعد سماح/منع بسيطة للتحكم في الأسرار التي تُشفَّر ولمن.
يدير .gitignore: يحدّث .gitignore تلقائيًا لإبقاء الأسرار غير المشفّرة خارج المستودع.
المعاينات: يولّد معاينات محجوبة بطوابع زمنية للأسرار المشفّرة لتحسين الرؤية.
فروقات غنية: يحافظ على نظافة git diff وقابليته للمراجعة، بينما يعرض ctg diff الفرق بين الأسرار المعدّلة محليًا ونظيراتها المشفّرة المتعقّبة.
التحقق من المجموع الاختباري: يمنع التلاعب بالتحقق من تطابق الأسرار المشفّرة وقوائم المستلمين مع البيانات الوصفية.
خطافات Git: إعداد خطافات git بسهولة للتحقق/التشفير التلقائي للأسرار قبل الإيداع وفك تشفيرها بعد السحب.
سير عمل الأسرار الدائمة: يحتفظ ctg decrypt/sync بالأسرار المفكوكة على القرص.
دورة تنظيف ذكية: يفكّ ctg run (اختصار ctgx) و ctg edit تشفير الأسرار قبل العملية، ويبقيها على القرص إن كانت موجودة مسبقًا أو ينظّفها تلقائيًا بعدها إن لم تكن كذلك.
تنظيف عند الإكمال: تضمن ctg encrypt --clean و ctg run --clean و ctg edit --clean تنظيف الملفات المفكوكة من القرص حتى لو كانت موجودة مسبقًا.
سير عمل حقن المتغيرات البيئية: يحقن ctg env الأسرار المفكوكة كمتغيرات بيئية لتشغيل أمر، دون كتابتها على القرص إطلاقًا.
تمرير الأسرار الآمن: يفكّ ctg cat PATH التشفير في الذاكرة ويطبعه إلى stdout للتمرير المباشر إلى stdin لأدوات أخرى.
التنظيف: يحذف ctg clean جميع الأسرار المفكوكة من المستودع المحلي ليتيح لك تشغيل وكلاء الذكاء الاصطناعي بقلق أقل قليلًا.
يدعم 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 IDE. تعمل بشكل مشابه لإضافة VS Code.

إضافة Vim

استخدم إضافة cottage.vim لتشفير/فك تشفير الأسرار من Vim أو Neovim.

تكاملات وكلاء الذكاء الاصطناعي

جميع التكاملات أدناه تمنع وكلاء الذكاء الاصطناعي من تشغيل 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 الملفات المفكوكة، وتحجب أوامر 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

قراءة سر مفكوك وتمريره دون كتابته على القرص:

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 للتحقق/التشفير التلقائي للأسرار قبل الإيداع وفك تشفيرها بعد السحب.

راجع مثال تهيئة 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 واجهة ctg env من dotenvx.

يدعم أي نوع ملف، وليس ملفات dotenv فقط.
يدير أسرارًا متعددة في المستودع.
قواعد تحكم في الوصول لتشفير الأسرار لمستلمين محددين.
فروقات أنظف - راجع cottage مقابل SOPS.

cottage مقابل agebox

agebox مشابه جدًا لـ cottage في الفلسفة الأساسية لكنه يفتقر إلى العديد من الميزات.

اقرأ المزيد