دقّق وحسّن الكود اللي كتنتجو الذكاء الاصطناعي مع Iron Laws

شنو هو Iron Laws؟

Iron Laws، المعروف حتى باسم 오철칙، هو أداة للفحص الساكن مصمّمة باش تلقى مشاكل الأمان وقابلية الصيانة اللي كتكون غالباً فالمشاريع المُنشأة بالذكاء الاصطناعي. كيطبّق دروس مستخلصة من عمليات تدقيق دمج الأنظمة فالمؤسسات والقطاع العام، وكيشرح كل نتيجة بلغة مفهومة.

الأداة ما كتشوفش غير واش التطبيق خدام. كتقلب على مشاكل بحال الأسرار المكتوبة مباشرة فالكود، التعامل غير الآمن مع المدخلات، ابتلاع الاستثناءات، واجهات API إدارية بلا مصادقة، غياب ضوابط الولوج ديال Supabase أو Firebase، ملفات .env المرفوعة للمستودع، الدوال المكررة، التبعيات الدائرية، وتجاوزات أمان الأنواع.

Iron Laws كيولّد حتى تعليمات إصلاح منظمة تقدر تلصقها فمساعد برمجة بالذكاء الاصطناعي. بهاد الشكل كينشأ مسار عمل قابل للتكرار:

البناء بالذكاء الاصطناعي → iron-laws check → iron-laws fix-prompt
→ طلب إصلاح النتائج من الذكاء الاصطناعي → إعادة الفحص

Iron Laws هو وسيلة مساعدة للمراجعة أثناء التطوير، وماشي منتوج رسمي للشهادة ولا دليل على أن التطبيق آمن. استعملو مع الاختبارات، ومراجعة الكود، وأدوات أمان أخرى.

الخصائص الرئيسية

فحص الأمان والجودة

المشروع فيه 90 قاعدة كتشمل مجالات متعددة:

• قواعد مرجعية: تغطية لجميع العناصر الـ49 ديال مرحلة التنفيذ المذكورة فالدليل الكوري المشار إليه لأمن تطوير البرمجيات الصادر عن وزارة الداخلية والسلامة، بما فيها الحقن، وXSS، وSSRF، وXXE، والتشفير الضعيف، وتعطيل التحقق من الشهادات، وإلغاء التسلسل غير الآمن، ومعالجة الأخطاء، وسلامة الذاكرة.
• تصحيحات كود الذكاء الاصطناعي: الإعدادات المكتوبة مباشرة فالكود، والقيم الاحتياطية السرية، وكشف أسرار الواجهة الأمامية، وCORS غير الآمن، وغياب قواعد الولوج، وإعدادات Docker أو CI الخطيرة، والأخطاء الإملائية فالتبعيات، والتبعيات بلا تثبيت للإصدار، وتسجيل المعلومات الحساسة، وIDOR، وخصائص ملفات تعريف الارتباط.
• فحوصات البنية: الدوال والملفات الكبيرة بزاف، والتبعيات غير المناسبة بين الطبقات، والولوج المباشر لقاعدة البيانات من معالجات الطلبات، والتبعيات الدائرية، والدوال المكررة، وثوابت السلاسل النصية المعادة، وغياب الاختبارات.
• فحوصات أمان الأنواع: any و@ts-ignore ديال TypeScript، وtype: ignore والتحويلات ديال Python، والأنواع الخام فـ Java، وdynamic ديال C#، وتجاوزات نظام الأنواع فاللغات المدعومة الأخرى.

نتائج مفهومة وإرشادات للإصلاح

كل نتيجة فيها شرح للمشكل، وعلاش خطير، وكيفاش يمكن يتصلح. ملي كتكون القاعدة مرتبطة بعنصر فدليل منشور، التقرير كيتضمن رقم داك العنصر وتصنيف CWE ديالو. قواعد الجودة الخاصة بالمشروع كيتشار ليها بوضوح على أنها قواعد Iron Laws وماشي متطلبات خارجية.

مطالبات إصلاح جاهزة للذكاء الاصطناعي

الأمر fix-prompt كينظم النتائج حسب الخطورة وكيحوّلها لتعليمات لأداة برمجة بالذكاء الاصطناعي. المطالبة كتأكد حتى على مبادئ بحال عدم ابتلاع الأخطاء، وعدم وضع الأسرار فالكود المصدري، وعدم تجاوز فحص الأنواع، وعدم إنشاء تطبيقات مكررة.

التحليل المحلي

المحللات المطلوبة مضمّنة فالحزمة، وبهذا الفحوصات تقدر تخدم بلا اتصال بالشبكة من بعد التثبيت.

دعم اللغات والملفات

مستوى الدعم كيختلف حسب اللغة ونوع الملف:

• دعم معمّق: Python وJavaScript وTypeScript وJava وC# كيتلقاو تحليل البنية، وتتبع المدخلات، وأوسع تغطية للقواعد.
• دعم أساسي: Go وPHP كيتلقاو تحليل البنية وفحوصات مهمة للحقن، ومعالجة الأخطاء، والتشفير.
• دعم محدود: Rust وC/C++ كيتلقاو فحوصات لمعالجة الأخطاء، واستعمال الذاكرة، وسلاسل التنسيق، وواجهات API، وتجاوزات الأنواع.
• ملفات الإعداد والتعريف: SQL وYAML وJSON و.env وDockerfile وCompose وGitHub Actions وMyBatis XML وقوالب HTML كيتفحصو بحثاً عن مشاكل الأسرار، وضبط الولوج، والنشر، والهروب من المحارف.

داخل الدوال، Iron Laws كيحلل التدفق عبر الفروع، والحلقات، والاستثناءات. وكيْتبع استدعاءات الدوال المساعدة فالنفس الملف حتى لأربع مستويات فالعمق. Python فيها زيادة تتبع تجريبي بين الملفات عبر الاستيرادات، مع الخضوع لحدود التحليل. التدفقات بين الملفات فاللغات الأخرى ممكن ما تتلقاش أو يتبلغ عليها بأنها محتاجة للمراجعة.

التثبيت

Iron Laws كيحتاج Python 3.12 أو أحدث. الطريقة الموصى بها هي تثبيتو كأداة مستقلة باستعمال uv:

uv tool install git+https://github.com/JinHo-von-Choi/iron-laws.git

وتقدر حتى تثبتو باستعمال pip:

pip install git+https://github.com/JinHo-von-Choi/iron-laws.git

من بعد التثبيت، تأكد أن الأمر متاح بعرض القواعد المضمّنة:

iron-laws rules

باش تفحص حالة التنفيذ والتحقق حسب اللغة والقاعدة، شغّل:

iron-laws support

هاد التمييز مهم، حيث وجود محلل ما كيعنيش بالضرورة أن كل قاعدة تم التحقق منها فداك اللغة.

دير أول فحص ديالك

فحص المشروع الحالي

حلّ الطرفية فمجلد المشروع وشغّل:

iron-laws check .

بشكل افتراضي، الأمر كيفشل ملي كيلقى نتيجة بدرجة خطورة HIGH أو أعلى. رموز الخروج هي:

• 0: الفحص داز حسب سياسة الخطورة المختارة.
• 1: كاينة نتيجة وحدة على الأقل وصلات أو فاتت درجة الفشل المضبوطة.
• 2: المدخلات أو الإعدادات غير صالحة، أو ما تفحص حتى ملف، أو الفحص ما قدرش يكمل بسبب مشاكل بحال أخطاء القواعد أو فشل قراءة الملفات.

الفحص اللي ما تكملش ما كياخدش درجة مؤكدة ولا نتيجة نجاح. الأسباب ديالو كتتسجل تحت diagnostics. حتى الهدف الخاوي ما كيتحسبش مسح ناجح إلا إلا تعطات --allow-empty بشكل صريح.

فهم قاعدة وحدة

استعمل explain ملي تحتاج شرح بعبارات واضحة لقاعدة:

iron-laws explain IL-501

وتقدر حتى تشوف شنو من بين 49 عنصر تنفيذ المشار ليهم مغطّى:

iron-laws coverage

إنشاء تقرير

باش تنشئ تقرير Markdown فيه حالة الفحص ديال العناصر الـ49 كاملين المشار ليهم، شغّل:

iron-laws audit . --format markdown -o report.md

باش تنشئ ملف SARIF لـ GitHub Code Scanning ولا لأي نظام آخر متوافق، استعمل:

iron-laws audit . --format sarif -o iron-laws.sarif

إنشاء تعليمات لمساعد برمجة بالذكاء الاصطناعي

من بعد ما تراجع النتائج، أنشئ prompt للإصلاح واجد للذكاء الاصطناعي:

iron-laws fix-prompt .

لسّق التعليمات اللي تنشئات فمساعد البرمجة ديالك، راجع التغييرات المقترحة، ومن بعد عاود شغّل الفحص:

iron-laws check .

الأمر fix-prompt كيرجع رمز الخروج 0 حتى إلا كانت كاينة نتائج، حيث الغرض ديالو هو إنشاء التعليمات. ما تستعملوش كبوابة للنشر. استعمل check ولا audit للتطبيق الإلزامي.

القيم السرية المعروفة كتتخفّى على شكل **** فالتقارير والـ prompts اللي كيتنشؤو. ولكن الأسرار اللي ما متعرفاش ما يمكنش يتخفّاو أوتوماتيكيا، لذلك راجع النص اللي تنشأ قبل ما تصيفطو لخدمة ذكاء اصطناعي خارجية.

تهيئة سياسات المشروع

أنشئ ملف تهيئة أولي بهاد الأمر:

iron-laws init

المشروع كيستعمل .iron-laws.yml. تهيئة نموذجية هي:

fail_on: HIGH
excludes: [".git", "node_modules", "dist"]
disabled_rules: ["ARC-206"]
limits:
  max_function_lines: 80
  max_file_lines: 600
  max_parameters: 7
  max_nesting: 5
  duplicate_similarity: 0.9

الإعداد fail_on كيقبل CRITICAL أو HIGH أو MEDIUM أو LOW. ترتيب الأولوية الفعلي هو خيار سطر الأوامر --fail-on، من بعد ملف التهيئة، ومن بعد القيمة الافتراضية HIGH. التقارير كتوثق شنو هو المصدر اللي عطى العتبة النشيطة.

افتراضيا، Iron Laws كيستعمل التهيئة الموجودة فالمجلد اللي كيتفحص. استعمل --config باش تختار ملف معيّن، ولا --search-parents باش يقلب فالمجلدات الأب. المفاتيح المجهولة والإعدادات غير الصحيحة ما كيتجاهلوش بصمت؛ كينتجو رمز الخروج 2.

التعامل مع الاستثناءات المقصودة

النتيجة الإيجابية الكاذبة ولا الاستثناء المقصود يقدر يتكبت غير إلا كان التكتيم فيه سبب. التعليق اللي ما فيهش سبب كيتجاهل.

باش تكتم نتيجة وحدة فـ Python:

except ImportError:  # iron-laws: ignore[IL-301] Optional dependency disables this feature
    yaml = None

باش تكتم قاعدة على ملف كامل، حط توجيه ignore-file فـ أول 30 سطر:

# iron-laws: ignore-file[IL-102] Pattern definitions intentionally identify weak algorithms

التكتيمات تقدر تتضمن تاريخ انتهاء:

# iron-laws: ignore[IL-101] until=2026-12-31 Temporary exception with documented reason

التكتيمات اللي فات تاريخها كتوقف على التطبيق وكتبّان فالتقارير. Iron Laws كيعطي حتى تقارير على التكتيمات اللي ما تستعملاتش والإشارات لمعرّفات قواعد مجهولة.

اعتماد Iron Laws فمشروع موجود

إنشاء خط أساس

إلا كان مستودع موجود فيه نتائج مقبولة من قبل، سجّلها كدين تقني مصادق عليه:

iron-laws baseline create .

من بعد قيّم غير النتائج الجديدة مقابل خط الأساس المحفوظ:

iron-laws check . --baseline .iron-laws-baseline.json

فحص الملفات المتبدلة

باش تحصل على ملاحظات ديال طلب السحب مركزة على الملفات المعدّلة، قارن مع الفرع الرئيسي:

iron-laws check . --changed-since origin/main

الـ README كيوصي بجمع فحص الملفات المتبدلة مع فحوصات كاملة ودورية باش ما تفوتش المشاكل اللي كتشمل المستودع كامل.

تسجيل ملاحظات المراجعة

النتائج اللي معلّمة بأنها محتاجة للمراجعة تقدر تصنّفها وتعيّن ليها تكلفة مراجعة:

iron-laws feedback add IL-501 src/a.py:3 --verdict false-positive --minutes 10

التحقق من التصحيحات اللي نشأها الذكاء الاصطناعي

Iron Laws فيه مسار متقدم كيحتافظ بالأدلة على شنو تراجع وشنو ما تراجعش من بعد ما كيبدّل الذكاء الاصطناعي الكود.

فحص عقد الأدلة

عقد الأدلة كيفرّق بين فحص سالا وفحص فعلا نتج الأدلة المطلوبة:

iron-laws check . --contract .iron-laws-contract.yml

مصادر الإدخال اللي ما تحلاتش ما كتتحولش أوتوماتيكيا لنتائج نظيفة. التغطية الحالية لعقد الأدلة كتضم تنفيذ أوامر Python، والوصول للمسارات، وعائلات إنشاء SQL.

إنشاء وصل التحقق من التصحيح

باش تفحص تصحيح مقترح وتحفظ وصل التحقق، شغّل أمرا بحال:

iron-laws verify-patch . --patch fix.diff \
  --finding IL-504@app.py:6 \
  --runner docker \
  --image IMAGE_NAME \
  -o receipt.json

أداة التحقق كتقارن بين النسخة الأصلية والنسخة المقترحة باستعمال نفس السياسة. وكتعطي بشكل منفصل تقارير على التغييرات المشبوهة بحال حذف الاختبارات، وزيادة عمليات التخطي، وتعليقات ignore جديدة، ولا إضعاف السياسات. اختفاء تحذير بوحدو ما كيتعتبرش دليلا على أن التصحيح صالح.

الاختبارات كتدار غير فبيئة معزولة ومؤقتة بلا بيانات اعتماد. إلا ما قدرناش نوفروا العزل، Iron Laws ما كينفذش الاختبارات بصمت فالجهاز المضيف؛ وكيخلي النتيجة غير محددة.

اقترح اختبار تراجعي مميّز

تقدر تولّد مواصفة مرشحة لاختبار تراجعي خاص باكتشاف:

iron-laws regression propose . --finding IL-504@app.py -o spec.yml

نمط التحقق المقصود كيتأكد باللي النسخة الأصلية كتفشل بسبب العيب، والمرشح كيدوز، ومن بعد نسخة متحوّرة رجعنا فيها الإصلاح كتفشل من جديد. ملف README كيشرح تكرار هاد السلسلة ثلاث مرات. الاختبار المولّد كيبقى غير اقتراح حتى كتأكد منو.

سجّل الموافقة البشرية

خزّن الموافقة مع السبب ديالها:

iron-laws approvals add . \
  --finding IL-504@app.py \
  --reason "Documented review reason" \
  --store approvals.jsonl

طبّق الموافقات الصالحة أثناء الفحص:

iron-laws check . --approvals approvals.jsonl

الموافقات كتبقى صالحة غير ما دامت الافتراضات ديالها قائمة. التغييرات فالمستدعين، أو تدفق البيانات، أو أدوات التنقية، أو نطاق الوصول، أو معنى القاعدة، تقدر تتطلب مراجعة جديدة. الكود المعرّض للخطر والمكرر ما كيستافدش تلقائياً من موافقة موجودة.

الدمج مع GitHub Actions

سير العمل التالي كيثبّت Iron Laws، وكيرفع تقرير SARIF، ومن بعد كيفرض بوابة نشر بدرجة خطورة عالية:

name: Iron Laws
on: [push, pull_request]
jobs:
  audit:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
      - run: uv tool install git+https://github.com/JinHo-von-Choi/iron-laws.git
      - run: iron-laws audit . --format sarif -o iron-laws.sarif || true
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: iron-laws.sarif
      - run: iron-laws check . --fail-on HIGH

خطوة إنشاء التقرير كتستعمل || true باش يبقى ملف SARIF قابل للرفع حتى إلا كانت كاينة اكتشافات. الأمر النهائي check هو اللي كيوفر بوابة النجاح أو الفشل الفعلية.

القيود العملية

• النتيجة النظيفة كتعني أنه ما تلقات حتى مشكلة ضمن القواعد المطبقة ونطاق التحليل المدعوم. ما كتثبتش باللي التطبيق خالي من الثغرات.
• تتبّع المدخلات بين الملفات ما زال تجريبياً فـ Python ومحدود فاللغات الأخرى. بعض التدفقات ممكن ما تتكتشفش أو يتبلغ عليها بأنها كتحتاج مراجعة يدوية.
• أدوات التنقية كيتعرف عليها غير فالسياق اللي كتحميه، بحال HTML أو SQL أو أوامر الصدفة أو المسارات.
• حسب README، التحقق من الترقيعات، والاختبارات التراجعية، وتتبع الموافقات مازال ما خضعوش لتقييم مستقل أو تجربة ميدانية حقيقية.
• نتائج OWASP Benchmark اللي كيستشهد بها المشروع كاتبيّن تحسن فعدة فئات، ولكن الإيجابيات الكاذبة ما زالت موجودة، بما فيها حالات SQL وأوامر الحقن اللي تم تنقيتها بأمان.
• بلا الرجوع لمستودع الحزم، الأداة ما كتقدرش تحدد بشكل موثوق كل تبعية مختلقة. وبدل ذلك كتبلغ على الأسماء اللي كتشبه لحزم معروفة.
• الملفات المضغوطة والمولّدة كتتجاوز، وكيتم تسجيل الأسباب تحت skipped_files.

لمزيد من التفاصيل، راجع وثائق المستودع الخاصة بـ التحقق من الترقيعات، وقياسات الدقة، ودعم اللغات والقواعد، وصيغ التقارير.

الخلاصة

Iron Laws كيوفر طريقة منظمة لمراجعة البرمجيات اللي كتولدها الذكاء الاصطناعي قبل ما تولّي مشاكل خفية فالأمن والصيانة حوادث فالإنتاج. بدا بـ iron-laws check .، وعاين التفسيرات، وولّد موجه للإصلاح، وراجع التغييرات ديال الذكاء الاصطناعي، ومن بعد دير الفحص من جديد. ومع نضج المشروع، زِد الإعدادات، والخطوط الأساسية، وتقارير SARIF، وإيصالات الترقيعات، والموافقات البشرية باش تولّي العملية قابلة للتكرار والتدقيق.

المشروع متاح بموجب رخصة MIT. النتائج ديالو خاصها تعاون الاختبارات، ومراجعة الكود اليدوية، والتقييم الأمني الأوسع، ماشي تعوضهم.