قواعد Semgrep

هذا هو المستودع المركزي لقواعد Semgrep الذي يستضيف قواعد Semgrep لـ محلل Semgrep الخاص بـ GitLab.

يتم تنظيم المستودع على النحو التالي:

.
├── mappings
│   ├── find_sec_bugs.yml
│   ├── eslint.yml
│   └── ...
├── rules
│   ├── lpgl
│   │   ├── java
│   │   │   ├── webview
│   │   │   │   ├── rule-ignore_ssl_certificate_error.yml
│   │   │   │   ├── rule-ignore_ssl_certificate_error.java
│   │   │   │   └── ...
│   │   │   └── ...
│   │   ├── python
│   │   │   └── ...
│   │   └── ...
│   ├── lpgl-cc
│   │   ├── java
│   │   │   └── ...
│   │   └── ...
│   └── ...
├── c
│   ├── buffer
│   │   ├── rule-strcpy.yml
│   │   ├── test-strcpy.c
│   │   ├── rule-memcpy.yml
│   │   └── test-memcpy.c
│   └── ...
└── javascript
│   └── ...
└── ...

الهيكل أعلاه يتبع النمط:

rules/<license>/<language>/<ruleclass>/rule-<rulename>\.(yml|<ext>)

حيث:

1. <license> هو ترخيص جميع القواعد تحته.
2. <language> لغة البرمجة المستهدفة.
3. <ruleclass> اسم وصفي لفئة القواعد تحته.
4. <rulename> اسم وصفي للقاعدة الفعلية.
5. <ext> امتداد الملف المعتاد لـ <language>.

القواعد القديمة تتبع النمط <language>/<ruleclass>/rule-...، ويجب تفضيل النمط الأحدث أعلاه كلما أمكن.

دليل mappings يتضمن تكوين حزمة القواعد.

Makefile

يحدد ملف Makefile بعض الأهداف المفيدة عند العمل على القواعد:

$ make help
TARGETS:
  test                  test all rules with Semgrep
  watch                 watch for file changes and auto-run affected tests
  help                  prints this message

إرشادات التنسيق

يجب أن تلتزم القواعد الموجودة في هذا المستودع بالتنسيق التالي:

• استخدام " للسلاسل النصية، وإلا استخدم كتلة YAML الحرفية |
• عدم طي عناصر المصفوفات
• أقصى طول للسطر/عرض النص: 100 حرف
• المسافة البادئة: مسافتان
• يجب أن تحتوي كل قاعدة على حالة اختبار مقابلة
• إذا تم توفيره، قسم التعليقات في أعلى ملف القاعدة
• كل ملفات YAML تبدأ بـ ---

الخرائط

يحتوي دليل mappings في هذا المستودع على ملفات تكوين YAML التي تربط معرفات المحلل الأصلي (مثل Bandit وBrakeman إلخ) بقواعد Semgrep المقابلة.

الغرض من ملفات الخرائط هو، أولاً وقبل كل شيء، فصل المعلومات الخاصة بالمحلل عن القواعد الفعلية، وثانيًا، توفير طريقة غير تدخلية لتوليد حزم القواعد أو مجموعات القواعد (عبر حدود اللغة أو المحلل) لأغراض مختلفة.

توجد ملفات الخرائط تحت دليل mappings/ حيث يشير اسم الملف إلى حزمة القواعد و/أو المحلل الذي تمثله مجموعة القواعد المستخدمة في الملف المعني. إذا كنت تريد تضمين القواعد في مجموعة القواعد القياسية لـ GitLab ولا تناسب القاعدة إحدى حزم القواعد (أو المحللات) المتوفرة بالفعل في دليل mappings/، يمكنك إضافة خرائطك إلى ملف mappings/gitlab_<license>_<language>.yml حيث <license> هو ترخيص مناسب تمليه المصدر الذي تم استقاء القاعدة منه، و<language> هو عنصر نائب للغة التي تشير إليها القاعدة.

إذا كنت تريد دمج قاعدة جديدة تم تطويرها من الصفر، يمكنك إضافة خريطة مقابلة إلى ملف mappings/gitlab_ee_<language>.yml. عند تحديد الترخيص الذي يجب أن ينطبق على قاعدة معينة تقوم بتخطيطها، ارجع إلى هذا التوجيه الداخلي.

تُستخدم الخرائط أيضًا لتجميع حزم القواعد تلقائيًا. يوضح المقتطف أدناه مثالاً مع ملفات خريطة لمحلل bandit. يحتوي قسم native_id على بعض المعلومات حول معرف المحلل الأصلي، أي المعلومات الوصفية التي يرفقها المحلل الأصلي (في هذه الحالة bandit) بالنتيجة التي ينتجها. يتم تعريف خرائط القواعد الفعلية في قسم mappings. تقوم كل خريطة بتعيين معرف قاعدة المحلل الأصلي (في المثال أدناه B301) إلى مجموعة من ملفات Semgrep في هذا المستودع تشبه، أو من الناحية المثالية معادلة بحكم الأمر الواقع، تلك القاعدة الأصلية المعينة.

bandit:
  native_id:
    type: "bandit_test_id"
    name: "Bandit Test ID: $ID"
    value: "$ID"
  mappings:
  - id: "B301"
    rules:
    - path: "python/deserialization/rule-pickle"
      primary_id: "bandit.B301-1"
      id: "bandit.B301-1"
    - path: "python/deserialization/rule-cpickle"
      primary_id: "bandit.B301-2"
      id: "bandit.B301-2"
    - path: "python/deserialization/rule-dill"
      primary_id: "bandit.B301-3"
      id: "bandit.B301-3"
    - path: "python/deserialization/rule-shelve"
      primary_id: "bandit.B301-4"
      id: "bandit.B301-4"
  # ...

يتم شرح بنية ملف الخريطة بمزيد من التفصيل أدناه.

1. id يُستخدم لتوليد معرفات قواعد Semgrep مستقرة وفريدة في حزمة قواعد Semgrep المقابلة لملف الخريطة.
2. primary_id يساعد في توليد معرفات أولية مستقرة للثغرات التي تُرفق بالثغرات عند إنشائها بواسطة محلل Semgrep الخاص بـ GitLab (في gl-sast-report.json) لأغراض إزالة التكرار.
3. native_id هو الإدخال الذي يشبه تمامًا بنية معرف الثغرة كما سينشئه المحلل الأصلي. سيتم إضافته إلى gl-sast-report.json الذي ينتجه محلل Semgrep الخاص بـ GitLab وسيكون متاحًا في تقرير الثغرات.
4. mappings يتضمن معرف المحلل الأصلي (في الحالة أعلاه B301 الذي يشير إلى إحدى قواعد محلل Python bandit). تشير مصفوفة rules إلى الملفات الموجودة في المستودع التي تشير إليها هذه القاعدة. بمعنى آخر، يتم تنفيذ منطق B301 في الملفات الأربعة المدرجة في المقتطف أعلاه.

نستخدم نوعين مختلفين من المعرفات id وprimary_id لدعم تقسيم القاعدة: يمكن تعيين قواعد Semgrep متعددة (id) إلى قاعدة واحدة للمحلل الأصلي (primary_id).

مصادر البيانات

القواعد وحالات الاختبار في هذا المستودع مستمدة جزئيًا من المصادر المدرجة أدناه:

1. https://github.com/returntocorp/semgrep-rules
2. https://github.com/PyCQA/bandit
3. https://github.com/nodesecurity/eslint-plugin-security
4. https://github.com/jsx-eslint/eslint-plugin-react
5. https://github.com/david-a-wheeler/flawfinder/blob/master/flawfinder.py

التفاصيل مدرجة في رؤوس جميع ملفات القواعد والاختبار بما في ذلك معلومات الترخيص والإسناد المناسب.

المساهمة

إذا كنت تعرف نمطًا غير موجود في هذا المستودع أو تحسينات يمكن تطبيقها على القواعد في هذا المستودع، يمكنك المساهمة عن طريق فتح مشكلة (issue)، أو حتى تقديم تحسين لملفات القواعد/حالات الاختبار في هذا المستودع.

الإصدارات

نطبق نظام الإصدارات الدلالية التالي على هذا المستودع:

1. زيادة الإصدار التصحيحي (patch): للقواعد المحدّثة/المصحّحة/المضافة.
2. زيادة الإصدار الثانوي (minor): لتغييرات مخطط YAML المتوافقة مع الإصدارات السابقة (مثل إضافة/إزالة الحقول الاختيارية).
3. زيادة الإصدار الرئيسي (major): لتغييرات مخطط YAML غير المتوافقة مع الإصدارات السابقة (مثل إضافة/إزالة الحقول الإلزامية).

عملية إصدار قواعد SAST

يجب دمج إصدارات قواعد SAST الجديدة في محلل Semgrep لكي تصبح سارية المفعول. لطلب إصدار جديد لـ Semgrep، قم بإنشاء مشكلة إصدار باستخدام التعليمات الموجودة في قالب مشكلة إصدار SAST.

الشكر والتقدير

نود أن نشكر المؤلفين التاليين جزيل الشكر على مساهماتهم القيمة.