代码评审前,开发人员想把某个源文件的QAC告警带到编辑器里看。Validate里的问题列表已经能查到记录,但截图看不出规则编号,复制表格也容易漏掉文件位置。此时可以通过Validate的Web API把查询结果存成SARIF。导出后,先挑一条已知告警核对编号、位置和状态,就能看出这份文件是否取对了项目和查询范围。
一、QAC怎么通过Validate导出SARIF
QAC负责分析,Validate负责管理上传的结果并按查询导出。项目已经接入时,可以跳过连接和上传,直接拿一个有已知告警的文件试导。
1、确认Validate上已有分析结果
①在QAC桌面端打开已完成分析的项目,依次进入【Portals】→【Validate】→【Connect Project】,连接到对应的Validate项目。
②连接后,依次选择【Portals】→【Validate】→【Upload Results】,上传本次分析结果。使用命令行时,可通过【qacli validate build】上传。
③登录Validate,在项目的问题列表里核对构建和告警内容,记下一条告警的问题编号及所在文件,供导出后对照。
2、用搜索接口请求SARIF
导出格式由请求参数决定。把普通搜索结果的扩展名改成`.sarif`,文件里的结构不会跟着变。
①向服务器的【/review/api】发送POST请求,在表单中设置【action=search】和【format=sarif】。
②填写【user】和【project】,使用具备该项目Web API访问权限的账号,并按服务器的认证方式提交请求。只想查某个文件时,可加入【query=file:MyFile.c】,把示例文件名换成实际名称。
③请求成功后,将完整响应以UTF-8保存为【qac-results.sarif】。若脚本收到的是错误响应,先处理错误,不把响应内容当成扫描结果归档。
3、打开文件核对导出内容
①用文本编辑器或SARIF查看器打开【qac-results.sarif】,检查【version】是否为2.1.0,并展开【runs】中的【results】。
②在【results】内查找刚才记下的问题编号,核对告警所在文件和消息内容。
查询没有匹配项时,接口仍可以返回结构完整的SARIF,只是结果列表为空。看到空列表时,先用相同条件回查Validate,再判断这次导出有没有问题。
二、QAC导出的SARIF包含哪些告警信息
在导出的文件里,每条结果对应一项检出问题。规则编号和问题编号分开保存,同一条检查规则可以在多个文件或多处代码中触发。
1、查看规则、消息和问题编号
①在【results】中选中一条记录,查看【ruleId】确认触发告警的检查规则,再读【message.text】了解这一处问题的描述。
②读取【properties.id】,用它和Validate问题列表里的编号对照。需要查看规则说明时,在【tool.driver.rules】中找到对应条目;条目带有【helpUri】时,可用它打开帮助页。
2、检查文件路径和源码行号
①展开【locations】下的【physicalLocation】,读取【artifactLocation.uri】标出的文件位置。
②若条目包含【region.startLine】,按该行号回到源码核对。如果只有文件路径,检查QAC是否具备所需的合规许可,并查看原始文件中是否真的缺少行号字段。
同一个文件在分析机和开发机上的路径可能不同。即使SARIF带了行号,查看器也得能把文件位置对应到本地源码,才能跳到那一行。
3、分清严重级别、基线状态和抑制标记
这三项回答的是不同的问题:告警有多严重、与基线相比有没有变化,以及它是否按相应状态被抑制。做统计时不要把它们并到同一列。
①读取【level】。QAC的8至9级映射为【error】,1至7级映射为【warning】,0级映射为【note】。
②读取【baselineState】。【new】表示新检出,【unchanged】表示当前和基线中均存在,【absent】表示基线中曾出现、当前未检出。
③检查【suppressions】。如果问题在Validate中被标为【Ignore】、【Not a Problem】或【Code Suppression】,且该条目包含在本次导出结果中,核对它的抑制标记。
三、QAC导出的SARIF与Validate列表不一致怎么查
对不上时,可以拿一条已知告警做对照。先比有没有导出来,再比导出来的字段是否被查看器正确显示,往往比直接核对总数更快。
1、用同一文件缩小查询范围
①在Validate的问题列表中找一个确定有告警的文件,记下项目名、问题编号和当前列表使用的筛选条件。
②将导出请求里的【project】与页面上的项目名对照,把【query】缩小到该文件后重导,再到【results】中查找对应的【properties.id】。
③如果还是找不到,核对页面是否正在查看历史构建或受项目视图约束,并检查API账号能访问的项目范围。
2、从原始文件区分导出问题和显示问题
同一个文件里,文本编辑器能看到告警,代码平台却没有显示,说明还要查导入端如何处理这条记录。可以从路径和状态入手。
①在原始SARIF中找到这条告警,核对【artifactLocation.uri】能否映射到接收平台上的源码路径,再检查有没有【region.startLine】。
②对照查看器的级别与状态筛选,检查该告警是否因【level】、【baselineState】或【suppressions】没有出现在当前列表里。
总结
交接QAC结果时,SARIF能把告警描述、规则和源码位置一起带过去。每次导出最好顺手记下项目、构建和查询条件。隔几天再回头看,文件里少了几条,就有依据判断是代码有变化,还是两次取数的范围不同。若有相关需求,欢迎交流。