API des rapports et détections

Scanner::run() renvoie un rapport stdClass après une analyse terminée. Scanner::getReport() renvoie la même structure de rapport actuelle. En cas d'échec d'analyse intercepté, run() renvoie false ; examinez getLastError() sur l'instance du scanner.

Contrat de rapport de premier niveau

Propriété	Type	Signification
scanned	int	Nombre de fichiers analysés.
detected	int	Nombre de correspondances de malware détectées.
verifiedByChecksum	int	Nombre de fichiers acceptés par vérification de somme de contrôle.
removed, ignored, edited, quarantine, whitelist	array	Chemins ou enregistrements affectés par l'action correspondante.
infectedFound	array	Chemins des fichiers infectés trouvés lors de l'analyse.
fileHashes	array	Métadonnées de hachages de fichiers collectées pendant l'analyse.
findings	array	Enregistrements canoniques de détections issus des analyses de fichiers, d'intégrité, d'archives et supplémentaires.
coverage	array	Exhaustivité, comptages et motifs d'exclusion.
diagnostics	array, lorsqu'il est présent	Erreurs non fatales d'analyse ou de mise à jour des définitions.
signature_indexes	array	Métadonnées des index de réputation intégrés et facultatifs.
inventory	array, lorsqu'il est présent	Inventaire des composants de plateforme détectés.

De nouveaux champs de rapport peuvent être ajoutés dans une version mineure. Les consommateurs doivent lire les champs nécessaires, tolérer les champs inconnus et utiliser isset() pour les propriétés facultatives.

Gérer la réussite et l'échec

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

Ne considérez pas un nombre detected non nul comme un échec d'exécution. Les détections identifient des conditions de code ou d'intégrité qui nécessitent un examen. Elles n'établissent pas une intention et n'autorisent pas la suppression.

Contrat d'enregistrement des détections

Chaque détection canonique contient ces champs :

Champ	Type	Signification
id	string	Identifiant SHA-256 stable dérivé du type, du fournisseur, de l'ID de règle et du sujet normalisé.
kind	string	Catégorie de détection, telle que malware, integrity ou un type d'analyse supplémentaire.
subject	string	Chemin de fichier ou sujet analysé.
rule_id	string	Identifiant stable de la règle ou de l'indicateur détecteur.
severity	string	Gravité fournie par le détecteur, généralement warn ou danger.
message	string	Détail de détection lisible par un humain.
status	string	État actuel de la détection. Les nouvelles détections commencent à open.
evidence	array	Contexte tel que line, match ou content_hash lorsqu'il est disponible.
provider	string	Source du détecteur, telle que builtin.
first_seen_at, last_seen_at	string	Horodatages ISO 8601 de l'observation de la détection.

Conservez rule_id, subject et le hachage de contenu observé lors de la déduplication des alertes. Un numéro de ligne ou un extrait peut changer lorsqu'un fichier est modifié.

La couverture fait partie du résultat

Le rapport inclut des comptages de couverture pour discovered, eligible, scanned, skipped, verified, cached et errors. coverage.reasons distingue les fichiers ignorés par path, extension, oversized, excluded, unreadable et archive_limit.

Utilisez ce contrôle avant d'accepter une analyse comme complète :

$coverage = $report->coverage;

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

Les lots avec décalage et limite, les fichiers illisibles, les limites de taille de fichier et les limites d'archives peuvent rendre le résultat incomplet. Un résultat complet sans détection a plus de valeur qu'un résultat partiel sans détection.

Diagnostics et données externes

diagnostics signale les erreurs non fatales. Par exemple, le scanner peut continuer avec les définitions Maltrail mises en cache lorsqu'une mise à jour échoue. Conservez les diagnostics avec les détections afin qu'un opérateur puisse distinguer un résultat propre d'une analyse réduite.

signature_indexes expose les nombres d'enregistrements et les hachages source des index intégrés de malware et de noyau historique. Lorsqu'un magasin Maltrail actif existe, il inclut également les métadonnées de l'index de domaines et son heure de mise à jour. Utilisez ces valeurs pour les pistes d'audit, et non comme substitut aux preuves de détection.

Sérialiser les rapports

Utilisez json_encode() avec gestion des erreurs lorsque vous stockez le rapport en mémoire :

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

Utilisez setReportFormat('json') ou setReportFormat('sarif') lorsque le scanner doit également écrire un fichier pour des outils externes. Choisissez un répertoire hors du projet analysé pour les rapports, points de contrôle, sauvegardes et fichiers mis en quarantaine.