OmniRoute/docs/i18n/ar/docs/security/COMPLIANCE.md

Compliance & Audit (العربية)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

مصدر الحقيقة: src/lib/compliance/، src/app/api/compliance/ آخر تحديث: 2026-06-28 — v3.8.40

يسجّل OmniRoute الإجراءات الإدارية وأحداث المصادقة وتغييرات دورة حياة بيانات اعتماد المزوّد واستدعاءات أدوات MCP في جداول تدقيق مدعومة بقاعدة بيانات SQLite. توضّح هذه الصفحة ما يتم تسجيله، ومكان تخزينه، ومدة الاحتفاظ به، وكيف يمكن لمفاتيح API إلغاء الاشتراك، وكيفية الاستعلام عن البيانات.

يوجد التنفيذ في src/lib/compliance/index.ts ‏(T-43 — «عناصر التحكم في الامتثال») وsrc/lib/compliance/providerAudit.ts. لا تطرح عمليات كتابة التدقيق أي استثناءات مطلقًا: عند حدوث أي فشل، يتم تجاهل الاستدعاء بصمت حتى لا يؤدي تسجيل التدقيق إلى تعطيل مسار الطلب الرئيسي.

ما يتم تسجيله

أحداث التدقيق الإدارية (audit_log)

ينتج كل استدعاء لـlogAuditEvent({ action, actor, target, details, ... }) صفًا واحدًا. تتبع سلاسل الإجراءات نمط domain.verb (أو domain.verb.outcome). تشمل أنواع الإجراءات المؤكدة في شجرة المصدر ما يلي:

الإجراء	المصدر
auth.login.success	src/app/api/auth/login/route.ts
auth.login.failed	src/app/api/auth/login/route.ts
auth.login.locked	src/app/api/auth/login/route.ts
auth.login.error	src/app/api/auth/login/route.ts
auth.login.misconfigured	src/app/api/auth/login/route.ts
auth.login.setup_required	src/app/api/auth/login/route.ts
auth.logout.success	src/app/api/auth/logout/route.ts
provider.credentials.created	src/app/api/providers/route.ts
provider.credentials.updated	src/app/api/providers/[id]/route.ts
provider.credentials.revoked	src/app/api/providers/[id]/route.ts
provider.credentials.batch_revoked	src/app/api/providers/route.ts
sync.token.created	src/app/api/sync/tokens/route.ts
sync.token.revoked	src/app/api/sync/tokens/[id]/route.ts
compliance.cleanup	src/lib/compliance/index.ts

يلتقط كل إدخال action وactor (القيمة الافتراضية هي "system") وtarget وdetails/metadata ‏(JSON) وip_address وresource_type وstatus وrequest_id وtimestamp. تُحجب المفاتيح الحساسة (apiKey وaccessToken وrefreshToken وpassword وأي مفتاح يطابق *token/*secret/*apikey وما إلى ذلك) بشكل تكراري وتُستبدل بـ"[redacted]" قبل كتابة الصف.

استدعاءات أدوات MCP ‏(mcp_tool_audit)

يكتب كل استدعاء لأداة MCP صفًا من خلال open-sse/mcp-server/audit.ts. المخطط (من src/lib/db/migrations/002_mcp_a2a_tables.sql):

العمود	ملاحظات
id	زيادة تلقائية
tool_name	معرّف أداة MCP
input_hash	تجزئة sha256 للمدخلات (لا تُخزَّن الحمولة)
output_summary	ملخص قصير ومقتطع
duration_ms	الزمن المنقضي
api_key_id	المستدعي (يمكن أن تكون قيمته خالية)
success	1 / 0
error_code	رمز الخطأ النهائي عند الفشل
created_at	طابع زمني بتنسيق ISO

سجلات الطلبات / الاستخدام

تمثل هذه السجلات قياسات تشغيلية (وليست تدقيقًا إداريًا بالمعنى الدقيق)، لكنها تشترك في مسار الاحتفاظ نفسه:

• usage_history — تجميع الاستخدام لكل طلب
• call_logs — سجل كامل لكل طلب (يخضع لحد أقصى لعدد الصفوف، انظر أدناه)
• proxy_logs — سجل حركة مرور الوكيل (يخضع لحد أقصى لعدد الصفوف)
• request_detail_logs — سجل قديم لتفاصيل الطلبات (يظل خاضعًا للتنقية إذا كان موجودًا)

مخطط التخزين

يُنشأ audit_log بشكل مؤجل بواسطة ensureAuditLogSchema() عند أول استخدام:

CREATE TABLE IF NOT EXISTS audit_log (
  id            INTEGER PRIMARY KEY AUTOINCREMENT,
  timestamp     TEXT NOT NULL DEFAULT (datetime('now')),
  action        TEXT NOT NULL,
  actor         TEXT NOT NULL DEFAULT 'system',
  target        TEXT,
  details       TEXT,
  ip_address    TEXT,
  resource_type TEXT,
  status        TEXT,
  request_id    TEXT,
  metadata      TEXT
);

تُنشأ الفهارس على timestamp وaction وactor وresource_type وstatus وrequest_id. وتُضاف الأعمدة المفقودة في قواعد البيانات القديمة عبر ALTER TABLE عند الحاجة.

الاحتفاظ والتنظيف

تُراعى نافذتان منفصلتان للاحتفاظ:

متغير البيئة	القيمة الافتراضية	ينطبق على
APP_LOG_RETENTION_DAYS	7	audit_log، mcp_tool_audit
CALL_LOG_RETENTION_DAYS	7	usage_history، call_logs، proxy_logs، request_detail_logs
CALL_LOGS_TABLE_MAX_ROWS	100000	تقليص call_logs وفق الحد الأقصى للصفوف
PROXY_LOGS_TABLE_MAX_ROWS	100000	تقليص proxy_logs وفق الحد الأقصى للصفوف

تُشغّل cleanupExpiredLogs() عملية الاحتفاظ. ويجري استدعاؤها عند بدء تشغيل الخادم من src/instrumentation-node.ts. ويسجّل كل تشغيل حدث تدقيق compliance.cleanup يتضمن أعداد العناصر المحذوفة لكل جدول. يُنفّذ تقليص سجلات الوكيل/الاستدعاءات على دفعات (BATCH_SIZE = 5000) لتجنب أقفال الكتابة طويلة الأمد.

يكون التنظيف اليدوي لسجل الطلبات منفصلًا عن عملية الاحتفاظ. تستدعي صفحة سجلات الطلبات POST /api/settings/purge-request-history، الذي يحذف call_logs وrequest_detail_logs القديم، وآثار الطلبات المحلية الموجودة ضمن ${DATA_DIR}/call_logs/.

تُعرّف القيم الافتراضية في src/lib/logEnv.ts (DEFAULT_APP_LOG_RETENTION_DAYS = 7، وDEFAULT_CALL_LOG_RETENTION_DAYS = 7).

إلغاء الاشتراك عبر noLog (لكل مفتاح API)

يمكن تمييز مفاتيح API بحيث لا تُسجّل حركة استدعاءاتها اللاحقة. توجد العلامة في جدول api_keys (no_log INTEGER DEFAULT 0)، وتُنسخ أيضًا إلى مجموعة في الذاكرة لإجراء عمليات البحث في المسار السريع.

# إنشاء مفتاح لا يسجّل البيانات (مصادقة الإدارة مطلوبة)
curl -X POST http://localhost:20128/api/keys \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Privacy key", "noLog": true}'

الدوال المساعدة (src/lib/compliance/index.ts):

• setNoLog(apiKeyId, true|false) — تبديل الإدخال الموجود في الذاكرة
• isNoLog(apiKeyId) — يُتحقق منها في مسار الطلب؛ وتعود إلى قراءة مخزنة مؤقتًا لمدة 30 ثانية من api_keys.no_log
• NO_LOG_API_KEY_IDS (متغير بيئة، مفصول بفواصل) — يُحمّل مسبقًا إلى المجموعة الموجودة في الذاكرة عند بدء التشغيل؛ وهو مفيد عندما يتعذر تبديل العمود مباشرةً

لا تتأثر أحداث التدقيق الإدارية (تسجيل الدخول، وتغييرات موفر الخدمة، واستدعاءات أدوات MCP، وما إلى ذلك) بـ noLog — إذ يقتصر إلغاء الاشتراك على تسجيل حركة المرور لكل طلب.

واجهة REST API

نقطة النهاية	الطريقة	الوصف	المصادقة
/api/compliance/audit-log	GET	إدخالات تدقيق إدارية مُرقّمة مع عوامل تصفية	management
/api/mcp/audit	GET	إدخالات تدقيق أدوات MCP مُرقّمة	(open-sse)
/api/mcp/audit/stats	GET	إحصاءات تدقيق MCP مُجمّعة	(open-sse)

لا تتوفر حاليًا نقطة نهاية لتصدير CSV — يمكنك التصدير من لوحة المعلومات أو الاستعلام عن قاعدة بيانات SQLite مباشرةً.

الاستعلام عن /api/compliance/audit-log

معاملات الاستعلام المدعومة (كلها اختيارية، وتستخدم جميع عوامل تصفية النصوص مطابقة LIKE %value%):

• action، actor، target، resourceType (أو resource_type)، status، requestId (أو request_id)
• from / since، to / until — طوابع زمنية بتنسيق ISO
• limit (القيمة الافتراضية 50، الحد الأدنى 1، الحد الأقصى 500)
• offset (القيمة الافتراضية 0، الحد الأقصى 10_000)

الاستجابة عبارة عن مصفوفة JSON. تُعاد بيانات ترقيم الصفحات الوصفية في الترويسات: x-total-count، x-page-limit، x-page-offset.

curl "http://localhost:20128/api/compliance/audit-log?action=provider.credentials&from=2026-05-01" \
  -H "Cookie: auth_token=..."

لوحة المعلومات

تعرض لوحة المعلومات بيانات التدقيق في /dashboard/audit (src/app/(dashboard)/dashboard/audit/page.tsx). تحتوي الصفحة على علامتي تبويب:

• الامتثال (ComplianceTab.tsx) — أحداث تدقيق الإدارة من /api/compliance/audit-log. يمكن التصفية حسب نوع الحدث ومستوى الخطورة (معلومات / تحذير / حرج، مشتق من الإجراء + الحالة) والنطاق الزمني. يُحسب مستوى الخطورة من جانب العميل استنادًا إلى سلاسل الإجراء/الحالة.
• MCP (McpAuditTab.tsx) — تدقيق أدوات MCP من /api/mcp/audit، مع عوامل تصفية حسب اسم الأداة والنجاح/الفشل.

تستخدم علامتا التبويب ترقيم الصفحات بحجم 50 (الامتثال) و25 (MCP) لكل صفحة.

دوال بيانات اعتماد المزوّد المساعدة

يوفّر src/lib/compliance/providerAudit.ts دوال مساعدة لتشكيل البيانات تستخدمها مسارات إدارة المزوّدين عند إصدار أحداث بيانات الاعتماد:

• summarizeProviderConnectionForAudit(connection) — يزيل apiKey، وaccessToken، وrefreshToken، وidToken، وproviderSpecificData.consoleApiKey قبل كتابة لقطة الاتصال في details.
• getProviderAuditTarget(connection) — ينشئ سلسلة ثابتة "<provider>:<name|id>" للحقل target.
• extractProviderWarnings(...payloads) — يفحص استجابات المزوّد بحثًا عن تحذيرات السياسة/السلامة ([sanitizer]، وprompt injection detected، وcontent has been filtered، وsafety filter، وpolicy violation) ويُظهر ما يصل إلى 5 نتائج، مع اقتطاع كل منها إلى 400 محرف.

أفضل الممارسات

• ميّز مفاتيح API التي تتعامل مع معلومات التعريف الشخصية (قانونية، طبية، إلخ) باستخدام noLog: true.
• اضبط APP_LOG_RETENTION_DAYS / CALL_LOG_RETENTION_DAYS بما يتوافق مع سياسة الاحتفاظ لديك. القيم الافتراضية البالغة 7 أيام متحفظة.
• صدّر جدول التدقيق إلى خارج المنصة (sqlite3 dump) وفق الوتيرة التي يتطلبها برنامج الامتثال لديك — لا توجد أرشفة مضمّنة.
• تتبّع أعداد auth.login.failed وauth.login.locked لاكتشاف هجمات القوة الغاشمة.
• عند إضافة نقاط نهاية إدارية جديدة، استدعِ logAuditEvent({ ... }) باستخدام سلسلة إجراء ثابتة بنمط domain.verb.outcome، ومرّر سياق الطلب عبر getAuditRequestContext(request) بحيث يتم التقاط عنوان IP وrequestId تلقائيًا.

انظر أيضًا

• docs/security/GUARDRAILS.md — إخفاء معلومات التعريف الشخصية، وحقن المطالبات
• docs/frameworks/MCP-SERVER.md — دليل أدوات MCP ونطاقاتها
• docs/reference/ENVIRONMENT.md — مرجع كامل لمتغيرات البيئة
• المصدر: src/lib/compliance/، src/app/api/compliance/، src/app/api/mcp/audit/، src/lib/logEnv.ts