tiiuae/flakevuln

# Flakevuln 针对 Nix flakes 的 flake 无关漏洞扫描，同时打包为可复用的 GitHub Action 和本地 CLI。 `flakevuln` 推广了 [`ghafscan`](https://github.com/tiiuae/ghafscan)：保留了经过验证的克隆、针对不同的 nixpkgs pins 重新锁定，然后对比漏洞集引擎；舍弃了 Ghaf 特定的假设和提交回退状态模型；将结果渲染为 GitHub Actions Step Summary 和详细的本地 markdown 报告。 ## 功能 - 扫描来自已检出仓库或远程 flakeref 的一个或多个 flake 输出。 - 将提交的锁定状态与所选输入（默认为 `nixpkgs`）重新锁定后的基线进行对比。 - 可选针对显式的不稳定输入添加第三次扫描，例如 `github:NixOS/nixpkgs/nixos-unstable`。 - 输出机器可读的检查结果以及 markdown 报告。 - 在本地和 GitHub Actions 中复用相同的引擎。 - 在多次工作流运行之间持久化 `grype`、`vulnix`、`sbomnix` HTTP 缓存数据以及先前运行的基线结果。 ## GitHub Action 复合 Action 会安装 Nix，构建 `flakevuln`，运行不受信任的扫描阶段，然后在受信任的阶段渲染报告。 ### 最小化工作流 ``` name: flakevuln on: pull_request: workflow_dispatch: permissions: contents: read jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - uses: tiiuae/flakevuln@ with: targets: | packages.x86_64-linux.default ``` 在生产工作流中，建议将 Action 固定到完整的 commit SHA。 ### 带有可选输入的示例 ``` name: flakevuln on: workflow_dispatch: schedule: - cron: "17 3 * * 1" permissions: contents: read jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - uses: tiiuae/flakevuln@ with: targets: | packages.x86_64-linux.default devShells.x86_64-linux.default unstable-ref: github:NixOS/nixpkgs/nixos-unstable whitelist: path/to/manual_analysis.csv nixprs: true cachix-caches: nix-community my-org ``` ### 示例：扫描子目录中的 flake ``` name: flakevuln on: pull_request: permissions: contents: read jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0 - uses: tiiuae/flakevuln@ with: flakeref: ./services/api targets: | packages.x86_64-linux.default ``` 有关直接使用已检出 Action 源的仓库内示例，请参见 [example-scan.yml](.github/workflows/example-scan.yml)。 ### 输入 | 输入 | 必需 | 默认值 | 描述 | | --- | --- | --- | --- | | `targets` | 是 | - | 要扫描的换行符分隔的 flake 输出。 | | `flakeref` | 否 | `.` | 要扫描的 flake。`.` 表示已检出的工作区根目录；子目录也可以。 | | `input-name` | 否 | `nixpkgs` | 要进行对比的重新锁定输入。 | | `unstable-ref` | 否 | `""` | 可选的第三次扫描目标，通常是 `github:NixOS/nixpkgs/nixos-unstable`。 | | `whitelist` | 否 | `""` | 调用者仓库中的抑制 CSV 的路径。 | | `nixprs` | 否 | `false` | 在报告渲染期间启用尽力而为的 nixpkgs PR 扩充。 | | `token` | 否 | `""` | 用于 `nixprs` 的可选 token；为空时，受信任的报告步骤会回退到 `github.token`。 | | `cachix-caches` | 否 | `""` | 空格分隔的 Cachix 缓存名称，作为只读 substituter 添加。 | ### 行为 - 支持的 runner：Linux runner。该 Action 围绕 [`cachix/install-nix-action`](https://github.com/cachix/install-nix-action) 设计，因此 macOS 也许可用，但本仓库目前仅在 Linux 上验证发布。 - 所需的工作流权限：正常的检出并扫描流程只需 `contents: read` 即可。 - 安全模型：不受信任的 `scan` 阶段在没有 `GH_TOKEN` 的情况下运行；可选的 GitHub 认证扩充随后会在受信任的 `report` 阶段进行。 - Action 输出：无。该 Action 将其面向操作者的结果写入 GitHub Step Summary。 - 基线差异对比：该 Action 会持久化以 flakeref、targets 和 `input-name` 为键的先前结果集，然后报告自上次相同范围成功运行以来的变化。 ### 缓存和报告输出 该 Action 会从之前的运行中恢复最新匹配的缓存条目，并为下次运行保存最新状态。它会持久化： - `grype` 数据库 - `vulnix` 数据库 - `sbomnix` 用于 OSV、repology 和可选 `nixprs` 查询的共享 HTTP 缓存 - 用于“自上次运行以来”部分的上一次运行的检查结果基线 ## 本地使用 ### 前置条件 - 启用了 `nix-command` 和 `flakes` 的 Nix - Linux - 如果你想在 `--nixprs` 查询时获得更高的 GitHub API 速率限制，请在环境中设置 `GH_TOKEN`；如果没有，`flakevuln` 将回退到匿名的尽力而为查询 ### 快速开始 针对当前检出运行： ``` nix run .#flakevuln -- local packages.x86_64-linux.default ``` 默认情况下，`local` 会将输出写入 `.flakevuln/` 目录下： - `findings.json` - `report/README.md` - `report/*.md` 用于每个目标的详细页面 通过将目标嵌入 flakeref 来扫描远程 flake： ``` nix run .#flakevuln -- local \ -f 'github:nix-community/poetry2nix#packages.x86_64-linux.default' ``` 当 `--flakeref` 已经包含 `#target` 片段时，你可以省略位置目标参数。 从本地子目录扫描 flake： ``` nix run .#flakevuln -- local \ -f ./services/api \ packages.x86_64-linux.default ``` 从当前检出扫描多个输出： ``` nix run .#flakevuln -- local \ packages.x86_64-linux.default \ devShells.x86_64-linux.default ``` 将输出写入其他位置： ``` nix run .#flakevuln -- local \ -o out/flakevuln \ packages.x86_64-linux.default ``` ### 常用本地选项 运行可选的不稳定版本对比： ``` nix run .#flakevuln -- local \ --unstable-ref github:NixOS/nixpkgs/nixos-unstable \ packages.x86_64-linux.default ``` 使用抑制 CSV： ``` nix run .#flakevuln -- local \ --whitelist examples/manual_analysis.csv \ packages.x86_64-linux.default ``` 启用尽力而为的 `nixprs` 扩充： ``` nix run .#flakevuln -- local \ --nixprs \ packages.x86_64-linux.default ``` 如果你想重新锁定的 flake 输入名称不是 `nixpkgs`，请显式设置： ``` nix run .#flakevuln -- local \ --input-name my-nixpkgs \ packages.x86_64-linux.default ``` ### 分阶段 CLI 使用 当你想先将结果实体化并稍后渲染报告时，请使用底层子命令： ``` nix run .#flakevuln -- scan \ --flakeref . \ --target packages.x86_64-linux.default \ --findings findings.json nix run .#flakevuln -- report \ --findings findings.json \ --outdir report \ --nixprs ``` ### 白名单格式 `whitelist` action 输入和 `--whitelist` CLI 标志都指向一个保存在你自己的仓库中的 CSV。可以从 [`examples/manual_analysis.csv`](examples/manual_analysis.csv) 开始。 建议在 `whitelist` 列中使用显式的 `True` 和 `False` 值： - `True` 抑制匹配的检查结果。 - `False` 保持检查结果为活动状态，仅记录附带的注释。

标签：GitHub Actions, Nix, 自动笔记, 逆向工具