Cover

أبقِ القيم الحساسة خارج طلبات LLM دون كسر المحادثة.

تثبيت · بدء سريع · السياسات · المراقبة · Pi / OMP · الأمان

Cover هو وكيل خصوصية محلي لـ Codex وClaude Code وCursor وSDKs وغيرها من عملاء الذكاء الاصطناعي المعتمدين على HTTP. يفحص JSON الصادر، ويستبدل القيم المطابقة محليًا، ويعيد الاستبدالات القابلة للعكس في استجابات JSON والاستجابات المتدفقة. يتلقى نموذج LLM القيم المحمية، بينما يمكن للوكيل مواصلة استخدام القيم الأصلية.

يعمل Cover كوكيل عكسي شفاف مع استبدال مدفوع بالسياسة، وأسماء مستعارة حتمية، وفحوصات تشغيلية، ودعم Codex، ومعالجة صارمة لحالات الفشل. صُمم ليبقى محليًا وقابلًا للمراقبة وواضحًا بشأن ما لا يمكنه فحصه.

flowchart LR
    A["Agent"] -->|"JSON request"| C["Cover<br/>detect · transform · enforce"]
    C -->|"protected request"| L["LLM or router"]
    L -->|"JSON or SSE response"| C
    C -->|"restored response"| A

أبرز المزايا

التثبيت

يقوم المثبّت باستنساخ Cover وبنائه باستخدام Go وتثبيته في ~/.local/bin/cover وتهيئة العملاء المحددين وتشغيل الوكيل.

curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

المتطلبات: git وإصدار Go المُعلَن في go.mod.

أرشيفات Linux وmacOS وWindows الجاهزة ومجاميعها الاختبارية متاحة من GitHub Releases.

للتثبيت غير التفاعلي:

COVER_AGENTS=openai,claude \
  curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

git clone https://github.com/DavidCarliez/cover.git
cd cover
go build -o cover ./cmd/cover
install -m 0755 cover ~/.local/bin/cover

GOOS=linux GOARCH=arm64 go build -o cover-linux-arm64 ./cmd/cover
GOOS=windows GOARCH=amd64 go build -o cover.exe ./cmd/cover

بدء سريع

cover init             # write ~/.config/cover/config.yaml
cover start --detach   # run in the background
cover doctor           # verify the local setup
cover test             # local redaction round trip, no network call
cover monitor          # watch privacy-safe request metadata

يطالبك cover init بإدخال مزوّد OpenAI أو Anthropic أو upstream مخصص. التكوين الكامل موثق في configs/config.example.yaml.

مرجع الأوامر

لا يغيّر إيقاف Cover تهيئة العملاء. العميل الذي لا يزال موجّهًا إلى Cover سيفشل في الاتصال حتى تتم إعادة تشغيل Cover أو يُعاد توجيه العميل إلى مزوّده المباشر أو الموجّه الخاص به.

سياسات الخصوصية

يغطي الكشف المدمج عبر التعبيرات النمطية مفاتيح AWS وGCP، ورمزات GitHub وGitLab وSlack وStripe وAnthropic، وكتل المفاتيح الخاصة، وJWTs، وتعيينات الأسرار العامة الصريحة، ورسائل البريد الإلكتروني، وأرقام الضمان الاجتماعي (SSNs)، وبطاقات الائتمان، وأرقام الهاتف، وأرقام IBAN. قيمة OpenAI المجردة بصيغة sk-... ليست عن قصد فئة مدمجة مخصصة. حدّد قاعدة صريحة إذا كانت بيئتك تحتاج إليها.

توجد القواعد تحت rules في ~/.config/cover/config.yaml. يمكن أن يكون المحدد تعبيرًا نمطيًا، أو كاشفًا من نوع builtin_*، أو قائمة بمفاتيح كائنات JSON.

rules:
  password_fields:
    keys: [password, passwd, pwd, passphrase, user_password, database_password]
    category: password
    action: pseudonymize
    generator: password
    priority: 220

  ipv4_addresses:
    detector: builtin_ipv4
    category: ip_address
    action: pseudonymize
    generator: ipv4
    priority: 100

  customer_name:
    pattern: '(?i)\bNIKE\b'
    category: customer
    action: pseudonymize
    generator: alias
    priority: 80

  forbidden_secret:
    pattern: '(?i)secret\s*[:=]\s*(?P<value>[^\s,;]+)'
    action: block
    priority: 200

تحمي محددات المفاتيح قيم السلاسل الكاملة. على سبيل المثال، تتم حماية {"password":"admin"} دون معاملة {"username":"admin"} غير المرتبطة بها ككلمة مرور. تتيح المجموعات المسماة (?P<value>...) للتعبير النمطي استبدال القيمة الملتقطة فقط.

مولّدات الأسماء المستعارة: ipv4 وipv6 وhostname وdomain وfqdn وemail وusername وpassword وsecret وuuid وurl وalias.

يتم التحقق من القواعد عند بدء التشغيل. المحددات أو التعبيرات أو الإجراءات أو المولّدات أو مجموعات الالتقاط غير الصالحة تمنع Cover من البدء. أخطاء الكاشف، واستنفاد التعيين، وJSON غير الصحيح، والأجسام المضغوطة، والحظر الصريح لا تتراجع إلى تمرير الطلب الأصلي.

الأسماء المستعارة المستقرة والتعيينات القابلة للعكس

ينشئ Cover ملف ~/.config/cover/pseudonym.key بصلاحيات المالك فقط. يشتق HMAC-SHA-256 الاسم المستعار نفسه لنفس القيمة الأصلية عبر الجلسات وعمليات إعادة التشغيل. تنتج التثبيتات المختلفة أسماء مستعارة مختلفة.

لا يمكن للمفتاح استعادة القيم الأصلية. تستخدم الاستعادة تعيينات محدودة محفوظة في ذاكرة العملية فقط. تُفصل التعيينات بواسطة X-Cover-Session، وتنتهي صلاحيتها بعد TTL المكوَّن، وتُحذف عند اكتمال طلب معزول. احتفظ بنسخة احتياطية من المفتاح فقط إذا كانت استمرارية الأسماء المستعارة المستقرة مهمة.

الفحص والتشخيص والمراقبة

المعاينة دون إرسال

cover inspect request.json
cover inspect request.json --session demo

يحتوي التقرير على الطلب المحوَّل، والقواعد المطابقة، والفئات، والإجراءات، والتحذيرات، وحالة الحظر. لا يرسل طلب شبكة ولا يطبع التعيين القابل للعكس.

التحقق من التثبيت

cover doctor
cover doctor --json

يتحقق Doctor من التهيئة، وسياسة المستمع، والحدود، ومفتاح الاسم المستعار، ودورة التنقيح، وحماية حلقة upstream، والخفيّة، وسلوك الإغلاق عند الفشل، وسجل التدقيق، وتوجيه البيئة، ومزوّد Codex، وضغط طلبات Codex. يُرفض اختباره الحي محليًا ولا يستهلك رمزات النموذج.

مراقبة آمنة افتراضيًا

cover monitor
cover monitor --follow=false -n 50
cover monitor --json

يعرض المُراقِب الافتراضي بيانات وصفية مدرجة في القائمة البيضاء فقط: الوقت، وحالة HTTP، وعدد التحويلات، وأعداد البايتات، وزمن الاستجابة، والفئات، والأخطاء العامة. لا تحتوي سجلات التدقيق أبدًا على أجسام الطلبات أو الاستجابات، أو القيم المطابقة، أو التعيينات، أو المسارات، أو الاستعلامات، أو بيانات اعتماد upstream.

عرض حي حساس صريح

cover monitor --show-content
cover monitor --show-content --once
cover monitor --show-content --json

يعرض هذا العرض الاختياري كل قيمة أصلية ملتقطة واستبدالها، يلي ذلك JSON المحوَّل تمامًا المُسلَّم إلى ناقل upstream. وهو حي فقط ولا يُضاف أبدًا إلى سجل التدقيق. يبدأ الالتقاط بعد أن يتصل عارض محلي موثَّق ويتوقف عند انقطاعه. التدفق مقتصر على الحلقة المحلية، ويستخدم رمزًا مشتقًا من مفتاح التثبيت، ويفصل العارضين البطيئين.

[!WARNING] مخرجات الطرفية هذه حساسة. لا تستخدم --show-content في أطراف مشتركة أو جلسات مسجَّلة أو سجلات CI أو نصوص الدعم.

توصيل العملاء

يمرّر Cover أساليب الطلبات ومساراتها واستعلاماتها وترويساتها إلى upstream المكوَّن. تظل مصادقة المزوّد الحالية تعمل لأن Cover لا يعيد كتابة ترويسات المصادقة.

Codex وCodex Router

يستخدم Codex واجهة Responses API. أضف مزوّدًا على مستوى المستخدم إلى ~/.codex/config.toml وعطّل ضغط الطلبات حتى يتمكن Cover من فحص الجسم:

model_provider = "cover"

[model_providers.cover]
name = "Cover"
base_url = "http://127.0.0.1:8317"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

[features]
enable_request_compression = false

تتبع هذه المفاتيح مرجع تهيئة Codex الرسمي. إذا كان [features] موجودًا بالفعل، أضف الإعداد إلى ذلك الجدول. بالنسبة لموجّه يقرأ رمزًا من البيئة، استبدل requires_openai_auth بـ env_key = "YOUR_ROUTER_KEY_ENV_NAME".

أبقِ upstream الخاص بـ Cover موجّهًا إلى عنوان URL الحقيقي للموجّه. استخدم configs/codex-router.example.yaml كنقطة بداية. يمكن أن يكون النموذج المحدد OpenAI أو Anthropic أو Gemini أو DeepSeek أو نموذجًا آخر لأن Cover يعمل على حركة JSON العامة للموجّه.

حقول encrypted_content في Responses API غير شفافة ومتحقق منها تشفيريًا. يتركها Cover دون تغيير أثناء فحص الطلبات واستعادة الاستجابات.

Claude Code وSDKs والعملاء الآخرون

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export OPENAI_BASE_URL=http://127.0.0.1:8317/v1

يستخدم Claude Code الصيغة الأولى. تستخدم SDKs والعملاء المتوافقون مع OpenAI الصيغة /v1 عمومًا. يمكن للمثبّت حفظ هذه الإعدادات، ويطبع cover env المُصدَّرات للعملاء المحددين أثناء التثبيت.

يمكن لمنشئات SDK تعيين عنوان URL الأساسي نفسه مباشرة:

client = OpenAI(base_url="http://127.0.0.1:8317/v1", api_key=os.environ["OPENAI_API_KEY"])
client = anthropic.Anthropic(base_url="http://127.0.0.1:8317", api_key=os.environ["ANTHROPIC_API_KEY"])

يمكن لـ Cursor والتطبيقات الأخرى استخدام نقطة النهاية نفسها عندما توفّر إعداد عنوان URL أساسي لواجهة API. أكّد التوجيه باستخدام cover doctor أو cover monitor.

Pi وOh My Pi

تتحكم إضافة التسخير الرسمية في Cover من Pi أو Oh My Pi مع إبقاء محرك الخصوصية في وكيل Go المحلي:

pi install npm:cover-harness
# or
omp plugin install cover-harness

قم بتهيئة المزوّدات التي يجب أن تمر عبر upstream الحالي الخاص بـ Cover فقط:

/cover providers openai-codex,deepseek=/
/cover on
/cover doctor

تستخدم مزوّدات عائلة OpenAI مسار الوكيل /v1 افتراضيًا. يحدد =/ جذر الوكيل للناقلات مثل DeepSeek التي تضيف مسار طلب خاصًا بها. استخدم /cover status و/cover start و/cover stop و/cover monitor للعمل العادي. يعيد /cover off التوجيه المباشر للمزوّدات.

الحماية مغلقة عند الفشل: عند التمكين، تظل المزوّدات المكوَّنة موجّهة إلى Cover عندما تكون الخفيّة الخاصة به غير متاحة، لذلك تفشل الطلبات محليًا بدلًا من تجاوز الوكيل. حالة الإضافة خاصة ومحلية في ~/.config/cover/harness.json.

تظهر الحزمة نفسها في معرض حزم Pi. يمكن لمستخدمي OMP أيضًا إضافة هذا المستودع كسوق:

omp plugin marketplace add DavidCarliez/cover
omp plugin install cover-harness@cover

كاشف LLM المحلي الاختياري

لا يمكن للتعبيرات النمطية والقواعد المدركة للمفاتيح تحديد كل اسم أو عنوان أو معرّف عميل أو اسم رمزي داخلي. يمكن لـ Cover تشغيل نموذج llama.cpp محلي صغير ككاشف دلالي إضافي.

cover models pull
cover models status
cover restart

النموذج الافتراضي هو Qwen2.5-0.5B-Instruct بصيغة Q4 GGUF بحوالي 490 ميجابايت. يشغّل Cover خادم llama-server على الحلقة المحلية ويفرض ميزانيات لكل استدعاء وللإجمالي. الملفات الثنائية المفقودة، وأعطال بدء التشغيل، وانتهاء المهلة، وأخطاء الكاشف تُغلق عند الفشل عندما يكون الكاشف مفعّلًا. يجب أن تظهر المقاطع المُعادة حرفيًا في الإدخال قبل أن يقبلها Cover.

اترك هذه الميزة معطّلة على المنصات غير المدعومة. راجع قسم detectors.llm_fallback في configs/config.example.yaml للحدود والتجميع (batching) والتزامن ومسارات النماذج.

حدود الأمان

يحمي Cover قيم السلاسل المطابقة في أجسام JSON التي تمر فعليًا عبر الوكيل. لا يدّعي اكتشاف كل قيمة حساسة.

لا يزال من الممكن أن تغادر البيانات الجهاز عندما تظهر في:

• قيمة لا يتعرف عليها أي كاشف أو قاعدة مفعّلة؛
• حقل تغطيه قاعدة allow؛
• ترويسات HTTP أو مسارات URL أو سلاسل الاستعلام؛
• بكسلات الصور أو الوسائط الثنائية أو الترميزات غير المدعومة؛
• قيم JSON غير نصية؛
• حقول بروتوكول هيكلية مثل النموذج والدور والنوع والمعرّفات وأسماء الأدوات أو الدوال؛
• encrypted_content غير الشفاف، الذي يجب أن يظل دون تغيير لسلامة البروتوكول؛
• حركة المرور من عميل يتجاوز Cover.

يمكن ضبط معالجة الصور المضمّنة عبر media.images: allow أو warn أو block. لا يفحص Cover البكسلات، ولا يمكن لأي سياسة وسائط التعرف على كل ترميز ممكن.

يرفض Cover المستمعات غير الموجودة على الحلقة المحلية ما لم يتم تكوين network.allow_remote: true صراحةً. إذا كان Cover وموجّه upstream خاصته يعملان على مضيفين مختلفين، فاستخدم TLS أو ناقلًا موثوقًا آخر وطبّق ضوابط وصول شبكة منفصلة. لا يقوم Cover نفسه بمصادقة حركة مرور الوكيل العادية.

تحدّ حدود الطلبات، والاستجابات المخزنة مؤقتًا، وإجمالي التدفقات، وأحداث SSE الفردية من استخدام الذاكرة. تُرجع الطلبات كبيرة الحجم HTTP 413، وتُرجع الاستجابات المخزنة كبيرة الحجم HTTP 502، وتُنهى التدفقات كبيرة الحجم.

اقرأ SECURITY.md قبل الإبلاغ عن ثغرة أمنية. يُرجى استخدام مسار الإبلاغ الخاص الموضح هناك بدلًا من فتح issue عامة.

المشروع

• التطوير والاختبارات: CONTRIBUTING.md
• قواعد السلوك: CODE_OF_CONDUCT.md
• الترخيص: Apache License 2.0