Tatos23/sbom-generator

# SBOM 生成器 一款命令行工具，用于扫描 Python 和 Java 项目，解析传递依赖，生成 CycloneDX 和 SPDX 格式的 SBOM，可视化依赖图，并生成 CVE 漏洞报告。这与美国第 14028 号行政令直接相关，该行政令要求销售给美国联邦政府的软件必须提供 SBOM。 ## 前置条件 - [Docker Desktop](https://www.docker.com/products/docker-desktop/)（必须处于运行状态） - [Git](https://git-scm.com/)）（扫描 GitHub URL 时需要） 无需安装 Python 或 Java —— 一切均在 Docker 中运行。 ## 快速开始 **1. 克隆仓库** ``` git clone https://github.com/GUC-CSEN1001-S26/project-team077.git cd project-team077 ``` **2. 创建所需的文件夹和环境文件** ``` # Windows PowerShell mkdir projects, output New-Item .env # macOS / Linux mkdir -p projects output && touch .env ``` **3. 构建 Docker 镜像（仅需一次）** ``` docker compose build ``` **4. 运行你的第一次扫描** ``` docker compose run --rm sbom-generator scan /projects/ ``` ## 项目结构 ``` project-team077/ ├── src/ ← Tool source code ├── projects/ ← Place local projects here to scan them ├── output/ ← All generated files are saved here ├── Dockerfile ├── docker-compose.yaml ├── requirements.txt ├── README.md ← This file (user guide) └── ONBOARDING.md ← Developer architecture guide ``` 要扫描本地项目，请将其复制或克隆到 `projects/` 文件夹中： ``` projects/ ├── my-python-app/ │ └── requirements.txt └── my-java-app/ └── pom.xml ``` ## CLI 命令 ### `scan` — 检测并列出所有依赖项 ``` docker compose run --rm sbom-generator scan /projects/ ``` 选项： ``` --json Machine-readable JSON output --search-depth INTEGER How deep to search for manifest files (default: 3) ``` 示例： ``` docker compose run --rm sbom-generator scan /projects/my-python-app docker compose run --rm sbom-generator scan /projects/my-python-app --search-depth 5 ``` ### `sbom` — 生成软件物料清单 ``` # CycloneDX JSON（默认） docker compose run --rm sbom-generator sbom /projects/ --format cyclonedx -o /output/bom.json # CycloneDX XML docker compose run --rm sbom-generator sbom /projects/ --format cyclonedx-xml -o /output/bom.xml # SPDX 3.0 JSON-LD docker compose run --rm sbom-generator sbom /projects/ --format spdx -o /output/bom.spdx.json # SPDX 3.0 tag-value docker compose run --rm sbom-generator sbom /projects/ --format spdx-tv -o /output/bom.spdx.tv ``` 选项： ``` --format cyclonedx | cyclonedx-xml | spdx | spdx-tv (default: cyclonedx) -o / --output Output file path --no-scan-vulns Skip vulnerability scan (faster) --no-validate Skip schema validation --search-depth INTEGER Manifest search depth (default: 3) ``` 生成的文件将保存到你本地的 `output/` 文件夹中。 ### `graph` — 可视化依赖图 ``` docker compose run --rm sbom-generator graph /projects/ -o /output/graph ``` 自动在给定路径保存 `graph.png` 和 `graph.pdf`。 选项： ``` -o / --output Output path without extension (default: /output/graph) --max-depth Limit visualization depth --search-depth Manifest search depth (default: 3) ``` ### `check` — 扫描 CVE 漏洞 ``` docker compose run --rm sbom-generator check /projects/ -o /output/report.pdf ``` 针对 OSV 漏洞数据库扫描**直接和传递依赖项**，并生成按严重程度（CRITICAL → HIGH → MEDIUM → LOW）排序的 PDF 报告。 选项： ``` -o / --output Output path for PDF report --fail-on Exit with code 1 if vulnerabilities at or above this severity are found Choices: critical | high | medium | low | none (default: none) --json Output results as JSON instead of a table (useful in CI/CD) --search-depth Manifest search depth (default: 3) ``` 示例 — 在出现 HIGH 或 CRITICAL 时中断 CI pipeline： ``` docker compose run --rm sbom-generator check /projects/ --fail-on high -o /output/report.pdf ``` ### `shell` — 交互模式 在单个 container 会话中运行多个命令： ``` docker compose run --rm -it sbom-generator shell ``` 然后在内部执行： ``` sbom-gen> scan /projects/my-java-app sbom-gen> sbom /projects/my-java-app --format cyclonedx -o /output/bom.json sbom-gen> check /projects/my-java-app --fail-on high -o /output/report.pdf sbom-gen> graph /projects/my-java-app -o /output/graph sbom-gen> exit ``` ## 扫描 GitHub 仓库 直接传入任何公开的 GitHub URL —— 该工具会自动克隆它，无需本地副本： ``` docker compose run --rm sbom-generator scan https://github.com/pallets/flask docker compose run --rm sbom-generator sbom https://github.com/pallets/flask --format cyclonedx -o /output/bom.json docker compose run --rm sbom-generator check https://github.com/spring-projects/spring-petclinic -o /output/report.pdf docker compose run --rm sbom-generator graph https://github.com/apache/kafka -o /output/graph ``` ## 输出文件 | 命令 | 输出文件 | 格式 | |---|---|---| | `sbom --format cyclonedx` | `bom.json` | CycloneDX 1.7 JSON | | `sbom --format cyclonedx-xml` | `bom.xml` | CycloneDX 1.7 XML | | `sbom --format spdx` | `bom.spdx.json` + `.ttl` + `.rdf` | SPDX 3.0 JSON-LD + RDF 导出 | | `sbom --format spdx-tv` | `bom.spdx.tv` | SPDX 3.0 tag-value | | `graph` | `graph.png` + `graph.pdf` | 依赖图 | | `check` | `report.pdf` | CVE 漏洞报告 | 所有文件都会出现在你本地的 `output/` 目录中。 ## 支持的生态系统 ### Python | 清单 / Lockfile | 处理方式 | |---|---| | `uv.lock` | 精确锁定的版本 + 完整依赖图 | | `Pipfile.lock` | 精确锁定的版本 | | `requirements.txt` | 通过 PyPI API 解析的版本约束 | | `pyproject.toml` | `[project.dependencies]`、可选依赖、PEP 735 分组 | | 无清单 | AST 导入扫描回退 | ### Java | 清单 / Lockfile | 处理方式 | |---|---| | `pom.xml` | Maven — 解析 `${property}` 占位符，跳过 test/provided 作用域 | | `build.gradle` / `build.gradle.kts` | Gradle — 优先使用 lockfile，回退到 regex 解析 | | `lib/*.jar` | JAR 扫描 — 读取内嵌的 `pom.properties` | | 无清单 | 通过 Maven Central 搜索推断 Java 导入 | 混合项目（一个仓库中同时包含 Python 和 Java）会被检测到并同时进行解析。 ## 演示日准备 ### 必需环境 在演示之前，请在你的 `projects/` 文件夹中准备**三个本地项目**： | 环境 | 所需文件 | 展示内容 | |---|---|---| | 仅 Python | `requirements.txt` 或其他 Python 清单 | `scan`、`sbom`、`graph`、`check` | | 仅 Java | `pom.xml` 或 `build.gradle` — **无 lock 文件** | `scan`、`sbom`、`graph`、`check` | | Python + Java 混合 | 同一仓库中同时包含 Python 和 Java 清单 | 演示同时检测 | **演示前：** 确保最新版本的代码已推送到 GitHub —— 助教们将在会议期间审查该仓库。 ### 必需交付物 演示必须展示至少一个项目的这四个输出文件： | # | 文件 | 如何生成 | |---|---|---| | 1 | `bom.json` — CycloneDX JSON | `sbom --format cyclonedx -o /output/bom.json` | | 2 | `bom.xml` — CycloneDX XML | `sbom --format cyclonedx-xml -o /output/bom.xml` | | 3 | `graph.pdf` — 依赖图 | `graph -o /output/graph` | | 4 | `report.pdf` — CVE 漏洞报告 | `check -o /output/report.pdf` | ### 快速演示脚本 ``` # 1. 扫描依赖项 docker compose run --rm sbom-generator scan /projects/ # 2. 生成 CycloneDX SBOM（JSON + XML — 两者均为必需） docker compose run --rm sbom-generator sbom /projects/ --format cyclonedx -o /output/bom.json docker compose run --rm sbom-generator sbom /projects/ --format cyclonedx-xml -o /output/bom.xml # 3. 可视化依赖图（保存 graph.png + graph.pdf） docker compose run --rm sbom-generator graph /projects/ -o /output/graph # 4. 生成 CVE 漏洞报告 docker compose run --rm sbom-generator check /projects/ -o /output/report.pdf ``` ## 基础需求之外 超越最低规范实现的功能： | 功能 | 描述 | |---|---| | **SPDX 3.0 SBOM** | 完整的 SPDX 3.0 JSON-LD 输出，带有自动的 RDF（`.ttl`、`.rdf`）导出和 schema 验证 | | **SPDX tag-value** | 人类可读的 SPDX 3.0 tag-value（`.spdx.tv`）格式 | | **交互式 shell** | `shell` 命令 — 在一个 container 会话中运行多次扫描，无需重新启动 Docker | | **GitHub URL 扫描** | 直接传入任何公开的 GitHub URL；工具会自动克隆它 | | **无清单扫描** | 当不存在清单时，回退到 AST 导入扫描（Python）和 Maven Central 推断（Java） | | **`--search-depth`** | 可配置的清单搜索深度，适用于深度嵌套的 monorepo | | **混合生态系统检测** | 同时检测同一仓库中的 Python 和 Java | | **CVSS 评分** | OSV 漏洞结果包含 CVSS 严重性评分，并按 CRITICAL → HIGH → MEDIUM → LOW 排序 | | **CI/CD 集成** | `--fail-on` 标志在出现 high/critical 结果时以退出码 1 退出；`--json` 标志用于机器可读的输出 | ## 实用技巧 **屏蔽孤立的 container 警告：** ``` docker compose run --rm --remove-orphans sbom-generator scan /projects/ ``` **更深入地搜索嵌套的清单**（例如深度 2 处的 `backend/requirements.txt`）： ``` docker compose run --rm sbom-generator scan /projects/ --search-depth 5 ``` **代码修改后重新构建镜像：** ``` docker compose build ``` ## 团队贡献 | 成员 | 部分 | 职责 | |---|---|---| | **Abdelrahman Ewida** | §1–2 (Python 解析器), §4 | Python 解析器（uv.lock、Pipfile.lock、requirements.txt、pyproject.toml），通过 PyPI 解析版本约束；许可证检测与元数据扩充（下载 URL、主页、维护者、SHA-256 校验和、SPDX 映射、许可证标志） | | **Abdullah Ahmed** | §1–2 (Python 解析器), §5B, §6 | Python 解析器（共享）；SPDX 3.0 SBOM 生成（JSON-LD、tag-value、RDF 导出）、schema 验证；OSV 漏洞扫描器（与 Hana 共享）、CVSS 评分、PDF 漏洞报告 | | **Hana Seif** | §1–2 (Java 解析器), §5A, §6 | Java 解析器（Maven pom.xml、Gradle、JAR 扫描、源码导入推断）；CycloneDX 1.7 SBOM 生成（JSON + XML）、schema 验证；OSV 漏洞扫描器（与 Abdullah 共享） | | **Farah Faisal** | §1–2 (Java 解析器), §3 | Java 解析器（共享）；传递依赖解析（PyPI + Maven API）、依赖图构建、冲突与循环检测、NetworkX PNG + PDF 可视化 |

标签：Python, SBOM生成, WebSocket, 依赖分析, 无后门, 版权保护, 特权检测, 请求拦截, 逆向工具