sarif-parsing

sarif-parsing スキルの概要

sarif-parsing は、CodeQL、Semgrep、その他の静的解析ツールが出力する SARIF 2.1.0 のスキャン結果を読み取り、絞り込み、変換するための実用的なスキルです。sarif-parsing スキルを使うのは、「スキャンはもう実行済みで、次に必要なのは結果の把握、重複排除、要約、変換」であって、「スキャンを走らせること」ではない場面です。

このスキルの用途

このスキルは、スキャン完了後に導入の障害になりがちな作業を支援します。たとえば、ノイズの多い結果から本質を抽出する、複数実行を比較する、ファイルパスを正規化する、検出結果を CI/CD や下流ツール向けに整える、といった用途です。複数のスキャナーやリポジトリにまたがって一貫した SARIF 処理が必要なチームに特に向いています。

ワークフローのどこに入るか

sarif-parsing はスキャン後のワークフロースキルです。SARIF を生成したいなら先にスキャナー固有のスキルを使い、SARIF を解釈・集約・整形したいならこのスキルが適切です。この境界を分けることで、スキャン設定と結果処理を混ぜずに済みます。

主な差別化ポイント

このスキルが最も強いのは、場当たり的なプロンプト解釈ではなく、再現性のある結果処理が必要なときです。SARIF の構造に関する具体的なガイダンス、すぐ使えるクエリパターン、よくある解析作業向けの補助ユーティリティを備えているため、単なる「この JSON を分析して」よりも実務で使いやすいのが特徴です。

sarif-parsing スキルの使い方

sarif-parsing のインストールと有効化

通常のディレクトリワークフローで次のコマンドを使ってインストールします。

npx skills add trailofbits/skills --skill sarif-parsing

そのうえで、入力が SARIF であり、求める出力がフィルタリング、集約、重複排除、変換などの解析タスクであることを明確にしたプロンプトで呼び出します。results.sarif のようなファイルパスや CI アーティファクト URL を明示しておくと、sarif-parsing のインストール後の活用効果が高くなります。

適切な入力を与える

sarif-parsing をうまく使うには、SARIF ファイル、ツールの出所、そしてデータから何を判断したいのか、という 3 点がそろっていることが重要です。弱い依頼は「この SARIF を分析して」です。より強い依頼は「results.sarif の検出結果を ruleId で重複排除し、ファイル名と行番号つきで重大度 error の一意な問題だけ返して」です。変換内容が具体的であるほど、スキル側の推測は少なくて済みます。

最初に読むべきファイル

Code Editing や自動化作業で sarif-parsing を実用的に使うなら、まず SKILL.md を確認し、その次に resources/jq-queries.md でコピー可能なクエリパターンを見て、resources/sarif_helpers.py でパス正規化と finding 抽出のロジックを把握してください。これらのファイルは、浅くリポジトリを流し見るよりも、想定されたワークフローをよく示しており、既存のユーティリティに合わせてプロンプトを組み立てやすくなります。

うまくいくプロンプトパターン

操作名、対象フィールド、出力形式を明示したプロンプトを使ってください。例:

• 「この SARIF を解析して、ruleId ごとの一意な値と件数を一覧化して」
• 「warning と error に絞って、ファイルパスごとにグループ化して」
• 「SARIF の検出結果を、ツール名、ルール、ファイル、行番号を含む CSV 向けテーブルに変換して」
• 「2 つの SARIF ファイルを比較し、実行間で消えた検出結果を特定して」

sarif-parsing スキル FAQ

sarif-parsing はセキュリティスキャナー専用ですか？

いいえ。CodeQL、Semgrep をはじめ、標準 SARIF を出力する SARIF 生成ツール全般が対象です。ただし、もっとも価値が高いのは、結果をそのまま見るだけではなく、後処理が必要なケースです。

どんなときに sarif-parsing を使うべきではありませんか？

スキャンの実行、ルール作成、ソースコードの直接確認が必要なら、sarif-parsing は使うべきではありません。また、まだ SARIF 入力がない場合も不向きです。このスキルは、すでに結果ファイルが存在する前提だからです。

一般的なプロンプトより優れていますか？

多くの場合はそうです。sarif-parsing は SARIF を任意の JSON として扱うのではなく、その構造と典型操作を前提にしているためです。重複排除、重大度によるフィルタリング、場所情報の抽出のような作業では、一般的なプロンプトよりもフィールドの取りこぼしが少なく、出力形状も安定しやすくなります。

sarif-parsing は初心者向けですか？

はい。SARIF ファイルと目的を特定できるなら、初心者でも使えます。最も良い結果が出やすいのは、「件数上位 10 のルールを表示して」や「src/ 内のすべての検出結果を抽出して」のように、一度に 1 つの変換を依頼するやり方です。依頼が具体的であるほど、扱いやすいスキルです。

sarif-parsing スキルを改善する方法

変換内容をできるだけ具体的にする

sarif-parsing の結果を最短で良くする方法は、実行したい操作と出力形式を正確に指定することです。「要約して」ではなく、「ruleId でグループ化し、重大度ごとに件数を数え、markdown テーブルで返して」と依頼してください。「検出結果を絞り込んで」ではなく、適用したいルール ID、レベル、パス条件を明示します。

SARIF の前提情報を十分に渡す

スキャナー名、分かるなら SARIF のバージョン、パスが repo-relative か absolute か URI エンコード済みか、といった情報を入れると精度が上がります。こうした文脈は、正規化、重複判定、ファイル照合に関する誤った前提を避けるのに役立ちます。SARIF parsing では、ここが失敗要因になりやすいです。

生の検出結果から判断まで段階的に進める

よい sarif-parsing の進め方は、まず検出結果を抽出して正規化し、次に集約し、最後に無視するものとエスカレートするものを判断する、という流れです。最初の出力がノイジーなら、最終レポートを求める前に level、ruleId、ディレクトリ、ツール実行単位で絞り込んでください。1 回でトリアージまで終わらせようとするより、こちらのほうが明確なシグナルが得られます。

よくある SARIF の落とし穴に注意する

主な落とし穴は、location の欠落、1 つのファイルに複数 run があること、ツール間で結果が重複していること、照合前に正規化が必要な file URI があることです。出力が不完全に見える場合は、すべての run を考慮し、正規化前の raw field も保持するようスキルに依頼してください。