systemslibrarian/PostQuantum.CryptographicBillOfMaterials

# PostQuantum.CryptographicBillOfMaterials (`dotnet-cbom`) 一款针对 .NET 的密码学物料清单 (CBOM) 生成器。它利用 Roslyn 静态分析来 **清点密码学使用情况、评估量子风险分类，并展示后量子 (PQC) 迁移 进度** —— 采用审计人员信任且现有工具已支持的格式。 专为普通的 .NET 团队（ county IT 、图书馆、SaaS 供应商、国防分包商）打造，这些团队必须 应对联邦政府的 PQC 迁移时间表，且通常**没有内部密码学家**。 ## 功能简介 - **发现**跨 `System.Security.Cryptography` 、JWT 验证、TLS/证书处理以及后量子 API (ML-KEM/ML-DSA/SLH-DSA) 的加密操作，并为每项发现提供**检测置信度**。 - **分类**每项发现的**两个独立维度** —— 经典弱点（例如 ECB、MD5）和量子脆弱性（Shor 算法攻破 RSA/ECC；Grover 算法降低 AES-128 的安全边际）—— 从而避免混淆评估建议。每个结论都附带**文档化依据**（FIPS/NIST/CWE 引用）。 - **评分**透明：提供 0-100 的发现风险评分和展示了计算过程的 **PQC 就绪度评分**，绝不是黑盒。 - **报告**生成格式包括 **CycloneDX 1.6** （一种标准化的 CBOM，而非专有格式）、**SARIF 2.1.0**、Markdown、HTML 以及执行摘要 —— 现在以**审计包**形式提供：包含首要迁移操作、相较于基线的变更内容、修复状态和豁免情况。 - **跟踪进度**：使用 `diff`/`--baseline`：“量子脆弱性发现 1 → 0，就绪度 64 → 100”，并为每项发现标记 新增 / 未变 / 退化 / 豁免 状态。 - **自我验证**：生成的 CBOM 会根据**官方 CycloneDX 1.6 JSON Schema** （内置，支持离线）以及 `dotnet-cbom` 配置文件进行校验 —— 适用于 `validate` 命令和 CI 环境。 - **超越源码的洞察**：通过 Bouncy Castle 检测第三方加密操作并进行**包清单清点**（ `project.assets.json` / `PackageReference` ），让依赖项中的加密操作也清晰可见。 ## 安装说明 ``` dotnet tool install -g PostQuantum.CryptographicBillOfMaterials.Cli ``` （扫描 `.sln`/`.csproj` 需要安装 .NET SDK；目录扫描无需该 SDK。） ## 快速开始 ``` # 扫描 solution、project、目录或单个文件 dotnet-cbom scan ./MyApp.sln # 选择 formats、policy posture 和 CI gate dotnet-cbom scan ./src --format cyclonedx,sarif,html --profile cnsa2 --fail-on critical # 显示相对于上一次运行的迁移进度（在 findings 上标记 New/Regressed/Unchanged） dotnet-cbom scan ./src --baseline ./last.cbom.json dotnet-cbom diff ./last.cbom.json ./cbom-out/cbom.cbom.json # 根据官方 CycloneDX 1.6 schema 和 dotnet-cbom profile 验证 CBOM dotnet-cbom validate ./cbom-out/cbom.cbom.json ``` ### 策略配置文件 `--profile` 用于选择安全姿态（记录在 CBOM 中）。配置文件只能**提升**严重级别或要求更多证据 —— 绝不会静默降低风险。 | 配置文件 | 安全姿态 | |---|---| | `general` | 保守的商业默认设置（草案指导标注为草案） | | `federal` | 以 NIST 为中心；易受 Shor 算法攻击的公钥加密至少为高风险 | | `cnsa2` | CNSA 2.0 / NSS ；AES-128 不充分（需使用 AES-256 ）；提供详细的依据 | | `audit` | 最大化证据；豁免项用于注释而非抑制 | | `developer` | 低噪音本地模式（风险分类保持不变） | ### 实用的扫描选项 `--changed-files a.cs,b.cs` （支持感知 PR ）， `--config cbom.config.json` ， `--restore`/`--no-restore` ， `--msbuild-property name=value` ， `--allow-partial` ， `-q` 。 ### 退出代码（对 CI 友好，安全失效） | 代码 | 含义 | |---|---| | 0 | 执行完成；没有达到或超过 `--fail-on` 设定的问题 | | 1 | 存在达到或超过 `--fail-on` （默认为 `high` ）的问题 | | 2 | 部分分析 —— 某个项目加载失败（绝不会被报告为“无问题”） | | 3 | 使用/配置错误 · 4 内部错误 | ## CI / GitHub Actions 使用官方复合操作（内置 SARIF 上传和制品保留）： ``` - uses: actions/setup-dotnet@v4 with: { dotnet-version: '8.0.x' } - uses: systemslibrarian/CryptographicBillOfMaterials@v1 with: target: ./MyApp.sln formats: cyclonedx,sarif,markdown,summary profile: general fail-on: ${{ github.event_name == 'pull_request' && 'none' || 'high' }} baseline: baseline/cbom.cbom.json ``` 适用于 **GitHub Actions** （带有 PR 基线差异注释）、**Azure DevOps** 和 **GitLab CI** 的完整可直接复制流程位于 [`examples/ci/`](examples/ci/) 中。建议从 `--fail-on critical` 开始，随着清点工作成熟逐渐降低阈值；SARIF 可点亮代码扫描功能，而 CBOM 制品则可提供给 Dependency-Track 或审计人员使用。 ## 风险与就绪度的计算方式（透明） - **发现风险** = `0.45·Q + 0.35·C + 0.20·X` （量子、经典弱点、使用暴露因素），带有安全失效底线（例如，禁用证书验证和硬编码密钥始终 ≥ 严重）。 - **PQC 就绪度** = `100 × 安全权重 / 总权重` ，仅针对量子相关算法进行计算；经典和配置问题将单独报告，以免扭曲 PQC 的评估情况。 完整的方法论和 CycloneDX 配置文件差异详见 [`docs/TECHNICAL-DESIGN.md`](docs/TECHNICAL-DESIGN.md)。 ## 标准对齐 输出的是有效的 **CycloneDX 1.6** BOM （即上游引入 CBOM 的版本） —— 每次运行都会通过官方 JSON Schema 进行验证。PQC/风险字段位于 `cbom:` 命名空间下指定的 `properties`/`evidence` 扩展点中，因此任何支持 CycloneDX 的工具都能对其进行解析。结论引用了 FIPS 203/204/205、NIST SP 800-131A/800-52、NIST IR 8547 (⚠ 草案)、CNSA 2.0 和 CWE —— 详见 [`docs/RULES.md`](docs/RULES.md) 中的引用状态表。 配置（ `cbom.config.json` ）：规则开关记录为**豁免**（理由/批准人/有效期）、**针对单个算法**的调整、仅提升级别的严重性底线、路径匹配符，以及按路径或命名空间（ `ns:` ）划分的**数据敏感性提示**，这些提示会提高对“先收集后解密”风险的评估级别。所有应用的操作都会记录回 CBOM 中。详见 [`samples/cbom.config.example.json`](samples/cbom.config.example.json)。 ## 项目布局 ``` src/ PostQuantum.CryptographicBillOfMaterials core model · risk · scoring · knowledge base PostQuantum.CryptographicBillOfMaterials.Analysis Roslyn detectors + scan engine PostQuantum.CryptographicBillOfMaterials.Reporting CycloneDX / SARIF / Markdown / HTML / diff PostQuantum.CryptographicBillOfMaterials.Cli dotnet-cbom docs/ TECHNICAL-DESIGN.md · THREAT-MODEL.md · KNOWN-GAPS.md · RULES.md · ROADMAP.md RULE-CHANGELOG.md · COMPATIBILITY.md · ACCURACY-AND-LIMITATIONS.md examples/ci/ github-actions.yml · azure-pipelines.yml · gitlab-ci.yml ``` ## 状态 正在积极开发中。目前已实现：扫描（解决方案/项目/目录）、**16 条规则**、作为审计包的所有报告格式、带有修复状态的差异/基线比对、**策略配置文件**、富有表现力的配置、**官方 CycloneDX 1.6 模式验证**、GitHub Action + CI 示例，以及工具 SBOM。关于静态分析能检测到和无法检测到的内容，请参阅 [`docs/ACCURACY-AND-LIMITATIONS.md`](docs/ACCURACY-AND-LIMITATIONS.md) 和 [`docs/KNOWN-GAPS.md`](docs/KNOWN-GAPS.md) 。 ## 许可证 Apache-2.0。

标签：CycloneDX, Roslyn, 云安全监控, 后量子密码, 多人体追踪, 密码学, 手动系统调用, 静态分析