
搭建 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、客户端各自的许可条件并不相同。在把任何组件接入内部流程之前,先逐个确认你实际要用的那部分组件的授权条款,再决定采用哪种组合。这一步不要跳过,也不要凭印象假设「开源就等于随便用」。
准备运行环境
下面是一套可用的技术组合,按角色划分:
| 角色 | 选用的组件 |
|---|---|
| 界面与 API | Next.js / React / Tailwind CSS |
| 扫描执行 | Node.js 常驻 worker,用数据库充当队列 |
| 扫描引擎 | SCANOSS(engine / API) |
| 登录 | 内部 GitLab 账号(better-auth) |
| 数据库 | PostgreSQL |
| 部署 | Docker Compose |
其中登录方式可以按你所在组织的实际情况替换,关键是扫描动作要能关联到具体的人,否则后面的「谁判断的」就无从记录。
准备两种扫描来源
扫描对象支持两类:上传 zip / tar.gz 压缩包,或者从已登记的 Git 仓库中选择。前者适合临时检查一段外部交付的代码,后者适合对自有项目做周期性复查。
操作步骤
第一步:选择扫描引擎并处理外部发送的同意
扫描方式有两种,区别在于比对的知识库在哪里、是否有数据离开你的环境:
| 方式 | 比对目标 | 外部发送 |
|---|---|---|
| 内部引擎 | 部署在内部服务器上的自建知识库 | 无 |
| SCANOSS API | SCANOSS 的公开知识库 | 发送文件指纹(哈希) |
选择 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 是整个文件的哈希:持有同一文件的人可以据此认出「就是这个文件」。如果文件本身是公开的开源文件,通常不成问题;但组织规定是否允许外发,仍应事先确认。
同意对话框里应当把这些点写清楚,而不是只写一句「会发送哈希」。
第三步:按规则自动分拣匹配结果
这是整套流程里最值得投入的部分。以扫描工具自身的仓库为例,可能得到十几条匹配,把它们自动分成三类:需要确认、建议确认、不在范围内。
规则本身很简单,从上到下依次判定即可:
package-lock.json、.gitignore这类「本来就该长得像」的文件,以及只有寥寥几行匹配的结果,归入不在范围内。- 命中 copyleft 系许可证,或匹配率较高的结果,归入需要确认。
- 其余归入建议确认。
每一条都要给出被分到该类的理由,例如「匹配率高(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 打开不会乱码,这样文件可以直接作为对内或对外的说明材料。
一个完整示例
把上面的步骤串起来,对一个仓库做一次完整扫描的流程如下。
- 选择来源:在界面中选择已登记的 Git 仓库,或上传一个
zip包。 - 选择引擎:如果代码不便离开本地环境,选内部引擎;如果使用 SCANOSS API,先阅读同意对话框,确认发送内容为哈希值、文件大小、随机 ID,不含源码正文与原始文件名,然后确认同意。系统记录同意人与时间。
- 等待扫描完成:worker 从数据库队列中取出任务并调用扫描引擎,完成后在本地把随机 ID 还原为原始文件名,删除对应表。
- 查看分拣结果:结果按「需要确认 / 建议确认 / 不在范围内」分组展示,每条附带判定理由。先处理「需要确认」组。
- 逐条判断:对每条匹配选择「无问题 / 已处理 / 需处理」,必要时填写备注说明依据。
- 导出 CSV:下载包含扫描元信息、分拣规则、判断记录与明细的 CSV,归档保存。
- 下次扫描:对同一仓库再次扫描时,已有判断自动延续;只有匹配行发生变化的条目会提示重新审视。
如果要在本地验证分拣规则,可以在测试目录中放入几份从开源项目复制的文件(例如 cJSON 相关文件),再跑一次扫描,确认它们被识别并归入「需要确认」,而不是被误判为「不在范围内」。
注意事项
- 哈希外发仍需按内部规定判断:WFP 不含源码正文,通常也无法从哈希还原源码,但哈希值本身是可用于比对的信息。是否允许发送到外部 API,应由组织内部规则决定,并在每次扫描时取得明确同意。
- 整文件 MD5 可被识别:
file=字段是整个文件的哈希,持有同一文件的人能据此认出该文件。公开的开源文件通常无碍,但内部文件的外发需要事先确认。 - 许可证义务取决于嵌入与分发方式:扫描结果只说明存在相似或一致,是否触发许可证义务、触发哪些义务,要结合代码如何被嵌入、以什么形式分发来判断。
- 分拣规则要统一:阈值与排除规则应保持全员一致,否则判断标准会因人而异,证据的可信度也会下降。
- 判断要能延续:仓库扫描必须把判断带到下一次扫描,否则每次都要从头复核,流程很快会被放弃。
- 组件授权条件需逐个确认:SCANOSS 的引擎、API、客户端许可条件不同,接入前逐一核实;相关条款与配额可能调整,以官网当前信息为准。
- 导出文件注意编码:CSV 要保证在常用表格软件中打开不乱码,否则作为证据材料的可用性会大打折扣。