报告和发现 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	从种类、提供程序、规则 ID 和规范化主题派生的稳定 SHA-256 标识符。
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.');
}

偏移量和限制批次、不可读文件、文件大小限制和归档限制都可能使结果不完整。完整的零发现结果比部分的零发现结果更有参考价值。

诊断和外部数据

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')。为报告、检查点、备份和隔离文件选择扫描项目之外的目录。