メインコンテンツまでスキップ
バージョン: v0.21

レポートと検出結果 API

完了したスキャン後、Scanner::run() は stdClass レポートを返します。Scanner::getReport() は同じ現在のレポート形式を返します。捕捉したスキャン失敗時には run() は false を返すため、スキャナーインスタンスの getLastError() を確認してください。

最上位のレポート契約​

プロパティ型意味
scanned, detected, verifiedByChecksumintスキャン済み、検出済み、チェックサムで検証済みのファイル数。
removed, ignored, edited, quarantine, whitelistarray一致したアクションの影響を受けたパスまたはレコード。
infectedFound, fileHashes, findings, coveragearray感染ファイル、ハッシュメタデータ、正規の検出レコード、完全性とスキップ理由。
diagnostics, inventory存在する場合は array致命的でないエラー、検出されたプラットフォームコンポーネント。
signature_indexesarray組み込みおよびオプションのレピュテーションインデックスのメタデータ。

新しいフィールドはマイナーリリースで追加されることがあります。必要なフィールドだけを読み、不明なフィールドを許容し、オプションのプロパティには 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、kind、subject、rule_id、severity、message、status、evidence、provider、first_seen_at、last_seen_at が含まれます。id は種別、プロバイダー、ルール ID、正規化済み対象から導出される安定した SHA-256 識別子です。新しい検出結果の status は open です。アラートを重複排除する際は、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 のレコード数、ソースハッシュ、ドメインインデックスメタデータは監査証跡用であり、検出の根拠の代わりにはなりません。

レポートをシリアル化する​

$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') を使用します。レポート、チェックポイント、バックアップ、隔離済みファイルはスキャン対象プロジェクトの外部に置いてください。