tweag/genealogos

## 关于该项目

Genealogos 项目是一个工具，它接收 Nix 评估工具的输出并生成 BOM 文件。 目前，它接收来自 [nixtract][nixtract-url] 的输入，并生成符合 [CycloneDX][cyclonedx-url] 1.3 或 1.4 规范的 JSON 输出。 Genealogos 的输出可用于执行进一步分析的各种其他工具。 请注意，Nix 主要适用于软件，因此 Genealogos 生成的 BOM 几乎总是 SBOM。 然而，为了保持一致性，我们将输出称为 BOM。 Genealogos 可能已被用于生成 SBOM，但需要意识到存在一些已知问题。 请参阅本 README 末尾的已知问题和其它限制列表。 ## 安装 Genealogos-cli 目前，Genealogos 仅通过我们的 Nix Flake 分发。 确保已启用实验性功能 `flakes` 和 `nix-command`，然后运行： ``` # 一次性运行 nix run github:tweag/genealogos -- --help # 临时添加到 $PATH nix shell github:tweag/genealogos ``` 你也可以不使用 Nix 而直接使用 cargo。 但是在这种情况下，你需要自行确保依赖项可用。 ``` cargo install --git https://github.com/tweag/genealogos.git genealogos-cli ``` ## 安装 Genealogos-api（及前端） CLI 的安装方法可以轻松调整为 API。 ``` # 一次性运行 nix run github:tweag/genealogos#genealogos-api # 临时添加到 $PATH nix shell github:tweag/genealogos#genealogos-api # Cargo 安装 cargo install --git https://github.com/tweag/genealogos.git genealogos-api ``` `frontend` 功能默认启用，因此 API 运行后请打开 `http://localhost:8000/` 访问前端。 ## 以 Docker 镜像运行 Genealogos API 和前端也可以打包成 Docker 镜像。 获取并运行镜像： ``` # 生成镜像 nix build github:tweag/genealogos#dockerImage # 加载到 Docker docker load -i=./result # 运行镜像 # 注意：--rm 将在容器退出后清除容器内的 Nix 存储 # 服务将在 8000 端口可用 docker run -it --rm -p 8000:8000 localhost/genealogos ``` ## 深入开发 ### 先决条件 开发 Genealogos 需要 Cargo，以及一些其它依赖项。 我们还推荐使用 `rust-analyzer` 和 `nixtract`。 获取这些工具最简单的方式是通过 Nix 开发环境。 ``` nix develop ``` 或者你可以手动安装依赖项，但那样你需要自己负责。 ### 构建 构建可以使用 Cargo 完成，通过指定特定包 `cargo COMMAND -p [genealogos, genealogos-cli, genealogos-api]` 或运行 `cargo COMMAND` 来构建整个工作区。 ## 用法 ### `genealogos-cli` 分析本地 flake： ``` genealogos /path/to/your/local/flake ``` 分析 nixpkgs 中的 `hello`： ``` genealogos nixpkgs#hello ``` 使用跟踪文件： 本节假设你使用的是最新的 [nixtract][nixtract] `main` 版本。 ``` nixtract --target-attribute-path hello /tmp/out && genealogos -f /tmp/out ``` 更多 `nixtract` 参数，请参见 `nixtract --help`。 设置后端选项： 任何实现 `Backend` 的类型都必须有包含 nar info 的方式，并且仅包含运行时选项。 Genealogos 会将 `--include-narinfo` 和 `--runtime-only` 传递给后端。 ### Narinfo 当后端被指示通过 `--include-narinfo` 提供 narinfo 时，它可以选择如何提供。 例如，Nixtract 查询系统并根据配置的替代源返回 narinfo。 Genealogos 收集 narinfo，并为（针对 CycloneDX）将它们添加到 `components.properties` 列表中，名称格式为 `nix:narinfo:`。 完整选项列表请参见： ``` genealogos --help ``` ### `genealogos-api` Genealogos 也可以作为 API 服务器运行，使用 `genealogos-api` 二进制文件。 `genealogos-api` 提供两类端点。 一类是阻塞端点，另一类是基于作业的端点。 #### 阻塞端点 目前只有一个阻塞端点：`/api/analyze?installable=`。 默认情况下，`genealogos-api` 绑定在 `localhost:8000`。 例如，使用 curl 调用 API： ``` curl "http://localhost:8000/api/analyze?installable=nixpkgs%23hello" ``` 注意 `nixpkgs#hello` 中的 `#` 已被 URL 编码。 此外，可以提供可选的 `bom_format` 查询参数来指定要使用的 BOM 格式。 示例： ``` curl "http://localhost:8000/api/analyze?installable=nixpkgs%23hello&cyclonedx_version=v1_4" ``` 当前支持 `[cyclonedx_1.3_json, cyclonedx_1.3_xml, cyclonedx_1.4_json, cyclonedx_1.4_xml]`，默认值为 `cyclonedx_1.4_json`。 #### 作业 基于作业的 API 包含三个端点：`/api/jobs/create`、`/api/jobs/status` 和 `/api/jobs/result`。 创建作业的方式与阻塞 API 类似： ``` curl "http://localhost:8000/api/jobs/create?installable=nixpkgs%23hello" ``` 此端点也支持 `bom_format` 查询参数。 该 API 调用的响应是一个 `job_id`，需要将其传递给后续调用以标识所需作业。 获取作业状态如下： ``` curl "http://localhost:8000/api/jobs/status/0" ``` 其中 0 是上一个调用提供的 `job_id`。 该 API 可能返回 `stopped`、`running` 或 `done`。 最后，获取结果使用 `result` 端点： ``` curl "http://localhost:8000/api/jobs/result/0" ``` #### 配置 `genealogos-api` 可通过 [Rocket](https://rocket.rs) 的配置机制进行配置。 它使用 Rocket 定义的[默认提供者](https://rocket.rs/guide/v0.5/configuration/#default-provider)。 [默认选项](https://rocket.rs/guide/v0.5/configuration/#overview)包含所有与 Web 服务器相关的配置。 除了这些默认配置选项外，Genealogos 还扩展了 Rocket 的配置，新增两个键： | key | kind | description | debug/release default | |------------------|--------------------|--------------------------------------------------------------------|-----------------------| | `gc_interval` | `u64` (in seconds) | 两轮垃圾回收之间的间隔时间 | `10` | | `gc_stale_after` | `u64` (in seconds) | 最后一次被访问后多久认为作业已过期 | `60 * 10` | ### `genealogos-frontend` Genealogos 附带一个纯 HTML/JavaScript 的 Web 前端。 默认情况下，该前端使用 `127.0.0.1` 连接到 `genealogos-api`。 可通过页面顶部的设置按钮更改此默认值。 Web UI 目前仅支持从 flake ref 和属性路径进行分析，尚未支持分析跟踪文件。 可以通过在喜爱的浏览器中打开 `index.html` 文件来打开前端。 另外，如果 `genealogos-api` 使用 `frontend` 功能标志构建，前端也可在 API 托管的根路径访问（例如 `http://localhost:8000/`）。 ### NixOS 模块 该项目提供的 Flake 包含一个用于部署 Genealogos 的 NixOS 模块。 将模块添加到 NixOS 配置后，可通过以下方式启用 Genealogos： ``` services.genealogos.enable = true; ``` 更多选项请参见 `./nix/genealogos-module.nix`。 ## 贡献 贡献是使开源社区成为学习、启发和创造美好之地的重要因素。你所做的任何贡献都 **非常受赞赏**。 如果你有改进建议，请 fork 本仓库并创建 Pull Request，也可以直接打开 Issue。 ## 测试 Genealogos 针对 `genealogos/tests/fixtures/nixtract/success/` 中的测试用例进行测试。 每个 `.in` 文件包含 `nixtract` 输出，每个 `.out` 文件包含对应的预期 `genealogos` 输出。 这些测试用例会在 `nix build` 时自动执行，也可手动使用 `cargo test` 运行。 通常，`genealogos` 的输出是非确定性的（UUID 是随机的，列表元素的顺序也是随机的），这使得测试略显复杂。 为了克服这一障碍，在运行 `cargo test` 或设置 `GENEALOGOS_DETERMINISTIC` 环境变量时，`genealogos` 的输出会被设为确定性模式。 这通过将 UUID 设为全零，并对 `dependsOn` 列表进行排序来实现。 为了更方便地处理这些测试用例，`nix develop .#scripts` 提供的 devShell 包含两个脚本： `verify-fixture-files`，它使用 `cyclonedx-cli` 工具验证 `.out` 文件，确保 `genealogos` 生成有效的 CycloneDX。 以及 `update-fixture-files`，应在 `genealogos` 输出变更时运行。 注意第二个脚本要求 `genealogos-cli`必须可构建。 ## 已知问题和限制 目前，Genealogos（通过 nixtract）会尝试查找所有作为输入派生物的属性。 这意味着某些输入可能会被遗漏，尤其是字符串上下文中的内容。 此外，Genealogos（通过 nixtract）为每个 SBOM 组件都会重启 nix。 当你的派生评估耗时较长时，这将导致 SBOM 生成非常缓慢。 ### 安全注意事项 由于 Genealogos API 的本质，它会评估用户提供的任意 Nix 代码。 如果你计划将其作为公共服务运行，请务必妥善保护进程并设置适当的服务管理措施，考虑以下方面： - 被任何用户发起的拒绝服务攻击风险，尤其是： * 无限制的内存使用， * 无限制的存储使用， * 无限制的 CPU 时间使用 - 对 Nix Flake 评估完全封闭且纯净、并因此安全的假设的依赖 - 对 Nix 沙箱的依赖以确保其安全且不泄露 因此，我们建议在任何公共部署的 Genealogos 实例中使用容器化环境（例如通过提供的 [Docker 镜像](#Running_as_a_Docker_image)），并为容器适当限制资源。 ## 许可证 根据 MIT 许可证分发。更多信息请参见 `LICENSE`。 ## 资金支持 该项目通过 [NGI0 Entrust](https://nlnet.nl/entrust) 获得资助， 该基金由 [NLnet](https://nlnet.nl) 建立，并得到 欧洲委员会的 [下一代互联网](https://ngi.eu) 计划的支持。更多详情请访问 [NLnet 项目页面](https://nlnet.nl/project/Genealogos)。 [](https://nlnet.nl) [](https://nlnet.nl/entrust) ## 联系 [][tweag-url] GitHub: [https://github.com/tweag/genealogos](https://github.com/tweag/genealogos)

标签：API服务, BOM生成, cargo, CycloneDX, Docker容器, GPT, LLM防护, Nix, Nix flakes, Rust, SBOM, Triage, WebSocket, 依赖分析, 前端, 可视化界面, 攻击面发现, 漏洞管理, 生成器, 硬件无关, 网络流量审计, 跌倒检测, 软件供应链, 软件物料清单, 软件组成分析, 通知系统