Noetheon/vuln-prioritizer-cli

# vuln-prioritizer [](https://www.python.org/) [](LICENSE) [](./CHANGELOG.md) [](#development) `vuln-prioritizer` 是一个用于已知 CVE 优先级排序的 Python CLI 工具。它接受纯 CVE 列表以及扫描器和 SBOM 导出文件，使用 `NVD + EPSS + CISA KEV` 对其进行富化，并添加可选的 ATT&CK、资产上下文、VEX、豁免和证据层，且不会将优先级模型变成一个黑盒。  ## 为什么使用它 - 透明的、基于规则的优先级排序，而非不透明的评分。 - 本地优先的工作流，支持保存的 JSON、HTML 报告、快照、可选的 SQLite 支持的历史记录视图、汇总和证据包。 - 来自本地 CTID/MITRE 数据的可选 ATT&CK 上下文，而非基于启发式的 CVE 到 ATT&CK 猜测。 - 对 CI 友好的输出，包括 Markdown 摘要、SARIF、GitHub Action 支持和策略门禁。 - 对 VEX、资产上下文、豁免和可复现的审查产物的显式支持。 - 豁免生命周期的可见性，具有活跃、待审查和过期状态，而非悄无声息的长期例外。 ## 它能做什么 核心命令： - `analyze`：对来自 CVE 列表、扫描器或 SBOM 导出的发现进行优先级排序 - `compare`：展示富化后的优先级与仅使用 CVSS 的差异 - `explain`：详细解释单个 CVE 的决策 - `doctor`：验证本地设置、配置、缓存、文件以及可选的实时数据源可达性 - `snapshot create|diff`：捕获一次运行并比较前后状态 - `state init|import-snapshot|history|waivers|top-services`：将快照保存在可选的本地 SQLite 存储中，并检查历史记录、豁免债务或重复的服务 - `rollup`：按资产或服务聚合已保存的分析或快照 - `attack validate|coverage|navigator-layer`：验证并使用本地 ATT&CK 映射 - `report html|evidence-bundle|verify-evidence-bundle`：渲染 HTML、构建可复现的 ZIP 证据包或验证证据包完整性 - `data status|update|verify`：检查和维护本地数据/缓存状态 支持的输入： - `cve-list` - `trivy-json` - `grype-json` - `cyclonedx-json` - `spdx-json` - `dependency-check-json` - `github-alerts-json` - `nessus-xml` - `openvas-xml` 支持的输出： - terminal 表格 - `markdown` - `json` - `sarif` - 通过 `--html-output` 直接生成 HTML 附带文件 - 通过 `--summary-output` 生成 Markdown 执行摘要 ## 范围边界 本项目是： - 一个用于已知 CVE 和现有发现的 CLI 工具 - 本地优先且面向可复现性的 - 对数据来源和评分规则明确透明的 - 专为漏洞管理、安全分类和证据生成而设计的 本项目不是： - 一个扫描器 - 一个 SIEM - 一个工单系统 - 一个 Web 应用程序 - 一个实时的 TAXII 收集器 - 一个基于启发式或 LLM 的 ATT&CK 映射器 ## 安装说明 ### 推荐：`pipx` ``` pipx install git+https://github.com/Noetheon/vuln-prioritizer-cli.git@vX.Y.Z vuln-prioritizer --help ``` 将 `vX.Y.Z` 替换为您打算使用的 GitHub 发布标签。本 README 跟踪的是当前的 `main` 分支，因此带有标签的公开发布版本所暴露的功能面，可能会少于 `main` 分支的最前沿代码。目前的最新公开发版是 `v1.1.0`。 该仓库已具备 PyPI 发布条件，但目前经过验证的公共安装路径是上述的 GitHub 标签安装。这是一种基于标签源码的安装路径，而不是 GitHub Release 资产安装路径。面向 PyPI/TestPyPI 的公开发布流程已配置并备有文档，但被显式限制，直到启用该仓库的 trusted-publisher（可信发布者）配置。当 PyPI 正式上线后，发布工作流将在发布后自动验证托管索引的安装；在此之前，上述 GitHub 标签安装仍是受支持的公共安装路径，并且发布工作流也会在推送标签时验证相同的基于标签源码的安装契约。 ### 示例范围 - 仅在 `pipx install` 后即可工作：使用您自己创建的或已经在您工作空间中拥有的文件的命令，例如 `cves.txt`、`trivy-results.json`、`analysis.json` 和 `report.html`。 - 需要额外的本地数据文件：ATT&CK 示例需要通过 `--attack-mapping-file` 和 `--attack-technique-metadata-file` 传递的文件。 - 仅限检出仓库：引用 `data/...`、`docs/...` 或 `make ...` 的示例。在本仓库中，这些路径指的是已提交的测试固定数据、已提交的文档产物或维护者目标。 ### 本地开发安装 ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt pip install -e .[dev] ``` 可选： ``` cp .env.example .env ``` 如果您想使用经过认证的 NVD 访问，请在 `.env` 中设置 `NVD_API_KEY`。 ## 快速入门 ### 1. 最快的公开发版分析运行 ``` printf 'CVE-2021-44228\nCVE-2024-3094\n' > cves.txt vuln-prioritizer analyze --input cves.txt --format markdown --output report.md ``` ### 2. 从您自己的扫描器导出文件进行公开发版分析 ``` vuln-prioritizer analyze \ --input trivy-results.json \ --input-format trivy-json \ --format json \ --output analysis.json \ --summary-output summary.md \ --html-output report.html ``` ### 3. 公开发版快照对比与服务汇总 ``` vuln-prioritizer snapshot create \ --input trivy-results.json \ --input-format trivy-json \ --output after.json vuln-prioritizer snapshot diff \ --before before.json \ --after after.json \ --format markdown vuln-prioritizer rollup \ --input after.json \ --by service \ --format markdown ``` ### 4. 公开发版证据包完整性验证 ``` vuln-prioritizer report evidence-bundle \ --input analysis.json \ --output evidence.zip vuln-prioritizer report verify-evidence-bundle \ --input evidence.zip \ --format json \ --output evidence-verification.json ``` ### 5. 使用您自己的本地映射文件进行 ATT&CK 感知分析 ``` vuln-prioritizer analyze \ --input cves.txt \ --format markdown \ --output attack-report.md \ --attack-source ctid-json \ --attack-mapping-file ./attack-mapping.json \ --attack-technique-metadata-file ./attack-techniques.json ``` 这些 ATT&CK 文件不会通过 `pipx` 安装打包。如果您是在仓库检出的基础上工作，提交的演示输入文件位于 `data/attack/` 下。 ### 6. 可选的本地 SQLite 状态存储 ``` vuln-prioritizer state init --db build/state.db vuln-prioritizer state import-snapshot \ --db build/state.db \ --input after.json vuln-prioritizer state top-services \ --db build/state.db \ --days 30 \ --format json \ --output state-top-services.json ``` ## 运行时配置 `v1.1.0` 增加了通过 `vuln-prioritizer.yml` 提供的一等公民运行时配置支持。 可选的 SQLite 状态存储被刻意独立出来：它是纯本地的、选择性加入的功能，不会改变 `analyze`、`report`、`snapshot` 或 evidence 的语义。 示例： ``` defaults: policy_profile: enterprise # Add ATT&CK defaults only if you keep local mapping files yourself. # attack_source: ctid-json # attack_mapping_file: ./attack-mapping.json # attack_technique_metadata_file: ./attack-techniques.json commands: analyze: format: json summary_output: build/summary.md ``` 通过自动发现或显式指定来使用它： ``` vuln-prioritizer analyze --input cves.txt vuln-prioritizer --config vuln-prioritizer.yml analyze --input trivy-results.json --input-format trivy-json vuln-prioritizer --no-config analyze --input cves.txt ``` ## 公开文档 请从以下内容开始了解公共 CLI 的使用： - [docs/use_cases.md](docs/use_cases.md) - [docs/playbooks.md](docs/playbooks.md) - [docs/support_matrix.md](docs/support_matrix.md) - [docs/benchmarking.md](docs/benchmarking.md) - [docs/contracts.md](docs/contracts.md) - [docs/methodology.md](docs/methodology.md) - [docs/evidence.md](docs/evidence.md) - [docs/integrations/reporting_and_ci.md](docs/integrations/reporting_and_ci.md) - [docs/releases/v1.1.0.md](docs/releases/v1.1.0.md) 维护者 / 仓库检出工作流： - [docs/release_operations.md](docs/release_operations.md) ## 社区与支持 - 使用问题与工作流帮助：GitHub Discussions - 可复现的 Bug 和有明确范围的特性请求：GitHub Issues - 安全报告：启用时的私密漏洞报告，否则请参考 [SECURITY.md](SECURITY.md) - 贡献规则和本地验证：[CONTRIBUTING.md](CONTRIBUTING.md) - 支持路由：[SUPPORT.md](SUPPORT.md) 参考资料： - [docs/roadmap.md](docs/roadmap.md) - [docs/reference_cve_prioritizer_gap_analysis.md](docs/reference_cve_prioritizer_gap_analysis.md) - [docs/examples/media/workflow-demo.gif](docs/examples/media/workflow-demo.gif) ## GitHub Action 该仓库包含一个用于 `analyze` 和 `report html` 的复合 GitHub Action。 请在 `actions/checkout` 之后使用它，因为被扫描的输入文件位于消费者仓库中，而不是在 Action 仓库中。 ``` - uses: actions/checkout@v6 - name: Prioritize vulnerabilities uses: Noetheon/vuln-prioritizer-cli@vX.Y.Z with: mode: analyze input: trivy-results.json input-format: trivy-json output-format: json output-path: analysis.json summary-output-path: summary.md summary-template: compact html-output-path: report.html github-step-summary: "true" ``` 将 `vX.Y.Z` 替换为您想要使用的发布标签或 commit SHA。`summary-template` 向后兼容，默认值为 `detailed`。当用于 GitHub 步骤摘要或 PR 评论时将其设置为 `compact`，或者当您需要完整的执行摘要产物时保持 `detailed`。如果某个工作流仅需要 `$GITHUB_STEP_SUMMARY`，该 Action 现在无需显式提供 `summary-output-path` 即可生成摘要。 有关完整的契约和 CI 模式，请参阅 [docs/integrations/reporting_and_ci.md](docs/integrations/reporting_and_ci.md)，以及 [docs/examples/github_action_summary_templates.md](docs/examples/github_action_summary_templates.md) 中关于 compact 与 detailed 的示例。 ## 开发 有用的本地门禁： ``` python3 -m pytest -q make check make benchmark-check make release-check ``` 如果您更改了文档、示例或报告产物，请运行 `make release-check`，以使提交的示例输出保持同步。 ## 项目状态 当前发布线： - 稳定版 `v1.1.0` - GitHub 标签安装路径现已可用 - `v1.1.0` 的 GitHub Release 已恢复 - PyPI 和 TestPyPI 工作流已准备就绪，但实时发布仍被显式限制，直到启用 trusted-publisher 设置 ## 许可证 [MIT](LICENSE)

标签：CISA KEV, CVE优先级排序, CVSS评估, DevSecOps, EPSS, GitHub Actions, GPT, HTML报告, NVD, Python, SARIF, SBOM解析, SQLite, VEX, 上游代理, 云计算, 威胁情报, 安全合规, 开发者工具, 快照对比, 无后门, 本地优先, 漏洞优先级评估, 漏洞管理, 网络代理, 自动笔记, 规则引擎, 豁免管理, 资产上下文, 逆向工具, 透明度