TimesysGit/vigiles-openwrt

# 用于 OpenWrt 的 Vigiles 这是一套用于软件物料清单（SBOM）生成的工具集，旨在作为 **[Vigiles](https://www.lynx.com/solutions/vulnerability-mitigation-management)** 产品服务的一部分，用于漏洞监控与通知。 # 什么是 Vigiles？ Vigiles 是一款漏洞管理工具，它为 OpenWrt 目标镜像提供构建时的 CVE 分析。它通过收集待安装软件包的元数据，并将其上传至 Vigiles CVE 数据库进行比对来实现。系统会返回检测到的漏洞的高层级概览，完整的详细分析可在线查看。 如需申请试用账户，请通过 sales@timesys.com 与我们联系。 # 使用 Vigiles CVE 检查 要生成漏洞报告，请遵循以下步骤： 1. 克隆 vigiles-openwrt 仓库。 git clone https://github.com/TimesysGit/vigiles-openwrt.git 2. 在此处下载您的 Vigiles API 密钥文件，并将其存储在（推荐的）路径。 mkdir $HOME/timesys cp $HOME/Downloads/linuxlink_key $HOME/timesys/linuxlink_key 3. 使用 **OpenWrt 构建目录**和 **Vigiles 输出目录**（用于存放生成的报告和清单）的路径，运行 **Vigiles CVE 扫描器** (vigiles-openwrt.py)。 cd {vigiles-openwrt 克隆目录} ./vigiles-openwrt.py -b {OpenWrt 目录路径} -o {Vigiles 输出目录路径} 4. 在本地查看 Vigiles CVE（文本）报告 CVE 报告将位于运行 Vigiles CVE 扫描器 (vigiles-openwrt.py) 工具时提供的 ```{Vigiles 输出目录}``` 中，文件名基于开发板名称；例如： wc -l vigiles/output/ath79-report.txt 240 vigiles/output/ath79-report.txtt 5. 查看 Vigiles CVE 在线报告 本地 CVE 文本报告将包含一个指向全面且图形化报告的链接；例如： -- Vigiles CVE Report -- View detailed online report at: https://vigiles.lynx.com/cves/reports/ **CVE 清单文件** Vigiles CVE 扫描器会创建一个清单文件，用于向 Vigiles 服务器描述您的构建配置。此清单文件位于运行 Vigiles CVE 扫描器 (vigiles-openwrt.py) 时提供的 ```{Vigiles 输出目录}``` 中（与其接收返回的文本报告位于同一位置）。 wc -l vigiles/output/ath79-manifest.json 854 vigiles/output/ath79-manifest.json 如果发生错误，或者结果似乎不正确，此文件可能有助于分析原因。在提交任何支持请求时，务必附上此文件。 # 配置 ### 报告与过滤 可以使用选项 **```-k / --kernel-config```** 和 **```-u / --uboot-config```** 来启用/禁用 Linux 内核和 U-Boot 的 .config 过滤功能。 如果为内核或 U-Boot 的 .config 文件使用了自定义位置，可以使用 **```-k / --kernel-config```** 和 **```-u / --uboot-config```** 指定路径。 这两个路径的默认值均为 _```auto```_，这将导致自动使用包配置的构建目录中的 .config。除非绝对必要，否则建议使用此默认值。 如果您想禁用 Linux 内核和 U-Boot 的 .config 过滤，请传递 _```none```_ 作为参数值。 ### 自定义/补充 Vigiles 报告 在某些情况下，可能需要修改 Vigiles 生成的 CVE 报告。 vigiles-openwrt 支持 _包含额外的软件包_、_排除软件包_ 和 _将已知 CVE 加入白名单_ 的功能。此外，本地生成的清单和 CVE 报告的文件名也可以自定义。 所有这些选项都通过 ```Vigiles CVE 扫描器 (vigiles-openwrt.py)``` 的一个参数支持，用户可以指定一个描述软件包或 CVE 的 CSV（逗号分隔值）文件。下面将逐一描述。 #### 清单和报告命名 默认情况下，将要上传的 Vigiles 清单文件和生成的 CVE 报告的文件名基于 kconfig 的值 ```CONFIG_TARGET_BOARD```，将产生如下文件： ``` output ├── ath79-manifest.json └── ath79-report.txt ``` 要为上传的本地 Vigiles 清单和生成的 CVE 报告使用自定义名称，可以使用 Vigiles CVE 扫描器参数 ```-N / --name```。 如果设置为 '**Custom-Name**'，则生成的文件将为： ``` output/vigiles ├── Custom-Name-manifest.json └── Custom-Name-report.txt ``` #### 包含额外的软件包 要包含在标准 OpenWrt 流程之外构建的软件包（因此不会包含在 Vigiles CVE 报告中），可以将 Vigiles CVE 扫描器的参数 ```-A / --additional-packages``` （“包含在报告中的额外软件包”）设置为一个 CSV 文件的路径。 该 CSV 文件包含一个可选的头部和以下字段： * Product - 软件包在 CVE 中使用的 CPE 名称 * （可选）Version - 使用的软件包版本。 * （可选）License - 使用的软件包许可证 以下示例展示了表示额外软件包的可接受语法： ``` $ cat /home/user/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 报告之外，可以将 Vigiles CVE 扫描器的参数 ```-E / --exclude-packages``` 设置为一个 CSV 文件的路径。 该 CSV 文件每行期望一个软件包名称。任何额外的 CSV 字段都会被忽略。 例如： ``` $ cat /home/user/vigiles-exclude-packages.csv linux-libc-headers opkg-utils packagegroup-core-boot ``` #### 将 CVE 加入白名单 某些软件包可能关联着已知不影响特定机器或配置的 CVE。 用户可以将 Vigiles CVE 扫描器的参数 ```-W / --whitelist-cves``` 设置为一个包含要从 Vigiles 报告中省略的 CVE 列表的 CSV 文件路径。 该 CSV 文件每行期望一个 CVE ID。任何额外字段都将被忽略。 例如： ``` $ cat /home/user/vigiles-cve-whitelist.csv CVE-2021-37155 CVE-2018-12886 ``` ### 仅上传清单 在某些情况下，可能只需要上传构建的 Vigiles 清单，而不生成 CVE 报告。 可以通过 Vigiles CVE 扫描器的参数 ```-U / --upload-only``` 来启用此行为。 系统将显示一个指向 Vigiles 仪表板（通过 VIGILES_DASHBOARD_CONFIG 指定）或私有工作区（如果未指定仪表板配置）的链接，而不是文本报告和在线报告链接。之后可以由 Vigiles 服务对其进行扫描。 ### Vigiles 凭证 要指定 Vigiles API 密钥文件的替代位置（默认为：```$(HOME)/timesys/linuxlink_key```），可以使用 Vigiles CVE 扫描器的参数 **```-K / --keyfile```** 进行设置。 ### Vigiles 仪表板配置 可以通过 Vigiles CVE 扫描器的参数 **```-C / --dashboard-config```** 指定路径来设置自定义的 Vigiles 仪表板配置。如果未提供，将使用默认路径（```$(HOME)/timesys/dashboard_config```）。 默认情况下，您的清单将上传到 Vigiles 仪表板上的“Private Workspace”产品。这可以通过下载其他产品和/或文件夹的“仪表板配置”来更改。 仪表板配置文件默认将下载到例如 ```"${HOME}/Downloads/dashboard_config"``` 的位置。根据需要移动和/或重命名后，您可以通过上述方式传递仪表板配置参数来控制 openwrt 的 Vigiles 行为。 ### 动态创建子文件夹 如果使用了仪表板配置，可以通过 Vigiles CVE 扫描器的参数 **```-F / --subfolder```** 指定一个子文件夹名称，以便动态创建文件夹。 清单将上传到仪表板配置中指定位置下具有此名称的子文件夹中。如果该子文件夹不存在，则会被创建。此选项将被环境变量 ```VIGILES_SUBFOLDER_NAME``` 覆盖。 ### 指定用于生成报告的生态系统（仅限企业版 Vigiles） 可以指定生态系统，以便将特定于该生态系统的漏洞包含在漏洞报告中。 此功能目前仅适用于企业版 Vigiles。 这接受以逗号分隔的生态系统字符串，如下所示。 要包含所有生态系统，请将此设置为“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'] ``` ### 订阅 SBOM 报告通知（仅限企业版 Vigiles） 可以使用此设置配置 SBOM 报告通知，允许用户订阅并设置其报告通知的频率。 此功能目前仅适用于企业版 Vigiles。 要指定通知频率，请使用 ```-s / --subscribe``` 参数，并选择以下选项之一：`none`、`daily`、`weekly`、`monthly`。 ### 指定自定义内核源代码 此选项允许用户指定自定义内核源代码目录。如果通过此选项提供了路径，脚本将从指定的内核源代码收集元数据。如果留空，脚本将回退到使用默认的内核源代码路径。 ### 指定自定义 U-Boot 源代码 此选项允许用户指定自定义的 U-Boot 源代码目录。如果通过此选项提供了路径，脚本将从指定的 U-Boot 源代码收集元数据。如果留空，脚本将回退到使用默认的 U-Boot 源代码路径。 ### 下载转换后的 SBOM 在上传过程完成后，可以下载标准 CycloneDX 或 SPDX 格式的转换后 SBOM。配置的 vigiles CLI 二进制文件用于将请求的转换后 SBOM 下载到 Vigiles 输出目录中。 需要安装 [vigiles-cli](https://github.com/TimesysGit/vigiles-cli)，并应提供其二进制文件的路径。 **注意：** 建议使用最新版本的 vigiles-cli。但是，如果您需要使用较旧的版本，请确保其版本为 v1.0.3 或更高。 示例用法： vigiles CLI 二进制文件路径可以通过 `--vigiles-bin` 或环境变量 `VIGILES_BIN_PATH` 提供。如果两者都设置，环境变量优先。 必需参数：```--download-sbom```、```--download-sbom-format```，以及通过 ```--vigiles-bin``` 或 ```VIGILES_BIN_PATH``` 指定的 vigiles CLI 路径。 每个参数的支持选项如下： * `--download-sbom-format`：`cyclonedx`、`spdx` 和 `spdx-lite` * `--download-sbom-file-type`（用于 `cyclonedx`）：`json`（默认）和 `xml` * `--download-sbom-file-type`（用于 `spdx` 和 `spdx-lite`）：`json`（默认）、`xml`、`yaml`、`tag`、`xlsx`、`xls` 和 `rdfxml` * `--download-sbom-version`（用于 `cyclonedx`）：`1.7`、`1.6`（默认）、`1.5`、`1.4`、`1.3`、`1.2` 和 `1.1` * `--download-sbom-version`（用于 `spdx` 和 `spdx-lite`）：`2.3`（默认）和 `2.2` ### 软件包生命周期信息 某些用户可能希望在软件包的 Makefile 中设置软件包生命周期信息，并将其包含在 SBOM 中。这可以通过在软件包的 Makefile 中使用以下自定义 Makefile 变量来实现： ``` PKG_RELEASE_DATE:=2025-01-15 PKG_END_OF_LIFE:=2027-01-15 PKG_LEVEL_OF_SUPPORT:=Actively maintained ``` 这些值将被收集并包含在相应软件包的 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 ``` ```PKG_LEVEL_OF_SUPPORT``` 和 CSV 列 `level_of_support` 的有效值均为：```Actively maintained```（积极维护）、```No longer maintained```（不再维护）、```Not available```（不可用）、```Abandoned```（已弃用）。 ### 高级选项 出于开发目的，提供了一些“专家”选项。 这些选项允许调试所收集的元数据。 这些功能不受支持，且未提供相关文档。 **将收集的元数据写入中间 JSON 文件**：```-I, --write-intermediate``` **启用调试消息**：```-D, --enable-debug``` **生成 SBOM 而不执行漏洞扫描**：```-M, --metadata-only``` ### 其他说明 #### 生成的 SBOM 中的软件包版本信息 Openwrt 包含一些缺少版本信息的软件包/配置脚本（例如 base-files、urandom-seeds 等）。 对于此类软件包，在生成的 SBOM 中，其版本被设置为 Openwrt 发行版版本。 # 维护 Vigiles CVE 扫描器和 OpenWrt 支持由 [Lynx 安全团队](mailto:vigiles@timesys.com) 维护。 如需获取更新、支持及更多信息，请参阅： [Vigiles 网站](https://www.lynx.com/solutions/vulnerability-mitigation-management)

标签：API集成, CVE分析, GPT, Homebrew安装, OpenWrt, SBOM生成, 可观测性, 安全扫描工具, 嵌入式Linux, 嵌入式系统, 构建时分析, 漏洞报告, 漏洞监控, 漏洞管理, 漏洞通知, 网络安全, 网络安全研究, 跌倒检测, 软件物料清单, 逆向工具, 隐私保护