llm-token-proxy

وكيل شفاف لإخفاء معلومات التعريف الشخصية (PII) لحركة مرور واجهة برمجة تطبيقات نماذج اللغة الكبيرة (LLM). يجلس بين تطبيقك وموفر LLM، حيث يقوم بإخفاء البيانات الحساسة باستخدام أسماء مستعارة (pseudonymization) في طريق الخروج، وإعادتها إلى حالتها الأصلية في طريق العودة.

لا يرى LLM الخاص بك أبدًا الأسماء الحقيقية أو رسائل البريد الإلكتروني أو عناوين IP أو النطاقات - بل يعمل بالكامل مع أسماء مستعارة منظمة مثل [email protected]. يحصل تطبيقك على القيم الأصلية مرة أخرى، بشفافية تامة.

لماذا

عند استخدام LLMs لعمليات الأمن، أو الاستجابة للحوادث، أو أي مهمة تتضمن بيانات حقيقية للعملاء، فإنك تخاطر بإرسال معلومات التعريف الشخصية (PII) إلى واجهات برمجة تطبيقات طرف ثالث. يحل هذا الوكيل تلك المشكلة عن طريق:

• استبدال معلومات التعريف الشخصية الحقيقية بأسماء مستعارة حتمية ومنظمة قبل وصولها إلى LLM
• استعادة القيم الأصلية في الرد قبل وصوله إلى تطبيقك
• الحفاظ على التناسق داخل الجلسة (نفس المدخلات تتوافق دائمًا مع نفس الاسم المستعار)
• العمل بشفافية - دون الحاجة إلى تغييرات في الكود في تطبيقك

بداية سريعة

# 1. أنشئ ملف التهيئة الخاص بك
cp config.json.example config.json
# قم بتعديل config.json بإضافة نطاقاتك الداخلية، الكيانات المعروفة، إلخ.

# 2. شغّل باستخدام Docker
docker build -t llm-token-proxy .
docker run -p 8090:8080 -v ./config.json:/app/config.json llm-token-proxy

# 3. وجّه تطبيقك إلى الوكيل
export ANTHROPIC_BASE_URL=http://localhost:8090/session/my-session/

هذا كل شيء. أصبحت استدعاءات واجهة برمجة تطبيقات Anthropic تمر الآن عبر الوكيل مع إخفاء معلومات التعريف الشخصية.

كيف يعمل

تيار نموذجي: تطبيق → وكيل الرموز (إخفاء PII) → واجهة برمجة تطبيقات LLM (أسماء مستعارة فقط) → وكيل الرموز (استعادة الأصول) → تطبيق

خط أنابيب الكشف (3 مرات)

1. التعبيرات النمطية (Regex) — عناوين البريد الإلكتروني، عناوين IP، النطاقات، وأنماط مدفوعة بالتهيئة (أشخاص معروفون، مؤسسات، أسماء مضيفين)
2. التعرف على الكيانات المسماة (NER) — يلتقط التعرف على الكيانات المسماة من spaCy أسماء الأشخاص والمؤسسات التي تفوتها التعبيرات النمطية
3. استخراج اسم المستخدم — الأجزاء المحلية لعناوين البريد الإلكتروني المجردة (مثل admin من [email protected])

تنسيق الاسم المستعار

الأسماء المستعارة حتمية داخل الجلسة - نفس القيمة الحقيقية تتوافق دائمًا مع نفس الاسم المستعار.

إخفاء عنوان IP مع الحفاظ على السياق

عندما يقوم LLM بتحليل سجلات الأمن، فإن مزود الاستضافة والموقع الجغرافي لعنوان IP مهمان - تسجيل الدخول من عنوان IP لـ Hetzner في ألمانيا يحكي قصة مختلفة عن تسجيل الدخول من مزود خدمة إنترنت سكني في الولايات المتحدة. الاستبدال الساذج بعناوين IP من نطاق التوثيق (مثل 198.51.100.x) يدمر هذا السياق.

مع قاعدة بيانات MaxMind GeoLite2-ASN الاختيارية، يستبدل الوكيل عناوين IP الحقيقية بعنوان IP مختلف من نفس ASN والشبكة الفرعية. يرى LLM عنوان IP يبدو حقيقيًا ويتحول إلى نفس مزود الاستضافة والموقع الجغرافي التقريبي - لكنه ليس العنوان الفعلي.

• يتم استبدال عنوان IP لـ Hetzner بعنوان IP مختلف لـ Hetzner من نفس البادئة
• يبقى عنوان IP لـ Cloudflare عنوان IP لـ Cloudflare
• يتم تعيين عناوين IP الداخلية / RFC1918 دائمًا إلى 10.99.99.x (لا يوجد سياق ASN للحفاظ عليه)
• بدون قاعدة بيانات GeoIP، تقع عناوين IP الخارجية إلى 198.51.100.x (نطاق التوثيق)

يتم اختيار عنوان IP المانح بشكل حتمي عبر HMAC مع ملح خاص بالجلسة، بحيث يتم تعيين نفس عنوان IP الحقيقي دائمًا إلى نفس المانح داخل الجلسة، لكن الجلسات المختلفة تنتج تعيينات مختلفة.

التهيئة

يأتي الوكيل مع config.json فارغ - لا توجد قوائم كلمات مدمجة أو افتراضات خاصة بالمجال. تم ضبط config.json.example المرفق لـ عمليات الأمن مع Microsoft Sentinel و Entra ID (أكثر من 8,000 اسم جدول/عمود لـ KQL، مصطلحات إذن Graph API، نطاقات مرجعية أمنية). إذا كان ذلك يتوافق مع حالة الاستخدام الخاصة بك، فانسخ ما تحتاجه منه. إذا كنت تستخدم الوكيل لمجال مختلف (الرعاية الصحية، القانوني، المالي، إلخ)، فابدأ من التهيئة الفارغة وقم ببناء قوائمك الخاصة.

config.json

{
  "internal_domains": ["yourcompany.com"],
  "partner_domains": ["partnercorp.com"],
  "internal_ip_ranges": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
  "known_persons": ["John Smith"],
  "known_orgs": ["YourCompany"],
  "known_hostnames": ["DC01", "FS01"],
  "ner_enabled": true,
  "ner_skiplist": [],
  "redaction_enabled": true
}

• internal_domains — النطاقات المصنفة على أنها "داخلية" (تحصل على أسماء مستعارة _internal_)
• partner_domains — النطاقات المصنفة على أنها "شريكة"
• internal_ip_ranges — نطاقات CIDR لتصنيف عناوين IP الداخلية
• known_persons/orgs/hostnames — الكيانات المطابقة بالتعبيرات النمطية (كشف مضمون)
• ner_enabled — تشغيل/إيقاف NER من spaCy (يتطلب spacy + en_core_web_sm)
• ner_skiplist — المصطلحات التي يجب على نموذج NER تجاهلها (يقلل من النتائج الإيجابية الخاطئة)
• redaction_enabled — مفتاح رئيسي؛ عندما يكون false، يصبح الوكيل مجرد تمرير نقي
• pseudonymize_domains — عندما يكون false، تمر النطاقات دون تعديل (لا يزال يتم إخفاء رسائل البريد الإلكتروني وعناوين IP والأسماء). مفيد عندما تحمل أسماء النطاقات سياقًا مهمًا لـ LLM (مثل التمييز بين outlook.com و protonmail.com) ولا تعتبر حساسة.

متغيرات البيئة

واجهة برمجة تطبيقات التهيئة أثناء التشغيل

إدارة القوائم البيضاء وتشغيل/إيقاف الإخفاء دون إعادة التشغيل:

# عرض جميع القوائم البيضاء
curl http://localhost:8090/token-proxy/config/whitelist

# إضافة مصطلحات إلى قائمة تخطي NER (يقلل النتائج الإيجابية الخاطئة)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "ner_skiplist", "values": ["EvoSTS", "Hetzner"]}'

# إضافة نطاقات إلى القائمة المسموح بها (لا يتم إخفاءها أبدًا)
curl -X POST http://localhost:8090/token-proxy/config/whitelist \
  -H "Content-Type: application/json" \
  -d '{"category": "domain_allowlist", "values": ["github.com"]}'

# تعطيل الإخفاء (وضع التمرير)
curl -X POST http://localhost:8090/token-proxy/config/status \
  -H "Content-Type: application/json" \
  -d '{"redaction_enabled": false}'

فئات القائمة البيضاء: ner_skiplist، domain_allowlist، known_persons، known_orgs، known_hostnames

واجهة برمجة تطبيقات التفتيش والتدقيق

تفحص ما يفعله الوكيل في الوقت الفعلي:

# عرض الجلسات النشطة
curl http://localhost:8090/token-proxy/sessions

# عرض تعيينات الأسماء المستعارة لجلسة
curl http://localhost:8090/token-proxy/sessions/{session_id}/mappings

# عرض سجل نشاط الإخفاء
curl http://localhost:8090/token-proxy/sessions/{session_id}/log

# البحث في التعيينات
curl http://localhost:8090/token-proxy/sessions/{session_id}/search?q=admin

# عرض البيانات الملتقطة (ما رآه LLM بالفعل)
curl http://localhost:8090/token-proxy/sessions/{session_id}/payloads

# استخدام الرموز لجلسة (رموز الإدخال/الإخراج عبر جميع الطلبات)
curl http://localhost:8090/token-proxy/sessions/{session_id}/usage

# إحصائيات عامة (تشمل total_tokens عبر جميع الجلسات)
curl http://localhost:8090/token-proxy/stats

تتبع استخدام الرموز

يسجل الوكيل input_tokens و output_tokens لكل طلب يقوم بتوجيهه - سواء كان غير متدفق (يُقرأ من كائن usage في الرد) أو متدفق (يُحلل من أحداث SSE message_start و message_delta). نظرًا لأن الوكيل يجلس بين تطبيقك و LLM، تحصل على نقطة اختناق واحدة لقياس الاستهلاك عبر جميع العملاء الذين يشاركونه، دون الحاجة إلى إضافة أجهزة قياس لكل عميل على حدة.

curl http://localhost:8090/token-proxy/sessions/my-session/usage
# {
#   "session_id": "my-session",
#   "request_count": 3,
#   "input_tokens": 1240,
#   "output_tokens": 587
# }

curl http://localhost:8090/token-proxy/stats | jq .total_tokens
# { "input_tokens": 48213, "output_tokens": 19044 }

يتم تضمين استخدام كل طلب أيضًا في /token-proxy/sessions/{session_id}/log تحت usage_counts. يتم تتبع أعداد الرموز الأولية فقط - يُترك التسعير للمتصل.

دعم التدفق (Streaming)

يدعم الوكيل تدفق SSE (stream: true). يتم استعادة الأسماء المستعارة في الوقت الفعلي باستخدام نهج المخزن المؤقت الذيل (tail-buffer) الذي يتعامل مع الأسماء المستعارة المقسمة عبر أجزاء SSE.

إضافة دعم لموفر

يستخدم الوكيل نمط محول الموفر (provider adapter pattern). يدعم حاليًا:

• واجهة برمجة تطبيقات رسائل Anthropic (/v1/messages)

انظر CONTRIBUTING.md لكيفية إضافة دعم لموفرين إضافيين (OpenAI، Google Gemini، إلخ).

القيود

• نص فقط — يقوم الوكيل بفحص حقول النص JSON في طلب/رد API. الصور، ملفات PDF، والمحتوى الثنائي الآخر (مثل المرفقات المشفرة بـ base64 في طلبات الرؤية) تمر دون إخفاء. إذا كان سير عملك يرسل لقطات شاشة أو مستندات تحتوي على PII، فستصل إلى LLM دون تعديل.
• NER مخصص للغة الإنجليزية فقط — يكتشف نموذج spaCy (en_core_web_sm) أسماء الأشخاص/المؤسسات الإنجليزية. قد يتم فقدان الأسماء بلغات أخرى ما لم يتم إضافتها إلى known_persons/known_orgs في التهيئة.
• للتعبيرات النمطية نقاط عمياء — لن يتم اكتشاف PII بتنسيقات غير عادية (مثل رسائل البريد الإلكتروني المخفية مثل admin [at] acme.com، أرقام الهواتف، العناوين الفعلية). تم ضبط خط أنابيب الكشف على البيانات الهيكلية لتكنولوجيا المعلومات/الأمن.
• جلسات في الذاكرة — تعيش تعيينات الجلسة في الذاكرة وتفقد عند إعادة التشغيل. لا يوجد تخزين دائم. يتم إخلاء الجلسات تلقائيًا بعد ساعتين.
• Anthropic فقط — يأتي حاليًا مع محول لواجهة برمجة تطبيقات رسائل Anthropic. يتطلب الموفرون الآخرون (OpenAI، Google Gemini) كتابة محول موفر (انظر CONTRIBUTING.md).
• لا توجد مصادقة على واجهات برمجة تطبيقات الإدارة — نقاط النهاية /token-proxy/config/* و /token-proxy/sessions/* ليس لديها مصادقة. الوكيل مصمم للشبكات الموثوقة/الداخلية - لا تعرض نقاط النهاية هذه لشبكات غير موثوقة.

التطوير

# تثبيت تبعيات التطوير
pip install -e ".[dev,ner]"
python -m spacy download en_core_web_sm

# تشغيل الاختبارات
pytest

# التدقيق اللغوي
ruff check token_proxy/ tests/

الترخيص

Apache 2.0 — انظر LICENSE.