mimecast/sbom-graph

 ## 工具概述与功能 该工具处理从软件物料清单（SBOM）文件生成的依赖图，并提供预配置的报告和可视化功能，以提供可操作的洞察。其主要功能包括： 漏洞影响分析：识别受漏洞影响的项目，并根据相互依赖关系确定修复优先级（例如，确定必须先更新哪些项目以避免连锁反应）。 检测不良实践： - 版本锁定错误，如果执行不当可能会导致运行时错误。 - 循环依赖。 - 非语义化版本控制（Non-SemVer）。 - 在生产版本中使用 SNAPSHOT 版本。 从 AppSec、架构和工程的角度来看，这些报告有助于发现设计缺陷、不良实践和错误。该工具在零日漏洞场景中特别有价值，能够快速识别所有受影响的项目和依赖项。 战略潜力与未来增强 该工具还具有进一步增强的潜力，即通过额外的数据点来丰富图谱。例如，通过纳入诸如库的安全性和质量评级等指标，我们可以实现高级的依赖威胁建模。这将允许您通过用更健壮的替代方案替换安全性较低的库，来主动识别和降低风险。 该项目由 5 部分组成： 1. **sbom-graph-model** -- 一个用于处理 CycloneDX 和 SPDX 文件并将其存储在 GraphDB 中的 Python 库 2. **sbom-graph-api** -- 一个 Flask 应用程序，用于可视化图数据、通过经过身份验证的 API 摄取 SBOM（CycloneDX 和 SPDX），并提供有关依赖关系、漏洞、许可证、策略合规性和供应链信任分数的报告 3. **sbom-graph-enrichment** -- 一个基于 Celery 的异步富化流水线，查询外部 API（OSV、ClearlyDefined、OpenSSF Scorecard、Sonatype OSS Index、deps.dev、endoflife.date）以丰富包元数据并计算信任分数 4. **sonatype-lifecycle-release-listener** -- 用于 SCA 扫描的发布监听器，用于检索 CycloneDX 文件并进行处理 5. **sbom-graph-cli** -- 用于摄取、查询、策略注释和报告导出（脚本和 CI/CD）的命令行界面 有关详细的架构文档，请参阅 [SPECIFICATION.md](SPECIFICATION.md)。 有关完整的部署演练（前置条件、TLS 设置、Helm 配置、本地和远程 Kubernetes），请参阅 [GETTING_STARTED.md](GETTING_STARTED.md)。 ### 功能 - **多格式 SBOM 摄取**：通过 REST API 上传 CycloneDX 和 SPDX 2.3 SBOM（`POST /ingest/cyclonedx`、`POST /ingest/spdx`、`POST /ingest/sbom` 用于自动检测）；响应中使用 `record_id` 跟踪 SBOM 来源；所有入站 payload 均根据 JSON Schema (Draft-07) 进行验证 - **漏洞富化**：持续从 OSV.dev 和 Sonatype OSS Index 进行富化，在摄取后发现新的 CVE - **许可证跟踪和合规性**：从 SBOM 中提取许可证并通过 ClearlyDefined 进行富化，按风险类别（Copyleft、Weak Copyleft、Permissive）分组，并进行冲突检测 - **VEX 支持**：摄取 OpenVEX 文档以传达漏洞是否实际影响产品，并提供覆盖率统计 - **补丁规划和爆炸半径**：针对漏洞的前沿级补丁规划，以及针对受损包的爆炸半径分析 - **策略注释**：将包标记为批准/拒绝/保留（certifyBad/certifyGood），并提供用于二进制授权的 CI/CD 门控 endpoint - **源代码仓库跟踪**：将包链接到其源代码仓库，用于来源检查和记分卡查找 - **供应链信任分数**：来自 OpenSSF Scorecard、OSV、Sonatype OSS Index 和 deps.dev 的综合信任分数，具有继承的风险传播和下降警报功能（请参阅[下方的专属章节](#supply-chain-trust-score)) - **可视化**： - 具有颜色编码分区级别的 K-Partite 依赖可视化 - 项目版本及其直接依赖项的 Bi-Partite 图 - 依赖图（完整的反向依赖树） - 具有多种布局（spring、radial、shell、BFS、circular）和循环检测的依赖图 - 交互式布局切换器和循环边缘高亮显示 - 信任分数热力图、风险传播图、应用程序风险仪表板、风险路径探索器、风险异常值和假设模拟器 - **报告**：提供 HTML 表格、Excel 导出和 JSON 导出，用于： - 带有版本的所有项目 - 具有最新版本过滤的应用程序清单 - SNAPSHOT 依赖项 - 自依赖检测 - 多版本依赖源跟踪（菱形依赖分析） - Non-SemVer 版本检测 - 传递依赖（某个版本所依赖的内容） - 具有分区级别和路径的依赖项 - 按严重程度排序的所有漏洞 - 漏洞依赖项（影响分析） - 中心性指标（inDegree/outDegree） - 许可证清单和每个项目的许可证摘要 - 漏洞新鲜度（富化时长） - 策略违规（仍在使用的被禁包） - VEX 覆盖率统计 - 许可证冲突（同一依赖树中不兼容的许可证） - 源代码仓库清单 - 富化覆盖率（最近、过期与从未扫描的包） - 许可证仪表板（按风险类别汇总） - 信任分数差距（没有信任分数的包） - 事件响应（每个漏洞的爆炸半径和补丁计划） - 源影响（受受损源代码仓库影响的应用程序） - SBOM 清单（已摄取的 SBOM 记录） - SBOM 覆盖率（每个应用程序的来源覆盖率） - **编程 API (v1)**：用于 CI/CD 流水线的仅限 JSON 的 endpoint，带有 `{data, pagination?, meta}` 包装格式。包括包元数据、依赖/依赖项树、关键依赖项、风险摘要、OpenAPI 规范、漏洞查找、策略检查、信任分数门控和富化触发器 - **CLI 工具**：`sbom-graph` CLI，用于摄取、查询（vulns、deps、dependants、patch-plan）、策略注释和报告导出，支持使用 `--output json` 用于流水线 - **交互式 UI 功能**： - 所有报告和可视化中的仅内部切换开关 - 遵守当前过滤状态的动态下载链接 - 带有可测试所有 endpoint 的表单的交互式 API 文档 - 可滚动数据表的冻结表头 ## 项目结构 ``` sbom-graph/ ├── sbom-graph-model/ # Python library for CycloneDX/SPDX → FalkorDB ├── sbom-graph-api/ # Flask API, reports, and visualizations ├── sbom-graph-enrichment/ # Celery enrichment pipeline (OSV, Scorecard, etc.) ├── sonatype-lifecycle-release-listener/ # SCA scan release listener ├── sbom-graph-cli/ # CLI for ingest, query, policy, export ├── helm/ │ └── sbom-graph/ # Umbrella Helm chart for all components ├── build-images.sh # Docker build script ├── release.sh # Build, tag, push images + update Helm values ├── deploy.sh # Helm upgrade/install preserving volumes ├── sync-helm-tags.sh # Sync pyproject.toml versions to Helm tags └── SPECIFICATION.md # Detailed architecture documentation ``` ## 供应链信任分数 信任分数通过聚合来自四个外部来源的数据，为依赖图中的每个包提供一个单一的、基于证据的评分 (0--10)： | 来源 | 提供的内容 | |--------|-----------------| | [OpenSSF Scorecard](https://scorecard.dev) | 18+ 项安全实践检查（分支保护、代码审查、SAST、模糊测试等） | | [OSV 数据库](https://osv.dev) | 漏洞数量、严重程度分布、平均修复时间 | | [Sonatype OSS Index](https://ossindex.sonatype.org) | 专有漏洞情报和修复指南 | | [deps.dev](https://deps.dev) | 项目健康状况、公告数量、记分卡数据和活动信号 | ### 评分类别 综合分数是通过四个加权类别计算的，每个类别都标准化为 0--10： | 类别 | 默认权重 | 衡量内容 | |----------|---------------|-----------------| | 安全实践 | 30% | 分支保护、代码审查、SAST、模糊测试、危险工作流 | | 漏洞概况 | 35% | 开放的 CVE 数量/严重程度、修复率、平均补救时间 | | 维护状况 | 20% | 近期活动、贡献者数量、维护信号 | | 供应链健康度 | 15% | 固定依赖、签名发布、CI 测试、打包 | 当某个数据源不适用于某个类别时，将按比例对其余来源重新计算权重。每个分数旁边都会报告一个**置信水平** (0--1)。 ### 继承的风险传播 一个包的*直接分数*只能说明部分情况。一个评分为 9/10 的库如果依赖于评分为 2/10 的库，其风险远比其自身分数显示的要高。信任分数系统计算出一个**有效分数**，该分数反映了整个传递依赖树中的总体风险： ``` effective_score(v) = α × direct_score(v) + (1 − α) × inherited_score(v) ``` - **α**（默认为 0.4）控制自身分数与继承风险之间的平衡 - **深度衰减**（衰减因子 δ = 0.8）降低了每个依赖级别的影响力：直接 = 1.0，深度 2 = 0.8，深度 5 ≈ 0.41 - **最小路径分数**跟踪从应用程序到叶节点的任何路径上最糟糕的单个组件（“最薄弱的环节”） - 分数通过反向拓扑顺序**自下而上**进行计算；当依赖项升级时，改进会自动传播 ### 信任分数下降警报 当一个包的有效分数低于 `TRUST_SCORE_ALERT_THRESHOLD`（默认值为 4.0）时，富化流水线将发出 WARNING 级别的日志警报，列出前 20 个处于风险中的包。可以通过 Helm values 中的 `trustScore.alertThreshold` 或 `TRUST_SCORE_ALERT_THRESHOLD` 环境变量来配置阈值。 ### API Endpoint | Endpoint | 描述 | |----------|-------------| | `GET /api/v1/package/{purl}/trust-score` | 完整的信任分数细分：直接分数、有效分数、继承分数、各类别分数、置信度 | | `GET /api/v1/package/{purl}/trust-score/risk-path` | 导致分数下降的主要依赖链 | | `GET /api/v1/application/{purl}/supply-chain-risk` | 应用程序级别的总体风险，包括最薄弱环节和主要贡献者 | | `GET /api/v1/analysis/trust-score-distribution` | 所有包的有效分数直方图 | | `GET /api/v1/analysis/remediation-priorities` | 按修复杠杆作用（每次升级改善的应用程序）排名的包 | | `GET /api/v1/package/{purl}/trust-check` | CI/CD 门控：对照最低有效分数阈值进行通过/失败判定 | ### CI/CD 门控 trust-check endpoint 专为流水线集成而设计： ``` curl -s -H "Authorization: Bearer $TOKEN" \ "$API_URL/api/v1/package/pkg:maven%2Fcom.example%2Fmy-lib@1.0.0/trust-check?min_score=5.0" ``` 返回 `pass` 或 `fail` 判定结果，以及包的有效分数、置信度和各类别细分。该门控检查的是**有效分数**（不仅仅是直接分数），从而能捕捉到包本身看起来正常但具有风险依赖项的情况。 ### 配置 评分参数可通过环境变量或 Helm values 进行配置： | 参数 | 默认值 | 描述 | |-----------|---------|-------------| | `trustScore.enabled` | `true` | 启用/禁用信任分数计算 | | `trustScore.weights.securityPractices` | `0.30` | 安全实践类别的权重 | | `trustScore.weights.vulnerabilityProfile` | `0.35` | 漏洞概况类别的权重 | | `trustScore.weights.maintenanceHealth` | `0.20` | 维护状况类别的权重 | | `trustScore.weights.supplyChainHygiene` | `0.15` | 供应链健康度类别的权重 | | `trustScore.propagation.alpha` | `0.4` | 自身分数与继承分数之间的平衡 | | `trustScore.propagation.decay` | `0.8` | 每深一层的衰减因子 | | `trustScore.propagation.maxDepth` | `20` | 最大遍历深度 | | `trustScore.alertThreshold` | `4.0` | 低于该有效分数将发出 WARNING 级别的警报 | ## 富化流水线 `sbom-graph-enrichment` 组件是一个基于 Celery 的异步 worker，在 SBOM 摄取后不断富化包元数据。它运行以下富化任务： - **漏洞富化**：查询 OSV.dev 和 Sonatype OSS Index 以获取已知漏洞，在图中创建 `Vulnerability` 节点和 `HAS_VULNERABILITY` 边 - **许可证富化**：查询 ClearlyDefined 以获取许可证元数据，按风险（Copyleft、Weak Copyleft、Permissive）对许可证进行分类 - **EOL 富化**：查询 endoflife.date API 以获取产品生命周期信息（生命周期结束日期） - **源代码仓库富化**：查询 deps.dev 以获取源代码仓库 URL，带有用于缓解 SSRF 的主机允许列表 - **信任分数计算**：查询 OpenSSF Scorecard、OSV、Sonatype 和 deps.dev 以计算综合信任分数，并通过依赖图传播继承的风险 富化任务可以通过 API（`POST /api/v1/enrich/vulnerabilities`）按需触发，或按可配置的计划运行。该流水线被设计为幂等的：重新运行富化会更新现有节点，而不是创建重复节点。 ## 部署 ### 推荐：`release.sh` + `deploy.sh` 构建镜像（限发生更改的镜像）、更新 Helm 标签并部署： ``` ./release.sh # Build changed images, update helm/charts/sbom-graph/values.yaml ./deploy.sh # helm upgrade --install, preserving volumes and secrets ``` 对于 minikube，将镜像直接加载到虚拟机中： ``` ./release.sh --load-minikube ./deploy.sh ``` 对于远程镜像仓库： ``` ./release.sh --registry ghcr.io/myorg --push ./deploy.sh --namespace production ``` 使用 `--force-build` 从头开始重建所有镜像（向 Docker 传递 `--no-cache`），并使用 `--dry-run` 进行预览而不执行： ``` ./release.sh --force-build --dry-run ``` 运行 `./release.sh --help` 或 `./deploy.sh --help` 获取完整选项列表。 ### 手动 Helm 安装 使用总括 Helm chart 直接部署所有组件： ``` helm install sbom-graph ./helm/charts/sbom-graph ``` ## Docker 构建 ### 使用 `release.sh`（推荐） `release.sh` 脚本从每个子项目的 `pyproject.toml` 中读取版本，仅构建本地尚不存在对应标签的镜像，并自动更新 Helm values： ``` ./release.sh # Build changed images ./release.sh --force-build # Clean rebuild of all images ./release.sh --registry ghcr.io/myorg --push # Build, tag with registry prefix, push ./release.sh --load-minikube # Build and load into minikube ``` ### 直接使用 `build-images.sh` 从**仓库根目录**（例如 `./build-images.sh`）运行脚本。每个镜像都是使用**该子项目文件夹作为 Docker 上下文**构建的（与 CI 相同），而不是 monorepo 根目录。该脚本处理构建顺序和依赖关系。 #### 构建所有镜像 ``` ./build-images.sh ``` 这将： 1. 构建 `sbom-graph-model` wheel（`sonatype-lifecycle-release-listener` 所需） 2. 构建 `sbom-graph-api` Docker 镜像 3. 构建 `sonatype-lifecycle-release-listener` Docker 镜像 4. 构建 `sbom-graph-enrichment` Docker 镜像 除非您传递 `--adv-tag`、`--rl-tag` 或 `--enr-tag`，否则每个镜像都会被打上标签 `:` 和 `:latest`，其中 **safe-version** 是该子项目的 `pyproject.toml` 中的 `[project].version`，并将 `+` 替换为 `-`（符合 OCI 安全规范）。安装时使用的 `--build-arg PYTHON_PACKAGE_VERSION` 仍然保持原始的 PEP 440 版本字符串。 #### 构建单个目标 ``` ./build-images.sh model # Wheel only ./build-images.sh sbom-graph-api # sbom-graph-api image only ./build-images.sh sonatype-lifecycle-release-listener # release listener image only ./build-images.sh sbom-graph-enrichment # enrichment image only ``` #### 自定义镜像标签 ``` ./build-images.sh --adv-tag myrepo/adv:v2 --rl-tag myrepo/rl:v2 ``` #### 不使用缓存重建 ``` ./build-images.sh --no-cache ``` 运行 `./build-images.sh --help` 获取完整选项列表。 ## 许可证 本项目是开源软件，基于 **MIT** 许可证。 ### 基础设施依赖：FalkorDB (SSPLv1) 本项目依赖 [FalkorDB](https://www.falkordb.com/) 作为其图数据库。FalkorDB 基于 **Server Side Public License v1 (SSPLv1)** 授权，这对如何部署完整的软件栈具有一定的影响： | 部署场景 | SSPLv1 义务 | |---------------------|-------------------| | **内部使用**（不作为服务提供给第三方） | 无限制。自由使用。如果需要，可以使用企业支持包或 FalkorDB 托管解决方案 | | **作为服务提供给外部用户**（例如 SaaS、托管 API） | 您必须在 SSPLv1 下开源**整个服务栈**——或者从 FalkorDB 获得[商业许可](https://www.falkordb.com/)。 | | **分发此源代码**（不含 FalkorDB 二进制文件） | 无 SSPL 义务。MIT 许可证适用于此代码。 | SSPLv1 仅适用于 FalkorDB **服务器二进制文件**。本项目使用的 FalkorDB Python 客户端库基于 MIT 许可证授权。本项目的 MIT 许可证与 SSPL 不冲突，因为 FalkorDB 作为单独的网络服务被使用，而不是被链接或嵌入的。 **如果您的组织无法接受 SSPLv1 条款**，您将需要获取 FalkorDB 的商业许可，或者调整持久层以使用基于其他授权的图数据库。 ### 其他依赖项 所有 Python 库依赖项均使用宽松的许可证（MIT、BSD-3、Apache-2.0），但有两个例外：**ldap3**（LGPL-3，弱 copyleft）和 **certifi**（MPL-2.0，弱 copyleft）。certifi 提供 Mozilla CA 证书包，被普遍接受用于 TLS 证书验证。有关完整的许可证评估，请参阅 [threat-model.md](threat-model.md)。 ## 贡献 请联系 Brett Crawley 获取贡献指南。

标签：GPT, Mutation, Python, WebSocket, 依赖分析, 可视化, 子域名突变, 无后门, 漏洞管理, 网络测绘, 请求拦截, 跌倒检测, 软件物料清单, 逆向工具