API отчетов и находок

Scanner::run() возвращает отчет stdClass после завершенного сканирования. Scanner::getReport() возвращает ту же структуру текущего отчета. При перехваченной ошибке сканирования run() возвращает false; проверьте getLastError() у экземпляра сканера.

Контракт отчета верхнего уровня

Свойство	Тип	Значение
scanned	int	Число просканированных файлов.
detected	int	Число обнаруженных совпадений с вредоносным ПО.
verifiedByChecksum	int	Число файлов, принятых при проверке контрольной суммы.
removed, ignored, edited, quarantine, whitelist	array	Пути или записи, затронутые соответствующим действием.
infectedFound	array	Пути к зараженным файлам, найденным во время сканирования.
fileHashes	array	Метаданные хешей файлов, собранные при сканировании.
findings	array	Канонические записи находок из файлового анализа, проверки целостности, архивов и дополнительных анализов.
coverage	array	Полнота, счетчики и причины пропуска.
diagnostics	array, если присутствует	Нефатальные ошибки анализа или обновления определений.
signature_indexes	array	Метаданные встроенных и необязательных репутационных индексов.
inventory	array, если присутствует	Инвентарь обнаруженных компонентов платформы.

Новые поля отчета могут быть добавлены в минорном выпуске. Потребители должны читать нужные поля, допускать неизвестные поля и использовать 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 ошибкой выполнения. Находки указывают на код или условия целостности, которые нужно проверить. Они не устанавливают намерение и не разрешают удаление.

Контракт записи находки

Каждая каноническая находка содержит следующие поля:

Поле	Тип	Значение
id	string	Стабильный идентификатор SHA-256, производный от типа, поставщика, ID правила и нормализованного объекта.
kind	string	Категория находки, например malware, integrity или тип дополнительного анализа.
subject	string	Путь к файлу или просканированный объект.
rule_id	string	Стабильный идентификатор обнаружившего правила или индикатора.
severity	string	Серьезность от детектора, обычно warn или danger.
message	string	Понятная человеку деталь обнаружения.
status	string	Текущий статус находки. Новые находки начинаются со статуса open.
evidence	array	Контекст, такой как line, match или content_hash, когда доступен.
provider	string	Источник детектора, например builtin.
first_seen_at, last_seen_at	string	Метки времени ISO 8601 наблюдения находки.

При дедупликации оповещений сохраняйте rule_id, subject и наблюдаемый хеш содержимого. Номер строки или фрагмент могут измениться при изменении файла.

Охват является частью результата

Отчет включает счетчики охвата для 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, нечитаемые файлы, ограничения размера файлов и архивов могут сделать результат неполным. Полный результат без находок имеет больший вес, чем частичный результат без находок.

Диагностика и внешние данные

diagnostics сообщает о нефатальных ошибках. Например, сканер может продолжить работу с кэшированными определениями Maltrail, если обновление не удалось. Сохраняйте диагностику вместе с находками, чтобы оператор мог отличить чистый результат от сокращенного анализа.

signature_indexes предоставляет количество записей и хеши источников для встроенных индексов вредоносного ПО и устаревшего ядра. Если активно хранилище Maltrail, оно также содержит метаданные индекса доменов и время его обновления. Используйте эти значения для аудиторских следов, а не как замену доказательствам находки.

Сериализация отчетов

Используйте 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());
}

Используйте setReportFormat('json') или setReportFormat('sarif'), если сканер должен также записывать файл для внешних инструментов. Выбирайте для отчетов, контрольных точек, резервных копий и файлов карантина каталог за пределами сканируемого проекта.