tayyabt/trustlock

# trustlock 适用于 npm、pnpm、yarn 和 Python 项目的依赖准入控制器。trustlock 评估依赖变更的信任信号，并根据声明的策略做出二元的准入/阻止决策 —— 在这些变更进入 CI 或被提交之前。 ## 工作原理 trustlock 作为 **Git pre-commit hook**（建议模式）和 **CI check**（强制模式）运行： - **建议（pre-commit）：** 在违规时发出警告，以退出码 0 退出，当所有包都被准入时推进受信任的基线。 - **强制（`--enforce`）：** 在违规时阻止，以退出码 1 退出，永不推进基线。 针对每个包评估的信任信号： - **Cooldown（冷却期）** —— 版本发布到注册表后的时间长短 - **Provenance（来源）** —— 包是否具有 SLSA 证明 - **Pinning（锁定）** —— lockfile 是否使用精确版本 - **Install scripts（安装脚本）** —— 包是否在安装时运行脚本 - **Sources（来源）** —— 包是来自注册表、git URL、本地路径还是 URL - **New dependencies（新依赖）** —— 首次添加到项目 - **Transitive surprise（传递依赖激增）** —— 传递依赖数量的意外激增 - **Publisher change（发布者变更）** —— 包的发布者身份在版本之间是否发生变化 ## 安装 ``` npm install -g trustlock ``` 需要 Node.js >= 18.3。 ## 支持的 lockfiles | Lockfile | Ecosystem | Versions | |----------|-----------|---------| | `package-lock.json` | npm | v1, v2, v3 | | `pnpm-lock.yaml` | pnpm | v5, v6, v9 | | `yarn.lock` | yarn | classic (v1), berry (v2/v3) | | `requirements.txt` | Python (pip) | — | | `uv.lock` | Python (uv) | — | ## 快速开始 ### 工作流 1 — 项目接入 ``` # 1. 在项目中初始化 trustlock trustlock init # 2. 安装 Git pre-commit hook 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 — 检查并准入依赖更新 ``` # 正常运行 dep install npm install lodash@4.17.21 # trustlock check 通过 pre-commit hook 自动运行。 # 要手动运行： trustlock check # 所有包被接纳时的输出： # ✔ lodash@4.17.21 — 已接纳 ``` 当所有包通过检查时，`trustlock check` 会自动推进基线（仅限建议模式）并以退出码 0 退出。 ### 工作流 3 — 处理被阻止的依赖 ``` # 新包未通过冷却规则： trustlock check # ✖ new-hotness@1.0.0 — 已阻止 # exposure:cooldown 2小时前发布（策略要求 72小时） # 运行以批准：trustlock approve new-hotness@1.0.0 --override cooldown --reason "..." --expires 7d # 批准覆盖，然后重新检查： trustlock approve new-hotness@1.0.0 \ --override cooldown \ --reason "Needed for feature X; verified safe by team review" \ --expires 7d trustlock check # ✔ new-hotness@1.0.0 — 已批准接纳 ``` ### 工作流 4 — 跨项目对比依赖状况 ``` # 检测 monorepo 包之间的版本漂移和来源不一致 trustlock audit --compare packages/frontend packages/backend packages/shared ``` ## 命令 | Command | Description | |---|---| | `trustlock init` | 在当前项目中初始化 trustlock | | `trustlock check` | 根据策略评估依赖变更 | | `trustlock approve @` | 准入一个被阻止的包 | | `trustlock audit` | 扫描完整的依赖树以评估信任状况 | | `trustlock audit --compare ` | 跨多个项目对比依赖状况 | | `trustlock clean-approvals` | 移除过期的准入条目 | | `trustlock install-hook` | 安装 Git pre-commit hook | ## 策略配置文件 trustlock 内置了两个通过 `--profile` 选择的配置文件： | Profile | Effect | |---------|--------| | `strict` | 168 小时冷却期，所有包均要求来源证明 | | `relaxed` | 24 小时冷却期，不因来源证明回退或发布者变更而阻止 | ``` # 在 CI 中使用 strict profile trustlock check --enforce --profile strict ``` ## 组织策略继承 团队可以在共享 URL 中集中管理策略，并按仓库进行扩展： ``` { "extends": "https://policy.example.com/trustlockrc.json", "cooldown_hours": 96 } ``` 仓库配置只能收紧组织策略 —— 基线强制执行可防止仓库降低组织要求的阈值。 ## 文档 - [USAGE.md](USAGE.md) — 完整的命令参考、所有标志、退出码、错误消息 - [POLICY-REFERENCE.md](POLICY-REFERENCE.md) — 每个 `.trustlockrc.json` 选项 - [ARCHITECTURE.md](ARCHITECTURE.md) — 设计决策和模块映射 - [examples/](examples/) — 配置和 CI 工作流示例 ## CI 集成 将 trustlock 添加到你的 CI 流水线中： ``` # GitHub Actions — 见 examples/ci/github-actions.yml - run: npx trustlock check --enforce ``` 请参阅 [`examples/ci/`](examples/ci/) 了解 GitHub Actions、Lefthook 和 Husky 的配置。 ## 关于 trustlock 的诞生源于对标准 Node.js 工具链在处理实际拉入项目内容方面过于被动的挫败感。`npm install` 会获取任何东西 —— 一个两分钟前发布的包、一个在安装时运行任意脚本的包、一个一夜之间从注册表 tarball 变为 git URL 的包 —— 而你得到的唯一反馈就是 lockfile diff。 trustlock 解决的威胁模型虽然狭窄但很真实：恶意版本发布与其被拉取或标记之间的时间窗口。漏洞扫描器是事后补救。trustlock 在准入点运作，在任何内容进入你的仓库或 CI 之前。 其设计刻意追求极简。trustlock 没有运行时依赖 —— 它本身就是一个零供应链风险工具。它并不取代漏洞扫描器或依赖审计；它强制执行信任的连续性。一旦某个版本进入你的基线，它就是受信任的。任何新内容都必须根据你声明的策略赢得准入。 批准工作流程是为那些需要紧急出口而又不想失去可审计性的团队准备的。每一次覆盖都有时间戳，作用于特定规则，并且会过期。`clean-approvals` 是一等公民命令，而非事后补救。

标签：DevSecOps, Git Hook, Homebrew安装, MITM代理, Npm, Pnpm, Pre-commit, Python, SLSA, Yarn, 上游代理, 依赖管理, 依赖锁定, 包管理, 安全可观测性, 安全合规, 无后门, 版本控制, 网络代理, 网络安全研究, 自动化检查, 自定义脚本, 跌倒检测, 软件物料清单