AB
AiBoss
チュートリアル

搭建 OSS 片段扫描与判断留痕流程:用 SCANOSS 检查 AI 生成代码的许可证风险

チュートリアル

搭建 OSS 片段扫描与判断留痕流程:用 SCANOSS 检查 AI 生成代码的许可证风险

介绍如何围绕 SCANOSS 搭建一套 OSS 片段扫描流程:上传 zip 或 Git 仓库、选择扫描引擎、理解 WFP 指纹里到底发送了什么、按规则自动把匹配结果分成三类、逐条记录判断并导出 CSV 作为可追溯的证据。适合在团队中引入 AI 编码工具、又需要说明生成代码来源与许可证合规的开发者。

AI 编码工具进入日常开发之后,一个绕不开的问题是:模型生成的代码可能和已有开源项目高度相似,甚至整段一致。一旦如此,原代码的许可证条件就可能适用于你的项目。MIT 这类只要求保留版权声明的许可证,和 GPL 这类对衍生作品分发附加条件的许可证,需要确认的点完全不同。所以「这是 AI 写的,应该没事」并不能作为结论。

麻烦在于,现成的 OSS 片段扫描工具并不少,但直接跑 CLI 得到的往往是一大堆 JSON。十几条匹配摆在那里,真正需要处理的是哪几条?.gitignore 和一个 GPL 项目 100% 一致,需要在意吗?确认过之后,谁在什么时候基于什么理由做了判断,又记录在哪里?扫描本身不是终点,能「查出来、做出判断、并且把判断展示给别人看」才算走完流程。

下面这套做法围绕 SCANOSS 扫描引擎展开,目标是把扫描、自动分拣、人工判断、证据导出串成一条可重复执行的流程。它适合准备在团队里引入 AI 编码工具、又需要向他人解释生成代码来源与许可证情况的开发者。文中涉及的许可证条款、SCANOSS 各组件的授权条件、配额与可用性都可能变化,实际使用前请以各项目官网的当前信息为准。

准备工作

明确要解决的问题边界

动手之前先把目标写清楚,否则很容易做成「又一个吐 JSON 的脚本」。这条流程需要同时满足两件事:

  • 任何人都能轻松发起扫描:不需要记命令行参数,从界面选一个 zip 或一个已登记的仓库即可。
  • 结果本身就能当证据:扫描用了什么方式、发送了什么、按什么规则分拣、谁在何时做了什么判断,都能一次性导出。

另外要提前认清一点:开源许可证的义务不只取决于「你有没有用某个工具」,还取决于软件如何被嵌入、以什么形式分发。扫描结果只是判断的输入,不是法律结论。

确认 SCANOSS 各组件的授权条件

SCANOSS 由多个相关组件构成,引擎、API、客户端各自的许可条件并不相同。在把任何组件接入内部流程之前,先逐个确认你实际要用的那部分组件的授权条款,再决定采用哪种组合。这一步不要跳过,也不要凭印象假设「开源就等于随便用」。

准备运行环境

下面是一套可用的技术组合,按角色划分:

角色选用的组件
界面与 APINext.js / React / Tailwind CSS
扫描执行Node.js 常驻 worker,用数据库充当队列
扫描引擎SCANOSS(engine / API)
登录内部 GitLab 账号(better-auth)
数据库PostgreSQL
部署Docker Compose

其中登录方式可以按你所在组织的实际情况替换,关键是扫描动作要能关联到具体的人,否则后面的「谁判断的」就无从记录。

准备两种扫描来源

扫描对象支持两类:上传 zip / tar.gz 压缩包,或者从已登记的 Git 仓库中选择。前者适合临时检查一段外部交付的代码,后者适合对自有项目做周期性复查。

操作步骤

第一步:选择扫描引擎并处理外部发送的同意

扫描方式有两种,区别在于比对的知识库在哪里、是否有数据离开你的环境:

方式比对目标外部发送
内部引擎部署在内部服务器上的自建知识库无
SCANOSS APISCANOSS 的公开知识库发送文件指纹(哈希)

选择 SCANOSS API 时,每次扫描都要先展示「发送什么、不发送什么」,取得操作者同意后才继续。发送的内容包括用于比对的哈希值、文件大小、随机 ID 等信息;源代码正文、原始文件名和目录名不发送。即便如此,数据终究离开了本地环境,所以每次扫描都要记录同意人与同意时间,这条记录本身也是证据的一部分。

第二步:理解 WFP 指纹里到底有什么

「只发送哈希值」这句话听起来抽象,最好能说清具体字段。这里用的是 WFP(Winnowing Fingerprint)机制:不发送源码本身,而是把代码特征转换成哈希值,用于和开源代码比对。

假设有一个 48 行的 C 文件 src/app/config_loader.c,其中包含类似下面的片段:

static unsigned parse_hex4(const unsigned char * const input) {
    unsigned int h = 0;
    size_t i = 0;
    for (i = 0; i < 4; i++) {
        /* parse digit */
        if ((input[i] >= '0') && (input[i] <= '9'))
            ...
    }
}

由它生成的 WFP 大致是这种形式:

file=0cbfaf08bde5df5db5024f1a6b946d85,1147,c67f3b71da5c462a939204217fb5c820.c
fh2=4950ff1285c0e56f3a6276ccd77b1afb
9=5f0fe9b5
12=05285d16
15=54119cfb
16=3342fed2
19=e34f0c28
24=5d65215e
29=ea303752
37=b20b1de6
41=39dd4a9e
46=627c0a3a

逐行看含义:

行内容用途
file=整个文件的 MD5、文件大小、随机 ID 加扩展名确认整个文件是否一致
fh2=用于兼容换行符差异的哈希值减少因换行符不同造成的漏匹配
9=5f0fe9b5 等行号 = 代码片段的哈希值比对代码的局部是否一致

几个关键点:

  • 不含源码正文:片段指纹是代码特征的哈希,通常无法从哈希值直接还原出源代码。但哈希值本身也是可用于比对的信息,是否允许外发仍要按组织内部规定判断。
  • 不发送原始文件名与目录名:src/app/config_loader.c 会被替换成 c67f3b71….c 这样的随机 ID 加扩展名。
  • ID 与文件名的对应表只留在本地:拿到结果后在本地把文件名还原,扫描结束后删除对应表。
  • file= 里的 MD5 是整个文件的哈希:持有同一文件的人可以据此认出「就是这个文件」。如果文件本身是公开的开源文件,通常不成问题;但组织规定是否允许外发,仍应事先确认。

同意对话框里应当把这些点写清楚,而不是只写一句「会发送哈希」。

第三步:按规则自动分拣匹配结果

这是整套流程里最值得投入的部分。以扫描工具自身的仓库为例,可能得到十几条匹配,把它们自动分成三类:需要确认、建议确认、不在范围内。

规则本身很简单,从上到下依次判定即可:

  1. package-lock.json、.gitignore 这类「本来就该长得像」的文件,以及只有寥寥几行匹配的结果,归入不在范围内。
  2. 命中 copyleft 系许可证,或匹配率较高的结果,归入需要确认。
  3. 其余归入建议确认。

每一条都要给出被分到该类的理由,例如「匹配率高(87%,阈值 80% 以上)」「copyleft 系许可证(GPL-2.0-only)」。这样看结果的人不必再去翻原始 JSON 就能判断。

阈值和排除规则应当做成全员共用的一份配置,避免不同的人对「这个算安全」「这个算有问题」各有一套标准。同时可以在结果页面临时调整阈值,观察分拣结果如何变化,用于校准规则,但不要让它成为个人化的长期设置。

验证规则是否有效的一个办法,是在测试目录里故意放几份从开源项目复制来的文件,看它们是否被正确识别并归入「需要确认」。如果连故意埋进去的样本都漏掉,规则就还需要调整。

第四步:逐条记录判断

对每一条匹配,记录一个判断。判断只有三种:

  • 无问题:自己写的代码,或者只是常见写法恰好相似。
  • 已处理:代码来自开源项目,且已按许可证要求完成相应处理。
  • 需处理:代码来自开源项目,尚未完成必要处理。

对仓库类扫描,要把已记录的判断延续到下一次扫描。这样每次只需复查发生变化的部分,而不是从头看一遍。如果匹配到的行发生了变化,界面应提示「请重新审视该判断」。

第五步:导出 CSV 作为证据

最后把结果导出为 CSV。文件里不只有匹配清单,还应当包含「何时、扫描了什么、按什么规则分拣、谁做了什么判断」。一份典型的导出内容结构如下:

项目值
扫描名test_1
扫描方式SCANOSS API
外部发送的同意2026/10/20 14:21:17(同意人)
分类:需要确认6
未判断(不含不在范围内)8
阈值:匹配率 %(达到即需确认)80

明细部分按行给出:分类、判定理由、判断、备注、判断人、判断时间、文件、匹配对象、许可证等字段。例如一行可能是:分类「需要确认」,理由「匹配率高(100%,阈值 80% 以上)」,判断「未判断」,文件 src/engine/tests/fixtures/full-copy/cJSON.c,匹配对象 cJSON,许可证 MIT。

导出时注意编码,确保用 Excel 打开不会乱码,这样文件可以直接作为对内或对外的说明材料。

一个完整示例

把上面的步骤串起来,对一个仓库做一次完整扫描的流程如下。

  1. 选择来源:在界面中选择已登记的 Git 仓库,或上传一个 zip 包。
  2. 选择引擎:如果代码不便离开本地环境,选内部引擎;如果使用 SCANOSS API,先阅读同意对话框,确认发送内容为哈希值、文件大小、随机 ID,不含源码正文与原始文件名,然后确认同意。系统记录同意人与时间。
  3. 等待扫描完成:worker 从数据库队列中取出任务并调用扫描引擎,完成后在本地把随机 ID 还原为原始文件名,删除对应表。
  4. 查看分拣结果:结果按「需要确认 / 建议确认 / 不在范围内」分组展示,每条附带判定理由。先处理「需要确认」组。
  5. 逐条判断:对每条匹配选择「无问题 / 已处理 / 需处理」,必要时填写备注说明依据。
  6. 导出 CSV:下载包含扫描元信息、分拣规则、判断记录与明细的 CSV,归档保存。
  7. 下次扫描:对同一仓库再次扫描时,已有判断自动延续;只有匹配行发生变化的条目会提示重新审视。

如果要在本地验证分拣规则,可以在测试目录中放入几份从开源项目复制的文件(例如 cJSON 相关文件),再跑一次扫描,确认它们被识别并归入「需要确认」,而不是被误判为「不在范围内」。

注意事项

  • 哈希外发仍需按内部规定判断:WFP 不含源码正文,通常也无法从哈希还原源码,但哈希值本身是可用于比对的信息。是否允许发送到外部 API,应由组织内部规则决定,并在每次扫描时取得明确同意。
  • 整文件 MD5 可被识别:file= 字段是整个文件的哈希,持有同一文件的人能据此认出该文件。公开的开源文件通常无碍,但内部文件的外发需要事先确认。
  • 许可证义务取决于嵌入与分发方式:扫描结果只说明存在相似或一致,是否触发许可证义务、触发哪些义务,要结合代码如何被嵌入、以什么形式分发来判断。
  • 分拣规则要统一:阈值与排除规则应保持全员一致,否则判断标准会因人而异,证据的可信度也会下降。
  • 判断要能延续:仓库扫描必须把判断带到下一次扫描,否则每次都要从头复核,流程很快会被放弃。
  • 组件授权条件需逐个确认:SCANOSS 的引擎、API、客户端许可条件不同,接入前逐一核实;相关条款与配额可能调整,以官网当前信息为准。
  • 导出文件注意编码:CSV 要保证在常用表格软件中打开不乱码,否则作为证据材料的可用性会大打折扣。