BastienBYRA/CPE-Mapper

# CPE-Mapper CPE-mapper 是一个 CLI 工具和基于 JSON 的数据库，旨在准确地将软件包名称映射到其对应的 CPE（通用平台枚举，Common Platform Enumerations）。 它的主要目标是，在标准包名无法匹配已知 CPE 的情况下，改进漏洞识别能力。 ## 亮点 - 📦 易于安装且易于使用 - ⚡ 轻量且快速 - 🔒 以安全为核心，提供有证据支持的映射 - 🔍 通过自定义 CPE 映射改进漏洞检测 - ✨ 兼容 CycloneDX JSON 和 SPDX JSON - 🧩 路线图包括 XML 支持、自定义用户映射数据库以及将其部署为服务器 ## 工作原理 CPE-mapper 是一个相当简单的工具。 它不会分析你的源代码或仓库来猜测哪些依赖项对应哪些 CPE。相反，它依赖于一个 [JSON 映射文件（我们的 CPE 数据库）](./data/cpe-mapper.json)，该文件为每个包名明确规定了其对应的 CPE。 我们使用 [NVD（国家漏洞数据库）](https://nvd.nist.gov/) 作为参考，以确定特定软件使用的是哪个 CPE，然后手动将它们链接在一起。 例如，NVD 报告 Apache Tomcat 的漏洞时使用的 CPE 是： ``` cpe:2.3:a:apache:tomcat:*:*:*:*:*:*:*:* ``` 然而，这个 CPE 无法直接从 Java 包名 `org.apache.tomcat.embed:tomcat-embed-core` 推导出来。 为了解决这个问题，CPE-mapper 在其数据库中维护了一个映射，这样当它处理 BOM 文件时，如果找到包 `org.apache.tomcat.embed:tomcat-embed-core`，它会自动将相应的 CPE `cpe:2.3:a:apache:tomcat::*:*:*:*:*:*:*` 添加到输出中。 ### 误报 由于 NVD 将 CPE 分配给 CVE 的方式，CPE-mapper **可能会报告误报**。 以 Log4j 为例：所有与 Log4j 相关的 CVE 都与以下 CPE 相关联： ``` cpe:2.3:a:apache:log4j::*:*:*:*:*:*:* ``` 这种标记漏洞的方式没有考虑到构成 Log4j 的不同模块，例如 `log4j-core`、`log4j-api`、`log4j-web` 或 `log4j-slf4j-impl`。 换句话说，NVD 不区分组成一个软件的不同包；它将整个项目视为一个单一实体。 因此，我们决定将 CPE 与每个软件的**核心**包（例如 `log4j-core`、`tomcat-embed-core`、`logback-core`...）关联起来，因为这些核心模块被其所有派生包使用或实现（例如在 Log4j 中：`log4j-api`、`log4j-web`...）。 这确保了每当为整个软件发布新的 CVE 时，你都会收到通知。 虽然这种方法可能会产生误报（例如，某些 CVE 可能影响你实际上并未使用的派生包），但它提供了最安全的覆盖范围，以确保你不会错过任何相关漏洞。 ## 入门指南 你可以在 CI/CD 或本地机器中使用 CPE-Mapper。 ### 安装 你可以通过多种方式安装 CPE-mapper： 1. 通过 `npm`。 ``` npm install -g @bastienbyra/cpe-mapper # 然后你可以使用 `cpe-mapper` 运行它 ``` 2. 通过我们的 `Docker image`。 ``` docker run -v path/to/your/bom/folder:/data --rm ghcr.io/bastienbyra/cpe-mapper:latest apply -i /data/bom.json -o /data/mapped_bom.json ``` ### 命令 #### 应用 ``` Usage: cpe-mapper apply [options] Apply CPE mappings to a BOM file Options: -i, --input-file Input BOM file (JSON) -o, --output-file Output mapped BOM file -u, --no-update Disable updating the CPE Mapping database --override-cpe Override BOM CPEs with mapped values from our database (CycloneDX only) -v, --verbose Enable verbose logging -h, --help display help for command ``` ##### 示例 将 CPE-mapper 数据库映射应用于 BOM 文件 ``` cpe-mapper apply -i input-bom.json -o output-bom.json ``` 将 CPE-mapper 数据库映射应用于 BOM 文件，并覆盖输入文件中现有的 CPE。 ``` cpe-mapper apply -i input-bom.json -o output-bom.json --override-cpe ``` #### 更新 ``` Usage: cpe-mapper update [options] Update the CPE mappings database Options: -h, --help display help for command ``` ##### 示例 检查数据库是否有更新并应用它们。 ``` cpe-mapper update ``` ### GitHub Actions CPE-Mapper 提供了一个 GitHub Action，可用于将 CPE 映射应用到你的 BOM 文件。 #### 配置 ``` - uses: BastienBYRA/CPE-Mapper@1.2.0 with: # The input BOM file to which CPE-Mapper applies the mapping. # Required. Example: testdata/bom.test.json input-file: '' # The name of the output BOM file. # Required. Example: testdata/bom.result.json output-file: '' # Whether to override existing CPEs in the input BOM file (CycloneDX only). Choices are `true` or `false`. # Optional. Default: false override-cpe: false # Enable verbose mode. Choices are `true` or `false`. # Optional. Default: false verbose: false ``` #### 用法 ``` name: Security CI on: [push] jobs: apply-cpe: name: Apply CPE to BOM file runs-on: ubuntu-latest steps: - name: Apply CPE mapping uses: BastienBYRA/CPE-Mapper@main with: input-file: testdata/bom.test.json output-file: testdata/bom.result.json # Archive the output BOM file as an artifact - name: Archive artifacts uses: actions/upload-artifact@v4 with: name: mapped-sbom path: testdata/bom.result.json retention-days: 1 ``` ## 贡献 如果你想为这个项目做贡献，无论是通过**报告问题**、**提出新想法**、**开发功能**，还是**向 CPE 数据库添加条目**，请参阅 [CONTRIBUTING](./CONTRIBUTING.md) 指南了解详细信息。 ## 路线图 [ROADMAP](./ROADMAP.md) 列出了未来计划的所有任务。 ## AI 使用 在为这个项目做贡献时，你可以使用 AI 作为助手。我唯一的要求 是你验证 AI 编写的代码是正确且安全的。 这个项目中的 AI 配置文件（例如 `CLAUDE.md`）包含了 [4 条 Karpathy 规则](https://github.com/multica-ai/andrej-karpathy-skills)，作为更好进行 AI 辅助编程的基准。

标签：CISA项目, CPE映射, CycloneDX, GPT, Homebrew安装, JSON数据库, MITM代理, NVD, SBOM生成, SPDX, WebSocket, 依赖分析, 假阳性处理, 包管理映射, 安全合规, 暗色界面, 漏洞管理, 网络代理, 网络安全, 自定义脚本, 请求拦截, 资产识别, 跌倒检测, 软件物料清单, 隐私保护