واجهة التقارير والنتائج

تعيد Scanner::run() تقرير stdClass بعد فحص مكتمل. تعيد Scanner::getReport() شكل التقرير الحالي نفسه. عند فشل فحص تم التقاطه، تعيد run() القيمة false؛ افحص getLastError() على نسخة الفاحص.

عقد التقرير عالي المستوى

الخاصية	النوع	المعنى
scanned	int	عدد الملفات المفحوصة.
detected	int	عدد مطابقات البرامج الخبيثة المكتشفة.
verifiedByChecksum	int	عدد الملفات المقبولة عبر التحقق من المجموع الاختباري.
removed, ignored, edited, quarantine, whitelist	array	المسارات أو السجلات المتأثرة بالإجراء المطابق.
infectedFound	array	مسارات الملفات المصابة التي عُثر عليها أثناء الفحص.
fileHashes	array	بيانات تعريف تجزئة الملفات المجمعة أثناء الفحص.
findings	array	سجلات النتائج الأساسية من تحليلات الملفات والسلامة والأرشيف والتحليلات التكميلية.
coverage	array	الاكتمال والأعداد وأسباب التخطي.
diagnostics	array، عند وجوده	أخطاء غير قاتلة في التحليل أو تحديث التعريفات.
signature_indexes	array	بيانات تعريف فهارس السمعة المضمّنة والاختيارية.
inventory	array، عند وجوده	مخزون مكونات المنصة المكتشفة.

قد تضاف حقول تقرير جديدة في إصدار ثانوي. ينبغي للمستهلكين قراءة الحقول التي يحتاجونها وتحمل الحقول غير المعروفة واستخدام isset() للخصائص الاختيارية.

معالجة النجاح والفشل

$report = $scanner->run();

if ($report === false) {
    throw new RuntimeException($scanner->getLastError() ?: 'Scan failed.');
}

foreach ($report->findings as $finding) {
    if ($finding['severity'] === 'danger') {
        // Send the finding to your incident workflow.
    }
}

لا تعامل عددا غير صفري في detected بوصفه فشل تنفيذ. تحدد النتائج شيفرة أو حالات سلامة تحتاج إلى مراجعة. وهي لا تثبت النية ولا تخول الحذف.

عقد سجل النتيجة

تتضمن كل نتيجة أساسية هذه الحقول:

الحقل	النوع	المعنى
id	string	معرّف SHA-256 ثابت مشتق من النوع والموفر ومعرّف القاعدة والموضوع الموحّد.
kind	string	فئة النتيجة، مثل malware أو integrity أو نوع تحليل تكميلي.
subject	string	مسار الملف أو الموضوع المفحوص.
rule_id	string	معرّف ثابت للقاعدة أو المؤشر الكاشف.
severity	string	الشدة التي يوفرها الكاشف، وعادة warn أو danger.
message	string	تفاصيل اكتشاف قابلة للقراءة البشرية.
status	string	حالة النتيجة الحالية. تبدأ النتائج الجديدة بحالة open.
evidence	array	سياق مثل line أو match أو content_hash عند توفره.
provider	string	مصدر الكاشف، مثل builtin.
first_seen_at, last_seen_at	string	طوابع زمنية ISO 8601 لملاحظة النتيجة.

احتفظ بـ rule_id وsubject وتجزئة المحتوى الملحوظة عند إزالة تكرار التنبيهات. يمكن أن يتغير رقم السطر أو المقتطف عندما يتغير ملف.

التغطية جزء من النتيجة

يتضمن التقرير أعداد التغطية لكل من discovered وeligible وscanned وskipped وverified وcached وerrors. تفصل coverage.reasons الملفات المتخطاة حسب path وextension وoversized وexcluded وunreadable وarchive_limit.

استخدم هذا الفحص قبل قبول الفحص بوصفه مكتملا:

$coverage = $report->coverage;

if (empty($coverage['complete']) || !empty($coverage['errors'])) {
    throw new RuntimeException('Scan coverage is incomplete.');
}

يمكن أن تجعل دفعات الإزاحة والحدود والملفات غير القابلة للقراءة وحدود حجم الملفات وحدود الأرشيف النتيجة غير مكتملة. تحمل نتيجة مكتملة بلا نتائج وزنا أكبر من نتيجة جزئية بلا نتائج.

التشخيصات والبيانات الخارجية

تبلغ diagnostics عن الأخطاء غير القاتلة. على سبيل المثال، يمكن للفاحص المتابعة باستخدام تعريفات Maltrail المخزنة مؤقتا عندما يفشل تحديث. احفظ التشخيصات إلى جانب النتائج كي يتمكن المشغل من تمييز نتيجة نظيفة من تحليل مخفّض.

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

تسلسل التقارير

استخدم json_encode() مع معالجة الأخطاء عند تخزين التقرير في الذاكرة:

$json = json_encode($report, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);

if ($json === false) {
    throw new RuntimeException('Could not serialize scan report: ' . json_last_error_msg());
}

استخدم setReportFormat('json') أو setReportFormat('sarif') عندما ينبغي للفاحص أيضا كتابة ملف لأدوات خارجية. اختر دليلا خارج المشروع المفحوص للتقارير ونقاط التحقق والنسخ الاحتياطية والملفات المعزولة.