jamesdfinance-dev/lazaretto-scan-action
GitHub: jamesdfinance-dev/lazaretto-scan-action
一个 GitHub Action，在 CI 中自动检测 lockfile 锁定的依赖版本是否为已知恶意软件包，命中即令构建失败。
Stars: 0 | Forks: 0
# Lazaretto Scan (GitHub Action)
当您实际锁定的依赖项是已知的恶意软件时，使构建失败。
该 action 会读取您的 lockfile，并将每个锁定的版本与已发布的恶意软件包公告（OSV / OpenSSF）进行比对。**该检查是免费的，不需要 API key，并且只需一次请求即可扫描您的整个依赖树。** 此外，还提供可选的深度行为扫描，适用于您希望进行分析而非仅仅识别的 artifact。
这能捕获实际发生的情况：`chalk@5.6.1`、`debug@4.4.2` 和 `@ledgerhq/connect-kit@1.1.6` 都曾是合法且被广泛使用的软件包的受损版本。它们的干净版本位于恶意版本的前后，因此，您的 lockfile 中的版本决定了您是否会受到影响。
## 快速开始
无需配置任何 secret。添加以下内容，如果存在恶意锁定，则会导致构建失败：
```
name: Lazaretto
on:
pull_request:
paths: ['package-lock.json', 'yarn.lock', 'pnpm-lock.yaml']
permissions:
contents: read
pull-requests: write # so the action can post its comment
jobs:
deps:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: jamesdfinance-dev/lazaretto-scan-action@v1
```
支持自动检测的 lockfile：`package-lock.json`、`npm-shrinkwrap.json`、`yarn.lock`（v1 和 Berry）、`pnpm-lock.yaml`（v5、v6、v9）。
## 添加深度行为扫描
lockfile 检查回答了“这个包是否是已知的恶意软件”。而深度扫描回答了“这个 artifact 实际上做了什么”：凭证访问、数据泄露、代码混淆、安装脚本、针对 agent 的提示注入，并附带每个信号的文件和行号。该部分消耗 credits，因此需要 key。
```
- uses: jamesdfinance-dev/lazaretto-scan-action@v1
with:
api-key: ${{ secrets.LAZARETTO_API_KEY }}
```
有了 key 且没有明确指定 `targets` 的情况下，该 action 会对 `package-lock.json` 中确切版本的**直接**依赖项进行深度扫描。您也可以自己指定目标：
```
- uses: jamesdfinance-dev/lazaretto-scan-action@v1
with:
api-key: ${{ secrets.LAZARETTO_API_KEY }}
targets: |
npm_package:left-pad@1.3.0
github_repo:some-org/some-skill
```
获取免费的开发者 key（每日扫描配额，无需注册，无需绑定信用卡）：
```
curl -s -X POST https://lazaretto.dev/v1/trial # returns an api_key
```
将其存储为仓库 secret。如需满足 CI 的调用量，请在 https://lazaretto.dev/#pricing 购买容量包。Agent 也可以通过 x402 按次调用付费。
## 报告内容
在 Pull Request 中，该 action 会发布一条置顶评论（创建一次，每次运行时更新），并且始终会写入一份作业摘要。两者都会显示哪些锁定版本是已知的恶意软件，并附带指向公告的链接；如果运行了深度扫描，还会显示每个目标的判定结果和 `risk` 风险级别。
设置 `comment: false` 可关闭评论。
## 输入项
| 输入项 | 默认值 | 描述 |
| --- | --- | --- |
| `lockfile` | `auto` | 要检查的 lockfile。`auto` 会在工作区根目录查找常见的文件名。设置为 `""` 可跳过。不需要 API key。 |
| `api-key` | (无) | 用于可选的深度行为扫描的 key。lockfile 检查不需要。 |
| `targets` | (无) | 用于深度扫描的 `type:ref` 换行列表。`type` 可以是 `npm_package`、`github_repo`、`clawhub_skill` 或 `raw_url`。 |
| `package-json` | `package.json` | 当 `targets` 为空时，深度扫描覆盖的直接依赖项。版本号来源于 lockfile。 |
| `fail-on` | `malicious` | 在此级别使构建失败：`malicious`、`flagged` 或 `never`。 |
| `comment` | `true` | 在 PR 上发布/更新置顶评论（需要 `pull-requests: write` 权限）。 |
| `github-token` | workflow token | 用于发布评论的 token。 |
| `base-url` | `https://lazaretto.dev` | API 的基础 URL。 |
## 输出项
| 输出项 | 描述 |
| --- | --- |
| `malicious-count` | 发现为已知恶意软件的锁定版本数量。 |
| `worst-verdict` | 最差的深度扫描判定结果，如果未运行深度扫描则为 `unscanned`。 |
## 不涵盖的范围
除了设置为 `never` 之外，在任何 `fail-on` 级别下，命中已知恶意软件都会导致构建失败：这是明确指向特定版本的已发布公告，而不是启发式推断。
其他所有内容都如实报告，绝不盲目乐观：
- 我们无法检查的版本会单独列出。只有当未验证栏中没有任何内容时，空的恶意列表才意味着一切正常。
- 没有发布身份的条目（`file:`、`link:`、`workspace:`、git）会被计为跳过并显示名称，因为“我们检查了您的 1432 个条目中的 1325 个”和“您是干净的”是两回事。
- 如果服务无法访问，该步骤会发出明显的警告，并且不会导致您的构建失败，但它也不会报告通过。
- 仅检查确切的版本。像 `^5.0.0` 这样的范围没有准确的答案，因为受损的版本通常位于干净版本之间。
`clear` 表示没有匹配到已知的恶意特征，也没有触发规则。这并不代表该包没有任何风险。
## 费用
lockfile 检查是免费且不限量的（按 IP 进行速率限制）。只有可选的深度扫描会消耗 credits，每次运行每个目标消耗一个。如快速开始中所示，将作业的触发条件设置为 lockfile 更改，这样它只会在内容发生更改时运行。
## 许可证
MIT。Lazaretto 服务及其检测引擎是独立的且专有的。
标签：GitHub Action, MITM代理, Syscall 审计, 依赖安全, 暗色界面