scan-results-bridge

تحويل دون اتصال لتقارير JSON الصادرة عن أداة الفحص الأمني CompleteTech إلى SARIF 2.1.0 أو NDJSON، مع إسقاط افتراضي يحافظ على الخصوصية.

المحتويات

• نظرة عامة
• المتطلبات
• البدء السريع
• سير العمل دون اتصال
• الاستخدام
• عقود الإدخال
• صيغ الإخراج
• الخصوصية والأدلة
• القيود
• تفسير النتائج
• التطوير
• المساهمة والأمان
• الترخيص وأصول العلامة التجارية

نظرة عامة

يقرأ scan_results_bridge.py تقارير JSON المحلية الموجودة ويكتب SARIF 2.1.0 أو NDJSON. وهو اختياري: لا تعتمد عليه أدوات الفحص الفردية.

• دون اتصال. لا يفحص الأهداف أبدًا، ولا ينفّذ تعليمات برمجية، ولا يحمّل حزمًا، ولا يقرأ بيانات اعتماد، ولا يرفع بيانات. لا توجد أي آلية نقل HEC/syslog أو إعداد لبيانات الاعتماد مُنفَّذة.
• بيانات وصفية فقط. يحوّل الأدلة المحلية المقدَّمة. تحتفظ كل ملاحظة بـ exploitability: not_tested؛ ولا شيء مما يصدره يؤكد الاستغلال، والإصدار المُصلَح المُبلَّغ عنه ليس أبدًا تصحيحًا مُتحقَّقًا من نشره أو ادعاءً بالسلامة.
• خاص افتراضيًا. تُستبدل تسميات الأصول وعناوين URL والمسارات ونصوص الأدلة والقيم المشابهة بمعرّفات SHA-256 ما لم تختر نشر مسارات المصدر النسبية. راجع الخصوصية والأدلة.
• يفشل بشكل مغلق. الأدوات أو الإصدارات غير المدعومة والإدخال المشوّه أو المتناقض تؤدي إلى الخروج بالرمز 2 بدلًا من إنتاج تحويل جزئي.

المتطلبات

• Python 3.10 أو أحدث (تشغّل CI الإصدارين 3.10 و3.14 على Linux وWindows وmacOS).
• لا شيء للتثبيت: ملف واحد مستقل، يعتمد على المكتبة القياسية فقط.
• jsonschema مطلوب فقط لفحص التطوير الاختياري لـ SARIF الصادر.

البدء السريع

المثال المرفق اصطناعي.

# Convert a report to SARIF (the output file must not already exist)
python scan_results_bridge.py --input examples/report.json --format sarif --output report.sarif

# NDJSON to stdout, publishing reported relative source paths
python scan_results_bridge.py --input examples/report.json --format ndjson --include-relative-paths

# A legacy node2shell-check report (placeholder file name), failing CI on findings or unknowns
python scan_results_bridge.py --input node-report.json --input-schema node2shell-v1 --fail-on either

# Run the tests and show all options
python -m unittest -v
python scan_results_bridge.py --help

أبقِ التقارير غير ذات الصلة خارج الالتزامات (commits).

سير العمل دون اتصال

تستخدم الأداة الأدلة المحلية المقدَّمة فقط. ولا تتواصل مع الأهداف ولا تنفّذ البرمجيات التي يجري تقييمها.

الاستخدام

python scan_results_bridge.py --input REPORT [--input REPORT ...]
    [--input-schema PROFILE] [--format {sarif,ndjson}] [--include-relative-paths]
    [--fail-on {none,findings,unknown,either}] [--output FILE [--force]]

الخيارات

الخيار	المعنى
--input FILE	مطلوب. ملف JSON لتقرير موجود؛ كرّره لما يصل إلى 20 مدخلًا.
--input-schema PROFILE	عقد الإدخال؛ الافتراضي contract-v1.0. يُطبَّق ملف تعريف واحد على كل مدخل في الاستدعاء.
--format {sarif,ndjson}	صيغة الإخراج؛ الافتراضي sarif.
--include-relative-paths	الاشتراك في نشر مسارات المصدر الصالحة المُبلَّغ عنها. لا تُنشر المواقع المستمدة من الجرد أبدًا. راجع الخصوصية والأدلة.
--fail-on {none,findings,unknown,either}	رمز خروج السياسة 1 بعد إخراج ناجح؛ الافتراضي none. راجع رموز الخروج.
--output FILE	الكتابة إلى ملف جديد بدلًا من stdout.
--force	استبدال ملف --output موجود بشكل ذرّي. لا يستبدل أبدًا مدخلًا أو المدقق نفسه.

الإخراج والمقاطعة

• الإخراج افتراضيًا إلى stdout. يُرفض ملف --output موجود ما لم يُعطَ --force.
• المدقق وكل مدخل محميان من الاستبدال، بما في ذلك عبر أسماء مستعارة من نوع symlink أو hardlink، حتى مع --force.
• يُعرض التقرير بأكمله قبل نشر أي شيء، ويُنشر إخراج الملف بشكل ذرّي.
• يُرفض الإدخال المشوّه أو غير المدعوم أو الذي يتجاوز الحد قبل أي إخراج.
• تؤدي المقاطعة إلى الخروج بالرمز 130 ولا يُعاد محاولة الإخراج. قد يترك stdout المتقطع، أو المقاطعة عند حد تنفيذ الملف، نشرًا غير مكتمل أو غير محدد؛ تحقق منه أو تخلَّ عنه.

رموز الخروج

الرمز	المعنى
0	نجح التحويل، وأبلغ كل مدخل عن complete: true، وسياسة --fail-on المحددة مستوفاة.
1	نجح التحويل وكُتب، لكن --fail-on تحققت.
2	فشل تشغيلي: إدخال مشوّه أو غير مدعوم أو يتجاوز الحد، أو إخراج محمي أو غير قابل للكتابة، أو مدخل يبلغ عن complete: false. لا يزال الإدخال غير المكتمل يُحوَّل ويُكتب قبل الخروج، ويُعلَّم كغير مكتمل في الإخراج.
130	مقاطعة.

سياسات --fail-on:

السياسة	الخروج بالرمز 1 عندما يحتوي الإخراج على
none (الافتراضي)	أبدًا.
findings	potentially_affected أو precondition_present أو likely_exposed.
unknown	unknown أو unsupported_runtime أو source_discrepancy.
either	أي مما سبق.

لا يكبت خروج السياسة النتائج أبدًا. رمز الخروج 2 له الأولوية على 1. الفشل التشغيلي متميز عن نتائج التقييم.

عقود الإدخال

اختر ملف التعريف صراحةً باستخدام --input-schema؛ يُطبَّق ملف تعريف واحد على جميع المدخلات في الاستدعاء. تفشل الأدوات أو الإصدارات غير المدعومة والأدلة الأساسية المشوّهة أو المتناقضة بشكل مغلق مع الخروج بالرمز 2. المدقق الأساسي مضمّن من عقد Sharp المشترك تحت ترخيص الكود نفسه؛ لا حاجة إلى حزمة مشتركة مثبّتة.

ملف التعريف	الإدخال
contract-v1.0 (الافتراضي)	كائن schema 1.0 كامل مع tool/rules/results، بما في ذلك التحقق الدلالي من مراجع الأدلة
node2shell-v1	JSON قديم غير مُصدَّر الإصدار لـ node2shell-check tool_version 1.0.0؛ محوّل مسمّى فقط، وليس مخططًا عالميًا
copyescape-v1.1	copyescape-check schema_version 1.1
vm2-v1.1	vm2-nesting-check report_schema_version 1.1
simplegit-v1.1	simplegit-rce-check report_schema_version 1.1
atlassian-v1	atlassian-cve-2026-21589-check integer schema_version 1
flowise-v1	flowise-cve-2026-69254-check integer schema_version 1; version_status يُعيَّن إلى الحالة المُطبَّعة

مشترك بين جميع ملفات التعريف: