nMoncho/sbt-dependency-check

# sbt-dependency-check [](https://github.com/nMoncho/sbt-dependency-check/actions/workflows/main.yaml) [](https://mit-license.org/) sbt-dependency-check 插件允许项目监控依赖库中已知的、公开披露的漏洞（例如 CVE）。该插件通过使用 出色的 [OWASP DependencyCheck 库](https://github.com/dependency-check/DependencyCheck)来实现这一点，该库已经提供了与其他构建和持续集成系统的多种集成。 为了保持本 `README.md` 的简明扼要，关于如何使用此插件的详细文档可以在我们的 [wiki](https://github.com/nMoncho/sbt-dependency-check/wiki) 中找到。 ## 安装说明 将插件添加到您的项目配置中： ``` addSbtPlugin("net.nmoncho" % "sbt-dependency-check" % "1.9.0") ``` 支持的最低 SBT 版本为 `1.9.0`。 ## 使用方法 ### 入门指南 不要被此插件中定义的所有配置设置所吓倒。它们都有合理的默认值。 最好的入门方式是安装插件，并设置您的 [NVD API Key](#nvd-api)： ``` import net.nmoncho.sbt.dependencycheck.settings._ dependencyCheckNvdApi := NvdApiSettings(apiKey = "YOUR_NVD_API_KEY") ``` 然后只需运行： ``` sbt -Dlog4j2.level=info dependencyCheck ``` 首次运行这些任务时会花费一些时间，甚至可能需要几分钟。对于 SBT 1.x，分析会将报告写入 `target/{scala-version}/dependency-check-report.html`；对于 SBT 2.x，报告将写入 `target/out/jvm/{scala-version}/{project}/dependency-check-report.html`。插件会通过日志提示报告的写入位置。 在此之后，您可以随意查看可用的任务和设置。 ### 任务 以下任务可用： | 任务 | 描述 | |:----------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `dependencyCheck` | 对项目运行 dependency-check 并为每个子项目生成报告。 | | `dependencyCheckAggregate` | 对项目聚合运行 dependency-check，并将结果合并到单个报告中。 | | `dependencyCheckAllProjects` | 对所有项目运行 dependency-check，并将结果合并到单个报告中。 | | `dependencyCheckUpdate` | 更新来自 NIST 的 NVD 数据的本地缓存。 | | `dependencyCheckPurge` | 删除 NVD 的本地副本。用于强制刷新数据。 | | `dependencyCheckListSettings` | 列出在分析期间使用的设置。 | | `dependencyCheckListUnusedSuppressions` | 列出未使用的抑制规则，仅考虑在项目定义（即 build.sbt）中定义的抑制文件或规则，不包括托管抑制或打包的抑制。 | | `dependencyCheckListSuppressions` | 列出添加到 Owasp 引擎中的抑制规则，这些规则在项目定义（即 build.sbt）中定义，或是导入的打包抑制。 | 默认情况下，报告将写入 `crossTarget.value`。可以通过设置 `dependencyCheckOutputDirectory` 来覆盖此行为。 详情请参见 [配置](#configuration)。 #### `dependencyCheck` 参数 默认情况下，`dependencyCheck` 将在选定的项目下运行，如果未选择任何项目，则默认在 `root` 下运行。它也会在该项目聚合的子项目上运行（就像 SBT 中的任何其他任务一样），为每个项目生成一份报告。 任务 `dependencyCheck` 支持可用于更改其行为的参数： - `list-settings`：在运行分析之前，将打印用于分析的设置。这与任务 `dependencyCheckListSettings` 的工作方式相同。 - `list-unused-suppressions`：分析完成后将打印任何未使用的抑制规则。这与任务 `dependencyCheckListUnusedSuppressions` 的工作方式相同。 - `single-report`：将为此项目及其所有聚合（如果有的话）生成单个报告。这与任务 `dependencyCheckAggregate` 的工作方式相同。 - `all-projects`：将为所有项目生成单个报告。这与任务 `dependencyCheckAllProjects` 的工作方式相同。 **重要提示**：此参数需要与 `single-report` 一起使用。 此任务还支持修改最后显示的报告摘要的方式： - `original-summary`：这是插件先前版本提供的原始摘要。遵循 `org.owasp.dependencycheck.agent.DependencyCheckScanAgent.showSummary` 的结构。 - `all-vulnerabilities-summary`：显示比 `original-summary` 更紧凑的报告，但包含每个漏洞的评分。 - `offending-vulnerabilities-summary`：与 `all-vulnerabilities-summary` 相同，但仅显示导致构建失败的违规漏洞（即那些导致构建失败的漏洞）。 ### 配置 该插件使用默认的 [DependencyCheck](https://github.com/dependency-check/DependencyCheck) 配置，可以通过 SBT Setting Key 或 System Property 来覆盖。库按以下顺序解析属性： (1) `dependencycheck.properties` 值，(2) SBT Setting Keys，(3) System Property。最后一个非空值生效。 可以使用 Setting Key `dependencyCheckSettingsFile` 覆盖默认的 `properties` 文件。大多数（即使不是全部）设置都是从 DependencyCheck 定义的默认值中获取的。您可以运行任务 `dependencyCheckListSettings` 来了解每个设置的最终值，以及此 properties 文件内容的示例。 SBT Setting Keys 通常用 `Option` 包装。这是为了允许保留默认值，代价是牺牲一些配置的便利性。 | 设置 | 描述 | 默认值 | |:---------------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------| | `dependencyCheckFailBuildOnCVSS` | 指定如果识别到高于指定级别的 CVSS 评分，是否应使构建失败 | 11.0 (永不使构建失败) | | `dependencyCheckJUnitFailBuildOnCVSS` | 如果使用 jUnit，指定在生成 jUnit 样式报告时被视为 `test` 失败的 CVSS 评分 | 0.0 | | `dependencyCheckSkip` | 在 dependency-check 分析中跳过此项目 | `false` | | `dependencyCheckScopes` | 在分析期间考虑哪些库的依赖范围 | Compile = true, Test = false, Runtime = true, Provided = true, Optional = true | | `dependencyCheckScanSet` | 可选的文件序列，指定要作为扫描的一部分进行分析的额外文件和/或目录 | 标准 Scala 约定 | | `dependencyCheckFormats` | 要生成的报告格式 | `HTML` | | `dependencyCheckAnalysisTimeout` | 设置分析超时时间。 | 180 分钟 (由 DependencyCheck 决定) | | `dependencyCheckOutputDirectory` | 写入报告的位置。 | `cross.target` | | `dependencyCheckAutoUpdate` | 设置是否启用 NVD CVE/CPE、retireJS 和托管抑制数据的自动更新。 | `true` | | `dependencyCheckDataDirectory` | 用于数据目录（用于嵌入式数据库和其他来自互联网的缓存资源）的基本路径 | `[JAR]/data/11.0` | | `dependencyCheckSettingsFile` | 在何处查找 'dependencycheck.properties' 文件 | 资源 `dependencycheck.properties` | | `dependencyCheckAnalyzers` | 用于在分析期间运行的不同分析器的设置 | 参见 [分析器设置](#analyzer-settings) | | `dependencyCheckSuppressions` | 将一系列 XML 抑制文件的文件路径或 URL，与分析应使用的任何托管抑制结合在一起。抑制用于忽略误报。 | 空 | | `dependencyCheckDatabase` | 用于在分析期间保存 CVE 的数据库设置。 | 参见 [数据库设置](#database-settings) | | `dependencyCheckNvdApi` | 用于联系 NVD API 的设置，例如 API Key、请求延迟、最大重试次数等。 | 参见 [NVD API](#nvd-api) | | `dependencyCheckProxy` | 使用代理的设置。支持 System Property，如 `https.proxyHost`、`https.proxyPort` 等。 | 参见 [在代理下运行](#running-behind-a-proxy) | | `dependencyCheckConnectionTimeout` | 设置下载外部数据时使用的 URL 连接超时时间（以毫秒为单位）。 | `10 秒` | | `dependencyCheckConnectionReadTimeout` | 设置下载外部数据时使用的 URL 连接读取超时时间（以毫秒为单位）。 | `60 秒` | #### 敏感配置 `DependencyCheck` 可能会使用诸如用户名、密码和 Bearer Tokens 等敏感信息。尽管这些可以作为 SBT Setting Keys 添加，但强烈建议不要这样做，以避免将敏感信息提交到您的 VCS 中。以下是一些替代方案： - 在 `~/.sbt//plugins.sbt` 下全局安装此插件，然后在该文件中定义这些值。 - 使用外部的 `dependencycheck.properties` 并设置 `dependencyCheckSettingsFile`。 - 在运行 SBT 任务时使用 System Property：`sbt -Danalyzer.central.password=12348765 dependencyCheck` #### NVD API Dependency-check 已从使用 NVD 数据源转向使用 NVD API。**强烈**建议获取 NVD API Key；请参见 [请求 API Key](https://nvd.nist.gov/developers/request-an-api-key)。如果没有 NVD API Key，更新速度将**极其缓慢**。 在 CI 环境中，必须使用缓存策略，例如缓存 CVE 数据库。 请阅读我们的 [wiki](https://github.com/nMoncho/sbt-dependency-check/wiki/NVD-API) 了解更多信息。 #### 抑制设置 由于 [dependency-check 识别库的方式](https://dependency-check.github.io/DependencyCheck/general/internals.html)，可能会出现误报（即识别到了不正确的 CPE）。`sbt-dependency-check` 提供了几种定义这些抑制的方法。 请阅读我们的 [wiki](https://github.com/nMoncho/sbt-dependency-check/wiki/SUPPRESSIONS) 了解更多信息。 #### 分析器设置 顾名思义，分析器是分析依赖或构件的一种方式。[DependencyCheck](https://github.com/dependency-check/DependencyCheck) 提供了开箱即用的广泛分析器列表。 请阅读我们的 [wiki](https://github.com/nMoncho/sbt-dependency-check/wiki/ANALYZERS) 了解更多信息。 ### 在代理下运行 SBT 和 `sbt-dependency-check` 都遵循 JVM 的标准 HTTP 和 HTTPS 代理设置。 ``` sbt -Dhttp.proxyHost=proxy.example.com \ -Dhttp.proxyPort=3218 \ -Dhttp.proxyUser=username \ -Dhttp.proxyPassword=password \ -Dproxy.nonproxyhosts="localhost|http://www.google.com" \ dependencyCheck ``` ### 更改日志级别 在运行任务时添加 `-Dlog4j2.level=`，例如： ``` sbt -Dlog4j2.level=debug dependencyCheck ``` 将 `dependencyCheck` 替换为您项目使用的正确 [任务名称](#tasks)。

标签：Claude, CVE检测, NVD API, OWASP DependencyCheck, SBT插件, Scala构建工具, 依赖安全检查, 开源依赖管理, 持续集成(CI), 软件成分分析(SCA)