تدقيق الأمان

ممارسات تدقيق الأمان ومراجعة الكود في شام باص كما يجب أن تُدار اليوم.

warning

الأمثلة في هذه الصفحة مفاهيمية. المرجع التنفيذي النهائي لأي workflow أو جدول أو مسار تدقيق هو التنفيذ الحالي في المستودع.

ملاحظة

هذه الصفحة تصف نهج التدقيق والمراجعة الحالي بصورة تشغيلية. أما النتائج المؤرخة فتوجد في صفحة مستقلة موسومة كتقرير تاريخي.

نظرة عامة

نتبع نهجاً متعدد الطبقات للتدقيق:

1. مراجعة الكود التلقائية
2. اختبارات الأمان
3. تدقيق السجلات
4. اختبار الاختراق الدوري

مراجعة الكود

أدوات التحليل الثابت

# .github/workflows/security.yml
- name: Verify documentation asset safety mitigations
  run: pnpm docs:quality

- name: Run production dependency audit
  run: pnpm audit:prod
# Jobs in the same workflow also run Gitleaks, Semgrep, Trivy and CodeQL.

استثناء Docusaurus المؤقت والمحدود

يعتمد بناء التوثيق على image-size@2.0.2 بصورة غير مباشرة عبر Docusaurus. توجد ثغرتان من درجة high في محللات ICNS وJXL/HEIF، ولا يوفر upstream إصداراً مصححاً حتى تاريخ التحقق. المخاطرة محصورة في وقت بناء موقع التوثيق؛ صورة الإنتاج النهائية ملفات ثابتة تخدمها Nginx ولا تتضمن Node أو Docusaurus.

طبقات التخفيف الإلزامية:

• يفشل pnpm docs:quality إذا دخل ملف .icns أو .jxl أو .heif أو .heic إلى مصادر التوثيق.
• مهلة بناء الويب وLighthouse في CI هي 30 دقيقة لمنع استهلاك runner بلا حد.
• pnpm audit:prod يقبل فقط المعرفين GHSA-w3rx-r6r6-pgpr وGHSA-5p2g-fcmc-qvqq، وفقط عندما تكون كل المسارات ضمن apps/docs عبر @docusaurus/mdx-loader ولا يوجد إصلاح upstream. أي ثغرة high/critical أخرى تفشل CI.
• عند صدور إصلاح، يتوقف الاستثناء تلقائياً عن المطابقة ويجب ترقية Docusaurus/image-size وإزالة هذا القبول.

سلامة متغيرات البناء

يجب أن تبقى USE_DEV_OTP=false في بناء الإنتاج وCI؛ يفشل مسار OTP أثناء جمع صفحات Next.js إذا كانت القيمة true مع NODE_ENV=production. يسجل turbo.json هذا المتغير وكل متغيرات NEXT_PUBLIC_* المؤثرة في الحزمة ضمن مفتاح cache، حتى لا يعاد استخدام artifact بُني بإعدادات بيئة مختلفة.

قواعد ESLint الأمنية

// eslint.config.js
export default [
  {
    plugins: ["security"],
    rules: {
      "security/detect-object-injection": "error",
      "security/detect-non-literal-regexp": "error",
      "security/detect-unsafe-regex": "error",
      "security/detect-buffer-noassert": "error",
      "security/detect-eval-with-expression": "error",
      "security/detect-no-csrf-before-method-override": "error",
      "security/detect-possible-timing-attacks": "warn",
    },
  },
];

مراجعة Pull Requests

قائمة التحقق:

• لا يوجد secrets في الكود
• التحقق من المدخلات (validation)
• التحقق من الصلاحيات (authorization)
• لا يوجد SQL injection
• لا يوجد XSS
• Rate limiting مطبق
• السجلات لا تحتوي بيانات حساسة

اختبارات الأمان

الأولوية الحالية في اختبارات الأمان هي:

• rate limiting لمسارات OTP والجلسات
• منع تجاوز الصلاحيات وعزل الشركات
• حماية مسارات الإدارة الحساسة
• التأكد من تنظيف الجلسات وcookies
• التأكد من عدم تسريب البيانات الحساسة إلى السجلات أو الاستجابات

ربط العامل الثاني بالجلسة

لا يكفي نجاح كلمة مرور Supabase للوصول إلى أسطح الإدارة أو السائق المحمية. بعد نجاح TOTP، يسجل الخادم session_id الحالي في verified_second_factor_sessions مع نوع الحساب ووقت انتهاء قصير. تتحقق الحراس من جلسة Supabase نفسها ومن هذا السجل معاً، لذلك لا تمنح جلسة أُنشئت مباشرة من نقطة كلمة المرور العامة صلاحية تتجاوز العامل الثاني.

• لا يقرأ الجدول أو يكتبه إلا service_role، مع RLS مفعّل وامتيازات المتصفح مسحوبة.
• يسجل log_2fa_attempt النجاح والفشل دون قبول هوية مشرف من عميل غير موثوق، ويحوّل عنوان IP إلى INET بصورة آمنة حتى لا يفشل تسجيل الدخول بسبب ترويسة proxy.
• يسحب تسجيل الخروج أو انتهاء المهلة صلاحية الجلسة الموثقة، ولا تُنقل الثقة إلى refresh token أو جلسة أخرى.
• يتحقق غلاف الإدارة من GET /api/auth/me قبل عرض التنقل المحمي. ترفض هذه البوابة التوكن الموجود في blocklist وإثبات العامل الثاني المنتهي، وتعيد المشرف إلى الدخول بدلاً من إبقاء واجهة تبدو موثقة بينما ترفض API طلباتها.
• تختبر استجابة الهوية صراحةً أنها لا تحتوي totp_secret أو backup_codes حتى إذا احتاج الحارس الصف الكامل لتنفيذ السياسة داخل الخادم.
• اختبارات الإنتاج تشمل دخول owner/admin/support الصحيح، رفض الأدوار غير المصرحة، ومنع الوصول قبل TOTP حتى عند وجود جلسة Auth صالحة.

دخل هذا العقد عبر الترحيلين 00184_fix_admin_2fa_audit_logging.sql و 00185_verified_second_factor_sessions.sql. يصحح الترحيل 00186_fix_support_admin_view_permission.sql كود صلاحية عرض المشرفين لحساب الدعم من دون توسيع بقية صلاحياته.

تدقيق صلاحيات الدوال وقت التشغيل

تمنع التهيئة الحالية منح EXECUTE الشامل للدورين anon وauthenticated. يطبق الترحيل 00198_security_runtime_hardening.sql قائمة سماح صغيرة لدوال SECURITY DEFINER العامة، ويعيد دوال الموافقة على الشركات والعروض و2FA والتنظيف والـ triggers إلى service_role فقط. يكرر اختبار القبول verifier بعد تشغيل db-bootstrap نفسه، لأن نجاحه قبل restart فقط لا يكشف regression في bootstrap.

في التحقق المحلي المؤرخ 2026-08-10 نجحت اختبارات التكامل 27/27 ملفاً و269/269 اختباراً بعد migration وbackfill وإعادة bootstrap. هذا دليل على العقود الآلية المذكورة، وليس بديلاً عن اختبار اختراق مستقل.

سجل التدقيق

الأحداث المسجلة

أمثلة الأحداث المتوقعة في سجل التدقيق:

• نجاح/فشل تسجيل الدخول
• أحداث 2FA الإدارية
• دعوات المشرفين وتعديل الصلاحيات
• تعليق الشركات والتحذيرات ورفعها
• تصدير البيانات أو تنفيذ أوامر إدارية حساسة

ما الذي يجب تسجيله؟

• من نفّذ العملية
• نوع الإجراء
• المورد أو السطح المتأثر
• توقيت التنفيذ
• النتيجة العامة
• أقل قدر ضروري من السياق دون كشف بيانات حساسة

تطبّع حدود إدخال TOTP الأرقام العربية والفارسية إلى أرقام Latin قبل التحقق، ثم تقارن رمزاً ASCII ثابتاً من ست خانات بصورة timing-safe. لا يُفسّر رفض رمز واحد كعطل في الساعة دون مقارنة توقيت الخادم وتسلسل أحداث النجاح والفشل في سجل التدقيق؛ ولا تُسجل قيمة الرمز أو السر في أي حال.

مراجعة السجلات

استخدم جدول المراجعة الإداري الفعلي في البيئة الحالية. إذا اختلف اسم الجدول أو بنية السجل، فالمرجع هو التنفيذ الحالي لا هذا المثال التوضيحي.

مراقبة الأمان

تنبيهات آلية

أمثلة على ما يجب مراقبته:

• ازدياد محاولات OTP أو login الفاشلة
• طلبات إدارة حساسة خارج النمط المعتاد
• أخطاء تحقق أو صلاحيات متكررة
• محاولات وصول متكرر إلى موارد خارج tenant المستخدم

لوحة المراقبة

مقاييس مهمة:

• محاولات الدخول الفاشلة/الناجحة
• طلبات محظورة (Rate Limit)
• أخطاء 403/401
• تغييرات الصلاحيات
• عمليات حذف البيانات

فحص الثغرات

صور البنية الأساسية وratchet

يفحص infrastructure/scripts/security-scan.sh صور التطبيقات افتراضياً. لتضمين الصور الرسمية المثبتة لـ Supabase/Kong:

SCAN_IMAGES=0 SCAN_INFRA_IMAGES=1 \
  ./infrastructure/scripts/security-scan.sh

يحتفظ infrastructure/security/image-vulnerability-baseline.json بالحد الأعلى المراجع لنتائج HIGH/CRITICAL التي لها FixedVersion، ومربوطاً ببصمة كل صورة. أي زيادة تفشل الفحص؛ أما الانخفاض فيقبل ويجب أن يتبعه خفض baseline. لا تعني المطابقة أن الثغرة «آمنة»، بل تمنع تدهوراً صامتاً حتى يصدر upstream image مصحح.

في مقارنة Trivy المؤرخة 2026-08-09 بين stack القديم والمرشح الرسمي الحالي كانت النتائج الخام (CVE × package، وقد تحتوي تكراراً) كالتالي:

المجموعة	Critical	High	Critical قابل للإصلاح	High قابل للإصلاح
الصور القديمة	60	599	42	521
الصور الجديدة المثبتة	38	463	8	188

أصبح Kong وPostgREST صفراً في الدرجتين. بقيت نتائج upstream في Studio وGoTrue وRealtime وStorage وPostgres Meta؛ وهي موثقة بالتقرير الكامل ولا تُخفى عبر --ignore-unfixed. رغم ارتفاع العد الخام غير القابل للإصلاح في صورة Studio الجديدة، انخفضت نتائجها القابلة للإصلاح من 6/106 إلى 1/30، وانخفضت النتيجة المجمعة للـ stack بوضوح. يجب إعادة القياس عند كل digest جديد، وعدم تعديل baseline فقط لجعل CI أخضر.

OWASP Top 10

الثغرة	الحماية
Injection	Prepared Statements، ORM
Broken Auth	JWT، Rate Limiting، 2FA
Sensitive Data	Encryption، HTTPS
XXE	لا نستخدم XML
Broken Access	RLS، Middleware
Security Misconfiguration	تدقيق الإعدادات
XSS	Sanitization، CSP
Insecure Deserialization	JSON فقط، Validation
Known Vulnerabilities	npm audit، Snyk
Insufficient Logging	Audit Log

اختبار الاختراق

جدول التدقيق:

• أسبوعياً: فحص الثغرات التلقائي
• شهرياً: مراجعة السجلات
• ربع سنوي: اختبار اختراق خارجي

الاستجابة للحوادث

خطوات الاستجابة

1. الكشف - تحديد الحادثة
2. الاحتواء - إيقاف الضرر
3. التحقيق - فهم ما حدث
4. الإصلاح - معالجة الثغرة
5. الإبلاغ - توثيق وإخطار
6. المراجعة - تحسين الإجراءات

قائمة الاتصال

المستوى	من يُبلّغ	الوقت
منخفض	فريق التطوير	يوم عمل
متوسط	المدير التقني	4 ساعات
عالي	الإدارة	فوري
حرج	الجميع + القانونيين	فوري

توثيق الحادثة

interface SecurityIncident {
  id: string;
  severity: "low" | "medium" | "high" | "critical";
  type: string;
  description: string;
  discoveredAt: Date;
  containedAt?: Date;
  resolvedAt?: Date;
  affectedUsers: number;
  affectedData: string[];
  rootCause: string;
  remediation: string;
  lessonsLearned: string;
}

قائمة التحقق الدورية

أسبوعياً

• مراجعة التنبيهات الأمنية
• فحص npm audit
• مراجعة محاولات الدخول الفاشلة

شهرياً

• تحديث التبعيات
• مراجعة سجل التدقيق
• اختبار النسخ الاحتياطية
• مراجعة الصلاحيات

ربع سنوي

• اختبار اختراق
• مراجعة سياسات الأمان
• تدريب الفريق
• تدوير المفاتيح