sarif-parsing

sarif-parsing 技能總覽

sarif-parsing 是一個實用的技能，專門用來讀取、篩選與轉換來自 CodeQL、Semgrep 及其他靜態分析工具的 SARIF 2.1.0 掃描輸出。當你的問題是「我已經有掃描結果了，現在要怎麼理解、去重、摘要或轉換它？」而不是「去執行一次掃描」時，就該使用 sarif-parsing 技能。

這個 sarif-parsing 技能適用於什麼情境

這個技能特別適合處理掃描完成後最常卡住的幾件事：從雜訊結果中提煉訊號、比較不同執行結果、標準化檔案路徑，以及把發現項目整理成適合 CI/CD 或下游工具使用的格式。對於需要在多個掃描器或多個 repository 之間維持一致 SARIF 處理方式的團隊來說，它尤其有用。

sarif-parsing 在工作流程中的位置

sarif-parsing 是一個掃描後的工作流程技能。若你需要產生 SARIF，應先使用對應掃描器的專用技能；若你需要解讀、彙整或重塑 SARIF，這個技能才是正確的層級。這個分界很重要，因為它可以避免把掃描設定與結果處理混在一起。

sarif-parsing 的主要差異點

當你需要的是可重複的結果處理，而不是臨時性的提示詞解讀時，這個技能最有優勢。它包含具體的 SARIF 結構指引、可直接使用的查詢樣板，以及常見解析工作的輔助工具；因此 sarif-parsing 比起泛泛的「分析這段 JSON」提示更具可操作性。

如何使用 sarif-parsing 技能

sarif-parsing 的安裝與啟用

以一般的目錄工作流程安裝這個技能：

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

接著，在你的提示詞明確指出輸入是 SARIF，且你要的輸出是某種解析任務時再呼叫它，例如篩選、彙整、去重或轉換。若你把 SARIF 成品的檔案路徑寫得很清楚，例如 results.sarif，或是直接提供 CI 成品 URL，sarif-parsing 的安裝與使用效果會最好。

提供正確的輸入給 sarif-parsing

好的 sarif-parsing 用法，通常從三個資訊開始：SARIF 檔案、工具來源，以及你要根據資料做出的決策。弱一點的請求會說「分析這個 SARIF」；更好的請求則會說「將 results.sarif 中的發現去重，以 ruleId 分組，只回傳有檔案與行號的唯一 error 等級問題」。你對轉換目標描述得越具體，這個技能就越不需要猜。

先讀這些檔案

如果你要把 sarif-parsing 實際用在 Code Editing 或自動化工作上，建議先看 SKILL.md，再看 resources/jq-queries.md 取得可直接複製的查詢樣板，最後看 resources/sarif_helpers.py 理解路徑標準化與發現項擷取的邏輯。這些檔案比粗略瀏覽 repository 更能看出預期工作流程，也能幫你把提示詞對齊既有工具。

可直接套用的提示詞模式

提示詞要把操作、目標欄位與輸出格式說清楚。範例如下：

• 「解析這個 SARIF，列出唯一的 ruleId 值與各自數量。」
• 「只保留 warning 與 error，並依檔案路徑分組。」
• 「把 SARIF 發現轉成可直接匯出 CSV 的表格，包含 tool name、rule、file 和 line。」
• 「比較兩個 SARIF 檔案，找出兩次執行之間已消失的發現項目。」

sarif-parsing 技能 FAQ

sarif-parsing 只適用於安全掃描器嗎？

不是。它適用於所有產生 SARIF 的工具，包括 CodeQL、Semgrep 與其他輸出標準 SARIF 的工具。只是當輸出需要後處理，而不只是直接檢視原始內容時，這個技能最有價值。

什麼情況下不該使用 sarif-parsing？

如果你需要的是執行掃描、撰寫規則，或直接檢查原始碼，就不該用 sarif-parsing。若你手上還沒有 SARIF 輸入，這個技能也不適合，因為它預設你已經有一個結果檔案。

sarif-parsing 會比一般提示詞更好嗎？

通常會，因為 sarif-parsing 會把 SARIF 的結構與常見操作先編碼進來，而不是把它當成任意 JSON 處理。這讓它在去重、嚴重度篩選與位置擷取等任務上更可靠；一般提示詞常常會漏掉欄位，或回傳不一致的格式。

初學者適合使用 sarif-parsing 嗎？

可以，只要使用者能指出 SARIF 檔案與目標即可。初學者通常在一次只要求一種轉換時效果最好，例如「列出前 10 個發現數量最多的規則」或「擷取 src/ 裡的所有發現」。當需求具體時，這個技能就更容易上手。

如何改善 sarif-parsing 技能

讓轉換目標更精準

要讓 sarif-parsing 的結果更快變好，最有效的方法就是把操作內容與輸出格式講到位。不要只說「摘要」，而是改成「依 ruleId 分組、按嚴重度計數，並輸出成 markdown 表格」。也不要只說「篩選發現」，而是明確指定要套用哪些 rule ID、等級與路徑規則。

提供足夠的 SARIF 背景資訊

如果你有提供掃描器名稱、已知的 SARIF 版本，以及路徑是 repo 相對路徑、絕對路徑，還是 URI 編碼，結果通常會更好。這些背景資訊能幫助技能避免在標準化、去重與檔案比對上做出錯誤假設；這些也正是 SARIF 解析中常見的失敗點。

從原始發現逐步推進到決策

一個好的 sarif-parsing 操作流程是：先擷取並標準化發現項，再做彙總，最後決定哪些要忽略、哪些要升級處理。若第一輪輸出太吵雜，就先用 level、ruleId、目錄或工具執行範圍縮小，再要求最終報告。這樣得到的訊號通常比想一次把分流判定做完更清楚。

留意常見的 SARIF 陷阱

最常見的坑包括：缺少 location、同一檔案內有多個 runs、不同工具之間的結果重複，以及在比對前需要先標準化的 file URI。若你的輸出看起來不完整，可以要求這個技能把所有 runs 都納入，並在保留原始欄位的同時，也保留標準化後的欄位。