TimesysGit/vigiles-buildroot
GitHub: TimesysGit/vigiles-buildroot
一款专为 Buildroot 嵌入式 Linux 构建系统设计的漏洞管理工具，可在构建时自动生成 SBOM 并进行 CVE 漏洞分析。
Stars: 11 | Forks: 5
# oper nouns, tool/library/framework names, and technical jargon in their original English form."
这是一套用于 **[Vigiles](https://www.lynx.com/solutions/vulnerability-mitigation-management)** 产品中进行漏洞监控与通知的 SBOM 生成工具集。
# 什么是 Vigiles？
Vigiles 是一款漏洞管理工具，可在构建时对 Buildroot 目标镜像进行 CVE 分析。它通过收集待安装软件包的元数据，并将其上传至 Vigiles CVE 数据库进行比对来完成分析。系统会返回检测到的漏洞概览，完整详细分析可在线查看。
如需申请试用账户，请通过 sales@timesys.com 联系我们。
# 系统要求
- [Buildroot](https://github.com/buildroot/buildroot/) 版本 2018.11.x 及以上
- Python 版本 3.6 及以上
# 安装步骤
1. 将 vigiles-buildroot 仓库克隆至与 Buildroot 目录相同的层级。
git clone https://github.com/TimesysGit/vigiles-buildroot
2. 安装依赖项
python3 -m pip install -r vigiles-buildroot/requirements.txt
# 配置
1. 在此处下载您的 Vigiles API 密钥文件，并将其存储在（推荐的）路径。
mkdir $HOME/timesys
cp $HOME/Downloads/linuxlink_key $HOME/timesys/linuxlink_key
2. 指示 Buildroot 在其配置中包含 Vigiles 接口。
make BR2_EXTERNAL=/path/to/vigiles-buildroot menuconfig
# 仅生成 SBOM
仅生成 SBOM 的选项可在 menuconfig 界面的高级 Vigiles 选项下找到。
```
*** Advanced Vigiles / Debug Options ***
[*] Generate SBOM only
```
此选项仅生成 SBOM。默认情况下，生成的 SBOM 也会上传至 Vigiles 进行漏洞扫描。
设置环境变量 `GENERATE_SBOM_ONLY` 为 `True` 或 `False` 可以覆盖 menuconfig 中的当前设置。
# 使用 Vigiles CVE 检查
1. 使用 Vigiles 目标执行 Make
make vigiles-check
2. 本地查看 Vigiles CVE（文本）报告
CVE 报告将位于您 Buildroot 构建输出的 `vigiles/` 子目录中，文件名基于目标配置；例如：
wc -l output/vigiles/buildroot-imx8mpico-report.txt
3616 output/vigiles/buildroot-imx8mpico-report.txt
3. 查看 Vigiles CVE 在线报告
本地 CVE 文本报告将包含一个指向综合图形化报告的链接；例如：
-- Vigiles CVE Report --
View detailed online report at:
https://vigiles.lynx.com/cves/reports/< Unique Report Identifier>
## So for "CVE SBOM", "CVE" is a proper term (Common Vulnerabilities and Exposures), and "SBOM" is a technical term (Software Bill of Materials). So I should keep them in English. But in the translation, I might include the Chinese explanation.
Vigiles CVE 扫描器会创建一个 SBOM，将其发送至 Vigiles 服务器以描述您的构建配置。此 SBOM 位于 Buildroot 输出的 `vigiles/` 子目录中（与其接收返回的文本报告位置相同）。
wc -l output/vigiles/buildroot-imx8mpico-manifest.json
557 output/vigiles/buildroot-imx8mpico-manifest.json
如果出现问题或结果似乎不正确，此文件可能提供有关原因的提示。在任何支持请求中包含此文件非常重要。
# 配置
如果已包含，Vigiles 将通过 Kconfig 选项 **`BR2_EXTERNAL_VIGILES`** 默认启用。此外，还有其他配置选项可用于控制子系统的行为。
### 基本配置
使用 `make menuconfig`，Vigiles 配置菜单可在 **`External Options`** 下找到。
```
External options --->
*** Vigiles CVE Checker (in /home/mochel/projects/buildroot/vigiles) ***
[*] Enable Vigiles CVE Check --->
```
### 报告与过滤
Linux 内核和 U-Boot .config 过滤功能可以通过 **`VIGILES_ENABLE_KERNEL_CONFIG`** 和 **`VIGILES_ENABLE_UBOOT_CONFIG`** 选项启用/禁用。
如果为内核或 U-Boot .config 文件使用自定义位置，路径可以通过 **`BR2_EXTERNAL_VIGILES_KERNEL_CONFIG`** 和 **`BR2_EXTERNAL_VIGILES_UBOOT_CONFIG`** 指定。
两个路径的默认值都是 _`auto`_，这将自动使用软件包配置构建目录中的 .config。除非绝对有必要指定替代路径，否则建议使用此值。
```
*** Vigiles Kernel CVE Reporting Options ***
[*] Enable Linux Kernel .config Filtering
(auto) Location of Linux Kernel .config file
[*] Enable U-Boot .config Filtering
(auto) Location of U-Boot .config file
```
### 自定义/修订 Vigiles 报告
在某些情况下，可能需要修改 Vigiles 生成的 CVE 报告。
vigiles-buildroot 支持 _包含额外软件包_、_排除软件包_ 和 _将已知 CVE 加入白名单_ 的功能。此外，本地生成的 SBOM 和 CVE 报告的文件名也可以自定义。
所有这些选项都通过 `Kconfig` 选项支持，用户可以在其中指定描述软件包或 CVE 的 CSV（逗号分隔值）文件。下面分别说明。
#### SBOM 与报告命名
默认情况下，要上传的 Vigiles SBOM 和生成的 CVE 报告的文件名基于 `BR2_HOSTNAME` 和 `BR2_DEFCONFIG`（或目标 CPU）的值，将产生如下文件：
```
output/vigiles
├── buildroot-nitrogen6x-manifest.json
└── buildroot-nitrogen6x-report.txt
```
要为上传的本地 Vigiles SBOM 和生成的 CVE 报告使用自定义名称，可以使用 Kconfig 选项 `BR2_EXTERNAL_VIGILES_MANIFEST_NAME`。如果设置为 '**Custom-Name**'，产生的文件将是：
```
output/vigiles
├── Custom-Name-manifest.json
└── Custom-Name-report.txt
```
#### 包含额外软件包
要包含在标准 Buildroot 进程之外构建的软件包（因此不会包含在 Vigiles CVE 报告中），可以将 Kconfig 选项 `BR2_EXTERNAL_VIGILES_INCLUDE_CSV`（“报告中包含的额外软件包”）设置为 CSV 文件的路径。
CSV 文件包含一个可选标题和以下字段：
* Product - 软件包在 CVE 中使用的 CPE 名称
* (可选) Version - 使用的软件包版本。
* (可选) License - 使用的软件包的许可证
以下示例展示了表达额外软件包的可接受语法：
```
$ cat $HOME/projects/buildroot/vigiles-additional-packages.csv
product,version,license
avahi,0.6
bash,4.0
bash,4.1,GPL 3.0
busybox,
udev,,"GPLv2.0+, LGPL-2.1+"
```
#### 排除软件包
在某些情况下，可能需要更简洁的 CVE 报告，因此可以指定要省略的特定软件包列表（例如：仅安装数据文件的软件包）。
要从 CVE 报告中排除软件包，可以将 Kconfig 选项 `BR2_EXTERNAL_VIGILES_EXCLUDE_CSV` 设置为 CSV 文件的路径。
CSV 文件每行期望一个软件包名称。任何额外的 CSV 字段都将被忽略。
例如：
```
$ cat $HOME/projects/buildroot/vigiles-exclude-packages.csv
linux-libc-headers
opkg-utils
packagegroup-core-boot
```
#### CVE 白名单
某些软件包关联的 CVE 可能已知不会影响特定机器或配置。Buildroot 软件包可以通过其 Makefile 中的 `IGNORE_CVES` 变量来表达这些 CVE。但是，可能还有其他需要忽略/加入白名单的 CVE。
用户可以将 Kconfig 选项 `BR2_EXTERNAL_VIGILES_WHITELIST_CSV` 设置为包含要从 Vigiles 报告中省略的 CVE 列表的 CSV 文件的路径。
CSV 每行期望一个 CVE ID。任何额外字段都将被忽略。
例如：
```
$ cat $HOME/projects/buildroot/vigiles-cve-whitelist.csv
```
### 仅上传 SBOM
在某些情况下，可能希望为构建上传 Vigiles SBOM，而不生成 CVE 报告。这可以加快构建速度并简化自动化批量构建的报告。
可以通过 Kconfig 选项 `BR2_EXTERNAL_VIGILES_UPLOAD_ONLY` 启用此行为。
将不显示文本报告和在线报告链接，而是显示指向 Vigiles Dashboard 产品工作区（使用 VIGILES_DASHBOARD_CONFIG 指定）的链接，之后可以从那里通过 Vigiles 服务进行扫描。
### Vigiles 凭证
要指定 Vigiles API 密钥文件的替代位置（默认：`$(HOME)/timesys/linuxlink_key`），可以通过字符串 **`BR2_EXTERNAL_VIGILES_KEY_FILE`** 设置。
```
*** Vigiles Account Options ***
($(HOME)/timesys/linuxlink_key) Vigiles API Key Location
```
### Vigiles Dashboard 配置
可以通过首先启用 **`VIGILES_ENABLE_DASHBOARD_CONFIG`** 并在字符串 **`BR2_EXTERNAL_VIGILES_DASHBOARD_CONFIG`** 中指定路径来设置自定义的 Vigiles Dashboard 配置。如果未设置，将使用默认路径（`$(HOME)/timesys/dashboard_config`）。
```
*** Vigiles Dashboard Options ***
[*] Use a custom Vigiles Dashboard Configuration
($(HOME)/timesys/dashboard_config) Vigiles Dashboard Config Location
```
默认情况下，您的 SBOM 将上传到 Vigiles Dashboard 上您的“私有工作区”产品。这可以通过下载替代产品和/或文件夹的“Dashboard Config”来更改。
Dashboard Config 文件默认下载到例如 `"${HOME}/Downloads/__config"` 的位置。根据需要移动和/或重命名后，您可以通过设置上述配置变量来控制 Vigiles for Buildroot 的行为。
### 动态子文件夹创建
```
--- Enable Vigiles CVE Check
*** Vigiles Kernel CVE Reporting Options ***
*** Customizing / Amending Vigiles Report ***
() Custom SBOM and Report Name
() Subfolder name
```
如果使用 Dashboard Config，可以指定子文件夹名称以动态创建文件夹。SBOM 将上传到 Dashboard Config 中指定位置下的具有此名称的子文件夹。如果不存在，将创建一个。此选项将被环境变量 `VIGILES_SUBFOLDER_NAME` 覆盖。
### 高级选项
出于开发目的，可以通过首先启用 **`VIGILES_ENABLE_EXPERT`** 来使用一些“专家”选项。这些选项允许调试所收集的元数据。
这些功能不受支持且不提供文档。
```
*** Advanced Vigiles / Debug Options ***
[*] Enable Vigiles Advanced and Debugging Options (Expert)
[ ] Enable Verbose Console Output
[ ] Write Intermediate JSON Files of Collected Metadata
[ ] Include virtual packages in SBOM
() Vigiles output location
[ ] Generate SBOM only (NEW)
```
### 在生成的 SBOM 中包含虚拟包
此选项可在高级 Vigiles 选项下找到。
```
*** Advanced Vigiles / Debug Options ***
[ ] Include virtual packages in SBOM
```
此选项将在生成的 SBOM 中包含虚拟包。默认情况下，vigiles-buildroot 将从生成的 SBOM 中排除虚拟包。
### 指定 Vigiles 输出位置
此选项可在高级 Vigiles 选项下找到。
```
*** Advanced Vigiles / Debug Options ***
() Vigiles output location
```
此选项指定 Vigiles 输出文件（如 SBOM、报告和 Vigiles 日志）的位置。默认位置是 `/output/vigiles` 目录。
环境变量 `VIGILES_OUTPUT_DIR` 可用于覆盖此配置。
### 指定 SBOM 格式
此选项可在高级 Vigiles 选项下找到。
```
Select SBOM format -->
```
此选项可用于指定要生成的 SBOM 格式。目前，vigiles-buildroot 支持生成 `Cyclonedx 1.4 JSON` 和 `Vigiles JSON` 格式的 SBOM。默认情况下，将生成 `Vigiles JSON` 格式的 SBOM。
### 下载转换后的 SBOM
此选项可在高级 Vigiles 选项下找到。
```
*** Advanced Vigiles / Debug Options ***
[*] Download Converted SBOM (CycloneDX/SPDX)
() Path to vigiles CLI binary (required)
SBOM format -->
SBOM file type -->
SBOM version -->
```
此选项允许在上传过程完成后，下载转换为标准 CycloneDX 或 SPDX 格式的 SBOM。配置的 vigiles CLI 二进制文件用于将请求的转换后的 SBOM 下载到 vigiles 输出目录。
需要安装 [vigiles-cli](https://github.com/TimesysGit/vigiles-cli)，并提供其二进制文件的路径。
**注意：** 建议使用最新版本的 vigiles-cli。但是，如果需要使用较旧版本，请确保它是 v1.0.3 或更高版本。
支持的选项包括：
* SBOM 格式：`CycloneDX`、`SPDX` 和 `SPDX-Lite`
* `CycloneDX` 的 SBOM 文件类型：`JSON` 和 `XML`
* `SPDX` 和 `SPDX-Lite` 的 SBOM 文件类型：`JSON`、`XML`、`YAML`、`Tag`、`XLSX`、`XLS` 和 `RDFXML`
* `CycloneDX` 的 SBOM 版本：`1.7`、`1.6`、`1.5`、`1.4`、`1.3`、`1.2` 和 `1.1`
* `SPDX` 和 `SPDX-Lite` 的 SBOM 版本：`2.3` 和 `2.2`
**注意：** CycloneDX SBOM 无法升级或降级。如果为 SBOM 生成选择了 SBOM 格式 `CycloneDX 1.4 JSON`，则下载 `SBOM version` 也必须设置为 `1.4`。
### 所需文件检查
Vigiles-buildroot 解析 `.config` 和 `.hash` 文件以获取软件包依赖关系和校验和。用户可以在 menuconfig 中设置“需要所有配置文件”和“需要所有哈希文件”选项，以在任何文件缺失时引发错误。默认情况下，如果这些文件中的任何一个缺失，vigiles-buildroot 将仅显示警告消息。
```
...
[*] Require all config files
[*] Require all hashfiles
```
### 指定用于生成报告的生态系统（仅限企业版 Vigiles）
可以指定生态系统以将特定于生态系统的漏洞包含到漏洞报告中。
此功能目前仅适用于企业版 Vigiles。
此选项可在高级 Vigiles 选项下找到。
```
...
() Specify Ecosystems
```
它接受逗号分隔的生态系统字符串，如下所示：
```
Linux, Maven, PyPI, Ubuntu:20.04:LTS
```
要包含所有生态系统，请将其设置为 "all"：
```
all
```
以下是可用的有效生态系统列表：
```
AlmaLinux:
['AlmaLinux', 'AlmaLinux:8', 'AlmaLinux:9']
Alpine:
['Alpine', 'Alpine:v3.10', 'Alpine:v3.11', 'Alpine:v3.12', 'Alpine:v3.13', 'Alpine:v3.14', 'Alpine:v3.15', 'Alpine:v3.16', 'Alpine:v3.17', 'Alpine:v3.18', 'Alpine:v3.19', 'Alpine:v3.2', 'Alpine:v3.20', 'Alpine:v3.3', 'Alpine:v3.4', 'Alpine:v3.5','Alpine:v3.6', 'Alpine:v3.7', 'Alpine:v3.8', 'Alpine:v3.9']
Debian:
['Debian', 'Debian:10', 'Debian:11', 'Debian:12', 'Debian:13', 'Debian:3.0', 'Debian:3.1', 'Debian:4.0', 'Debian:5.0', 'Debian:6.0', 'Debian:7', 'Debian:8', 'Debian:9']
Rocky:
['Rocky Linux', 'Rocky Linux:8', 'Rocky Linux:9']
Ubuntu:
['Ubuntu', 'Ubuntu:14.04:LTS', 'Ubuntu:16.04:LTS', 'Ubuntu:18.04:LTS', 'Ubuntu:20.04:LTS', 'Ubuntu:22.04:LTS', 'Ubuntu:23.10', 'Ubuntu:24.04:LTS', 'Ubuntu:Pro:14.04:LTS', 'Ubuntu:Pro:16.04:LTS', 'Ubuntu:Pro:18.04:LTS', 'Ubuntu:Pro:20.04:LTS', 'Ubuntu:Pro:22.04:LTS', 'Ubuntu:Pro:24.04:LTS']
Others:
['Android', 'Bitnami', 'CRAN', 'GIT', 'GSD', 'GitHub Actions', 'Go', 'Hackage', 'Hex', 'Linux', 'Maven', 'NuGet', 'OSS-Fuzz', 'Packagist', 'Pub', 'PyPI', 'RubyGems', 'SwiftURL', 'UVI', 'crates.io', 'npm']
```
### 其他注意事项
#### Make 4.3 解决方法
Ubuntu 22.04 附带的 `make` 版本存在一个错误，描述如下：
在 Buildroot 论坛中讨论过：
不幸的是，这阻止了 Vigiles-Buildroot 的工作，因为它本质上依赖于 `make printvars` 命令。
为了启用 Vigiles 功能，我们不得不采取一个非常“特殊”的策略，当且仅当检测到 Make 4.3 时，通过 (a) 抑制 Buildroot 的解决方法（仅对该调用使用修复后的顶层 Makefile）；以及 (b) 执行 `make printvars` 时使用增加的进程栈大小（用 `prlimit` 包装它）。
如果这与您的构建系统冲突，可以使用替代方法，尽管它需要对 vigiles-buildroot 和 Buildroot 本身进行自定义修改。
- 还原 vigiles-buildroot 提交
- 还原 Buildroot 解决方法 (25cec5ea733251eb)
- 在构建前使用 `ulimit` 增加进程栈大小。
请注意，此方法不受官方支持，效果可能因环境而异。
#### 生成的 SBOM 中的软件包版本信息
Buildroot 包含一些缺少版本信息的软件包/配置脚本（例如 initscripts、urandom-scripts 等）。
在此类软件包的生成 SBOM 中，版本设置为 Buildroot 版本或 Buildroot 提交哈希。
#### 设置 CPE ID 变量
Buildroot 允许在软件包的 makefile（`.mk`）中定义一组变量来指定其 CPE 标识符。
例如，对于 busybox 软件包，这些变量如 product、version、vendor 等可以在 busybox.mk 中设置如下：
BUSYBOX_CPE_ID_PRODUCT = busybox BUSYBOX_CPE_ID_VERSION = 1.36.1 BUSYBOX_CPE_ID_VENDOR = busybox vigiles-buildroot 使用这些变量在未指定的情况下生成 cpe id。 ### 软件包生命周期信息 某些用户可能希望在软件包的 makefile 中设置软件包生命周期信息，并将其包含在 SBOM 中。这可以使用软件包 .mk 文件中的以下自定义 makefile 变量完成： ``` FOO_RELEASE_DATE = "2025-01-15" FOO_END_OF_LIFE = "2027-01-15" FOO_LEVEL_OF_SUPPORT = "Actively maintained" ``` 对于主机包，在定义变量时在包名前加 `HOST_`，例如： ``` HOST_FOO_LEVEL_OF_SUPPORT = "Actively maintained" ``` **注意：** `FOO` 是占位符，请将其替换为实际的包名。 这些值将被收集并包含在对应软件包的 SBOM 中。 您也可以使用 ```包含额外软件包``` 中引用的 CSV 文件为额外的软件包提供生命周期信息。示例 CSV 格式： ``` product,version,license,release_date,end_of_life,level_of_support avahi,0.6,MIT,2025-09-01,2026-01-01,Actively maintained ``` `FOO_LEVEL_OF_SUPPORT` 和 CSV 列 `level_of_support` 的有效值是：```Actively maintained```、```No longer maintained```、```Not available```、```Abandoned```。 # 维护
标签：Buildroot安全工具, Buildroot集成, CVE分析, GPT, LLM防护, meg, SBOM生成, Vigiles工具, 二进制发布, 信息安全, 威胁情报, 安全扫描, 嵌入式Linux, 嵌入式系统, 开发者工具, 开源工具, 时序注入, 构建时安全分析, 漏洞监控, 漏洞管理, 网络安全, 软件供应链安全, 远程方法调用, 逆向工具, 隐私保护