nnatuan03/auto-scan-vuln-license
GitHub: nnatuan03/auto-scan-vuln-license
一款自动化依赖漏洞与许可证扫描工具，通过一条命令完成 SBOM 生成、漏洞检测与许可证规范化，并输出汇总报告。
Stars: 0 | Forks: 0
# 自动扫描漏洞与许可证
**目标：** 只需在源码目录下运行一条命令——工具会自动处理剩余的所有工作，从检测、生成 SBOM、扫描、规范化许可证，到生成最终报告。
## 目录
1. [快速开始](#bắt-đầu-nhanh)
2. [命令行界面](#giao-diện-dòng-lệnh)
3. [进度面板](#dashboard-tiến-độ)
4. [安装要求](#yêu-cầu-cài-đặt)
5. [支持的代码库类型](#các-loại-mã-nguồn-được-hỗ-trợ)
6. [扫描流程](#luồng-quét)
7. [ITS 文档对照](#đối-chiếu-tài-liệu-its)
8. [代码结构](#cấu-trúc-mã-nguồn)
9. [输出结果](#đầu-ra)
10. [使用报告](#sử-dụng-báo-cáo)
11. [排查结果缺失/错误](#gỡ-lỗi-khi-kết-quả-thiếusai)
12. [多生态系统测试矩阵](#ma-trận-kiểm-thử-đa-ecosystem)
13. [CLI 选项](#tùy-chọn-cli)
14. [安全与源码保护注意事项](#lưu-ý-bảo-mật--an-toàn-mã-nguồn)
15. [常见问题](#lỗi-thường-gặp)
## 快速开始
### Windows / PowerShell
```
.\run_scan.ps1 -Path "D:\Projects"
```
### 所有操作系统 — 直接使用 Python 运行
```
python autoscan.py "D:/Projects"
```
### `Path` 参数的含义
- 如果 `Path` 指向**单个项目**（包含 `pom.xml`、`package.json`、`pubspec.yaml` 等）—— 工具将扫描单个项目。
- 如果 `Path` 指向包含多个一级子服务的**父目录** —— 工具会自动检测每个服务，并行扫描并合并报告。
- 没有识别**标记**的一级目录仍会通过 `trivy fs` 进行扫描，并标记为 `kind = unknown`，以避免遗漏。
运行完成后，打开汇总报告：
```
D:\Projects\scan-results\consolidated-report.html
```
## 命令行界面
在扫描过程中，终端会为调用的**每个外部命令**（Maven、Gradle、npm/npx、Flutter、Trivy 等）实时打印日志，每组命令都有各自的颜色：
```
[RUN] trivy sbom --scanners vuln,license --format json ...
[OK ] exit=0 time=1.24s trivy sbom --scanners vuln,license --format json ...
[FAIL] exit=1 time=0.42s gradle cyclonedxBom
```
批量扫描时，将出现一个不断更新的**进度面板**（见下一节）。
完成后，终端会打印**摘要**：
```
Auto Scan Summary
=================
Root : D:\Projects
Run output : D:\Projects\scan-results\20260609-153000
Projects : 10
OK : 8
FAIL : 2
Report : D:\Projects\scan-results\20260609-153000\consolidated-report.html
Stable copy: D:\Projects\scan-results\consolidated-report.html
Debug : D:\Projects\scan-results\20260609-153000\debug-report.md
Stable dbg : D:\Projects\scan-results\debug-report.md
[OK ] backend-api [maven] vulns=4 licenses=87 sbom=ok
[OK ] web-portal [node] vulns=2 licenses=43 sbom=ok
[FAIL] legacy-app [gradle] vulns=0 licenses=0 sbom=fail
error: gradle cyclonedxBom exited with code 1
```
## 进度面板
每当一个服务完成或开始合并报告时，进度面板都会自动更新：
```
Auto Scan Dashboard
===================
Stage : scanning
Progress : [###############---------------] 5/10 ( 50.0%)
Status : DONE=5 OK=5 FAIL=0 RUNNING=5
Elapsed : 03:20
ETA : 03:20
```
- **Stage** —— 当前阶段：`scanning` 或 `merging`。
- **Progress** —— 文本进度条 + 百分比。
- **Status** —— 处于 `DONE` / `OK` / `FAIL` / `RUNNING` 状态的服务数量。
- **Elapsed / ETA** —— 已运行时间和预计剩余时间。
如果需要为 CI 保留精简日志，可以通过 `--no-dashboard` (CLI) 或 `-NoDashboard` (PowerShell) 关闭面板。
## 安装要求
### 必需项
| 组件 | 最低版本 | 备注 |
| --- | --- | --- |
| **Python** | **3.10+** | 工具使用了 `PEP 604` 语法 (`list[str] \| None`, `X \| Y`)。 |
| **Trivy** | 最新版 | 必须在 `PATH` 中可用。 |
| **PowerShell** | 5.1+ (Windows) | 仅在使用 `run_scan.ps1` 包装器时需要。 |
### 推荐项 —— 为了在各生态系统中获得更准确的 SBOM
| 生态系统 | 首选工具 | 回退机制 |
| --- | --- | --- |
| **Maven** | 项目中的 `mvnw` / `mvnw.cmd` | `PATH` 中的 `mvn` |
| **Gradle** | 项目中的 `gradlew` | `PATH` 中的 `gradle` |
| **Node.js** | `node`, `npm`, `npx` | — |
| **.NET** | `dotnet` | 如有缺失，自动安装 `dotnet-CycloneDX` |
| **Flutter** | `flutter` | — |
### 快速检查
```
python --version
trivy --version
```
### 配置 Python 环境
该工具**仅使用 Python 的标准库**，因此无需额外的 `pip install`。但是，为了保持环境的一致性和可重复性，建议使用代码库附带的 `requirements.txt` 文件（该文件仅包含指导注释——相当于为 `pip install -r requirements.txt` 提供“锚点”）。
```
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate
pip install -r requirements.txt
```
## 支持的代码库类型
| 生态系统 | 识别标记 |
| --- | --- |
| **Maven** | `pom.xml` |
| **Gradle** | `build.gradle`, `build.gradle.kts`, `settings.gradle`, `settings.gradle.kts`, `gradlew`, `gradlew.bat` |
| **Node.js** | `package.json`, `package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, `bun.lockb` |
| **Flutter** | `pubspec.yaml` |
| **.NET** | `.sln`, `.csproj` |
| **Python** | `requirements.txt`, `pyproject.toml`, `Pipfile`, `poetry.lock` |
| **Go** | `go.mod` |
| **PHP** | `composer.json`, `composer.lock` |
| **Ruby** | `Gemfile`, `Gemfile.lock` |
| **Unknown** | 没有标记的一级目录 —— 回退到 `trivy fs` |
如果没有专用的生成器或生成器报错，工具**始终会回退**到：
```
trivy fs --format cyclonedx
```
## 扫描流程
对于**每个**项目 / 服务：
1. 根据标记**检测代码库类型**。
2. 针对当前扫描**始终生成新的 SBOM** —— *不复用* 源码中已有的 SBOM，以避免重新扫描时出现旧结果。
3. **预构建内部 Maven lib**（如果扫描目录包含多个相互引用的 Maven 项目）：
- 读取所有 `pom.xml`，查找被同一源码目录下其他项目引用的 Maven 项目。
- 在扫描前，对内部 lib / parent 运行 `mvn clean install -DskipTests -Dmaven.test.skip=true -DskipITs`。
- 目标：确保本地 `.m2` 中包含完整的 `.jar` 和 `.pom`，避免因缺少内部 lib 元数据而导致服务扫描到旧版本的 dependency。
- 可以通过此选项跳过此步骤以进行快速调试：`--skip-maven-prebuild` (CLI) 或 `-SkipMavenPrebuild` (PowerShell)。
4. 如果存在合适的工具，则**根据生态系统生成 SBOM**：
| 生态系统 | 首选命令 | 备注 |
| --- | --- | --- |
| Maven | 优先使用 `mvnw.cmd` / `mvnw`，回退到 `mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom -DskipTests` | |
| Gradle | `gradlew cyclonedxBom` 或 `gradle cyclonedxBom` | 如果缺少插件，则使用临时 init script 应用 `org.cyclonedx.bom` v2.3.1 —— **不修改** `build.gradle.kts`。 |
| Node.js (npm lock) | `npx --yes @cyclonedx/cyclonedx-npm --ignore-npm-errors --package-lock-only` | |
| Node.js (yarn / pnpm / bun) | 回退到 `trivy fs` | |
| .NET | `dotnet-CycloneDX -j` | 如果缺少工具但存在 `dotnet`，会自动运行 `dotnet tool install --global CycloneDX`。 |
| Flutter / Python / Go / PHP / Ruby / unknown | 回退到 `trivy fs` | |
如果专用生成器失败或未生成新的 SBOM → 回退到 `trivy fs --format cyclonedx`。
5. 将 SBOM 中的版本与在当前源码 / lock file 中找到的最新版本进行 **核对(Reconcile)**。例如：Node 同时有 `package-lock.json` 和 `yarn.lock`，如果 SBOM 输出为 `1.80.0`，但 `package.json` / `yarn.lock` 处于 `1.84.0` —— 工具会在扫描前将 SBOM 更新为 `1.84.0`。工具**不会主动查询 registry** 来升级源码之外的 dependency。
6. 将许可证**规范化**到 `SBOM.cdx-fix.json`。
7. 对每个服务**仅运行一次 Trivy**：
- `trivy sbom --scanners vuln,license --format json` → `report.json`。
- 从 `report.json` 中提取出 `license.json`、`license.txt`、`vuln.json`。
- 这种方式保持了与之前相同的输出，但减少了每个服务调用 Trivy 的次数。
8. 将 `SBOM.cdx-fix.json` 中的许可证与 `report.json` / `license.json` 进行**比对**；如果 Trivy 返回的 package 许可证缺失，工具会自动从 SBOM 中补充。未声明许可证的组件将显示为 `LicenseRef-No-Declared-License`，以防止其被“静默遗漏”。
9. 为每个服务**生成 HTML 报告**：
- `report.html`
- `report-vuln.html`
10. 将所有服务**合并**为 `consolidated-report.html`。
11. **生成调试报告** `debug-report.md` / `debug-report.json`，用于对照文档并调试各个服务。
## ITS 文档对照
该工具覆盖了文档中的许可证 / dependency 扫描用例，不包括已排除在范围之外的部分：
| 文档中的用例 | 工具的处理方式 |
| --- | --- |
| Trivy dependency vulnerability scan | 运行 `trivy sbom --scanners vuln --format json`，随后生成 `report-vuln.html`。 |
| Gradle license scan | 运行 `gradlew / gradle cyclonedxBom`；如果缺少插件，则使用带有 `org.cyclonedx.bom` v2.3.1 的临时 init script。 |
| Maven license scan | 如果其他服务依赖于源码目录中的内部 Maven lib，则进行预构建 / install，随后运行 `mvnw / mvn org.cyclonedx:cyclonedx-maven-plugin:makeAggregateBom`。 |
| Node.js npm / package-lock license scan | 运行 `npx --yes @cyclonedx/cyclonedx-npm --ignore-npm-errors`；如果存在 npm lock，则使用 `--package-lock-only`。 |
| .NET license scan | 如有缺失则自动安装 `CycloneDX`，然后在 `.sln` / `.csproj` 上运行 `dotnet-CycloneDX`。 |
| Normalize SBOM trước khi scan license | 通过内部 normalize 模块创建 `SBOM.cdx-fix.json`。 |
| License TXT / JSON | 为每个服务创建 `license.txt` 和 `license.json`。 |
### 有意为之的差异
- 每次扫描都会在 `scan-results\` 中生成新的 SBOM，**不写入 / 不将 dependency 放入 `third-party`**，以避免重新扫描时使用旧的 SBOM。
- Gradle **不修改** `build.gradle` / `build.gradle.kts`；临时 init script 仅保留在输出目录中。
- `report-vuln.html` 是使用**内部模板**从 `vuln.json` 生成的，而不是使用 Trivy 的 `html.tpl`。
- 根据确定的范围，当前已排除 SonarQube 以及 CI/CD / Jenkins / email 脚本。
## 代码结构
```
auto-scan-vuln-lic/
├── autoscan.py # Entrypoint chính, nhận path và điều phối quét
├── run_scan.ps1 # Wrapper PowerShell trên Windows
├── README.MD # File này
├── requirements.txt # Cài đặt môi trường Python (xem chi tiết)
│
├── autoscan/
│ ├── __init__.py
│ ├── batch.py # Quét nhiều project / service song song và gộp báo cáo
│ ├── config.py # Hằng số cấu hình, marker hệ sinh thái, ignore-dir
│ ├── debug_report.py # Sinh debug report đối chiếu tài liệu, marker, command, count SBOM / license
│ ├── dependency_health.py # Phát hiện lock file thiếu / cũ và mismatch manifest ↔ lock trước khi sinh SBOM
│ ├── detector.py # Tự phát hiện Maven, Gradle, Node, Flutter, .NET, Python, Go, PHP, Ruby
│ ├── license_inventory.py # Bù license từ SBOM vào report nếu Trivy không trả đủ dòng license
│ ├── license_normalizer.py # Chuẩn hóa license SBOM về SPDX / LicenseRef
│ ├── license_rules.py # Bộ rule normalize license từ tên vendor / free-text về SPDX ID
│ ├── maven_prebuild.py # Prebuild / install lib Maven nội bộ trước khi quét
│ ├── models.py # Dataclass: Project, CommandRecord, ScanResult
│ ├── package_names.py # Khôi phục package name bị thiếu từ PURL, PkgID, node_modules path, license file path, Target
│ ├── progress.py # Dashboard terminal: tiến độ %, elapsed, ETA
│ ├── sbom_generator.py # Sinh SBOM theo từng loại mã nguồn, fallback `trivy fs`
│ ├── scanner.py # Quét một project / service
│ ├── terminal.py # In command, status, màu terminal / PowerShell
│ ├── trivy_runner.py # Chạy Trivy và sinh output JSON / TXT
│ ├── utils.py # Tiện ích chung: subprocess, JSON, ensure_dir, copy_file
│ ├── version_reconciler.py # Đối chiếu version SBOM với lock file / manifest hiện tại
│ └── reporting/
│ ├── __init__.py
│ ├── merge_report.py # Engine sinh report HTML tổng hợp
│ ├── reports.py # Facade gọi generator single / merged
│ └── single_report.py # Engine sinh report HTML cho từng service
│
└── tests/
└── ecosystem_matrix.py # Tạo fixture nhiều ecosystem để test detect / dependency-health / report recovery
```
## 输出结果
### 运行示例
```
python autoscan.py "D:/Projects"
```
### 结果目录结构
```
D:\Projects\scan-results\
├── consolidated-report.html # Bản ổn định (ghi đè) trỏ tới lần chạy mới nhất
├── scan-summary.json # Bản ổn định
├── debug-report.md # Bản ổn định
├── debug-report.json # Bản ổn định
│
└── 20260609-153000\ # Thư mục theo timestamp mỗi lần chạy
├── consolidated-report.html
├── scan-summary.json
├── debug-report.md
├── debug-report.json
└── services\
├── backend-api\
│ ├── SBOM.cdx.json
│ ├── SBOM.cdx-fix.json
│ ├── license-normalize.log
│ ├── report.json
│ ├── report.html
│ ├── report-vuln.html
│ ├── license.json
│ ├── license.txt
│ ├── vuln.json
│ └── scan.log
└── web-portal\
└── ...
```
### 重要文件
| 文件 | 作用 |
| --- | --- |
| `consolidated-report.html` | 最终的汇总报告 —— 打开此文件查看全貌。 |
| `scan-summary.json` | 机器可读的摘要：OK / FAIL，统计 vuln / license，各个服务的输出路径。 |
| `debug-report.md` | Markdown 格式的调试报告：文档对照、检测到的服务、已执行的命令、SBOM / license 计数。 |
| `debug-report.json` | JSON 格式的调试报告 —— 在需要后续追踪时用于发送 / 解析。 |
| `services\\scan.log` | 详细的命令日志，用于调试。 |
| `services\\license-normalize.log` | 统计 SBOM 中拥有许可证的组件数量以及已规范化的许可证。 |
## 使用报告
打开文件：
```
scan-results\consolidated-report.html
```
报告包含：
- vulnerability / license 的**概览**。
- **vulnerability 表格** —— 按 package、severity、category、action 进行筛选。
- **license 表格** —— 进行类似筛选，但没有 category / action 列。
- **导出 Excel** —— 报告中直接提供 **Export Excel** 按钮。
### 导出 Excel
HTML 报告内置了 **Export** 按钮。Excel 文件将下载到本地。特点：
- `Severity` 带有颜色标识：
- `CRITICAL` —— 深红色
- `HIGH` —— 红色
- `MEDIUM` —— 黄色
- `LOW` —— 绿色
- 如果每个 package 有多行（例如：多个 CVE），这些行会**合并**在顶部，以便于阅读。
- `License` 工作表**移除**了 `Category` 和 `Action` 列。
## 排查结果缺失/错误
### 第 1 步 —— 先进行 Dry-run
运行 dry-run 以查看工具检测到了多少个服务：
```
python autoscan.py "D:/Projects" --dry-run
```
### 第 2 步 —— 打开调试报告
```
D:\Projects\scan-results\debug-report.md
```
按顺序检查：
| 调试项 | 检查内容 |
| --- | --- |
| `Document Coverage` | 哪些用例已覆盖，哪些是有意与文档不同，哪些被排除了。 |
| `Services` | 检测到了哪些服务，属于什么类型，基于什么标记，通过哪个生成器生成的 SBOM。 |
| `Maven Prebuild` | 在扫描前有哪些内部 Maven lib / parent 被 `mvn clean install`，哪些命令失败了。 |
| `Dependency health` | 警告缺失的 lock file、manifest 中声明但 lock 中缺失的 dependency，或者 manifest 版本高于 lock 版本的情况。 |
| `Commands` | 实际执行的命令及其 exit code。 |
| `Retry / fallback note` & `Command failures` | 后续失败 / 成功的命令，并附带 stderr 尾部信息 —— 用于查看回退原因。 |
| `Pkg name recovery` | 原始报告缺失 package name 的行数，工具恢复的行数，以及仍然未知的行数。 |
| `Version updates` | SBOM 中被升级到源码 / lock file 里找到的更高版本的组件数量。 |
| `Fixed components` | `SBOM.cdx-fix.json` 中的组件数量；如果数量本身缺失，则错误出在生成 SBOM 的步骤。 |
| `SBOM license rows` & `Trivy licenses` | 如果 SBOM 具备完整的 license rows 但 Trivy 缺失，工具会将其 backfill（回填）到报告中。 |
### 常见的 dependency health 状态
| 状态 | 含义 |
| --- | --- |
| `DEPENDENCY_HEALTH_OK` | 在工具支持的用例中未发现 manifest / lock 不匹配的情况。 |
| `LOCK_FILE_MISSING` | 有 manifest (`package.json`, `pubspec.yaml`, `composer.json`, `Gemfile`, …) 但缺少相应的 lock file。 |
| `MANIFEST_LOCK_MISMATCH` | manifest 要求更高的版本，但 lock 依然解析为旧版本 —— 扫描将以 lock / SBOM 为准。 |
| `LOCK_DEPENDENCY_MISSING` | manifest 声明了 dependency，但 lock 中不存在该 dependency。 |
| `UNPINNED_DEPENDENCY` | Python `requirements.txt` 中的 dependency 没有通过 `==` 指定固定版本 (pin)。 |
| `BUILD_FILE_MISSING` | 找不到足以根据生态系统解析 dependency 的 build / dependency manifest。 |
## 多生态系统测试矩阵
运行本地测试夹具，**无需安装** Maven / Gradle / Flutter / PHP / Go：
```
python tests/ecosystem_matrix.py
```
测试会自动生成 **Maven, Gradle, Node, Flutter, .NET, Python, Go, PHP, Ruby** 以及 `unknown source` 的示例代码。它验证了以下用例：
- Lock file 正常。
- 缺失 Lock file。
- manifest 声明的版本高于 lock。
- manifest 中的 dependency 在 lock 中缺失。
- Python dependency 未指定固定版本。
- 报告恢复了缺失的 package name。
## CLI 选项
### 常见示例
```
# 增加并行扫描的 worker 数量
python autoscan.py "D:/Projects" --max-workers 6
# 增加嵌套 project 的搜索深度（对 monorepo、位于 apps/ packages/ frontend/ 的 frontend 很有用）
python autoscan.py "D:/Projects" --recursive-depth 4
# 跳过单独的 generator，仅使用 trivy fs
python autoscan.py "D:/Projects" --trivy-only
# 仅 detect，不运行 Trivy / 外部 tool
python autoscan.py "D:/Projects" --dry-run
# 关闭 dashboard 进度（为 CI 简化 log）
python autoscan.py "D:/Projects" --no-dashboard
# 不在 terminal 中打印每个 command，关闭颜色
python autoscan.py "D:/Projects" --hide-commands --no-color
# 更改 output folder
python autoscan.py "D:/Projects" --output "D:/Audit/scan-results"
```
### 选项表格
| 选项 | 描述 |
| --- | --- |
| `--max-workers` | 并行扫描的项目数。默认为 `4`。 |
| `--recursive-depth` | 查找子项目 / 嵌套项目的深度。默认为 `5`。 |
| `--trivy-only` | 跳过 Maven / Gradle / Node / .NET 生成器，仅使用 `trivy fs`。 |
| `--skip-maven-prebuild` | 跳过扫描前针对内部 Maven lib 的 `mvn clean install` 步骤。仅建议在快速调试时使用。 |
| `--dry-run` | 仅检测项目，不运行 Trivy 或任何外部工具。 |
| `--output` | 更改默认输出文件夹 (`/scan-results`)。 |
| `--no-dashboard` | 在终端中关闭进度面板。 |
| `--hide-commands` | 不在终端中打印每一条命令。 |
| `--no-color` | 关闭终端颜色。 |
### PowerShell 包装器 —— 对应选项
```
.\run_scan.ps1 -Path "D:\Projects" -MaxWorkers 6 -RecursiveDepth 4
.\run_scan.ps1 -Path "D:\Projects" -TrivyOnly
.\run_scan.ps1 -Path "D:\Projects" -SkipMavenPrebuild
.\run_scan.ps1 -Path "D:\Projects" -DryRun
.\run_scan.ps1 -Path "D:\Projects" -NoDashboard
.\run_scan.ps1 -Path "D:\Projects" -HideCommands -NoColor
```
## 安全与源码保护注意事项
- **默认不修改源码。** 所有附属产出物 (`build/`, `target/`, `SBOM.cdx.json`, …) 都位于输出目录中。
- **Gradle：** 如果 task / plugin 已存在，则优先使用 `cyclonedxBom`。如果缺少插件，工具会在输出目录中创建**临时 init script** 以根据文档应用 CycloneDX 插件；**不修改** `build.gradle.kts`。
- **Node.js：** 如果存在 `package-lock.json` / `npm-shrinkwrap.json`，则使用 `cyclonedx-npm --package-lock-only` 以**不依赖** `node_modules`。如果是 yarn / pnpm / bun，则回退到 `trivy fs` 读取相应的 lock。如果既没有 lock file 也没有 `node_modules`，报告将仅依赖于 Trivy 从源码读取到的信息 —— 因此请提交 lock file 以扫描完整的 dependency。
- **Node.js 包含多个 lock file：** 根据 `package.json`、`package-lock.json`、`npm-shrinkwrap.json` 和 `yarn.lock` 中找到的**最高版本**核对 SBOM，避免旧 lock 导致报告输出的版本低于当前源码。
- **Frontend monorepo / workspace：** 会继续在 `apps/`、`packages/`、`frontend/` 等目录中寻找子项目，而不是在父级 `package.json` 处停止。
- **Flutter mobile：** 扫描 Flutter 根目录，并**跳过** `android`、`ios`、`web`、`windows`、`linux`、`macos` 等平台文件夹，不将其视为独立项目，以避免子目录导致报告版本重复 / 累加。如果 `packages/` 中的 Flutter package 包含 `pubspec.yaml`，仍会被单独检测。
- **Maven / Gradle / .NET：** 可能会根据原始工具的机制在 `target/`、`build/` 或 SBOM 输出中生成文件。
- **所有命令均通过参数列表执行**（使用 `subprocess.run([...])`），**不使用 shell 字符串拼接** —— 避免在 `path` 包含特殊字符时出现注入风险。
## 常见问题
### Frontend 扫描缺失 package
按顺序检查：
1. 运行 `--dry-run` 查看工具是否检测到了所有子应用 (`apps/web`, `packages/ui`, `frontend/admin`, …)。
2. **建议提交 lock file** (`package-lock.json`, `npm-shrinkwrap.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, `bun.lockb`)。如果仅有 `package.json`，工具无法获知完整的 transitive dependency / version。
3. 如果前端应用嵌套层级超过 5 层，请增加 `--recursive-depth`。
4. 如果使用 npm 并且存在 `package-lock.json`，工具将使用 `--package-lock-only` —— **不需要** `node_modules`。
5. 如果终端 / CI 设置了 `NODE_ENV=production`，Node SBOM 生成器仍会在取消设置 `NODE_ENV` 的情况下运行，以免自动忽略 `devDependencies`。
### License 扫描缺失 package
按顺序检查：
1. 打开 `services\\license-normalize.log` —— `Components total` 和 `Components with licenses` 行显示了 SBOM 中包含的组件 / 许可证数量。
2. 如果 SBOM 包含许可证，但 Trivy 没有在 `license.json` 中全部返回，工具会**自动将** `SBOM.cdx-fix.json` 中缺失的行补充到 `report.json` 和 `license.json` 中。
3. 如果组件在 SBOM 中**没有许可证**，报告将显示带有 `UNKNOWN` 严重程度的 `LicenseRef-No-Declared-License`，以便审核人员手动处理。
4. 如果 `Components total` 已经缺少 package，原因在于生态系统的**生成 SBOM / 生成器**步骤 —— 而不是报告。
### `trivy not found in PATH`
安装 Trivy 并打开新的终端：
```
trivy --version
```
官方安装指南：\services\\scan.log
```
### Export Excel 按钮无效
HTML 报告正在从 CDN 加载 `xlsx-js-style` 库。计算机需要访问互联网，或者在内部环境中预先缓存 CDN。
## 许可证
内部工具 —— 关于使用和分发方式，请参考您所在组织的政策。
标签：AI合规, SBOM, 依赖管理, 后台面板检测, 多人体追踪, 安全合规, 开源许可协议, 暗色界面, 硬件无关, 网络代理, 逆向工具