EdgewareRoad/TrivySummary

# Trivy 摘要 TrivySummary 旨在汇总 Trivy 扫描的 JSON 输出，以便用于报告。软件包漏洞会被精简为相应的 CVE，并提供不同[优先级](#priority-model)的漏洞头条计数。 除了 Trivy 提供的厂商严重性和 CVSS v3 评分外，还可以获取 EPSS 评分，从而允许对所有漏洞的可利用性和严重性进行图表化展示和优先级排序。 该工具提供了多种选项来辅助报告生成。 * 它可以接收单个 Trivy 扫描的 JSON 文件，并将其汇总输出为 PDF 或 JSON * 它可以接收在不同时间点获取的同一逻辑组件的两个 Trivy 扫描 JSON 文件并进行比较，同样可以汇总输出为 PDF 或 JSON 它还可以通过以下方式辅助 CI/CD 流水线：如果存在达到或超过给定优先级的未解决漏洞，则以错误状态退出（例如，如果发现至少一个 CRITICAL 或 HIGH 漏洞，则判定为失败）。 ## 用法 需要 Java Runtime Environment 17 或更高版本。从 _bin_ 文件夹运行应用程序（在 Windows 上，请使用 _trivysummary.bat_ 而不是 _trivysummary_）。 要汇总单个 Trivy JSON 文件，请使用以下格式： ``` trivysummary .json ``` 要汇总并比较同一组件的两个 Trivy JSON 文件，请使用以下格式： ``` trivysummary .json .json ``` 关于扫描日期，本应用程序依赖于由 Trivy 后续版本（自 v0.48.0 起）添加的 createdAt 属性。 ### 参数 ``` --help Displays this help message --title=... Sets a report title. If unset, a default title is used containing the input file path(s) provided --outputFile=... The required output file name. If the filename ends in .pdf then the output is a PDF report. If not, a JSON format is used. Defaults to "trivysummary.pdf" in the current working directory. Please note that the --bothPDFAndJSONOutput argument can be used to output both PDF _and_ JSON --bothPDFAndJSONOutput If set, both PDF and JSON output will be created, using the --outputFile argument and intelligently amending the suffix. Saves time if you need both output forms. --failPriorityThreshold=... The priority threshold at or above which any open vulnerabilities will cause this app to return an error (returns 1, rather than 0). Must be one of LOW, MEDIUM, HIGH or CRITICAL. If unset, an error won't be returned for any set minimum priority. --whitelist=... If set, one or more files in JSON format listing CVEs which should be whitelisted in the output. You can specify this argument multiple times if you wish to load multiple whitelists --treatmentPlan=... If set, the JSON format treatment plan so that progress can be reported and tracked. Only one treatment plan may be specified. --offline If set, TrivySummary will not attempt to access EPSS scores to assess the exploitability of CVEs. This will bypass graphing and prioritisation but is useful if using this tool from airgapped environments. --priorityModel=... If this is set, TrivySummary will load the specified priority model JSON file. If this isn't set, the model defaults to SEVERITYONLY, i.e. that the priority is the same as the vendor severity. --useTodayForEPSSQuery If this is set, TrivySummary will request EPSS scores for today and not for the date of the scan (the default). Is ignored if in offline mode ``` ### 白名单 本应用程序支持将漏洞加入白名单，方式是提供一个或多个 JSON 文件，每个文件均需采用下面指定的格式。 将某个 CVE 加入白名单会导致其从 Trivy 报告的未解决漏洞列表中移除，并且在判定是否达到失败阈值时将其排除在外（例如，如果失败阈值设置为 CRITICAL，而您将唯一一个未解决的 CRITICAL CVE 加入了白名单，那么应用程序将不会将其报告为错误）。 每个 JSON 文件都是一个由白名单条目组成的数组。每个白名单条目包含以下属性： * vulnerabilityID _（必填）_ CVE 引用编号。 * reason _（必填）_ 说明该漏洞为何可被加入白名单的理由，即为何它不会影响您的代码。它是否已被确认为误报？您的代码是否通过功能控制禁用了该组件的暴露面？等等。 * nextReviewDate _（必填）_ 格式为 yyyy-MM-dd 的日期。必须指定。如果您正在创建一个需要立即审查的新条目（例如，为了让您的代码在您评估是否需要在发布前进行修复之前能够顺利构建，请将此日期设置为今天或过去的某个日期）。 * approvalDate _（可选）_ 审查该漏洞的日期，格式为 yyyy-MM-dd。必须同时设置 approvalDate 和 approvedBy 字段，TrivySummary 才会将其识别为已批准。approvalDate 不能是将来的日期，否则 TrivySummary 将不会承认其已被批准。 * approvedBy _（可选）_ 批准人的姓名。必须同时设置 approvalDate 和 approvedBy 字段，TrivySummary 才会将此白名单识别为已批准。 有关加入白名单的示例 JSON，请[参见此处](src/test/resources/sampleWhitelist1.json) ### 处理计划 本应用程序支持通过指定处理计划来提供更完整的进度报告结构，该计划将被合并到任何生成的 PDF 报告中。 处理计划的格式如下： * ticketSystemURLTemplate _（必填）_ 工单系统的模板化 URL 格式，其中工单引用号需替换为 _{ticketId}_。 例如，典型的 Jira 配置可能是 `https://myjirasystem.mydomain.com/browse/{ticketId}` * defaultNoteText _（必填，但可留空）_ 当检测到的漏洞未匹配到任何注释或处理方式时，将显示的默认注释。 * treatments _（必填）_ 当前工单系统中存在的处理方式列表，需匹配一个或多个 CVE 引用号，和/或一个或多个构件名称。 * notes _（必填）_ 可能适用的注释列表，需匹配一个或多个 CVE 引用号，和/或一个或多个构件名称。 构件名称基于“开头匹配”原则进行匹配，因此您可以编写一条匹配多个标签的注释（例如，提供有关该组件在您架构中所处位置的操作背景信息）。 其目的在于：在工单不太合适的情况下（例如，目前尚无可用修复程序，但预计即将发布补丁版本，此时使用注释来解释这一情况及其追踪方式，可能比链接到工单的处理方式更为妥当），能够清晰地说明已达成一致的处理方案。 有关处理计划的示例 JSON，请[参见此处](src/test/resources/testapp/testAppTreatments1.json) ### 通过 EPSS（可利用性评分）实现更好的修复优先级排序 [Trivy](https://github.com/aquasecurity/trivy) 的开源版本仅支持针对严重性进行评估（更准确地说，是强调厂商对严重性的评估）。除此之外，还有其他评估 CVE 的方法，包括 [EPSS](https://www.first.org/epss/)（即漏洞利用预测评分系统）。 默认情况下，TrivySummary 会为每个 CVE 添加 EPSS 评分（除非使用 _--offline_ 标志覆盖此行为）并绘制结果图表。对于 CVSS 和 EPSS 综合得分最高的 CVE，将会进行标注。 此外，通过使用自定义的[优先级模型](#priority-model)，可以比仅考虑严重性的模型更有效地对同时具有 CVSS 和 EPSS 评分的 CVE 进行优先级排序。 **请注意**，CVE 标记的严重性和 CVSS 评分可能不一致，因为像 RedHat 这样的厂商通常会根据他们对更广泛情况以及软件部署和使用方式的评估，设定与 CVSS 所暗示的严重性不同的厂商严重性。Trivy 会考虑到这一点，并优先采用厂商的评估（请参阅[严重性选择](https://aquasecurity.github.io/trivy/dev/docs/scanner/vulnerability/)部分）。 ## 优先级模型 只要 TrivySummary 没有在 _--offline_ 模式下使用，就支持多种不同的优先级模型。 ### 仅严重性 默认模式（即不指定优先级模型）是“仅严重性”，在这种模式下，优先级的设定与开源的 Trivy 产品一样，完全由厂商严重性（CRITICAL、HIGH、MEDIUM、LOW）决定。 示例图表可能如下所示： 虽然概念上很简单，但缺点是它并不能真正帮助开发者进行漏洞的分类和优先级排序，因为每个厂商的严重性可能符合、也可能不符合 CVSS v3 评分的预期，更不用说结合 EPSS 评分来衡量漏洞的可利用性了。 ### 矩形模型 在此模型类型中，可以通过为 CRITICAL、HIGH 和 MEDIUM 优先级的 CVE 分别设置最低 CVSS 和 EPSS 阈值来进行识别。TrivySummary 完全根据每个漏洞是否超过相应的阈值来设定优先级。这使得每个优先级区域在图表上呈现为矩形，如下例所示： 请注意现在的颜色分级，以及这是一个更加清晰的模型这一事实。另外请注意，这使得对漏洞进行有效的分类成为可能（可将 CRITICAL、HIGH 和 MEDIUM CVE 的数量与上述“仅严重性”模型进行比较）。 它的明显优势在于提高了漏洞评估的信噪比，并且是一个非常容易向利益相关者描述的模型。 然而，它确实容易让每个矩形的左下角成为边界漏洞的潜在陷阱，可能会使它们看起来比实际情况具有更高的优先级。可以通过简单地保持阈值与分配文本标记的标准模型（如果存在）保持一致来缓解这种情况（例如，CVSS 评分 9.0 及以上为 CRITICAL），但这可能会产生相反的效果，导致实际窗口比预期的要小。 为了解决这个问题，我们开发了如下的椭圆优先级模型。 ### 椭圆形 此优先级模型与上述矩形模型非常相似，但在此模型中，每套优先级 CVSS/EPSS 阈值定义的是椭圆的长轴和短轴，并使用标准的椭圆方程来界定 CVE 属于哪个优先级。最好通过以下示例来说明： 这更准确地模拟了希望优先处理那些最接近 CVSS=10.0 / EPSS=1.0 漏洞的需求。 该模型的一大优势在于，它促使我们采用更宽泛的严重性视角。它可以设定比假设的仅严重性模型（例如，CVSS 评分 9.0 及以上为 CRITICAL）所规定的更低的 CVSS 阈值，而不会对整体风险阈值产生不利影响。 因此，作者强烈推荐使用椭圆形优先级模型，而不是其他模型，当然，用户可以自行选择。 ### 指定优先级模型 默认的优先级模式是“仅严重性”，因为其他模式需要设置一些自定义阈值。 要覆盖此行为，可以使用 _--priorityModel=..._ 属性指向一个包含优先级模型的 JSON 文件。 这里提供了[仅严重性](src/test/resources/samplePriorityModelSeverityOnly.json)、[矩形](src/test/resources/samplePriorityModelRectangular.json)和[椭圆形](src/test/resources/samplePriorityModelElliptical.json)模型的示例文件。 每个 JSON 文件都有一个简单的结构，包含以下字段： * type _（必填）_ 优先级模型类型。可选值为 SEVERITYONLY、RECTANGULAR 或 ELLIPTICAL。 * criticalPriorityThresholds _（可选）_ 仅在 RECTANGULAR 和 ELLIPTICAL 模型中有意义。这是一个包含两个属性的复杂类型： * minimumCVSS _（必填）_ * minimumEPSS _（必填）_ 用于测试 CVE 的 CVSS 和 EPSS 评分。如果 CVE 的两项得分均 >= 此处配置的相应最低阈值，则该 CVE 可被视为属于此优先级。 * highPriorityThresholds _（可选）_ 仅在 RECTANGULAR 和 ELLIPTICAL 模型中有意义。这是一个包含与 criticalPriorityThresholds 相同两个属性的复杂类型。 * mediumPriorityThresholds _（可选）_ 仅在 RECTANGULAR 和 ELLIPTICAL 模型中有意义。这是一个包含与 criticalPriorityThresholds 相同两个属性的复杂类型。 请注意，CVE 会按 CRITICAL、HIGH 然后是 MEDIUM 的顺序进行评估，以检查它们是否满足相应的阈值。 省略某些阈值是允许的（例如，只保留 CRITICAL 和 HIGH），但是，省略所有的优先级阈值显然是不合逻辑的。对于不符合上述任何阈值的 CVE，将被归类为 LOW 优先级。