Noetheon/vuln-prioritizer-workbench

# vuln-prioritizer [](https://www.python.org/) [](LICENSE) [](./CHANGELOG.md) [](#development) `vuln-prioritizer` 是一个用于已知 CVE 优先级排序的 Python CLI 和自托管工作台（Workbench）。它接受纯 CVE 列表以及现有的扫描器和 SBOM 导出结果，通过 `NVD + EPSS + CISA KEV` 对其进行数据富化，并添加可选的 ATT&CK、防御上下文、资产上下文、VEX、豁免（waiver）和证据层，同时不会将优先级模型变成一个黑盒。  Workbench 演示截图：     未来版本 README 媒体维护清单： - 从 [docs/workbench-offline-demo.md](docs/workbench-offline-demo.md) 中锁定的离线演示路径截取屏幕截图，而不是来自客户数据或仅限实时的 provider 运行数据。 - 保持截图路径相对于仓库，并在同一更改中保留或更新 README 链接。 - 仅裁剪到 Workbench 或报告 UI；不要包含 shell 历史、API 密钥、cookies、私有主目录路径、浏览器配置文件或环境变量值。 - 仅在已脱敏的 `` 或 `` 状态下显示包含密钥的设置。 - 仅将生成的截图替换作为发布证据或文档刷新更改的一部分提交。 ## 问题与目标 安全团队通常从扫描器、SBOM 工具、公告导出或问题追踪器中获得一长串 CVE 列表。仅凭原始 CVSS 评分无法解释应首先修复哪些漏洞、哪些系统已暴露、哪些发现已被 VEX/豁免覆盖，或哪些决策需要证据支持。 `vuln-prioritizer` 将现有的 CVE 证据转化为可解释的从风险到决策的工作流： ``` existing findings or SBOM exports -> normalized CVE occurrences -> CVSS, EPSS, KEV, optional ATT&CK, asset, VEX, waiver, and provider context -> transparent priority and rationale -> reports, CI gates, evidence bundles, and Workbench decision queues ``` 目标不是发现漏洞。目标是帮助运维人员从他们已有的漏洞证据中做出有理有据的决策。 ## 为什么使用它 - 透明、基于规则的优先级排序，而不是不透明的评分。 - 本地优先的工作流，支持保存 JSON、HTML 报告、快照、可选的 SQLite 历史视图、汇总和证据包。 - 来自本地 CTID/MITRE 数据的可选 ATT&CK 上下文，而不是启发式的 CVE 到 ATT&CK 猜测。 - 对 CI 友好的输出，包括 Markdown 摘要、SARIF、GitHub Action 支持和策略门禁。 - 明确支持本地防御上下文、VEX、资产上下文、豁免和可复现的审查工件。 - 豁免生命周期可见性，包含激活、待审查和过期状态，而不是静默的长期例外。 - 一个 Docker/Compose 路径，运行当前与模板对齐的 Workbench shell，同时在同一镜像中保留 CLI 核心。 ## 它能做什么 核心命令： - `analyze`：对来自 CVE 列表、扫描器导出或 SBOM 导出的发现项进行优先级排序 - `compare`：展示数据富化后的优先级与纯 CVSS 评分的区别 - `explain`：详细解释单个 CVE 的决策过程 - `doctor`：验证本地设置、配置、缓存、文件以及可选的实时数据源可达性 - `snapshot create|diff`：捕获一次运行并比较前后状态 - `state init|import-snapshot|history|waivers|top-services|trends|service-history`：在可选的本地 SQLite 存储中持久化快照，并检查历史、豁免债务、重复服务或服务趋势 - `rollup`：按资产或服务聚合已保存的分析或快照 - `input validate`：在数据富化之前本地验证 CVE 列表、扫描器/SBOM 导出文件、资产上下文和 VEX - `input inspect` / `input normalize`：从支持的输入中发出标准化的事件（occurrences），无需查找 provider - `attack validate|coverage|navigator-layer`：验证并使用本地 ATT&CK 映射 - `report html|evidence-bundle|verify-evidence-bundle`：渲染 HTML，构建可复现的 ZIP 证据包，或验证包的完整性 - `data status|update|verify|export-provider-snapshot`：检查缓存状态，维护本地 provider 数据，并导出可重放的 provider 快照 - `db init`：初始化 Workbench SQLite 数据库 - `web serve`：运行 FastAPI/Jinja2 Workbench Web 应用 支持的输入格式： - `cve-list` - `generic-occurrence-csv` - `trivy-json` - `grype-json` - `cyclonedx-json` - `spdx-json` - `dependency-check-json` - `github-alerts-json` - `nessus-xml` - `openvas-xml` 支持的输出格式因命令而异。主要的 `analyze` 命令支持： - terminal table（终端表格） - `markdown` - `json` - `sarif` - 通过 `--html-output` 直接生成 HTML 附件 - 通过 `--summary-output` 生成 Markdown 执行摘要 其他命令会暴露符合其契约的格式。例如，`report html` 从保存的分析 JSON 写入 HTML，证据包命令写入或验证 ZIP 包，而辅助命令如 `doctor`、`snapshot`、`rollup`、`state`、`attack` 和 `data` 在支持的情况下会暴露特定于命令的 Markdown、JSON 或表格输出。 ## 范围边界 本项目是： - 一个用于已知 CVE 和现有发现项的 CLI 和本地 Workbench - 本地优先且面向可复现性 - 对数据来源和评分规则保持明确 - 专为漏洞管理、安全分类和证据生成而设计 本项目不是： - 一个扫描器 - 一个漏洞利用框架、PoC 生成器或主动探测工具 - 一个 SIEM - 一个工单系统 - 一个自动修补程序或自主修复代理 - 一个更重型的漏洞管理平台的替代品 - 一个实时的 TAXII 收集器 - 一个启发式或基于 LLM 的 ATT&CK 映射器 它不执行凭证测试、网络扫描、漏洞利用、载荷生成、攻击模拟或启发式 CVE 到 ATT&CK 的映射。 ATT&CK 支持是防御性和基于证据的：仅使用经过审查的本地映射和技术元数据。 ## 安装 ### 推荐：`pipx` ``` pipx install git+https://github.com/Noetheon/vuln-prioritizer-workbench.git@vX.Y.Z#subdirectory=backend vuln-prioritizer --help ``` 将 `vX.Y.Z` 替换为您打算使用的 GitHub 发布标签。本 README 跟踪当前的 `main` 分支，因此带有标签的公开发布版本其暴露的接口面可能 legitimately 少于 `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 ...` 的示例。在此仓库中，这些路径指的是已检入的固件（fixtures）、已检入的文档工件或维护者目标。 ### 本地开发安装 ``` python3 -m venv .venv source .venv/bin/activate pip install -r backend/requirements.txt pip install -e "backend[dev]" ``` 可选： ``` cp .env.example .env ``` 如果您想要经过身份验证的 NVD 访问，请在 `.env` 中设置 `NVD_API_KEY`。 ### Docker / Compose 工作台 从全新的仓库检出在本地运行与模板对齐的 Workbench shell 和 React 前端： ``` cp .env.example .env docker compose -f compose.yml -f compose.override.yml up --build backend frontend ``` 检入的 `.env.example` 已经适合此本地快速入门。`NVD_API_KEY` 可以保留为空，因为演示导入路径使用的是检入的锁定 provider 快照。不要在本地工作站之外重复使用占位符 `SECRET_KEY` 或 `FIRST_SUPERUSER_PASSWORD`。 然后打开这些本地 URL： - React Workbench shell：`http://127.0.0.1:5173` - 模板后端状态：`http://127.0.0.1:8000/api/v1/workbench/status` - 模板工具健康检查： `http://127.0.0.1:8000/api/v1/utils/health-check/` 本地模板登录使用 `.env` 默认值： - email：`admin@example.com` - password：`changethis` 登录后，创建一个项目并导入 `data/sample_cves.txt` 作为 `CVE list`。启用锁定 provider 数据并使用 provider 快照 `demo_provider_snapshot.json`。Compose 后端以只读方式将 `./data` 挂载到 `/app/examples`，因此导入可以在没有实时 API 密钥的情况下重放 provider 数据。 登录后的等效 API 演示导入： ``` TOKEN="$( curl -sS -X POST http://127.0.0.1:8000/api/v1/login/access-token \ -H 'Content-Type: application/x-www-form-urlencoded' \ --data 'username=admin@example.com&password=changethis' \ | python3 -c 'import json, sys; print(json.load(sys.stdin)["access_token"])' )" PROJECT_ID="$( curl -sS -X POST http://127.0.0.1:8000/api/v1/projects/ \ -H "Authorization: Bearer ${TOKEN}" \ -H 'Content-Type: application/json' \ --data '{"name":"online-shop-demo","description":"Local Docker quickstart demo"}' \ | python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])' )" curl -sS -X POST "http://127.0.0.1:8000/api/v1/projects/${PROJECT_ID}/imports" \ -H "Authorization: Bearer ${TOKEN}" \ -F input_type=cve-list \ -F provider_snapshot_file=demo_provider_snapshot.json \ -F locked_provider_data=true \ -F file=@data/sample_cves.txt ``` 用于 CI/CD 的作用域服务令牌在登录后通过 `/settings` 或 `/api/v1/api-tokens/` 进行管理。模板 API 仅存储 PBKDF2-SHA256 令牌哈希，仅在创建响应中显示明文令牌，并支持 `read`、`import`、`report` 和 `admin` 作用域。服务令牌只有在具有匹配作用域或 `admin` 作用域时才能调用导入和报告端点。 进行快速状态检查： ``` curl http://127.0.0.1:8000/api/v1/workbench/status ``` 维护者可以通过 `make docker-demo-smoke` 运行相同的 Compose 就绪路径，它会启动后端和前端，轮询 `/api/v1/workbench/status`，验证锁定的 provider 数据导入，通过 `/api/v1/providers/update-jobs` 触发仅缓存的 provider 更新，并在检查后拆除堆栈。 默认的 Compose 堆栈现在遵循 FastAPI Full Stack Template 的结构：`db`、`backend` 和 `frontend`。后端服务有意提供新的模板 shell (`app.main:app`)，并未声称旧版 Jinja2 Workbench 已迁移。模板 provider 更新快照被写入位于 `/app/provider-snapshots` 的 `template-provider-snapshots` 卷，而 `/app/examples` 仍然是只读的演示数据挂载。要针对可选的 Postgres 配置文件和相同的 Alembic 迁移路径对旧版 Workbench 进行冒烟测试，请运行： ``` make docker-postgres-migration-smoke ``` 这将启动 `db` 和配置好的 `workbench-postgres` 服务，在 `http://127.0.0.1:8001` 上提供旧版 Workbench，并在健康检查后拆除配置卷。 当前的本地 Compose 堆栈中未启用 Adminer 和 Mailcatcher/Mailpit。`.env.example` 保留了 SMTP 占位符以保持模板一致性，但邮件投递不属于本地快速入门的一部分。仅将数据库或电子邮件调试服务作为明确的部署/开发工具更改来添加。 后端镜像仍包含 CLI 和旧版 Workbench 命令，用于配置化的迁移检查。您可以使用以下命令显式初始化一个配置化的旧版数据库： ``` docker compose -f compose.yml -f compose.override.yml --profile postgres run --rm workbench-postgres vuln-prioritizer db init ``` CLI 在同一镜像中仍然可用： ``` docker build -f backend/Dockerfile -t vuln-prioritizer-workbench-backend:local . docker run --rm vuln-prioritizer-workbench-backend:local vuln-prioritizer --help ``` 在正常 Python 安装后等效的本地 Workbench 命令： ``` export VULN_PRIORITIZER_DB_URL=sqlite:///./data/workbench.db export VULN_PRIORITIZER_UPLOAD_DIR=./data/uploads export VULN_PRIORITIZER_REPORT_DIR=./data/reports export VULN_PRIORITIZER_PROVIDER_SNAPSHOT_DIR=./data export VULN_PRIORITIZER_CACHE_DIR=./.cache/vuln-prioritizer vuln-prioritizer db init vuln-prioritizer web serve --host 127.0.0.1 --port 8000 ``` Workbench 运行时环境： | 变量 | 默认值 / Compose 值 | 用途 | | --- | --- | --- | | `NVD_API_KEY` | 空 | 可选的经身份验证的 NVD 访问。 | | `VULN_PRIORITIZER_NVD_API_KEY_ENV` | `NVD_API_KEY` | 为读取 NVD 密钥而读取的环境变量名称。 | | `VULN_PRIORITIZER_DB_URL` | 本地: `sqlite:///./data/workbench.db`; 配置化的 Compose 迁移冒烟测试: `postgresql+psycopg://...@db:5432/workbench` | 旧版 Workbench 数据库 URL。 | | `VULN_PRIITIZER_UPLOAD_DIR` | 本地: `data/uploads`; Compose: `/app/uploads` | 上传的源文件。 | | `VULN_PRIORITIZER_REPORT_DIR` | 本地: `data/reports`; Compose: `/app/reports` | 生成的报告和证据包。 | | `VULN_PRIORITIZER_PROVIDER_SNAPSHOT_DIR` | 本地: `data`; Compose: `/app/provider-snapshots` | 用于锁定 provider 快照重放和生成的 provider 更新快照的受信目录。 | | `VULN_PRIORITIZER_CACHE_DIR` | 本地: `.cache/vuln-prioritizer`; Compose: `/app/.cache/vuln-prioritizer` | Workbench 分析使用的 Provider 缓存。 | | `VULN_PRIORITIZER_MAX_UPLOAD_MB` | `25` | 每次导入的上传大小限制。 | | `VULN_PRIORITIZER_CSRF_TOKEN` | 未设置时每个进程随机 | 可选的固定本地表单令牌，用于可重复的演示。 | | `VULN_PRIORITIZER_ALLOWED_HOSTS` | 本地: `127.0.0.1,localhost,testserver`; 配置化的 Compose 迁移冒烟测试: `127.0.0.1,localhost` | 本地 Workbench 的逗号分隔 Host 头允许名单。 | 密钥和 provider 加固契约： - 可选的 NVD API 密钥仅从由 `VULN_PRIORITIZER_NVD_API_KEY_ENV` 命名的环境变量中读取，该变量默认为 `NVD_API_KEY`。仅存储和显示变量名，绝不存储密钥值。 - 环境变量名称设置必须符合 `^[A-Z_][A-Z0-9_]*$`。无效的名称属于配置错误，绝不能将其视为字面密钥值。 - 模板占位符密钥（例如 `changethis`）仅作为本地/开发引导的默认值。预发布和生产环境部署必须拒绝 `SECRET_KEY`、`FIRST_SUPERUSER_PASSWORD` 和等效凭据设置的默认模板密钥。未知的 `ENVIRONMENT` 值会默认拒绝访问（失败即关闭），而不是回退到本地模式。 - 针对 NVD、FIRST EPSS 和 CISA KEV 的内置实时 provider 端点是固定的 HTTPS 公共源常量。运行时设置可以选择缓存目录、锁定的快照或离线文件，但绝不能提供不安全的实时 provider URL 覆盖。 - 设置页面、报告、证据包、清单、日志和诊断负载必须对密钥值和本地绝对路径进行脱敏处理，仅暴露非机密状态，如 ``、``、变量名、计数、哈希值、包路径或来源标签。 对于锁定的 Workbench 重放，仅提交快照文件名，例如 `demo_provider_snapshot.json`。应用会从 `VULN_PRIORITIZER_PROVIDER_SNAPSHOT_DIR` 或 provider 缓存中解析它，并拒绝任意路径。 旧版 Workbench API 令牌行为被有意设为本地优先。一个全新的本地数据库没有激活的令牌，因此对 `/api/*` 的修改请求在离线演示期间保持开放。使用 `POST /api/tokens` 创建第一个令牌；在存在任何激活的令牌之后，修改 `/api/` 的请求需要 `Authorization: Bearer ` 或 `X-API-Token: `。旧版令牌现在带有相同的 `read`、`import`、`report` 和 `admin` 作用域。现有升级的令牌被视为 `admin`；除非提供了作用域，否则新的旧版令牌默认为 `admin`。仅存储 SHA-256 令牌哈希。 与模板对齐的 Workbench shell 目前具有一个已配置超级用户的 JWT 登录冒烟测试路径。基于 DB 的模板用户、RBAC 和最终的项目成员资格规则是独立的迁移工作。 Workbench 项目设置可以通过 `POST /api/projects/{project_id}/settings/config` 保存为配置即代码。负载使用与 CLI 运行时配置相同的 `vuln-prioritizer.yml` schema，拒绝未知键，并在没有项目快照存在时保留向后兼容的默认值。 Provider 更新作业在两个 Workbench 界面中均可用： - 模板 API：`POST /api/v1/providers/update-jobs` 和 `GET /api/v1/providers/update-jobs`，使用已配置的用户 JWT 或 `admin` API 令牌进行身份验证。 - 旧版本地 Workbench：`POST /api/providers/update-jobs` 和“设置”页面。 它们是同步的本地作业，旨在用于 cron 或其他受信任的本地调度器；失败会被记录下来而不会替换之前的 provider 快照，并且重叠的刷新会返回 HTTP 409。可选的 Compose `postgres` 配置文件还包含一个默认禁用的 `provider-scheduler` 服务。仅当您希望本地 Workbench 提交定期的 provider 更新作业时才启动它： ``` docker compose -f compose.yml -f compose.override.yml --profile postgres up -d db workbench-postgres provider-scheduler ``` 调度器向 `http://workbench-postgres:8000/api/providers/update-jobs` 发送请求，默认每 86400 秒进行一次仅缓存的 provider 刷新，并接受以下环境变量： | 变量 | 默认值 | 用途 | | --- | --- | --- | | `VULN_PRIORITIZER_PROVIDER_UPDATE_INTERVAL_SECONDS` | `86400` | 计划的 provider 更新提交之间的延迟。 | | `VULN_PRIORITIZER_PROVIDER_UPDATE_SOURCES` | `nvd,epss,kev` | 逗号分隔的 provider 来源列表。 | | `VULN_PRIORITIZER_PROVIDER_UPDATE_CACHE_ONLY` | `true` | 默认情况下保持计划作业为离线/仅缓存；仅当打算进行实时 provider 出站访问时才设置为 `false`。 | | `VULN_PRIORITIZER_PROVIDER_UPDATE_MAX_CVES` | 空 | 每次计划刷新的可选上限。 | | `VULN_PRIORITIZER_PROVIDER_UPDATE_API_TOKEN` | 空 | 当已启用 API 令牌时使用的可选本地 Workbench API 令牌。 | Provider 更新作业使用 provider 快照目录锁文件来拒绝重叠的刷新，并返回 HTTP 409 而不是竞争快照写入。 GitHub issue 导出从模板 API `POST /api/v1/projects/{project_id}/github/issues/preview` 开始。请求可以传递显式的 `finding_ids` 以生成经过审查的 issue markdown，其中包含优先级、理由、修复建议和证据参考。Issue 创建需要带有 `dry_run: false`、一个仓库以及一个显式配置的令牌环境变量的 `POST /api/v1/projects/{project_id}/github/issues/export`。 当前本地 Workbench 的限制： - Compose 路径是本地优先且单节点的。它没有针对互联网暴露进行加固。 - Workbench UI/API 支持与 CLI 相同的输入格式矩阵，用于本地单文件和多文件导入。 - SQLite 仍然是默认的 Workbench 运行时；Compose Postgres 配置文件是一个可选的迁移冒烟测试路径。Workbench 记录本地导入、provider 刷新、报告和证据包的持久化作业状态，但独立的异步工作进程、SSO、组织范围的工单同步策略和多工作区租户仍然在当前的本地优先范围之外。 - 本项目仍然不扫描系统、修补软件或生成启发式/AI 的 CVE 到 ATT&CK 的映射。 - 未经涵盖 TLS/代理、备份/恢复、审计保留、角色设计、令牌处理和威胁模型的单独加固审查，请勿将本地 Workbench 暴露在公共互联网上。 当前 Workbench 的就绪状态和共享部署前提条件记录在 [docs/workbench-threat-model.md](docs/workbench-threat-model.md) 中。VPW-071 密钥/provider 加固证据记录在 [docs/evidence/vpw-071-secret-provider-hardening.md](docs/evidence/vpw-071-secret-provider-hardening.md) 中。 历史实施计划仍可在 [docs/workbench-masterplan.md](docs/workbench-masterplan.md) 中找到，并且 [docs/roadmap.md](docs/roadmap.md) 跟踪已发布的 CLI 以及本地 Workbench 发布线。 ## 演示 对于本地浏览器演示，请使用检入的离线运行手册：[docs/workbench-offline-demo.md](docs/workbench-offline-demo.md)。它使用仓库固件和锁定的 provider 重放，因此可以在没有客户数据或仅限实时的 provider 行为的情况下复现截图和证据。 对于模板迁移冒烟测试演示，请运行： ``` make docker-demo-smoke ``` 该命令启动模板后端和 React shell，验证 `/api/v1/workbench/status`，检查前端和登录路由，然后拆除堆栈。 无需运行 Workbench 即可查看已提交的模板报告演示工件： - [docs/examples/vpw-054-template-technical-report.md](docs/examples/vpw-054-template-technical-report.md) - [docs/examples/vpw-054-template-executive-report.html](docs/examples/vpw-054-template-executive-report.html) - [docs/examples/vpw-054-template-analysis-result.v1.json](docs/examples/vpw-054-template-analysis-result.v1.json) ## 快速入门 有关跨安装、Docker、Workbench 演示、架构、数据模型、导入、provider、评分、报告、ATT&CK、安全性和已知限制的完整外部用户文档路径，请从 [docs/user_documentation.md](docs/user_documentation.md) 开始。 ### 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 感知分析 本项目中的 ATT&CK/TTP 上下文是用于风险解释、检测覆盖、缓解讨论和优先级排序的防御性上下文。它不是漏洞利用证明、攻击链指导，或 CVE 正在被 actively 用于攻击您的环境的证据。 ``` 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. 可选的本地防御上下文覆盖 ``` vuln-prioritizer analyze \ --input trivy-results.json \ --input-format trivy-json \ --defensive-context-file ./defensive-context.json \ --format json \ --output analysis.json ``` `--defensive-context-file` 是一个用于 OSV、GHSA、Vulnrichment 或 SSVC 证据（您已经拥有的）的本地/离线 JSON 覆盖。它不是一个实时公告获取路径，并且不会影响来自 CVSS、EPSS 和 KEV 的基本优先级评分。 ### 7. 可选的本地 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 vuln-prioritizer state trends --db build/state.db --format json vuln-prioritizer state service-history --db build/state.db --service payments ``` ### 8. 可复现的 Provider 快照重放 ``` vuln-prioritizer data export-provider-snapshot \ --input cves.txt \ --output provider-snapshot.json vuln-prioritizer analyze \ --input cves.txt \ --provider-snapshot-file provider-snapshot.json \ --locked-provider-data \ --format json \ --output analysis.json ``` 当本地冒烟测试必须避免实时的 provider 刷新时，请在 `data export-provider-snapshot` 上使用 `--cache-only`。 ### 9. 维护者演示证据包 从仓库检出中，维护者可以在没有实时 provider 调用的情况下复现 Workbench v1.0 演示证据包： ``` make demo-evidence-bundle-check ``` 该目标使用检入的固件、`data/demo_provider_snapshot.json`、锁定的 provider 重放以及在 `Makefile` 中配置的固定演示时间戳。它将写入： - `build/v1.0-demo-analysis.json` - `build/v1.0-demo-evidence-bundle.zip` - `build/v1.0-demo-evidence-bundle-verification.json` 要从检出中验证已生成的包，请直接运行相同的 CLI 契约： ``` PYTHONPATH=backend/src VULN_PRIORITIZER_FIXED_NOW=2026-04-21T12:00:00+00:00 \ python3 -m vuln_prioritizer.cli report verify-evidence-bundle \ --input build/v1.0-demo-evidence-bundle.zip \ --output build/v1.0-demo-evidence-bundle-verification.json \ --format json ``` 仅使用相对于仓库的路径记录发布证据。归档命令输出、`git rev-parse HEAD`、其中 `summary.ok` 为 `true` 的验证 JSON，以及这三个生成文件的 SHA-256 值： ``` shasum -a 256 \ build/v1.0-demo-analysis.json \ build/v1.0-demo-evidence-bundle.zip \ build/v1.0-demo-evidence-bundle-verification.json ``` 请勿在公开的发布证据中记录特定于机器的绝对路径、`.env` 内容、API 密钥、令牌、cookies 或私有扫描导出。 ## 运行时配置 `v1.1.0` 通过 `vuln-prioritizer.yml` 增加了一等公民（first-class）的运行时配置。 可选的 SQLite 状态存储被有意独立出来：它仅限本地、选择启用，并且不会更改 `analyze`、`report`、`snapshot` 或证据的语义。 示例： ``` 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 attack: validate: attack_mapping_file: ./attack-mapping.json attack_technique_metadata_file: ./attack-techniques.json data: export-provider-snapshot: cache_only: true ``` 通过自动发现或显式方式使用它： ``` 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 用法和本地 Workbench 应用路径： - [docs/user_documentation.md](docs/user_documentation.md) - [docs/use_cases.md](docs/use_cases.md) - [docs/playbooks.md](docs/playbooks.md) - [docs/support_matrix.md](docs/support_matrix.md) - [docs/architecture/index.md](docs/architecture/index.md) - [docs/architecture/core-workbench-schema.md](docs/architecture/core-workbench-schema.md) - [docs/architecture/analysis-run-provider-schema.md](docs/architecture/analysis-run-provider-schema.md) - [docs/benchmarking.md](docs/benchmarking.md) - [docs/contracts.md](docs/contracts.md) - [docs/methodology.md](docs/methodology.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/roadmap.md](docs/roadmap.md) - [ROADMAP.md](ROADMAP.md) - 历史 Workbench 总体规划：[docs/workbench-masterplan.md](docs/workbench-masterplan.md) 维护者 / 仓库检出工作流： - [docs/release_operations.md](docs/release_operations.md) ## 社区与支持 - 使用问题和工作流帮助：GitHub Discussions - 可复现的 Bug 和范围明确的功能请求：GitHub Issues - 安全报告：GitHub 私有漏洞报告，并以 [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) ## GitHub Action 本仓库包含一个复合 GitHub Action，用于 `analyze`、`compare`、`explain`、`doctor`、输入验证、快照、汇总、provider 数据验证、ATT&CK 验证/覆盖、静态报告渲染、Workbench 风格的报告工件、证据包和 SARIF 验证。 在 `actions/checkout` 之后使用它，因为扫描导出、SBOM 或其他分析输入文件位于消费者仓库中，而不是在 action 仓库中。 在 `mode: analyze` 中，`input` 和 `input-format` 接受换行符分隔的值，这样一个 action 步骤就可以合并多个来源。该 action 还传递了 CLI 的豁免（waiver）、过滤器、排序、缓存、provider 重放和失败门禁标志，用于确定性的 CI 运行。 ``` - uses: actions/checkout@v6 - name: Prioritize vulnerabilities uses: Noetheon/vuln-prioritizer-workbench@vX.Y.Z with: mode: analyze input: | trivy-results.json github-alerts-export.json input-format: | trivy-json github-alerts-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" defensive-context-file: defensive-context.json waiver-file: waivers.yml hide-waived: "true" fail-on: critical fail-on-expired-waivers: "true" max-provider-age-hours: "48" fail-on-stale-provider-data: "true" sort-by: operational max-cves: "250" ``` 将 `vX.Y.Z` 替换为您想要使用的发布标签或提交 SHA。`summary-template` 向后兼容，默认为 `detailed`。对于 GitHub 步骤摘要或 PR 评论，将其设置为 `compact`，或者当您需要完整的执行摘要工件时保留 `detailed`。如果工作流只需要 `$GITHUB_STEP_SUMMARY`，该 action 现在可以在不需要显式 `summary-output-path` 的情况下生成摘要。 常见的 analyze/compare/snapshot Action 输入包括 `waiver-file`、`defensive-context-file`、`hide-waived`、`fail-on-provider-error`、`fail-on-expired-waivers`、`fail-on-review-due-waivers`、`priority`、`kev-only`、`min-cvss`、`min-epss`、`sort-by`、`max-cves`、`provider-snapshot-file`、`locked-provider-data`、`max-provider-age-hours`、`fail-on-stale-provider-data`、`no-cache`、`cache-dir`、`cache-ttl-hours`、`nvd-api-key-env`、`offline-kev-file` 和 `offline-attack-file`。`defensive-context-file` 仅传递本地/离线 JSON 上下文覆盖；它不获取公告数据，也不改变基本优先级评分。报告模式包括 `report-html`、`workbench-report`、`report-evidence-bundle`、`verify-evidence-bundle` 和 `validate-sarif`；当本地的 SARIF 契约未满足时，在 analysis/report 步骤中设置 `validate-sarif: "true"` 可使作业在上传前失败。 有关完整的契约和 CI 模式，请参阅 [docs/integrations/reporting_and_ci.md](docs/integrations/reporting_and_ci.md)，包括检入的 [Workbench Markdown/JSON artifact workflow](.github/examples/workbench-report-artifacts.yml)，以及 [docs/examples/github_action_summary_templates.md](docs/examples/github_action_summary_templates.md) 中的精简与详细示例。 ## 开发 有用的本地门禁： ``` python3 -m pytest -q make check make benchmark-check make playwright-install make playwright-check make release-check make demo-sync-check-temp make package-check-temp ``` 使用 `make playwright-check` 进行真实浏览器 Workbench 覆盖；在首次运行 Playwright 之前，在开发机器上运行一次 `make playwright-install`。如果您更改了 docs、examples 或报告工件，请运行 `make release-check`，以便提交的示例输出保持同步。当您希望在不修改检入的 docs 工件或 `dist/` 的情况下在临时副本中进行相同的演示或包验证时，请使用 `*-temp` 目标。 拉取请求准备就绪： - 说明更改是否影响了 CLI、Workbench、Docker、docs、发布或打包行为。 - 包含您运行的本地检查。对于仅文档的更改，`make docs-check` 加上有针对性的 CLI 帮助检查通常就足够了；更广泛的行为更改应使用 `make check` 或 `make release-check`。 - 保持公开示例与受支持的安装路径、上述本地 Workbench 限制以及无扫描器/无启发式 ATT&CK 的范围边界保持一致。 ## 项目状态 当前发布线： - 当前包版本线 `v1.1.0` - Workbench 本地应用、高级 ATT&CK、治理、报告和集成表面已在 `main` 上实现 - `v1.1.0` 提供了 GitHub 标签安装路径 - `v1.1.0` 发布了包含源码和 wheel 分发资产的 GitHub Release - PyPI 和 TestPyPI 工作流已准备就绪，但在受信发布者设置启用之前，实时发布仍被明确限制 ## 许可证 [MIT](LICENSE)

标签：ATT&CK映射, CISA KEV, CISA项目, CVE管理, EPSS, MIT许可, NVD, Python CLI, SBOM解析, TTP分析, VEX, Web报告, XXE攻击, 占用监测, 可解释性安全, 安全合规, 安全工作台, 开源安全工具, 插件系统, 无线安全, 本地优先, 漏洞优先级排序, 漏洞修复决策, 离线安全工具, 网络代理, 网络安全, 网络安全审计, 自托管仪表盘, 证据管理, 请求拦截, 豁免管理, 资产管理, 逆向工具, 逆向工程平台, 速率限制处理, 防御上下文, 隐私保护