技能使用指南

sarif-parsing（SARIF解析Skill）Skill 是什么？如何下载？

SARIF解析Skill（sarif-parsing）专为静态分析结果交换格式设计，能读取 CodeQL、Semgrep 等工具输出的 SARIF 文件，完成多工具聚合、指纹去重、按严重性过滤、漏洞字段提取与 CI/CD 门禁配置。本文详解技能定位、安装验证步骤、jq 与 pysarif、sarif-tools 三种调用方式、竞品对比及真实场景体验，帮你把堆积的扫描报告变成可执行的修复清单，立即上手提升代码安全运营效率。

SARIF解析Skillsarif-parsing
14 个章节 约 16 分钟阅读 AI 智能生成

SARIF解析Skill：把多工具安全扫描结果变成可读、可去重、可进 CI/CD 的结构化数据

  • 干什么用：专门读取、分析、处理 SARIF（静态分析结果交换格式）文件，把 CodeQL、Semgrep 等工具吐出来的原始扫描结果，变成能看懂、能聚合、能去重、能卡门禁的数据。
  • 不干什么用：它不跑扫描、不写规则、不直接读源码，只处理“已经生成好的 SARIF 结果”，定位非常清晰。
  • 核心能力：多文件聚合、指纹去重、按严重级别过滤、提取漏洞字段、基线对比找新增问题、转换成 CSV/HTML 等格式。
  • 调用方式：以 Bash、Read、Glob、Grep 为底层工具，配合 jq 做一次性查询、pysarif 做对象化编程、sarif-tools 做聚合与 CLI 报告，三条路线覆盖从“看一眼”到“接流水线”。
  • 最适合谁：安全工程师、DevSecOps 工程师、需要处理扫描报告的平台研发。

该技能叫什么？如何下载安装 AI 技能提升开发效率？

基本信息

项目 内容
技能中文名 SARIF解析Skill
技能英文名 sarif-parsing
技能ID 13556
底层允许工具 Bash、Read、Glob、Grep

它解决什么问题

安全团队一个项目往往跑三五个扫描器：CodeQL 查语义漏洞、Semgrep 查规则模式、依赖扫描查组件风险。每个工具都支持输出 SARIF，于是你手上会堆着 codeql.sarif、semgrep.sarif、trivy.sarif 一堆文件。问题随之而来：

  • 同一个问题在多个工具里重复出现，人工比对根本对不完；
  • 路径写法不一致（file:///path/to/project/ 和 /github/workspace/），脚本一匹配就错位；
  • 想知道“这次 PR 是不是引入了新漏洞”，但没有稳定的指纹做基线对比；
  • 想把结果接进 CI/CD，卡一个“高危不为零就失败”的门禁，却不知道从哪下手。

SARIF解析Skill 就是把这类“结果处理”的脏活标准化：它内置 SARIF 2.1.0 的结构认知、路径规范化方案、指纹去重策略和 CI/CD 集成模式，让你不用每次从零写解析脚本。

一键安装的思路与步骤

需要说明的是：本技能详情中并未给出技能本身的安装命令与下载入口，具体安装方式请以官方说明为准。但从技能设计可以推断，它依赖的是“在具备文件读写与命令行能力的环境中加载技能”，因此可按以下通用路径操作：

  1. 确认前提：你手头已有至少一个合法的 SARIF 文件（version 字段为 2.1.0），并且所在环境允许执行 Bash 命令、读取本地文件。这是本技能最主要的能力底座。
  2. 安装技能：在你使用的 AI 技能平台/客户端的技能市场中搜索技能名「SARIF解析Skill」或技能英文名 sarif-parsing，按平台的安装入口完成加载；具体入口与命令以官方说明为准。安装后确认技能已启用，并具备 Bash、Read、Glob、Grep 四项工具权限。
  3. 准备辅助工具（可选但强烈建议）：快速命令行查询需要 jq（brew install jq 或 apt install jq）；Python 侧可用 pip install pysarif 或 pip install sarif-tools。这些都是通用开源工具，版本请以官方文档为准。
  4. 验证是否生效：把一份 SARIF 文件放进工作目录，向技能提出明确请求，例如“统计这个 SARIF 里共有多少条发现，按级别和规则 ID 分组”。若技能能返回结构化的数量与分组结果，说明加载成功、工具权限正常。
  5. 进一步自检：让它“列出触发了哪些规则 ID”或“只提取 level 为 error 的发现”。能稳定返回结果，就说明解析链路已经完全打通。

该技能的主要功能和特点

  • 读懂 SARIF 结构：完整覆盖 runs → tool.driver → results → locations → physicalLocation → region 的层级，能准确告诉你某条发现属于哪个工具、哪条规则、哪个文件、哪一行。
  • 多工具结果聚合：把多个 SARIF 文件的 runs 数组合并成一份日志，同时保留各自的工具元数据，避免“合并完不知道是谁报的”。
  • 指纹去重：优先使用 partialFingerprints / fingerprints 做唯一性判断；指纹缺失时，回退到“规则 ID + 文件路径 + 起始行”组合键，保证不同环境之间的结果可比。
  • 按严重级别过滤与排序：按 error / warning / note / none 分级筛选并排序，直接给出优先修复顺序。
  • 结构化字段提取：把发现抽取成“规则 ID、级别、消息、文件路径、起止行、指纹”这样的规整字段，方便二次加工成工单或报表。
  • 路径规范化：处理 file:// 前缀、URL 编码、相对路径拼接和分隔符差异，解决跨工具路径对不上的老问题。
  • CI/CD 集成模式：提供 GitHub Actions 上传 SARIF、以及“新增高危即失败”的门禁写法，含基线对比逻辑。
  • 格式转换：把 SARIF 转成 CSV 便于贴表格、转成 HTML 便于给非技术同学看。
  • 大文件流式处理：面对 100MB+ 的 SARIF，可用流式读取避免一次性载入内存。
  • 模式验证：处理前先校验 schema，提前拦下格式损坏的文件。

和普通工具比强在哪：直接用 jq 或肉眼读 SARIF，你只能看到一堆嵌套 JSON，还得自己记住字段路径；单纯用某个库，又缺“怎么去重、怎么规范化、怎么卡门禁”的方法论。这个技能的价值在于把“结构知识 + 工程经验 + 代码模板”一次性打包，减少试错。

如何使用该技能？

第一步：确认输入与目标

先用 Read/Glob 确认工作目录里有哪些 SARIF 文件，再明确你的目标属于哪一类：快速看数、程序化处理、聚合去重、还是接流水线。目标不同，调用路线不同。

第二步：路线 A —— jq 快速查询（一次性探索最省事）

# 统计总发现数
jq '[.runs[].results[]] | length' results.sarif

# 列出所有触发的规则 ID
jq '[.runs[].results[].ruleId] | unique' results.sarif

# 只看 error 级别，并按规则统计数量
jq '[.runs[].results[] | select(.level == "error")] | group_by(.ruleId) | map({rule: .[0].ruleId, count: length})' results.sarif

输出说明：第一条返回数字，第二条返回规则 ID 数组，第三条返回“规则 → 数量”的对象数组，可直接作为修复排期的依据。

第三步：路线 B —— pysarif 做对象化编程

适合需要遍历、修改、再保存的场景。加载文件后遍历 runs 与 results，打印工具名、级别、规则 ID、消息、文件与行号；修改完毕后可另存为新文件。这种方式字段访问直观，适合写可维护的脚本。

第四步：路线 C —— sarif-tools 做聚合与报告

# 摘要
sarif summary results.sarif

# 列出全部结果详情
sarif ls results.sarif

# 只看 error
sarif ls --level error results.sarif

# 基线对比，找出新增与已修复
sarif diff baseline.sarif current.sarif

# 转换格式
sarif csv results.sarif > results.csv
sarif html results.sarif > report.html

输出说明：summary 给概览，diff 给“本次新增/已修复”的对比结论，csv/html 给可直接分发的交付物。

第五步：聚合多文件并去重

合并思路是新建一份 version: 2.1.0 的空日志，把每个文件的 runs 追加进去；随后遍历 results，以指纹（或“规则 + 路径 + 起始行”回退键）为集合键去重。合并时务必保留工具元数据，否则后续无法定位来源。

第六步：接入 CI/CD 门禁

- name: 上传 SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

- name: 检查高严重性
  run: |
    HIGH_COUNT=$(jq '[.runs[].results[] | select(.level == "error")] | length' results.sarif)
    if [ "$HIGH_COUNT" -gt 0 ]; then
      echo "找到 $HIGH_COUNT 个高严重性问题"
      exit 1
    fi

若要“只卡新增问题”，则用基线 SARIF 与当前 SARIF 做指纹差集，仅当差集内存在 error 级别时才让流水线失败。

同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势 不足
SARIF解析Skill（本技能） 面向 SARIF 结果处理的 AI 技能 结构解读、聚合、去重、过滤、提取、CI/CD 集成、格式转换 需在技能平台加载并具备文件读写与命令行权限 多工具结果治理、安全运营、流水线门禁 覆盖“知识 + 方法 + 代码模板”，能按自然语言需求即时给出方案 不执行扫描，依赖已有 SARIF 输入
Microsoft SARIF SDK（.NET） 官方 .NET 类库 强类型对象模型、读写、合并、验证 需 .NET 环境与 NuGet 依赖 .NET 生态内的工具开发 官方维护、类型安全、生态完整 非 .NET 技术栈接入成本高
sarif-tools（Python CLI） 命令行报告与对比工具 summary、ls、diff、csv/html 转换 pip install sarif-tools 快速出报告、基线对比 开箱即用，CLI 友好 深度定制仍需写 Python
pysarif（Python 库） 轻量 Python 对象映射 加载、遍历、修改、保存 pip install pysarif 脚本化处理与二次开发 字段访问直观，学习成本低 聚合、去重等高级逻辑需自行实现
GitHub Code Scanning 内置视图 平台内可视化 结果展示、告警跟踪 依赖平台与仓库配置 单一仓库的日常查看 无需写代码，界面直观 跨工具聚合与自定义门禁灵活度有限

选择建议：只想快速看结果，用 jq 一行命令或平台视图就够；要做跨工具治理和门禁，本技能提供的组合方案更完整；技术栈锁定 .NET，则优先考虑官方 SDK。

该技能的典型应用场景与实际体验情况

场景一：安全工程师汇总三款扫描器的结果

角色：应用安全工程师。痛点是每次发版前要把 CodeQL、Semgrep、依赖扫描的结果合到一起，重复项占比常在三成以上，人工比对手工耗时且易漏。使用方式：让技能聚合三份 SARIF、按指纹去重、输出按级别排序的清单。

实际体验：上手难度低，描述清楚目标即可拿到可执行的 jq 或 Python 片段；效果上重复项被有效合并，并且能说明“这条是哪个工具报的”。注意事项：不同工具的指纹算法可能不同，需要接受“指纹缺失时回退到规则 + 路径 + 行号”的策略，代码被重新格式化后行号变化可能产生误判为新问题。

场景二：DevSecOps 在流水线里设“新增高危即失败”

角色：DevSecOps 工程师。痛点是全量卡门禁会把历史遗留问题也算进去，导致流水线长期红着、团队直接关掉检查。使用方式：维护一份基线 SARIF，每次构建产出当前 SARIF，做指纹差集，仅对新增 error 级别失败。

实际体验：这是本技能最有价值的用法，能把“安全门禁”从形同虚设变成真正可执行。注意事项：必须保证基线与当前结果的路径归一化一致，否则差集会被环境差异污染；同时要固定工具版本，避免指纹算法变更带来噪声。

场景三：研发负责人要一份能看懂的报告

角色：研发经理。痛点是不看 JSON，只想知道“哪些文件问题最多、优先修哪几类”。使用方式：转成 HTML 或 CSV，按文件聚合计数，按规则分类排序。

实际体验：一次转换即可交付，省去手工整理。注意事项：HTML 报告适合分发，但如果要进 BI 或工单系统，CSV 更合适。

场景四：处理超大 SARIF 文件

角色：平台研发。痛点是单文件上百 MB，直接加载容易内存吃紧。使用方式：采用流式读取逐条消费 results。

实际体验：技能会明确指出大文件应走流式路径，避免踩坑。注意事项：流式模式下无法一次性拿到全局统计，需要边读边累加。

该技能能为用户带来的价值

  • 效率提升：把“读懂 SARIF 结构—写解析脚本—调字段路径—处理路径差异—补去重逻辑”这条原本需要半天到一天的链路，压缩成一次对话内的方案输出。
  • 门槛降低：不需要熟记 SARIF 2.1.0 的完整规范，也不需要精通 jq 语法，用自然语言描述需求即可获得可直接运行的命令与代码。
  • 质量收益：指纹去重与基线对比让“新增漏洞”可被准确识别，减少历史遗留问题对新代码的干扰，让安全门禁真正具备可执行性。
  • 协作收益：CSV/HTML 输出让非技术角色也能参与评审，安全结论从“安全团队的内部文件”变成“团队共享的清单”。
  • 长期价值：技能沉淀的六条关键原则（先验证、防御性访问可选字段、尽早规范化路径、指纹多策略、大文件流式处理、聚合时保留工具元数据）是可复用的工程规范，能直接写进团队的安全工具链标准。

常见问题 FAQ

Q1：这个技能怎么安装？需要额外付费吗？

安装方式请以官方说明为准：在所用 AI 技能平台中搜索「SARIF解析Skill」或 sarif-parsing 完成加载，并确认 Bash、Read、Glob、Grep 权限可用。技能详情中未提及收费信息，具体计费方式同样以官方说明为准。辅助工具 jq、pysarif、sarif-tools 均为开源软件，可免费使用。

Q2：它能帮我跑代码扫描吗？

不能。本技能明确定位为“处理已有的 SARIF 扫描结果”，不负责运行静态分析扫描，也不负责编写 CodeQL 或 Semgrep 规则，更不直接分析源码。需要执行扫描时，应使用对应的扫描类技能；需要处理结果时再回到本技能。

Q3：它适合谁用？不做安全的人有必要装吗？

主要适合安全工程师、DevSecOps 工程师、负责安全平台建设的研发，以及需要在 CI/CD 中接入安全门禁的团队。如果你只是偶尔看一次扫描结果，平台自带的可视化页面可能更省事；但只要你需要跨工具聚合、去重、做基线对比，这个技能的价值就会立刻体现。

Q4：和直接写 Python 脚本、或者单用 sarif-tools 相比怎么选？

单用 sarif-tools 适合“快速出报告和基线对比”，开箱即用；自己写 Python 适合高度定制的场景，但需要自己解决路径规范化、指纹回退、字段缺失等细节。本技能相当于把这些经验和方法模板一起给你，并在你需要时给出对应的 jq 命令或 Python 实现，更适合“既要快、又要覆盖多种处理需求”的团队。

Q5：为什么我做的去重结果不稳定，同一个问题每次都被当成新的？

大概率是路径或指纹不一致导致的。常见原因有三类：不同工具报告的路径形式不同（绝对路径、相对路径、带 file:// 前缀、URI 编码）；工具版本升级后指纹算法变化；代码重新格式化导致行号变动。建议先做路径规范化，再采用“指纹优先 + 规则与位置回退”的多策略组合，并在基线对比时固定工具版本。