API report e rilevamenti

Scanner::run() restituisce un report stdClass dopo una scansione completata. Scanner::getReport() restituisce la stessa struttura del report corrente. In caso di errore di scansione intercettato, run() restituisce false; esamina getLastError() sull'istanza dello scanner.

Contratto del report di primo livello

Proprietà	Tipo	Significato
scanned	int	Numero di file scansionati.
detected	int	Numero di corrispondenze malware rilevate.
verifiedByChecksum	int	Numero di file accettati dalla verifica del checksum.
removed, ignored, edited, quarantine, whitelist	array	Percorsi o record interessati dall'azione corrispondente.
infectedFound	array	Percorsi dei file infetti trovati durante la scansione.
fileHashes	array	Metadati degli hash dei file raccolti durante la scansione.
findings	array	Record canonici dei rilevamenti provenienti da analisi di file, integrità, archivi e supplementari.
coverage	array	Completezza, conteggi e motivi di salto.
diagnostics	array, se presente	Errori non fatali nell'analisi o nell'aggiornamento delle definizioni.
signature_indexes	array	Metadati degli indici di reputazione integrati e opzionali.
inventory	array, se presente	Inventario dei componenti della piattaforma rilevati.

Nuovi campi del report possono essere aggiunti in una release minore. I consumer devono leggere i campi necessari, tollerare quelli sconosciuti e usare isset() per le proprietà opzionali.

Gestire successo e fallimento

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

Non trattare un conteggio detected diverso da zero come errore di esecuzione. I rilevamenti identificano condizioni del codice o di integrità che richiedono revisione. Non stabiliscono l'intento né autorizzano l'eliminazione.

Contratto del record di rilevamento

Ogni rilevamento canonico contiene questi campi:

Campo	Tipo	Significato
id	string	Identificatore SHA-256 stabile derivato da tipo, provider, ID della regola e soggetto normalizzato.
kind	string	Categoria del rilevamento, ad esempio malware, integrity o un tipo di analisi supplementare.
subject	string	Percorso del file o soggetto scansionato.
rule_id	string	Identificatore stabile della regola o dell'indicatore di rilevamento.
severity	string	Gravità fornita dal rilevatore, comunemente warn o danger.
message	string	Dettaglio del rilevamento leggibile dall'utente.
status	string	Stato corrente del rilevamento. I nuovi rilevamenti iniziano come open.
evidence	array	Contesto come line, match o content_hash, se disponibile.
provider	string	Origine del rilevatore, ad esempio builtin.
first_seen_at, last_seen_at	string	Timestamp ISO 8601 dell'osservazione del rilevamento.

Mantieni rule_id, subject e l'hash del contenuto osservato quando deduplichi gli avvisi. Un numero di riga o uno snippet possono cambiare quando un file cambia.

La copertura fa parte del risultato

Il report include i conteggi di copertura per discovered, eligible, scanned, skipped, verified, cached ed errors. coverage.reasons separa i file saltati in base a path, extension, oversized, excluded, unreadable e archive_limit.

Usa questo controllo prima di accettare una scansione come completa:

$coverage = $report->coverage;

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

Batch con offset e limite, file illeggibili, limiti di dimensione dei file e limiti degli archivi possono rendere incompleto il risultato. Un risultato completo senza rilevamenti ha maggior peso di un risultato parziale senza rilevamenti.

Diagnostica e dati esterni

diagnostics segnala errori non fatali. Per esempio, lo scanner può continuare con definizioni Maltrail in cache quando un aggiornamento non riesce. Rendi persistente la diagnostica insieme ai rilevamenti affinché un operatore possa distinguere un risultato pulito da un'analisi ridotta.

signature_indexes espone i conteggi dei record e gli hash di origine degli indici malware e legacy-core integrati. Quando è presente un archivio Maltrail attivo, espone anche i metadati dell'indice di domini e l'ora di aggiornamento. Usa questi valori per le tracce di audit, non in sostituzione delle prove del rilevamento.

Serializzare i report

Usa json_encode() con gestione degli errori quando memorizzi il report in memoria:

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

Usa setReportFormat('json') o setReportFormat('sarif') quando lo scanner deve anche scrivere un file per strumenti esterni. Scegli una directory al di fuori del progetto scansionato per report, checkpoint, backup e file in quarantena.