trustlock

一个原生集成的 Git 依赖准入控制器。在每次依赖变更时评估信任信号。

工作原理

trustlock 作为 Git 预提交钩子（建议模式）和 CI 检查（强制模式）运行：

• 建议模式（预提交）： 对违规发出警告，退出码为 0，当所有包均被准入时推进信任基线。
• 强制模式（--enforce）： 阻止违规，退出码为 1，永不推进基线。

每个包评估的信任信号：

• 冷却期 — 版本发布到注册表后经过的时间
• 来源证明 — 包是否具有 SLSA 证明
• 版本固定 — 锁定文件是否使用精确版本
• 安装脚本 — 包是否运行安装时脚本
• 来源 — 包来自注册表、Git URL、本地路径还是 URL
• 新增依赖 — 首次添加到项目的依赖
• 传递性意外 — 传递依赖数量的意外跳增
• 发布者变更 — 包在不同版本间的发布者身份是否改变

安装

npm install -g trustlock

需要 Node.js >= 18.3。

支持的锁定文件

快速开始

工作流 1 — 项目初始化

# 1. 在项目中初始化 trustlock
trustlock init

# 2. 安装 Git 预提交钩子
trustlock install-hook

# 3. 可选：审查当前依赖状态
trustlock audit

执行 init 后，trustlock 创建：

• .trustlockrc.json — 策略配置
• .trustlock/baseline.json — 受信任的依赖快照
• .trustlock/approvals.json — 审批记录
• .trustlock/.cache/ — 注册表缓存（已加入 gitignore）

将 .trustlockrc.json 和 .trustlock/baseline.json 提交到你的仓库。

工作流 2 — 检查并准入依赖更新

# 正常执行依赖安装
npm install [email protected]

# trustlock check 通过预提交钩子自动运行。
# 如需手动运行：
trustlock check

# 当所有包都通过时的输出：
# ✔ [email protected] — 已准入

当所有包都通过时，trustlock check 会自动推进基线（仅建议模式）并退出码为 0。

工作流 3 — 处理被阻止的依赖

# 新包未通过冷却期规则：
trustlock check
# ✖ [email protected] — 被阻止
#   exposure:cooldown  发布于2小时前（策略要求72小时）
#   运行以下命令以批准：trustlock approve [email protected] --override cooldown --reason "..." --expires 7d

# 批准覆盖，然后重新检查：
trustlock approve [email protected] \
  --override cooldown \
  --reason "特性X所需；经团队审查确认为安全" \
  --expires 7d

trustlock check
# ✔ [email protected] — 已通过审批准入

工作流 4 — 比较项目间的依赖状态

# 检测单体仓库中各包的版本漂移和来源证明不一致
trustlock audit --compare packages/frontend packages/backend packages/shared

命令

策略配置

trustlock 内置了两个配置文件，可通过 --profile 选择：

# 在CI中使用严格配置
trustlock check --enforce --profile strict

组织策略继承

团队可以将策略集中托管在一个共享URL，并在各仓库中扩展：

{
  "extends": "https://policy.example.com/trustlockrc.json",
  "cooldown_hours": 96
}

仓库配置只能收紧组织策略——底层执行机制阻止仓库降低组织强制要求的最低阈值。

文档

• USAGE.md — 完整命令参考，所有标志、退出码、错误信息
• POLICY-REFERENCE.md — 所有 .trustlockrc.json 选项
• ARCHITECTURE.md — 设计决策和模块映射
• examples/ — 配置和CI工作流示例

CI 集成

将 trustlock 添加到你的 CI 流水线：

# GitHub Actions — 参见 examples/ci/github-actions.yml
- run: npx trustlock check --enforce

参见 examples/ 获取 GitHub Actions、Lefthook 和 Husky 的配置。

trustlock 在时间线中的位置

Trustlock 在提交时评估锁定文件变更。它不会拦截或沙盒化 npm install。如果一个恶意包运行了 postinstall 脚本，该脚本会在 trustlock 看到它之前执行。Trustlock 阻止了被篡改的锁定文件被提交和合并，从而将影响范围限制在单个开发者机器上，而非整个团队和生产环境。如需阻止安装时脚本运行，请使用 --ignore-scripts 或 pnpm 默认的生命周期脚本控制。

trustlock 不做的事情

• 不是恶意软件扫描器 — trustlock 不检查包的源代码或检测已知恶意签名。请使用专门的扫描工具。
• 不是安装时沙盒 — trustlock 不拦截 npm install。请使用 --ignore-scripts 实现此目的。
• 不是 CVE 追踪器 — 请使用 npm audit 或 Snyk 进行漏洞数据库查询。
• 不是许可证检查器 — 请使用 license-checker 或类似工具。
• 不是 pnpm trustPolicy 或 npm min-release-age 的替代品 — 这些是注册表强制执行的服务器端控制。trustlock 是仓库边界处的客户端准入控制。

关于

trustlock 的诞生源于对标准 Node.js 工具链在实际上被拉入项目的内容上过于被动的失望。npm install 会拉取任何内容——两分钟前发布的包、在安装时运行任意脚本的包、一夜之间从注册表压缩包切换为 Git URL 的包——而你得到的唯一反馈只是一个锁定文件差异。

trustlock 处理的威胁模型虽然狭窄但真实存在：即恶意版本发布到被移除或标记之间的时间窗口。漏洞扫描器在事后操作，而 trustlock 在准入点操作，在内容进入你的仓库或 CI 之前就进行控制。

设计上刻意保持最小化。trustlock 没有运行时依赖——它本身就是一个零供应链风险的工具。它不替代漏洞扫描器或依赖审计；它强制信任连续性。一旦一个版本进入基线，它就是受信任的。任何新内容都必须根据你声明的策略争取准入。

审批工作流是为需要逃生舱口但不失去可审计性的团队准备的。每个覆盖都有时间戳、限定在特定规则范围内，并会过期。clean-approvals 是一等命令，而非事后考虑。