为 AI 编码助手新增依赖设置 CI 审计门禁:从锁文件差异到来源核验与构建回归

枫少@KillBoy
枫少@KillBoy
枫少@KillBoy
管理员
484
文章
0
粉丝
安全开发9119字数 3163阅读10分32秒阅读模式
AI智能摘要
AI 编码助手只加一行声明,锁文件却可能多出几百行传递依赖——构建、测试、漏洞扫描全绿,却没人回答“这个包是谁选的”。文章主张把锁文件差异拆成声明变化、解析结果变化与来源完整性变化三类,用脚本列明新增条目的类型、版本与下载地址:直接依赖可追问选择理由,传递依赖则要核验 registry 白名单、integrity 字段与元数据自洽。包龄短、下载量低只是需要解释的信号而非判决,你的门禁分得清吗?
— AI 生成的文章内容摘要

一个 AI 编码助手被要求修一个偶发失败的测试。它读了报错,判断需要一个新的断言辅助库,执行安装命令,测试跑通,然后提交。打开这个 PR,package.json 只多了一行,package-lock.json 却能多出几百行,因为新库自己拖着一串传递依赖。其中某个包可能换了维护者,另一个包可能整个团队都没见过。流水线跑完,构建通过,单元测试通过,已知漏洞扫描没有命中,许可证检查通过。评审的人扫了一眼那一行声明,点了 approve。

这是一条完全合理的工作流,不是任何一次真实事故的复盘。问题也不在助手做了什么,而在于流水线里没有任何一环回答"这个包是谁选的"。开发者手敲 npm install 时,选择有明确的所有者;助手建议包的时候,这个所有权得靠流程重新分配,否则它就悄悄消失了。

单片白色卡片与下方层层垂落的半透明薄膜片,其中两片被琥珀色小夹子标记

理解一条绿色流水线到底验证了什么,是设计门禁的第一步。它确认了这个提交能构建、测试能过、锁文件和声明对得上、没有匹配到已知安全通告、没有撞上被拒绝的许可证。这些都很有用,但共同指向的问题是"这个候选变更有没有触发现有规则",而不是"新出现的这个包应不应该在这里"。这两件事经常被混为一谈,因为传统流程里它们恰好重合:写代码的人就是选包的人。AI 辅助改变了这个前提。

先把差异拆成三类事件

一上来就写"任何依赖变更都阻断",通常撑不过两周。团队很快会发现正常升级也被拦,于是开始加 bypass 标签,最后门禁变成形式。更实用的做法是先按性质把锁文件差异分类,不同类别走不同路径。

第一类是声明变化:manifest 里出现新包、删掉包,或者版本范围改了。这类变化有明确的人类可读记录,评审时最容易看到。

第二类是解析结果变化:锁文件里条目增删、版本升降、下载来源改动。这里最需要区分的是新增条目到底属于直接依赖还是传递依赖。直接依赖能对应到 manifest 里的某一行,传递依赖只能顺着依赖树回溯,而评审的人往往就在这一步放弃。

第三类是制品与完整性信息变化:resolved 指向的下载地址、integrity 记录的哈希。来源地址从公共 registry 变成 git 仓库、本地路径、内网地址或裸 http,都应当作独立事件处理,而不是当成一次"版本变化"。

三类混在一起看,锁文件 diff 就是一团噪声;分开看,每一类都能对上一个具体的判断动作。

用一段脚本把新增条目摊开

很多包管理器提供了直接可用的命令,比如 npm diff 能看到两个版本之间的差异。但当基线是上一次合并而不是某个发布版本时,从锁文件本身做集合比较更稳妥。以下示例只在 lockfileVersion 为 3 的 package-lock.json 上验证过,workspace、别名依赖和嵌套 node_modules 路径需要额外处理:

// check-lockfile-additions.mjs:比较两个提交的锁文件,列出新增条目
import { readFileSync } from "node:fs";

const load = (p) => JSON.parse(readFileSync(p, "utf8")).packages ?? {};
const before = load(process.argv[2]);
const after = load(process.argv[3]);

const declared = new Set(Object.keys(after[""]?.dependencies ?? {}));

for (const key of Object.keys(after)) {
  if (!key || key in before) continue;
  const entry = after[key];
  const name = entry.name ?? key.replace(/^.*node_modules\//, "");
  const kind = declared.has(name) ? "direct" : "transitive";
  console.log([kind, name, entry.version, entry.resolved].join("\t"));
}

输出的四列足以支撑第一轮判断:类型、包名、版本、来源地址。实际落地时通常还会补上三样东西——integrity 是否存在、该包上一次出现在历史锁文件里是什么时候、引入它的父依赖是谁。前三列是机械可得的,第四项需要顺着依赖树往上找,而这一项恰恰是人工复核最需要的上下文。

顺带提一句版本影响:这段脚本依赖锁文件的内部结构,lockfileVersion 升级、包管理器切换、monorepo 里 packages 键的组织方式变化,都可能让它静默给出空结果。稳妥的做法是让它先输出条目总数,与 npm ls --all 的实现数量做一次粗对照,数量对不上就报错退出,而不是继续往下判定。

区分直接依赖与传递依赖的意义

这不是分类洁癖,它决定了谁能对变更负责。

直接依赖新增,说明有人(或某个助手)主动挑了它。这种情况下有一个可以追问的对象:为什么选它、有没有比较过替代方案、维护状态如何。传递依赖新增没有人主动挑选,它是上一个选择的副产物。对它的判断不应落在"为什么选它",而应落在"它为什么出现在这里、来源是否可靠、有没有更小的替代路径"。

一个常见的坑是把两者放进同一个阻断规则。结果是每个直接依赖升级都会因为某个传递依赖的元数据不达标而被拦,评审者逐渐学会直接无视阻断信息。反过来,如果完全不管传递依赖,上周那个换过维护者的包就会一路绿灯进生产。

核验来源与维护状态

锁文件条目里的 resolved 告诉你包管理器准备从哪下载,integrity 告诉你下载后拿什么核对字节。这两者能回答"我拿到的是不是预期内容",但回答不了"预期内容本身值不值得信任"。前者是完整性,后者是来源判断,两者不能互相替代。

来源核验至少应覆盖三点。其一,resolved 的主机是否在允许的 registry 列表里,git 地址、文件路径、内网镜像、http:// 都应作为独立事件上报。其二,integrity 字段是否存在且算法可接受;缺失不直接等于恶意,但说明这条记录没有可核对的字节依据。其三,包元数据是否自洽:发布历史、维护者数量、仓库链接能否与包名对应上、最近的发布是否过于密集。

对传递依赖来说,这层核验尤其重要,因为它通常不在任何人的关注列表里。有几个信号值得看,但它们都只是需要解释的信号,不是判决:包龄很短、周下载量极低、维护者近期变更、仓库链接指向个人仓库、名字与流行包高度相似。所有这些都可能在合法场景下出现——内部私有 registry 上的基础库下载量常年为零,一个小而专的工具包也可能刚发布三天。因此例外需要能按 scope、registry 和包名精确记录,而不是一个全仓库开关。

人工复核可疑包时,比较省时间的顺序是:先看 resolved 是不是预期 registry,再看包里有没有安装期执行的脚本,再看这个包在依赖树里由谁引入、能不能换成已经批准过的替代品。三项都过了,再回到版本和功能本身。

锁文件一致性与构建回归

npm ci 在清单与锁文件不一致时会直接失败,不会替你修改锁文件。这是成本最低、也最该先上的一道检查。它的局限同样明确:只能确认两者对得上,不能确认内容有问题。流水线里如果用 npm install 代替,它会容忍不一致并顺手改写锁文件,等于把"哪个包进来了"这个问题直接抹掉。yarn 和 pnpm 有对应的冻结安装模式,Python 侧则需要先有哈希锁定的依赖文件才有类似效果。

第二道是构建产物回归。做法是在不改变构建命令的前提下,为升级前的产物保存一份基线,比如打包结果的哈希清单或文件列表,升级后逐项对比。能归结到某个依赖变化上的差异可以接受;无法解释的差异应停下来,而不是当成噪声忽略。

纵向三层孔径递变的筛网,颗粒按大小被不同层级拦截或放行

分级阻断与例外到期

门禁设计成三档比一刀切耐用得多。

阻断类应当没有商量余地:resolved 指向非白名单来源、integrity 校验失败、命中撤回或恶意通告、清单与锁文件不一致、出现绕过安装脚本限制的尝试。这些事件本身就说明状态异常,不需要人工解释。

需人工审批类适合直接依赖新增。审批不是走形式,而是在 PR 上留一条记录:谁批准、依据是什么、包龄和维护状态如何。这条记录在半年后排查问题时比任何扫描报告都有用。

标记观察类适合元数据全部落在阈值内的传递依赖新增。门禁不拦,但会把它写进本次构建附带的依赖变更摘要里,让评审的人至少知道有这么个东西进来了。

例外机制要有到期时间。配置里记录包名、适用范围、原因、审批人和到期日,到期后门禁回到默认策略。如果例外只写"临时"三个字而没有日期,它很快就会变成永久的白名单条目。到期机制本身也需要被测试——至少在一次演练里确认过期例外确实会让门禁重新变红。

回滚已合并的依赖变更

门禁做得再好,也会有漏过去的时候。回滚步骤应当提前写进 runbook,而不是临时想办法。

第一步,把 manifest 和锁文件恢复到变更前的提交,整体还原,不要只删掉那一行声明;只删声明会让锁文件里残留传递依赖条目,下一次安装时行为不可预期。第二步,重新安装并确认锁文件没有被缓存改写。第三步,如果构建缓存以锁文件哈希为键,回滚后需要清理对应缓存,否则可能命中上次构建的产物。第四步,检查被移除包有没有执行过安装期脚本、有没有写入过缓存目录或运行时目录,这部分不会随卸载自动恢复。

有条件的话,在合并前对这个 PR 做一次锁文件回滚演练,确认回滚后的构建产物与基线一致。这比事后猜测便宜得多。

适用范围与边界

这套方法对 npm、pnpm、yarn 最直接,因为它们有明确的锁文件和完整性字段。Python 需要先有哈希锁定的依赖文件,requirements.txt 加 --hash 或相应工具生成的锁文件都可以,但生态里没有统一标准。Go 的 go.sum 和 Rust 的 Cargo.lock 侧重内容校验,不判断下载来源是否可接受,来源判断需要额外一步。

单一扫描器回答的是"这个包是否已知有问题",不回答"这个包是谁选的、为什么在这里"。把它当成完整供应链方案,就会重新回到那条绿色流水线的问题上:每个检查都完成了自己的工作,但没有一个检查对应最该回答的那个问题。

最后一点是版本影响。锁文件结构、包管理器行为、安装脚本的默认策略都会随版本变化,门禁里引用的解析逻辑应当和 CI 镜像的版本绑定在一起做验证,而不是在两套版本上各跑各的。先在观察模式跑一两周,把误报统计出来,再收紧阻断规则——这比一次上齐所有检查然后被迫关掉一半要省事得多。

 
枫少@KillBoy
评论  9  访客  9
    • 感恩的麦穗
      感恩的麦穗 1

      传递依赖没人挑,确实容易漏

      • 代码吟游
        代码吟游 1

        误报太多会不会变成摆设

        • 镜中影
          镜中影 1

          例外带到期日这点很对

          • 落霞生
            落霞生 0

            最近就被锁文件几百行吓到

            • 墨中魂
              墨中魂 2

              绿灯不等于来源可信啊

              • 空城夜
                空城夜 1

                先观察一两周再收紧比较稳

                • 镜中梦
                  镜中梦 0

                  npm ci 这关应该先上

                  • 风之旅者
                    风之旅者 1

                    小工具包刚发布会不会被拦

                    • 寂静的夜风
                      寂静的夜风 2

                      回滚还要清缓存,挺真实

                    匿名

                    发表评论

                    匿名网友

                    拖动滑块以完成验证