依赖混淆(Dependency Confusion)是一种不需要漏洞的供应链攻击:攻击者不去破解你的仓库,而是把内部包名抢注到公共源上,再发布一个版本号更高的同名包。构建时解析器按「版本更高者优先」的规则选中了公网那个包,CI 流水线就亲手把攻击者的代码装进了生产环境。本文从命名空间收口、私有源拓扑、解析顺序校验到 CI 门禁,给出一套可直接落地的配置方案。
适用场景
以下条件同时成立时,团队已经具备被依赖混淆命中的完整前提:
- 内部包使用了通用单词命名,如
utils、common、auth-sdk、logging,且从未在公共源注册; - 构建配置里同时存在私有源与公共源,例如 pip 的
index-url加extra-index-url,或 NuGet 配了多个packageSources; - CI 流水线使用动态版本范围(
^1.0.0、>=2.0),没有提交 lockfile; - 开发者本机能直连公网源,本地
npm install与 CI 走的不是同一套源配置; - 内部包名、版本号会出现在前端产物、开源仓库或错误堆栈里,外部可被动收集。
只要满足两条以上,就应当把「包名收口」排进本季度整改,而不是等到某次构建异常再去排查。
前置条件
- 已部署私有制品库(Nexus 3、Artifactory 或云厂商制品仓库),并能按 hosted / proxy / group 三种仓库类型配置;
- Node.js 不低于 16.x,npm 不低于 8.x;Python 不低于 3.9,pip 不低于 23.x;
- CI 具备注入凭据的能力(
NPM_TOKEN、PIP_INDEX_URL),可区分「读源」与「发版」两类权限; - 有权限修改
.npmrc、pip.conf、nuget.config等解析配置文件,并能推动全量仓库改造; - 准备一份内部包清单(名称、维护人、被依赖项目),用于后续逐个确认命名归属。
原理说明
攻击成立需要三个条件同时满足:内部包名在公共源上未被占用、解析器会同时查询多个源、且选择逻辑按版本号择优而不区分来源。三者缺一,攻击就不成立,这也正好对应三条防御路径。
不同生态的解析行为差异很大,必须分清。npm 对未加 scope 的包名只认一个 registry,由 .npmrc 的 registry 决定,本身不会「多源择优」;风险来自内部包名被他人抢注后,某个环境把 registry 指向了公网,或者依赖树里的传递依赖引用了同名包。pip 则是典型的多源合并:index-url 与 extra-index-url 会一起进候选集,然后统一按版本号排序取最高,完全不管这个版本来自哪个源——这是依赖混淆最经典的命中方式。NuGet 同样会把多个 packageSources 的候选合并后择优。
因此防御的核心不是「把私有源配得更快」,而是让解析入口唯一:所有依赖只从一个入口取,入口内部再决定去哪找。具体做法有两条。第一条是命名空间隔离:内部包统一加 @公司名/ 前缀(npm scope)或项目前缀(Python 用 corp-),scope 在 npm 里强制绑定到指定 registry,公网无法解析该 scope 下的包。第二条是源聚合:私有库上建一个 group 仓库,把内部 hosted 与公共 proxy 组合成一个地址,客户端只配这一个地址,多源择优的问题在服务端就被消解了。
还有一条容易被忽略:lockfile 与哈希锁定。它能防住「解析结果被替换」,但防不住「第一次解析就选错」。所以 lockfile 是必要非充分条件,真正的第一道防线仍是命名空间与单一入口。
操作步骤
第一步:清点包名并探测公网占用情况
先确定哪些内部包名暴露在公共源上,这是判断风险面最直接的方式:
# 逐个检查内部包名是否已被公共源占用(0 表示未被占用,风险最高)
for name in utils common auth-sdk internal-logging; do
code=$(curl -s -o /dev/null -w "%{http_code}" "https://registry.npmjs.org/$name")
echo "npm $name HTTP $code"
done
for name in corp-utils corp-auth; do
code=$(curl -s -o /dev/null -w "%{http_code}" "https://pypi.org/pypi/$name/json")
echo "pypi $name HTTP $code"
done
# 同时确认 CI 实际使用的源(这一步经常发现和本地不一致)
npm config get registry
pip config list
404 意味着这个名字在公网是空位,任何人都能注册;200 意味着已被占用,需要进一步确认占用者是不是自己人。把两类结果分别记录:前者必须改名为带前缀的形式,后者要核对维护者身份,避免出现「名字被注册了但没人认领」的情况。
第二步:npm 侧用 scope 收口
把内部包全部迁移到 @公司名/ 之下,并在仓库级 .npmrc 里把 scope 与私有源硬绑定:
# 项目根目录 .npmrc:scope 绑定私有源,默认源也指向私有 group
@corp:registry=https://nexus.corp.local/repository/npm-hosted/
registry=https://nexus.corp.local/repository/npm-group/
//nexus.corp.local/repository/npm-group/:_authToken=${NPM_TOKEN}
//nexus.corp.local/repository/npm-hosted/:_authToken=${NPM_TOKEN}
always-auth=true
strict-ssl=true
# 迁移内部包名:package.json 里 name 改为 @corp/xxx,并发布到 hosted 仓库
npm publish --registry=https://nexus.corp.local/repository/npm-hosted/
# 客户端验证:解析结果必须落在私有域名上
npm view @corp/utils --json | jq -r '.dist.tarball'
npm config get @corp:registry
@corp:registry 这一行是硬约束:npm 遇到该 scope 的包时只会去这个地址找,公网源根本不会参与候选。相比之下,仅配置全局 registry 是不够的,因为一旦某个环境的配置被覆盖(例如镜像脚本、CI 变量),未加 scope 的包就会跟着走。所以「改 scope」不是洁癖,而是把解析路径写死在包名里。
第三步:在私有库上做源聚合
私有库里建三类仓库,客户端只拿 group 地址:hosted 存内部包,proxy 代理公共源并缓存,group 把两者组合。group 成员的顺序决定了同名包的优先级,把 hosted 放在第一位:
# 只读校验:确认 group 成员顺序与客户端实际地址(Nexus 3 管理 API)
curl -s -u admin:"$NEXUS_PASS" \
"https://nexus.corp.local/service/rest/v1/repositories" |
jq -r '.[] | select(.format=="npm") | [.name,.type,.online] | @tsv'
# 校验 group 的成员顺序:hosted 必须排在 proxy 之前
curl -s -u admin:"$NEXUS_PASS" \
"https://nexus.corp.local/service/rest/v1/repositories/npm/group/npm-group" |
jq -r '.group.memberNames[]'
# 客户端侧最终确认:同一个包从 group 取,落点必须是 hosted
curl -sI "https://nexus.corp.local/repository/npm-group/@corp%2futils" \
-H "Authorization: Bearer $NPM_TOKEN" | grep -i -E "HTTP|x-nexus-repository-name"
x-nexus-repository-name 响应头会直接告诉你这个包是从哪个成员仓库取到的,这是排查「被 proxy 抢答」最快的手段。需要注意,不同 Nexus 版本对 group 内同名包的处理顺序存在差异,升级后必须重新跑一遍这条验证,不能假设配置没动就行为不变。
第四步:pip 侧收敛为单一索引
Python 生态是依赖混淆的重灾区,原因就是 extra-index-url 会与主索引合并择优。正确做法是只配一个索引地址,由私有库在服务端代理公共源:
# /etc/pip.conf 或 ~/.config/pip/pip.conf
[global]
index-url = https://nexus.corp.local/repository/pypi-group/simple
trusted-host = nexus.corp.local
timeout = 30
retries = 3
# 禁用用户级配置,防止个人 ~/.pip/pip.conf 覆盖企业配置
PIP_CONFIG_FILE=/etc/pip.conf
# 验证:输出里应只有一个索引地址,不应出现 pypi.org
pip config list
pip download --no-deps --dest /tmp/probe corp-auth -v 2>&1 | grep -i "looking in indexes"
# 需要哈希锁定时(推荐在 CI 中使用)
pip install --require-hashes -r requirements.txt
如果因为网络原因必须保留公网源,也不能写成两个 index-url。可行做法是:内部包统一加 corp- 前缀并在私有源上做 hosted,公共包通过 proxy 缓存,两者在 group 里合并,客户端只见一个地址。这时候即使公网有人抢注了 corp-auth 的高版本,客户端也压根不会去公网查询这个名字。
第五步:CI 门禁拦截异常来源
配置改完之后,还需要一道自动检查,防止有人偷偷改回多源或提交了指向公网的 lockfile:
import json, sys, urllib.parse
ALLOW = {"nexus.corp.local", "registry.npmjs.org"}
SCOPED = "@corp/"
lock = json.load(open("package-lock.json", encoding="utf-8"))
bad = []
for path, meta in lock.get("packages", {}).items():
url = meta.get("resolved")
if not url or not path:
continue
host = urllib.parse.urlparse(url).hostname
name = meta.get("name", path.split("node_modules/")[-1])
if name.startswith(SCOPED) and host != "nexus.corp.local":
bad.append((path, host, "scope 包必须来自私有源"))
elif host not in ALLOW:
bad.append((path, host, "未知来源"))
for item in bad:
print("[BLOCK]", *item)
print(f"检查 {len(lock.get('packages', {}))} 个依赖,异常 {len(bad)} 个")
sys.exit(1 if bad else 0)
这个脚本要放进 CI 的 pre-install 阶段,失败即中断构建,而不是发一条告警。Python 侧对应的检查是 requirements.txt 中每个包都必须带 --hash,配合 --require-hashes 使用;一旦有人手工加了不带哈希的依赖,安装阶段就会直接报错。
配置验证
整改后用下面几条命令做回归,重点看「解析落点」而不是「能不能装上」:
# 1) npm:内部包只从私有源解析,公网包经 group 缓存
npm config get @corp:registry
npm view @corp/utils dist.tarball
npm view lodash dist.tarball # 应从 group 地址返回,而非 registry.npmjs.org
# 2) pip:确认只有一个索引,且内部包命中私有源
pip config list | grep index-url
pip index versions corp-auth 2>/dev/null | head -3
# 3) 模拟攻击:在临时目录用公网源装同名包,观察是否被私有源优先拦截
mkdir -p /tmp/dc-test && cd /tmp/dc-test
npm init -y >/dev/null && npm install @corp/utils --dry-run
# 4) 复跑门禁脚本,应输出 0 个异常
python3 ci_check_lockfile.py
第 3 条是关键验证:--dry-run 不会真的写入文件,但会把解析结果打印出来,从中可以直接看到 GET https://nexus.corp.local/... 这样的请求地址。如果出现对公共源的请求,说明 scope 配置没有生效,需要回头检查 .npmrc 是否被更高优先级的配置覆盖(项目级 > 用户级 > 全局级)。
常见问题
内部包必须发布到公网源才能被外部合作方使用吗?
不需要,也不建议。对外交付走「源码包 + 私有源只读令牌」的方式更可控:给合作方发一个只读 token,限定只能拉取指定 scope,令牌可随时吊销并带审计日志。把内部包发到公共源等于永久放弃命名控制权,一旦未来有人在同名下发布恶意版本,你连申诉下架都要走流程。
已经提交了 lockfile,为什么还是有风险?
lockfile 只固定「上次解析的结果」,不校验「这个结果是否合理」。如果 lockfile 是在某台配置了公网源的机器上首次生成的,里面记录的 resolved 就是公网地址,后续 npm ci 会忠实复现这个错误结果。所以判断是否安全,要看 lockfile 里的域名,而不是看有没有 lockfile。前面那个门禁脚本干的就是这件事。
私有库的 group 里 hosted 排第一,为什么还取到了公网版本?
三个常见原因:客户端配置的其实是 proxy 仓库地址而不是 group 地址;缓存里已经存在该包的公网副本,group 命中缓存后直接返回;或者包名大小写、编码不一致(如 @corp%2futils 与 @corp/utils)导致查询走了另一条路径。排查时优先看响应头 x-nexus-repository-name,它会明确告出实际命中的成员仓库。
迁移 scope 会不会打断现有构建?
会,而且影响面不小。稳妥做法是双写过渡:新包名 @corp/xxx 与旧名同时在 hosted 上发布,旧名加 deprecated 标记并在描述里写明迁移期限;同时在 group 上为旧名建一条别名路由,保证未改造的项目仍能构建。等依赖清单全部切换完成后,再统一删除旧名,避免出现「改了一半、两边都装不上」的中间态。
总结
依赖混淆的本质是「名字的所有权」与「解析的入口」两件事同时失控。修复也不需要复杂工具:把内部包名收进 scope、把客户端入口收敛成唯一地址、把命名空间在公共源上占住,攻击者就失去了插入点。剩下的事情交给自动化——lockfile 检查拦住来源异常,哈希锁定拦住内容替换,CI 门禁保证这三个约束不会在某个深夜被临时改回去。供应链安全做到最后,拼的不是检测能力,而是这些看起来琐碎、但必须全员遵守的配置纪律。