रिपोर्ट और फाइंडिंग्स API

पूरा स्कैन होने के बाद Scanner::run() एक stdClass रिपोर्ट लौटाता है। Scanner::getReport() उसी वर्तमान रिपोर्ट आकार को लौटाता है। पकड़ी गई स्कैन विफलता पर run() false लौटाता है; स्कैनर instance पर getLastError() जांचें।

शीर्ष-स्तरीय रिपोर्ट कॉन्ट्रैक्ट

प्रॉपर्टी	प्रकार	अर्थ
scanned	int	स्कैन की गई फ़ाइलों की संख्या।
detected	int	पहचाने गए मैलवेयर मिलानों की संख्या।
verifiedByChecksum	int	checksum सत्यापन से स्वीकार की गई फ़ाइलों की संख्या।
removed, ignored, edited, quarantine, whitelist	array	मिलान कार्रवाई से प्रभावित पथ या रिकॉर्ड।
infectedFound	array	स्कैन के दौरान मिले संक्रमित फ़ाइल पथ।
fileHashes	array	स्कैन के दौरान एकत्र किया गया फ़ाइल हैश metadata।
findings	array	फ़ाइल, integrity, archive, और पूरक विश्लेषण से canonical finding records।
coverage	array	पूर्णता, गणनाएं, और skip कारण।
diagnostics	मौजूद होने पर array	गैर-गंभीर analysis या definition update त्रुटियां।
signature_indexes	array	अंतर्निहित और वैकल्पिक reputation-index metadata।
inventory	मौजूद होने पर array	पहचानी गई प्लेटफ़ॉर्म component inventory।

नई रिपोर्ट फ़ील्ड को किसी minor release में जोड़ा जा सकता है। उपभोक्ताओं को आवश्यक फ़ील्ड पढ़ने चाहिए, अज्ञात फ़ील्ड सहन करने चाहिए, और वैकल्पिक प्रॉपर्टी के लिए 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 गिनती को निष्पादन विफलता न मानें। फाइंडिंग्स ऐसे कोड या अखंडता स्थितियों की पहचान करती हैं जिनकी समीक्षा आवश्यक है। वे मंशा स्थापित नहीं करतीं और न ही deletion को अधिकृत करती हैं।

फाइंडिंग रिकॉर्ड कॉन्ट्रैक्ट

हर canonical finding में ये फ़ील्ड होते हैं:

फ़ील्ड	प्रकार	अर्थ
id	string	kind, provider, rule ID, और सामान्यीकृत subject से प्राप्त स्थिर SHA-256 identifier।
kind	string	finding श्रेणी, जैसे malware, integrity, या पूरक analysis प्रकार।
subject	string	फ़ाइल पथ या स्कैन किया हुआ subject।
rule_id	string	detecting rule या indicator के लिए स्थिर identifier।
severity	string	detector द्वारा दी गई गंभीरता, आमतौर पर warn या danger।
message	string	मनुष्यों के लिए पढ़ने योग्य detection विवरण।
status	string	वर्तमान finding स्थिति। नई findings open से शुरू होती हैं।
evidence	array	उपलब्ध होने पर line, match, या content_hash जैसा संदर्भ।
provider	string	detector स्रोत, जैसे builtin।
first_seen_at, last_seen_at	string	finding अवलोकन के ISO 8601 timestamps।

चेतावनियों को deduplicate करते समय rule_id, subject, और देखा गया content hash रखें। फ़ाइल बदलने पर पंक्ति संख्या या snippet बदल सकता है।

कवरेज परिणाम का हिस्सा है

रिपोर्ट में 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.');
}

Offset और limit batch, पढ़ने योग्य न होने वाली फ़ाइलें, फ़ाइल-आकार सीमाएं, और archive सीमाएं परिणाम को अपूर्ण बना सकती हैं। शून्य फाइंडिंग वाला पूर्ण परिणाम, शून्य फाइंडिंग वाले आंशिक परिणाम से अधिक महत्वपूर्ण होता है।

डायग्नोस्टिक्स और बाहरी डेटा

diagnostics गैर-गंभीर त्रुटियों की रिपोर्ट करता है। उदाहरण के लिए, update विफल होने पर स्कैनर cached Maltrail definitions के साथ जारी रह सकता है। diagnostics को findings के साथ सहेजें ताकि operator स्वच्छ परिणाम और सीमित विश्लेषण में अंतर कर सके।

signature_indexes अंतर्निहित malware और legacy-core indexes के लिए रिकॉर्ड गणना और source hashes दिखाता है। जब सक्रिय Maltrail store मौजूद हो, तो इसमें domain-index metadata और उसका update समय भी शामिल होता है। इन मानों का उपयोग audit trails के लिए करें, finding evidence के विकल्प के रूप में नहीं।

रिपोर्ट serializing

इन-मेमोरी रिपोर्ट संग्रहीत करते समय त्रुटि प्रबंधन के साथ 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());
}

जब स्कैनर को बाहरी tooling के लिए भी फ़ाइल लिखनी हो तो setReportFormat('json') या setReportFormat('sarif') का उपयोग करें। रिपोर्ट, checkpoints, backups, और quarantined फ़ाइलों के लिए स्कैन किए गए प्रोजेक्ट के बाहर की डायरेक्टरी चुनें।