tartinerlabs/lockfile-integrity
GitHub: tartinerlabs/lockfile-integrity
检测 PR 中 lockfile 是否在没有 package.json 变更的情况下被修改，及时发现供应链篡改信号。
Stars: 1 | Forks: 0
# Lockfile 完整性检查
**你的 lockfile 改变了，但 `package.json` 没变。为什么？**
这是一个零依赖的 GitHub Action，用于检测 Pull Request 中可疑的 lockfile 修改，这类修改通常会逃过代码审查，从而为供应链攻击打开大门。
支持 `pnpm-lock.yaml`、`package-lock.json`、`yarn.lock` 和 `bun.lock`。
## 问题所在
仅修改 Lockfile 是 npm 供应链攻击中最容易被忽视的途径之一。攻击者（或受损的 CI 步骤）可以直接向 lockfile 中注入恶意包解析。由于 lockfile 的差异（diff）通常很大且杂乱，审查者很少会逐行检查它们。
此 Action 让那些不可见的变化变得可见，并在有人解释清楚之前阻止 PR 合并。
## 工作原理
```
PR opened
|
v
git diff origin/main...HEAD
|
|__ lockfile changed?
| |
| |__ package.json also changed? --> Pass (legitimate dependency update)
| |
| |__ package.json untouched? --> Fail with annotation (possible tampering)
|
|__ no lockfile changed? --> Skip (nothing to check)
```
## 快速开始
```
name: Lockfile Integrity
on:
pull_request:
paths:
- pnpm-lock.yaml
- package-lock.json
- yarn.lock
- bun.lock
permissions:
contents: read
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 0 # Required: the action diffs against the base branch
- uses: tartinerlabs/lockfile-integrity@v1
with:
base-ref: ${{ github.base_ref }}
```
就这样。该 Action 会自动检测哪些 lockfile 发生了变化。无需配置。
### 指定特定的 Lockfile
如果你的仓库使用单一的包管理器，你可以明确指定：
```
- uses: tartinerlabs/lockfile-integrity@v1
with:
base-ref: ${{ github.base_ref }}
lockfile: pnpm-lock.yaml # or package-lock.json, yarn.lock, bun.lock
```
### 警告而非失败
适用于渐进式推广。为 PR 添加注释但不阻止合并：
```
- uses: tartinerlabs/lockfile-integrity@v1
with:
base-ref: ${{ github.base_ref }}
fail-on-warning: "false"
```
### 在后续步骤中使用输出
```
- uses: tartinerlabs/lockfile-integrity@v1
id: integrity
with:
base-ref: ${{ github.base_ref }}
fail-on-warning: "false"
- if: steps.integrity.outputs.tampered == 'true'
run: echo "Suspicious lockfiles: ${{ steps.integrity.outputs.lockfiles }}"
```
## 输入参数
| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `base-ref` | Yes | | 用于比较的基础分支（例如 `main`） |
| `lockfile` | No | _(自动检测)_ | 要监控的 Lockfile；省略时从更改的文件中自动检测 |
| `fail-on-warning` | No | `true` | 是失败检查还是仅发出警告 |
## 输出
| Output | Description |
|--------|-------------|
| `tampered` | 如果检测到 lockfile 篡改则为 `"true"`，否则为 `"false"` |
| `lockfiles` | 被修改的 lockfile 列表，以空格分隔 |
## 要求
Checkout 步骤**必须**使用 `fetch-depth: 0`，以便 Action 能与基础分支进行差异比较。否则，Git 历史记录将不可用，检查将失败。
## 常见问题
**这能捕获所有供应链攻击吗？**
不能。这只捕获一个特定的信号：仅 lockfile 发生变化。它是一个轻量级的触发器，而不是完整的依赖审计。请将其与 `npm audit`、Socket 或 Snyk 等工具结合使用以进行更深入的分析。
**如果我故意重新生成 lockfile 怎么办？**
在同一个 PR 中触碰一下 `package.json`（即使是仅包含空白的更改也算数），检查就会通过。或者使用 `fail-on-warning: "false"` 来获取警告注释而不是硬性失败。
**它适用于 Monorepo 吗？**
是的。该 Action 会检查仓库中*任何* `package.json` 是否发生更改，因此由工作区依赖项更改引起的 lockfile 更新将通过检查。
## 许可证
[MIT](LICENSE)
标签：Bun, CI/CD 安全, DevSecOps, GitHub Actions, Lockfile 完整性, NPM 安全, pnpm, PR 检查, Yarn, 上游代理, 云安全监控, 代码审查, 依赖劫持检测, 前端安全, 包管理器, 安全可观测性, 数据可视化, 数据投毒防御, 文档安全, 注入攻击防护, 版本控制, 篡改检测, 结构化查询, 统一API, 网络安全研究, 自动化安全, 自动笔记, 软件开发工具包, 静态分析