TimesysGit/meta-timesys

$ cat $HOME/projects/yocto/vigiles-not-affected.csv



cve-id,package,version,description

CVE-2019-1010023,glibc,2.39,External whitelist

CVE-2019-1010024,glibc,2.39,External whitelist




$ cat $HOME/projects/yocto/vigiles-not-affected.csv



CVE-2019-1010023

CVE-2019-1010024

### 内核配置过滤器

Vigiles CVE 扫描器可以配置为与 SBOM 一起上传 Linux 内核 _.config_ 文件。此过滤器将通过移除与未为您的内核构建的功能相关的 CVE 来减少报告的内核 CVE 数量。有 2 种方式启用此功能 -- 自动检测或手动指定

* 自动检测

这将在 Yocto 任务 ```do_configure``` 执行后，使用 ```PREFERRED_PROVIDER_virtual/kernel``` 中指定的内核的 _.config_。


```
VIGILES_KERNEL_CONFIG = "auto"
```


* 手动指定

**注意：这必须是_完整_的内核配置，而不是 defconfig！**


```
VIGILES_KERNEL_CONFIG = "/projects/kernel/linux-4.14-ts+imx-1.0/.config"
```


### U-Boot 配置过滤器

Vigiles CVE 扫描器可以配置为与 SBOM 一起上传 U-Boot _.config_ 文件。此过滤器将通过移除与未为您的 U-Boot 构建的功能相关的 CVE 来减少报告的 U-Boot CVE 数量。有 2 种方式启用此功能 -- 自动检测或手动指定

* 自动检测

这将在 Yocto 任务 ```do_configure``` 执行后，使用 ```PREFERRED_PROVIDER_virtual/bootloader``` 中指定的 U-Boot 的 _.config_。


```
VIGILES_UBOOT_CONFIG = "auto"
```


* 手动指定

**注意：这必须是_完整_的 U-Boot 配置，而不是 defconfig！**


```
VIGILES_UBOOT_CONFIG = ""
```


### 指定 Vigiles API 密钥文件

运行 Vigiles CVE 扫描器并生成 CVE 报告需要 Vigiles API 密钥。

要使用备用密钥或非默认位置的密钥，您可以在 _conf/local.conf_ 中通过类似以下语句指定位置：


```
VIGILES_KEY_FILE = "/tools/timesys/linuxlink_key"
```


如果设置了此选项，可以通过设置环境变量 VIGLES_KEY_FILE 指向备用密钥文件的位置，在命令行上覆盖它。开发人员可以使用此功能，在不更改共享的 local.conf 的情况下，使用个人/本地密钥。

### 指定产品或清单

默认情况下，您的清单将上传到 Vigiles 仪表板上"私有工作区"产品的顶级文件夹。这可以通过下载替代产品和/或文件夹的"仪表板配置"并在您的 local.conf 文件中指定来更改。

如果设置了此选项，可以通过设置环境变量 VIGILES_DASHBOARD_CONFIG 指向备用仪表板配置文件的位置，在命令行上覆盖它。开发人员可以使用此功能，在不更改共享的 local.conf 的情况下，使用个人/本地配置。


```
VIGILES_DASHBOARD_CONFIG = "${HOME}/timesys/dashboard_config"
```


### 动态子文件夹创建

如果使用了仪表板配置，可以指定子文件夹名称以进行动态文件夹创建。清单将上传到仪表板配置中指定位置下的具有此名称的子文件夹中。如果该子文件夹不存在，则会创建它。此选项将被环境变量 ```VIGILES_SUBFOLDER_NAME``` 覆盖。您可以通过修改 ```conf/local.conf``` 来设置适当的变量来控制 Vigiles 与 meta-timesys 的行为：


```
VIGILES_SUBFOLDER_NAME = "Release X.x"
```


### 指定要检查的其他软件包

在某些情况下，BSP 可能希望包含在 Bitbake/Yocto 流程之外构建的软件包。如果需要，可以使用 ```VIGILES_EXTRA_PACKAGES``` 来指定一个或多个 CSV（逗号分隔值）文件，这些文件描述了要包含在 CVE 检查中的额外软件包。

例如，可以在其 local.conf 中这样设置：


```
VIGILES_EXTRA_PACKAGES = "${HOME}/projects/this-bsp/non-yocto/yocto-extra.csv"
```


或者可能：


```
VIGILES_EXTRA_PACKAGES = " \

	${HOME}/projects/this-bsp/non-yocto/yocto-extra-boot.csv \

	${HOME}/projects/this-bsp/non-yocto/yocto-extra-ui.csv   \

"
```


为了显式包含由 Bitbake/Yocto 流程构建但因某种原因未出现在 rootfs 清单中的软件包（例如某些引导加载程序或自定义固件可能未通过镜像的递归 RDEPENDS 被拾取），可以使用 ```VIGILES_EXTRA_BACKFILL```。

例如，可以在其 local.conf 中这样设置：


```
VIGILES_EXTRA_BACKFILL = "some-firmware-package"
```


##### CSV 格式

CSV 文件由一个可选的标题行和以下字段组成：

* Product - 软件包在 CVE 中使用的 CPE 名称
* (可选) Version - 使用的软件包版本。
* (可选) License - 使用的软件包许可证

以下示例显示了表达额外软件包的有效语法：


```
$ cat yocto-extra.csv

product,version,license

avahi,0.6

bash,4.0

bash,4.1,GPL 3.0

busybox,

udev,,"GPLv2.0+, LGPL-2.1+"
```


### 从 CVE 检查中排除软件包

在某些情况下，BSP 可能希望从 Vigiles 报告中_排除_软件包；例如，通过移除已"安装"但没有文件（例如 packagegroups 或那些仅安装数据文件的包）的软件包来压缩输出。

这可以通过设置 ```VIGILES_EXCLUDE``` 为一个或多个 CSV 文件的空格分隔列表来完成，这些文件包含要在提交 CVE 检查之前从生成的清单中删除的软件包列表。

例如，在 ```conf/local.conf``` 中：


```
VIGILES_EXCLUDE = "${TOPDIR}/vigiles-exclude.csv"
```


并且在 ```${TOPDIR}/vigiles-exclude.csv``` 中：


```
linux-libc-headers

opkg-utils

packagegroup-core-boot
```




### 仅上传清单

在某些情况下，可能希望在不生成 CVE 报告的情况下上传构建的 Vigiles 清单。这可以加快构建时间并简化自动化批量构建的报告。

可以通过在 ```conf/local.conf``` 中将布尔变量 ```VIGILES_UPLOAD_ONLY``` 设置为 '1' 或 'True' 来启用此行为


```
VIGILES_UPLOAD_ONLY = "1"
```


将显示指向 Vigiles 仪表板（由 VIGILES_DASHBOARD_CONFIG 指定）或私有工作区（如果未指定仪表板配置）的链接，而不是文本报告和指向在线报告的链接，之后可以由 Vigiles 服务对其进行扫描。

### 在 SBOM 中排除具有“CLOSED”许可证的软件包

默认情况下，具有闭源许可证的软件包会包含在 SBOM 中。

要排除这些软件包，请在 ```conf/local.conf``` 中将 ```VIGILES_INCLUDE_CLOSED_LICENSES``` 设置为 "0" 或 "False"。


```
VIGILES_INCLUDE_CLOSED_LICENSES = "0"
```


### 在 SBOM 中排除本机和仅构建的软件包

要排除所有软件包（回填软件包除外（在 BitBake 流程期间构建但未列在 SBOM 中的软件包，因为它们可能不是最终 rootfs 清单或其软件包依赖项的一部分，例如 glibc）以及出现在 rootfs 清单中的软件包），请设置 VIGILES_SBOM_ROOTFS_MANIFEST_ONLY = "1"

**注意：** 这可能导致生成的 SBOM 不符合 NTIA 要求。

### 禁用 initramfs 镜像的 SBOM 和报告生成

可以在 local conf 中禁用 initramfs 镜像的 SBOM 和报告生成。

如果设置了 INITRAMFS_IMAGE，默认情况下会生成 Initramfs SBOM 和报告。

要禁用 initramfs SBOM 生成，请设置 VIGILES_DISABLE_INITRAMFS_SBOM = "1"

注意：如果禁用 Initramfs SBOM 生成，它将默认禁用 initramfs 报告生成。


```
VIGILES_DISABLE_INITRAMFS_SBOM = "1"
```


要仅禁用 initramfs 报告生成，请设置 VIGILES_DISABLE_INITRAMFS_REPORT = "1"


```
VIGILES_DISABLE_INITRAMFS_REPORT = "1"
```


### 设置 Vigiles 错误的错误级别

用户可以在 conf/local.conf 中配置 VIGLES_ERROR_LEVEL 来控制与 vigiles 检查相关的错误的记录方式。根据具体的用例，错误级别可以设置为 `FATAL`、`ERROR`、`WARNING` 或 `INFO`，以便将错误消息记录为 bitbake 的致命、错误、警告或普通日志。默认设置为 `INFO`。


```
VIGILES_ERROR_LEVEL = "FATAL"
```


### 指定用于生成报告的生态系统（仅限企业版 Vigiles）

可以指定生态系统以在漏洞报告中包含特定于该生态系统的漏洞。

此功能目前仅适用于企业版 Vigiles。

要指定使用的生态系统，请将 VIGILES_ECOSYSTEMS 设置为逗号分隔的生态系统字符串


```
VIGILES_ECOSYSTEMS = "Linux, Maven, PyPI, Ubuntu:20.04:LTS"
```


要包含所有生态系统，请将 VIGILES_ECOSYSTEMS 设置为 "all"


```
VIGILES_ECOSYSTEMS = "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 中。可以使用软件包配方中的以下自定义变量来实现：


```
LIFECYCLE_RELEASE_DATE = "2025-01-15"

LIFECYCLE_END_OF_LIFE   = "2027-01-15"

LIFECYCLE_SUPPORT_LEVEL = "Actively maintained"
```


这些值将被收集并包含在相应软件包的 SBOM 中。

您也可以使用 ```VIGILES_EXTRA_PACKAGES``` 中引用的 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
```


```LIFECYCLE_SUPPORT_LEVEL``` 和 CSV 列 level_of_support 的有效值均为：```Actively maintained```、```No longer maintained```、```Not available```、```Abandoned```。

### 指定漏洞报告格式

用户可以以各种格式导出漏洞报告。

要导出报告，请在 local.conf 中将 `VIGILES_EXPORT_FORMAT` 设置为以下任一选项：

- pdf
- pdfsummary
- xlsx
- csv
- cyclonedx-vex
- cyclonedx-sbom-vex


```
VIGILES_EXPORT_FORMAT = "pdf"
```


如果选择以 cyclonedx 格式导出报告，您需要指定额外的详细信息，如

`VIGILES_CYCLONEDX_FORMAT`

- json [默认]
- xml

`VIGILES_CYCLONEDX_VERSION`

- 1.6 [默认]
- 1.5
- 1.4


```
VIGILES_EXPORT_FORMAT = "cyclonedx-vex"

VIGILES_CYCLONEDX_FORMAT = "xml"

VIGILES_CYCLONEDX_VERSION = "1.5"
```


### 下载转换后的 SBOM

此选项允许将 vigiles 格式生成的 SBOM 转换为标准 SPDX 或 CycloneDX 格式。启用后，转换后的 SBOM 将下载到 `build/tmp/deploy/images//`。

#### 启用 SBOM 下载

要启用 SBOM 转换和下载，请将以下内容添加到 local.conf


```
VIGILES_ENABLE_DOWNLOAD_SBOM = "1"
```


如果启用，它将下载 CycloneDX 1.6 json 格式的 SBOM。要指定 SBOM 的规范、格式和版本，请参考以下内容：

#### 指定 vigiles 二进制文件的路径

如果设置了 `VIGILES_BIN_PATH` 变量，meta-timesys 将使用指定的二进制文件与 Vigiles 服务器通信并下载 SBOM。

如果未设置，meta-timesys 会自动使用 vigiles-cli-native 配方将 [vigiles-cli](https://github.com/TimesysGit/vigiles-cli) 安装到本机 sysroot 中，并默认使用它进行 SBOM 下载。

**注意：** 建议使用最新版本的 vigiles-cli。但是，如果需要使用旧版本，请确保其版本为 v1.0.3 或更高。

可以在 local.conf 中按如下方式指定路径


```
VIGILES_BIN_PATH = "/usr/local/bin/vigiles"
```


#### 选择 SBOM 规范

您可以使用 `VIGILES_DOWNLOAD_SBOM_SPEC` 选择目标 SBOM 规范。选择以下任一选项：

- spdx
- spdx-lite
- cyclonedx [默认]


```
VIGILES_DOWNLOAD_SBOM_SPEC = "spdx"
```


#### 选择输出格式

使用 `VIGILES_DOWNLOAD_SBOM_FORMAT` 指定转换后 SBOM 的输出格式：

**支持的 SPDX 格式：**

- tag
- json
- xlsx
- xls
- rdfxml
- yaml
- xml

**支持的 CycloneDX 格式：**

- json [默认]
- xml


```
VIGILES_DOWNLOAD_SBOM_FORMAT = "tag"
```


#### 选择输出版本

使用 `VIGILES_DOWNLOAD_SBOM_VERSION` 指定转换后 SBOM 的输出版本：

**SPDX 版本：**

- 2.2
- 2.3

**CycloneDX 版本：**

- 1.1
- 1.2
- 1.3
- 1.4
- 1.5
- 1.6 [默认]


```
VIGILES_DOWNLOAD_SBOM_VERSION = "2.3"
```


# 维护

Vigiles CVE 扫描器和 meta-timesys 由 [Lynx 安全团队](mailto:vigiles@timesys.com) 维护。

[Vigiles 网站](https://www.lynx.com/solutions/vulnerability-mitigation-management)

和

[meta-timesys @ GitHub](https://github.com/TimesysGit/meta-timesys)