API de informes y hallazgos

Scanner::run() devuelve un informe stdClass tras completar un análisis. Scanner::getReport() devuelve la misma estructura de informe actual. Ante un fallo de análisis capturado, run() devuelve false; inspeccione getLastError() en la instancia del escáner.

Contrato del informe de nivel superior

Propiedad	Tipo	Significado
scanned	int	Número de archivos analizados.
detected	int	Número de coincidencias de malware detectadas.
verifiedByChecksum	int	Número de archivos aceptados mediante verificación de suma de comprobación.
removed, ignored, edited, quarantine, whitelist	array	Rutas o registros afectados por la acción coincidente.
infectedFound	array	Rutas de archivos infectados encontradas durante el análisis.
fileHashes	array	Metadatos de hashes de archivos recopilados durante el análisis.
findings	array	Registros canónicos de hallazgos procedentes de análisis de archivos, integridad, archivos comprimidos y suplementarios.
coverage	array	Exhaustividad, recuentos y motivos de omisión.
diagnostics	array, cuando está presente	Errores no fatales de análisis o actualización de definiciones.
signature_indexes	array	Metadatos de índices de reputación integrados y opcionales.
inventory	array, cuando está presente	Inventario de componentes de plataforma detectados.

Se pueden añadir nuevos campos de informe en una versión menor. Los consumidores deben leer los campos que necesitan, tolerar campos desconocidos y usar isset() para propiedades opcionales.

Gestionar éxito y fallo

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

No considere un recuento detected distinto de cero como un fallo de ejecución. Los hallazgos identifican condiciones de código o integridad que requieren revisión. No establecen una intención ni autorizan la eliminación.

Contrato de registro de hallazgos

Cada hallazgo canónico contiene estos campos:

Campo	Tipo	Significado
id	string	Identificador SHA-256 estable derivado del tipo, proveedor, ID de regla y sujeto normalizado.
kind	string	Categoría del hallazgo, como malware, integrity o un tipo de análisis suplementario.
subject	string	Ruta de archivo o sujeto analizado.
rule_id	string	Identificador estable de la regla o indicador detector.
severity	string	Gravedad proporcionada por el detector, normalmente warn o danger.
message	string	Detalle de detección legible por humanos.
status	string	Estado actual del hallazgo. Los hallazgos nuevos comienzan como open.
evidence	array	Contexto como line, match o content_hash cuando está disponible.
provider	string	Fuente del detector, como builtin.
first_seen_at, last_seen_at	string	Marcas temporales ISO 8601 para la observación del hallazgo.

Conserve rule_id, subject y el hash de contenido observado al eliminar alertas duplicadas. Un número de línea o un fragmento puede cambiar cuando cambia un archivo.

La cobertura es parte del resultado

El informe incluye recuentos de cobertura para discovered, eligible, scanned, skipped, verified, cached y errors. coverage.reasons separa los archivos omitidos por path, extension, oversized, excluded, unreadable y archive_limit.

Use esta comprobación antes de aceptar un análisis como completo:

$coverage = $report->coverage;

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

Los lotes con offset y límite, archivos ilegibles, límites de tamaño de archivo y límites de archivos comprimidos pueden hacer que el resultado sea incompleto. Un resultado completo sin hallazgos tiene más peso que un resultado parcial sin hallazgos.

Diagnósticos y datos externos

diagnostics informa de errores no fatales. Por ejemplo, el escáner puede continuar con definiciones de Maltrail almacenadas en caché cuando falla una actualización. Conserve los diagnósticos junto con los hallazgos para que un operador pueda distinguir un resultado limpio de un análisis reducido.

signature_indexes expone los recuentos de registros y hashes de origen de los índices integrados de malware y núcleo heredado. Cuando existe un almacén Maltrail activo, también incluye metadatos del índice de dominios y su hora de actualización. Use esos valores para las pistas de auditoría, no como sustituto de las evidencias de los hallazgos.

Serializar informes

Use json_encode() con gestión de errores cuando almacene el informe en 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());
}

Use setReportFormat('json') o setReportFormat('sarif') cuando el escáner también deba escribir un archivo para herramientas externas. Elija un directorio fuera del proyecto analizado para los informes, puntos de control, copias de seguridad y archivos en cuarentena.