verilyze/verilyze
GitHub: verilyze/verilyze
一款使用 Rust 编写的快速模块化软件组成分析（SCA）工具，专注于依赖漏洞检测。
Stars: 0 | Forks: 0
Find[Find manifests]
Find --> Parse[Parse dependencies]
Parse --> Resolve[Resolve versions]
Resolve --> CVE[Check CVEs]
CVE --> Report[Report results]
```
报告会包含每个易受攻击包的清单文件路径，因此您可以看到在扫描包含许多
嵌套清单（例如单体仓库）的目录时，是哪个清单引入了每个 CVE。
**可达性：** 根据 [architecture/PRD.md](architecture/PRD.md) FR-032，报告
最终可能会附加每个 CVE 的可达性标志。当前版本不会设置该字段，或在分析实现完成前省略该字段；严重性和 CVE 列表仍遵循记录的行为。
## 安装
预构建的二进制文件、crates.io 包、公共容器镜像和发布的发行包**目前尚不可用**。典型方法：
- **本地构建：** `make release`，然后运行 `target/release/vlz`（请参考快速入门）。
- **系统安装：** 使用可选的 `PREFIX` / `DESTDIR` 执行 `make install`。
- **软件包：** 通过 Makefile 目标构建 `.deb`、`.rpm`、AUR 制品或 Alpine APK；使用 `make docker` 构建 **本地** OCI 镜像。
完整命令、Docker 用法、可选提供程序和 Shell 补全：
[INSTALL.md](INSTALL.md)。
## Shell 补全
补全功能通过 **`make install`** 安装，或使用
`vlz generate-completions` 生成（请参考 [INSTALL.md](INSTALL.md#shell-completion)）。
## 配置优先级
选项按优先级顺序解析；每个来源会覆盖其下方的选项：
1. **CLI 标志**（例如 `--parallel 20`、`--cache-ttl-secs 86400`、`--min-score 7.0`）——最高优先级
2. **环境变量** `VLZ_*`（例如 `VLZ_PARALLEL_QUERIES=20`，
`VLZ_CACHE_TTL_SECS=86400`）
3. **用户配置文件**（`-c/--config <路径>` 或默认
`$XDG_CONFIG_HOME/verilyze/verilyze.conf`）
4. **系统配置**（`/etc/verilyze.conf`）——最低优先级
**缓存 TTL：** 修改 **cache_ttl_secs**（通过配置、环境变量或 CLI）只会影响
**新的**缓存条目；现有条目保留其存储的过期时间，直到它们
过期或被清除。请参考 [docs/configuration.md](docs/configuration.md) 和
`vlz db set-ttl` 以调整现有条目。
请参考 [architecture/PRD.md](architecture/PRD.md)（CFG-001 - CFG-008）和
[docs/configuration.md](docs/configuration.md) 中的完整关键表。运行
`vlz config --list` 以查看有效值。
**可选 CVE 提供程序的环境变量**（不会存储在配置中）：
| 变量 | 提供程序 | 用途 |
|------|----------|------|
| GITHUB_TOKEN | GitHub | 可选；更高的速率限制（Actions 会设置此值） |
| VLZ_GITHUB_TOKEN | GitHub | 覆盖 GITHUB_TOKEN |
| VLZ_SONATYPE_EMAIL | Sonatype | Sonatype OSS Index 所必需 |
| VLZ_SONATYPE_TOKEN | Sonatype | Sonatype OSS Index 所必需 |
## CLI 参考（摘要）
**帮助与手册：** `vlz --help` 会从 clap 打印简短用法摘要。
**`vlz help`** 通过运行嵌入的 **`vlz.1`** 打开完整手册
（在默认 `docs` 特性下构建时有效；否则退出 2 并给出提示）。
**`vlz help [子命令]`** 接受可选的子命令名称；目前它显示
与 `vlz help` 相同的主手册。执行 `make install` 后，**`man vlz`**
使用已安装的手册页。来源：[man/vlz.1](man/vlz.1)。
| 子命令 | 描述 |
|--------|------|
| `vlz scan [路径]` | 扫描清单和 CVE；可选路径（默认：当前工作目录） |
| `vlz list` | 列出已注册的语言插件 |
| `vlz config --list` | 显示有效配置 |
| `vlz config --example` | 输出 verilyze.conf.example 并附上当前环境的有效值 |
| `vlz config --set KEY=VALUE` | 设置配置键（例如 `python.regex="^requirements\\.txt$"`） |
| `vlz db list-providers` | 列出 CVE 提供程序（例如 osv、nvd、github、sonatype（在构建时启用相应特性时）） |
| `vlz db stats` | 缓存统计信息 |
| `vlz db show [--format FORMAT] [--full]` | 显示缓存条目（键、TTL、添加时间、CVE 摘要或完整负载） |
| `vlz db set-ttl SECS [--entry KEY] [--all] [--pattern PATTERN] [--entries KEYS]` | 更新现有缓存条目的 TTL |
| `vlz db verify` | 验证数据库完整性（SHA-256） |
| `vlz db migrate` | 运行迁移 |
| `vlz fp mark CVE-ID [--comment ...] [--project-id ID]` | 将 CVE 标记为误报（可选项目范围） |
| `vlz fp unmark CVE-ID` | 移除误报标记 |
| `vlz generate-completions SHELL` | 生成 Shell 补全脚本（bash、zsh、fish） |
| `vlz help [子命令]` | 显示完整手册（`vlz.1`），通过 `man`；子命令可选 |
| `vlz --version` |打印版本 |
**扫描选项（示例）：** `--format plain|json|sarif|cyclonedx|spdx`，
`--summary-file html:路径,cyclonedx:sbom.json,spdx:sbom.spdx.json`，
`--provider osv|nvd|github|sonatype`，`--parallel N`，`--project-id ID`，
`--cache-ttl-secs SECS`，`--offline`，`--benchmark`，`--min-score`，`--min-count`，
`--exit-code-on-cve`，`--fp-exit-code`，`--cache-db`，`--ignore-db`。
### 项目范围的误报
对于项目范围的误报：
1. 运行 `vlz fp mark CVE-ID --project-id X` 添加项目范围的误报；
2. 运行 `vlz scan --project-id X` 扫描该项目。
两个命令必须使用相同的 `project_id`，误报才会生效。
如果不使用 `--project-id`，则仅应用全局误报（标记时未指定 `--project-id`）。
## 退出代码
退出 0 表示分析成功完成且结果已知。任何
失败（配置、网络、解析等）都会返回非零代码，以防止
CI 中的误报。
| 代码 | 含义 |
|------|------|
| 0 | 成功：分析完成；无 CVE（或仅根据 fp-exit-code 的误报） |
| 1 | 恐慌 / 内部错误 |
| 2 | 配置错误（未知键、无效值等） |
| 3 | 缺少必需的包管理器 |
| 4 | 需要 CVE 查询但使用了 `--offline` |
| 5 | CVE 提供程序获取失败（网络、API 错误、认证等） |
| 86 | 一个或多个 CVE 达到阈值（可通过 `--exit-code-on-cve` 覆盖） |
## 错误报告与反馈
通过 **[GitHub Issues](https://github.com/verilyze/verilyze/issues)** 报告错误、回归或功能建议，以便
保持可搜索和可链接。对于**安全漏洞**，请使用
[SECURITY.md](SECURITY.md) 中的流程（私有报告），而非公开问题。
## 贡献者指南
首先运行 `make setup`。它会检查必需的系统工具（`python3`、`cargo`、
`shellcheck`）并引导非系统级开发者工具（`cargo-deny`、
`cargo-about`、`cargo-llvm-cov`、`cargo-afl`，以及 Python lint/test 虚拟环境）。
如果首次编译时提示缺少链接器，请安装 `gcc` + `ld.bfd`
（通常通过 `binutils`），然后重试。可通过每次调用覆盖默认设置，
例如 `CC=clang RUSTFLAGS="-Clink-arg=-fuse-ld=lld" make debug`。
在 Linux 上，如果覆盖率链接行为需要显式使用 GNU `ld.bfd`，请使用
`VLZ_COVERAGE_USE_BFD=1`，具体说明请参考
[CONTRIBUTING.md](CONTRIBUTING.md#running-tests-and-coverage)。
然后运行 `make check` 以通过标准的预提交检查。对于模糊测试
（烟雾测试、仅变更代码测试或扩展测试），请参考
[CONTRIBUTING.md](CONTRIBUTING.md)
（模糊测试，NFR-020）。
## 文档
- **安装与打包：** [INSTALL.md](INSTALL.md)
- **配置参考：** [docs/configuration.md](docs/configuration.md)
- **需求与架构：** [architecture/PRD.md](architecture/PRD.md)
- **执行流程：** [architecture/execution-flow.mmd](architecture/execution-flow.mmd)
- **常见问题与故障排除：** [docs/FAQ.md](docs/FAQ.md)
- **贡献指南：** [CONTRIBUTING.md](CONTRIBUTING.md)
- **AI 代理使用指南：** [AGENTS.md](AGENTS.md)
- **安全：** [SECURITY.md](SECURITY.md)
- **变更日志：** [CHANGELOG.md](CHANGELOG.md)
- **OpenSSF 最佳实践：** [bestpractices.dev 项目入口](https://www.bestpractices.dev/en/projects/12361)
标签：CI集成, CVE查询, GPL许可证, HTTP代理, Linux安全, LLM防护, Makefile构建, OSS安全, Rust, SCA工具, SLSA, 依赖漏洞扫描, 依赖管理, 可视化界面, 快速, 模块化, 离线扫描, 网络安全, 网络流量审计, 请求拦截, 软件供应链, 软件组成分析, 逆向工具, 通知系统, 隐私保护