API für Berichte und Funde

Scanner::run() gibt nach einem abgeschlossenen Scan einen stdClass-Bericht zurück. Scanner::getReport() gibt dieselbe Form des aktuellen Berichts zurück. Bei einem abgefangenen Scanfehler gibt run() false zurück; prüfen Sie getLastError() auf der Scanner-Instanz.

Berichtsvertrag auf oberster Ebene

Eigenschaft	Typ	Bedeutung
scanned	int	Anzahl gescannter Dateien.
detected	int	Anzahl erkannter Malware-Übereinstimmungen.
verifiedByChecksum	int	Anzahl durch Prüfsummenprüfung akzeptierter Dateien.
removed, ignored, edited, quarantine, whitelist	array	Pfade oder Datensätze, die von der passenden Aktion betroffen sind.
infectedFound	array	Während des Scans gefundene infizierte Dateipfade.
fileHashes	array	Während des Scans erfasste Metadaten zu Dateihashes.
findings	array	Kanonische Funddatensätze aus Datei-, Integritäts-, Archiv- und ergänzenden Analysen.
coverage	array	Vollständigkeit, Zählungen und Gründe für das Überspringen.
diagnostics	array, sofern vorhanden	Nicht schwerwiegende Fehler bei Analyse oder Definitionsaktualisierung.
signature_indexes	array	Metadaten zu eingebauten und optionalen Reputationsindizes.
inventory	array, sofern vorhanden	Inventar erkannter Plattformkomponenten.

Neue Berichtsfelder können in einem Minor-Release hinzukommen. Verbraucher sollten die benötigten Felder lesen, unbekannte Felder tolerieren und isset() für optionale Eigenschaften verwenden.

Erfolg und Fehler behandeln

$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.
    }
}

Behandeln Sie eine detected-Anzahl ungleich null nicht als Ausführungsfehler. Funde kennzeichnen Code- oder Integritätsbedingungen, die geprüft werden müssen. Sie belegen keine Absicht und autorisieren keine Löschung.

Vertrag für Funddatensätze

Jeder kanonische Fund enthält diese Felder:

Feld	Typ	Bedeutung
id	string	Stabile SHA-256-Kennung, abgeleitet aus Art, Anbieter, Regel-ID und normalisiertem Subjekt.
kind	string	Fundkategorie wie malware, integrity oder ein Typ ergänzender Analyse.
subject	string	Dateipfad oder das gescannte Subjekt.
rule_id	string	Stabile Kennung für die erkennende Regel oder den Indikator.
severity	string	Vom Detektor bereitgestellter Schweregrad, üblicherweise warn oder danger.
message	string	Menschenlesbares Detail zur Erkennung.
status	string	Aktueller Fundstatus. Neue Funde beginnen mit open.
evidence	array	Kontext wie line, match oder content_hash, sofern verfügbar.
provider	string	Quelle des Detektors, etwa builtin.
first_seen_at, last_seen_at	string	ISO-8601-Zeitstempel für die Beobachtung des Funds.

Bewahren Sie beim Deduplizieren von Alarmen rule_id, subject und den beobachteten Inhaltshash auf. Eine Zeilennummer oder ein Ausschnitt kann sich ändern, wenn sich eine Datei ändert.

Abdeckung ist Teil des Ergebnisses

Der Bericht enthält Abdeckungszählungen für discovered, eligible, scanned, skipped, verified, cached und errors. coverage.reasons trennt übersprungene Dateien nach path, extension, oversized, excluded, unreadable und archive_limit.

Verwenden Sie diese Prüfung, bevor Sie einen Scan als vollständig akzeptieren:

$coverage = $report->coverage;

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

Offset- und Limit-Stapel, nicht lesbare Dateien, Dateigrößenlimits und Archivlimits können das Ergebnis unvollständig machen. Ein vollständiges Ergebnis ohne Funde ist aussagekräftiger als ein unvollständiges Ergebnis ohne Funde.

Diagnosen und externe Daten

diagnostics meldet nicht schwerwiegende Fehler. Beispielsweise kann der Scanner bei einem fehlgeschlagenen Update mit zwischengespeicherten Maltrail-Definitionen fortfahren. Speichern Sie Diagnosen zusammen mit Funden, damit ein Betreiber ein sauberes Ergebnis von einer eingeschränkten Analyse unterscheiden kann.

signature_indexes stellt Datensatzanzahlen und Quellhashes für die eingebauten Malware- und Legacy-Core-Indizes bereit. Wenn ein aktiver Maltrail-Speicher vorhanden ist, enthält es auch Metadaten zum Domainindex und dessen Aktualisierungszeit. Verwenden Sie diese Werte für Prüfpfade, nicht als Ersatz für die Fundbelege.

Berichte serialisieren

Verwenden Sie json_encode() mit Fehlerbehandlung, wenn Sie den In-Memory-Bericht speichern:

$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());
}

Verwenden Sie setReportFormat('json') oder setReportFormat('sarif'), wenn der Scanner außerdem eine Datei für externe Tools schreiben soll. Wählen Sie für Berichte, Checkpoints, Sicherungen und Dateien in Quarantäne ein Verzeichnis außerhalb des gescannten Projekts.