From a5cb0a8db34fb20b5de091a859521d6fafefb426 Mon Sep 17 00:00:00 2001 From: Hans Aikema Date: Thu, 2 Jan 2025 12:50:35 +0100 Subject: [PATCH] chore(docs): Document the new gradle plugin authentication options (#7281) --- .../configuration-aggregate.md | 39 ++++++++++++------- .../configuration-update.md | 27 ++++++++++++- .../dependency-check-gradle/configuration.md | 32 +++++++++++---- 3 files changed, 76 insertions(+), 22 deletions(-) diff --git a/src/site/markdown/dependency-check-gradle/configuration-aggregate.md b/src/site/markdown/dependency-check-gradle/configuration-aggregate.md index 576eb416c32..ad09c4af170 100644 --- a/src/site/markdown/dependency-check-gradle/configuration-aggregate.md +++ b/src/site/markdown/dependency-check-gradle/configuration-aggregate.md @@ -76,12 +76,13 @@ dependencyCheck { ### Advanced Configuration -The following properties can be configured in the dependencyCheck task. However, they are less frequently changed. One exception -may be the cvedUrl properties, which can be used to host a mirror of the NVD within an enterprise environment. -Note, if ANY of the cve configuration group are set - they should all be set to ensure things work as expected. +The following properties can be configured in the dependencyCheck task. However, they are less frequently changed. Config Group | Property | Description | Default Value | -------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| +  | suppressionFileUser | Credentials used for basic authentication for web-hosted suppression files |   | +  | suppressionFilePassword | Credentials used for basic authentication for web-hosted suppression files |   | +  | suppressionFileBearerToken | Credentials used for bearer authentication for web-hosted suppression files |   | nvd | apiKey | The API Key to access the NVD API; obtained from https://nvd.nist.gov/developers/request-an-api-key |   | nvd | endpoint | The NVD API endpoint URL; setting this is uncommon. | https://services.nvd.nist.gov/rest/json/cves/2.0 | nvd | maxRetryCount | The maximum number of retry requests for a single call to the NVD API. | 10 | @@ -90,6 +91,7 @@ nvd | resultsPerPage | The number records for a single page from NVD nvd | datafeedUrl | The URL for the NVD API Data feed that can be generated using https://github.com/jeremylong/Open-Vulnerability-Project/tree/main/vulnz#caching-the-nvd-cve-data |   | nvd | datafeedUser | Credentials used for basic authentication for the NVD API Data feed. |   | nvd | datafeedPassword | Credentials used for basic authentication for the NVD API Data feed. |   | +nvd | datafeedBearerToken | Credentials used for bearer authentication for the NVD API Data feed. |   | nvd | validForHours | The number of hours to wait before checking for new updates from the NVD. The default is 4 hours. | 4 | data | directory | Sets the data directory to hold SQL CVEs contents. This should generally not be changed. |   | data | driver | The database driver full classname; note, only needs to be set if the driver is not JDBC4 compliant or the JAR is outside of the class path. |   | @@ -97,6 +99,15 @@ data | driverPath | The path to the database driver JAR file; onl data | connectionString | The connection string used to connect to the database. See using a [database server](../data/database.html). |   | data | username | The username used when connecting to the database. |   | data | password | The password used when connecting to the database. |   | +slack | enabled | Whether or not slack notifications are enabled. | false +slack | webhookUrl | The custom incoming webhook URL to receive notifications. |   +hostedSuppressions | enabled | Whether the hosted suppressions file will be used. | true +hostedSuppressions | forceupdate | Sets whether hosted suppressions file will update regardless of the `autoupdate` setting. | false +hostedSuppressions | url | The URL to a mirrored copy of the hosted suppressions file for internet-constrained environments. | https://jeremylong.github.io/DependencyCheck/suppressions/publishedSuppressions.xml +hostedSuppressions | user | Credentials used for basic authentication for the hosted suppressions file. |   | +hostedSuppressions | password | Credentials used for basic authentication for the hosted suppressions file. |   | +hostedSuppressions | bearerToken | Credentials used for bearer authentication for the hosted suppressions file. |   | +hostedSuppressions | validForHours | The number of hours to wait before checking for new updates of the hosted suppressions file . | 2 #### Example ```groovy @@ -116,13 +127,11 @@ Config Group | Property | Description -------------|-----------------------|-------------------------------------------------------------------------------------------------------------------|------------------ analyzers | experimentalEnabled | Sets whether the [experimental analyzers](../analyzers/index.html) will be used. If not set to true the analyzers marked as experimental (see below) will not be used | false analyzers | archiveEnabled | Sets whether the Archive Analyzer will be used. | true -analyzers | knownExploitedEnabled | Sets whether the Known Exploited Vulnerability update and analyzer are enabled. | true -analyzers | knownExploitedURL | Sets URL to the CISA Known Exploited Vulnerabilities JSON data feed. | https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json analyzers | zipExtensions | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. |   analyzers | jarEnabled | Sets whether Jar Analyzer will be used. | true analyzers | dartEnabled | Sets whether the [experimental](../analyzers/index.html) Dart Analyzer will be used. | true analyzers | centralEnabled | Sets whether Central Analyzer will be used; by default in the Gradle plugin this analyzer is disabled as all information gained from Central is already available in the build. Enable this analyzer when you hit false positives for (embedded) Maven dependencies that do not have an associated maven package-URL in the report. | false -analyzers | nexusEnabled | Sets whether Nexus Analyzer will be used (requires Nexus Pro). This analyzer is superceded by the Central Analyzer; however, you can configure this to run against a Nexus Pro installation. | true +analyzers | nexusEnabled | Sets whether Nexus Analyzer will be used (requires Nexus Pro). This analyzer is superceded by the Central Analyzer; however, you can configure this to run against a Nexus Pro installation. | false analyzers | nexusUrl | Defines the Nexus Server's web service end point (example http://domain.enterprise/service/local/). If not set the Nexus Analyzer will be disabled. |   analyzers | nexusUsesProxy | Whether or not the defined proxy should be used when connecting to Nexus. | true analyzers | pyDistributionEnabled | Sets whether the [experimental](../analyzers/index.html) Python Distribution Analyzer will be used. `experimentalEnabled` must be set to true. | true @@ -137,6 +146,7 @@ analyzers | pathToDotnet | The path to dotnet core - needed on some analyzers | cmakeEnabled | Sets whether the [experimental](../analyzers/index.html) CMake Analyzer should be used. `experimentalEnabled` must be set to true. | true analyzers | autoconfEnabled | Sets whether the [experimental](../analyzers/index.html) autoconf Analyzer should be used. `experimentalEnabled` must be set to true. | true analyzers | composerEnabled | Sets whether the [experimental](../analyzers/index.html) PHP Composer Lock File Analyzer should be used. `experimentalEnabled` must be set to true. | true +analyzers | composerSkipDev | Sets whether the [experimental](../analyzers/index.html) PHP Composer Lock File Analyzer should skip "packages-dev". | false analyzers | cpanEnabled | Sets whether the [experimental](../analyzers/index.html) Perl CPAN File Analyzer should be used. `experimentalEnabled` must be set to true. | true analyzers | cocoapodsEnabled | Sets whether the [experimental](../analyzers/index.html) Cocoapods Analyzer should be used. `experimentalEnabled` must be set to true. | true analyzers | carthageEnabled | Sets whether the [experimental](../analyzers/index.html) Carthage Analyzer should be used. `experimentalEnabled` must be set to true. | true @@ -145,7 +155,7 @@ analyzers | swiftPackageResolvedEnabled | Sets whether the [experimental](../ analyzers | bundleAuditEnabled | Sets whether the [experimental](../analyzers/index.html) Ruby Bundle Audit Analyzer should be used. `experimentalEnabled` must be set to true. | true analyzers | pathToBundleAudit | The path to bundle audit. |   analyzers | golangDepEnabled | Sets whether the [experimental](../analyzers/index.html) Golang Dependency Analyzer should be used. `experimentalEnabled` must be set to true. | true -analyzers | golangModEnabled | Sets whether the [experimental](../analyzers/index.html) Goland Module Analyzer should be used; requies `go` to be installed. `experimentalEnabled` must be set to true. | true +analyzers | golangModEnabled | Sets whether the [experimental](../analyzers/index.html) Goland Module Analyzer should be used; requires `go` to be installed. `experimentalEnabled` must be set to true. | true analyzers | pathToGo | The path to `go`. |   #### Additional Configuration @@ -159,6 +169,12 @@ artifactory | parallelAnalysis | Whether the Artifactory analyzer should b artifactory | username | The user name (only used with API token) to connect to Artifactory instance. |   artifactory | apiToken | The API token to connect to Artifactory instance, only used if the username or the API key are not defined by artifactoryAnalyzerServerId,artifactoryAnalyzerUsername or artifactoryAnalyzerApiToken |   artifactory | bearerToken | The bearer token to connect to Artifactory instance. |   +kev | enabled | Sets whether the Known Exploited Vulnerability update and analyzer are enabled. | true | +kev | url | The URL to (a mirror of) the CISA Known Exploited Vulnerabilities JSON data feed. | https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json | +kev | user | Credentials used for basic authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | +kev | password | Credentials used for basic authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | +kev | bearerToken | Credentials used for bearer authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | +kev | validForHours | The number of hours to wait before checking for new updates of the hosted suppressions file . | 2 | nodeAudit | enabled | Sets whether the Node Audit Analyzer should be used. This analyzer requires an internet connection. | true nodeAudit | useCache | Sets whether the Node Audit Analyzer should cache results locally. | true nodeAudit | skipDevDependencies | Sets whether the Node Audit Analyzer should skip devDependencies. | false @@ -172,18 +188,15 @@ nodeAudit | url | The node audit API url to use. retirejs | enabled | Sets whether the RetireJS Analyzer should be used. | true retirejs | forceupdate | Sets whether the RetireJS Analyzer should update regardless of the `autoupdate` setting. | false retirejs | retireJsUrl | The URL to the Retire JS repository. | https://raw.githubusercontent.com/Retirejs/retire.js/master/repository/jsrepository.json +retirejs | user | Credentials used for basic authentication for the Retire JS repository URL. |   | +retirejs | password | Credentials used for basic authentication for the Retire JS repository URL. |   | +retirejs | bearerToken | Credentials used for bearer authentication for the Retire JS repository URL. |   | retirejs | filterNonVulnerable | Configures the RetireJS Analyzer to remove non-vulnerable JS dependencies from the report. | false retirejs | filters | Configures the list of regular expessions used to filter JS files based on content. |   ossIndex | enabled | Sets whether [OSS Index Analyzer](../analyzers/oss-index-analyzer.html) will be used. This analyzer requires an internet connection. | true ossIndex | username | To authenticate Sonatype OSS Index requests and profit from higher rate limits, provide the OSS account email address as username. Provide both a username _and_ a password (see below) or none. |   ossIndex | password | Password or API token to connect to Sonatype's OSS Index. Provide both a username (see above) _and_ a password or none. |   ossIndex | warnOnlyOnRemoteErrors| Sets whether remote errors from the OSS Index (e.g. BAD GATEWAY, RATE LIMIT EXCEEDED) will result in warnings only instead of failing execution. | false -slack | enabled | Whether or not slack notifications are enabled. | false -slack | webhookUrl | The custom incoming webhook URL to receive notifications. |   -hostedSuppressions | enabled | Whether the hosted suppressions file will be used. | true -hostedSuppressions | forceupdate | Sets whether hosted suppressions file will update regardless of the `autoupdate` setting. | false -hostedSuppressions | url | The URL to the Retire JS repository. | https://jeremylong.github.io/DependencyCheck/suppressions/publishedSuppressions.xml -hostedSuppressions | validForHours | The number of hours to wait before checking for new updates of the hosted suppressions file . | 2 #### Example ```groovy diff --git a/src/site/markdown/dependency-check-gradle/configuration-update.md b/src/site/markdown/dependency-check-gradle/configuration-update.md index 24c6f7a1310..4916446b373 100644 --- a/src/site/markdown/dependency-check-gradle/configuration-update.md +++ b/src/site/markdown/dependency-check-gradle/configuration-update.md @@ -68,6 +68,7 @@ nvd | resultsPerPage | The number records for a single page from NVD nvd | datafeedUrl | The URL for the NVD API Data feed that can be generated using https://github.com/jeremylong/Open-Vulnerability-Project/tree/main/vulnz#caching-the-nvd-cve-data |   | nvd | datafeedUser | Credentials used for basic authentication for the NVD API Data feed. |   | nvd | datafeedPassword | Credentials used for basic authentication for the NVD API Data feed. |   | +nvd | datafeedBearerToken | Credentials used for bearer authentication for the NVD API Data feed. |   | nvd | validForHours | The number of hours to wait before checking for new updates from the NVD. The default is 4 hours. | 4 | data | directory | Sets the data directory to hold SQL CVEs contents. This should generally not be changed. | ~/.gradle/dependency-check-data/ | data | driver | The database driver full classname; note, only needs to be set if the driver is not JDBC4 compliant or the JAR is outside of the class path. |   | @@ -77,7 +78,10 @@ data | username | The username used when connecting to the data data | password | The password used when connecting to the database. |   | hostedSuppressions | enabled | Whether the hosted suppressions file will be used. | true | hostedSuppressions | forceupdate | Sets whether hosted suppressions file will update regardless of the `autoupdate` setting. | false | -hostedSuppressions | url | The URL to the Retire JS repository. | https://jeremylong.github.io/DependencyCheck/suppressions/publishedSuppressions.xml | +hostedSuppressions | url | The URL to (a mirror of) the hosted suppressions file. | https://jeremylong.github.io/DependencyCheck/suppressions/publishedSuppressions.xml | +hostedSuppressions | user | Credentials used for basic authentication for the hosted suppressions file. |   | +hostedSuppressions | password | Credentials used for basic authentication for the hosted suppressions file. |   | +hostedSuppressions | bearerToken | Credentials used for bearer authentication for the hosted suppressions file. |   | hostedSuppressions | validForHours | The number of hours to wait before checking for new updates of the hosted suppressions file . | 2 | #### Example @@ -86,3 +90,24 @@ dependencyCheck { data.directory='d:/nvd' } ``` + +### Analyzer Configuration + +Cached web datasources for several analyzers are configured inside the `analyzers` section with some properties +taking relevance also in the update task. In addition to the above, the updateTask can be customized for retrieval +of these resources by the following analyzer-specific properties underneath the `analyzers` section. + + Config Group | Property | Description | Default Value | +--------------|---------------|---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------| + kev | enabled | Sets whether the Known Exploited Vulnerability update and analyzer are enabled. | true | + kev | url | The URL to (a mirror of) the CISA Known Exploited Vulnerabilities JSON data feed. | https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json | + kev | user | Credentials used for basic authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | + kev | password | Credentials used for basic authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | + kev | bearerToken | Credentials used for bearer authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | + kev | validForHours | The number of hours to wait before checking for new updates of the hosted suppressions file . | 2 | + retirejs | enabled | Sets whether the RetireJS Analyzer should be used / the repository be updated. | true | + retirejs | retireJsUrl | The URL to the Retire JS repository. | https://raw.githubusercontent.com/Retirejs/retire.js/master/repository/jsrepository.json | +retirejs | user | Credentials used for basic authentication for the Retire JS repository URL. |   | +retirejs | password | Credentials used for basic authentication for the Retire JS repository URL. |   | +retirejs | bearerToken | Credentials used for bearer authentication for the Retire JS repository URL. |   | + retirejs | forceupdate | Sets whether the Retire JS repository should update regardless of the `autoupdate` setting. | false | diff --git a/src/site/markdown/dependency-check-gradle/configuration.md b/src/site/markdown/dependency-check-gradle/configuration.md index 496c97f2e85..ca4f53ba9b2 100644 --- a/src/site/markdown/dependency-check-gradle/configuration.md +++ b/src/site/markdown/dependency-check-gradle/configuration.md @@ -66,6 +66,9 @@ The following properties can be configured in the dependencyCheck task. However, Config Group | Property | Description | Default Value -------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------ +  | suppressionFileUser | Credentials used for basic authentication for web-hosted suppression files |   | +  | suppressionFilePassword | Credentials used for basic authentication for web-hosted suppression files |   | +  | suppressionFileBearerToken | Credentials used for bearer authentication for web-hosted suppression files |   | nvd | apiKey | The API Key to access the NVD API; obtained from https://nvd.nist.gov/developers/request-an-api-key |   | nvd | endpoint | The NVD API endpoint URL; setting this is uncommon. | https://services.nvd.nist.gov/rest/json/cves/2.0 | nvd | maxRetryCount | The maximum number of retry requests for a single call to the NVD API. | 10 | @@ -74,6 +77,7 @@ nvd | resultsPerPage | The number records for a single page from NVD nvd | datafeedUrl | The URL for the NVD API Data feed that can be generated using https://github.com/jeremylong/Open-Vulnerability-Project/tree/main/vulnz#caching-the-nvd-cve-data |   | nvd | datafeedUser | Credentials used for basic authentication for the NVD API Data feed. |   | nvd | datafeedPassword | Credentials used for basic authentication for the NVD API Data feed. |   | +nvd | datafeedBearerToken | Credentials used for bearer authentication for the NVD API Data feed. |   | nvd | validForHours | The number of hours to wait before checking for new updates from the NVD. The default is 4 hours. | 4 | data | directory | Sets the data directory to hold SQL CVEs contents. This should generally not be changed. |   | data | driver | The database driver full classname; note, only needs to be set if the driver is not JDBC4 compliant or the JAR is outside of the class path. |   | @@ -81,6 +85,15 @@ data | driverPath | The path to the database driver JAR file; onl data | connectionString | The connection string used to connect to the database. See using a [database server](../data/database.html). |   | data | username | The username used when connecting to the database. |   | data | password | The password used when connecting to the database. |   | +slack | enabled | Whether or not slack notifications are enabled. | false +slack | webhookUrl | The custom incoming webhook URL to receive notifications. |   +hostedSuppressions | enabled | Whether the hosted suppressions file will be used. | true +hostedSuppressions | forceupdate | Sets whether hosted suppressions file will update regardless of the `autoupdate` setting. | false +hostedSuppressions | url | The URL to a mirrored copy of the hosted suppressions file for internet-constrained environments. | https://jeremylong.github.io/DependencyCheck/suppressions/publishedSuppressions.xml +hostedSuppressions | user | Credentials used for basic authentication for the hosted suppressions file. |   | +hostedSuppressions | password | Credentials used for basic authentication for the hosted suppressions file. |   | +hostedSuppressions | bearerToken | Credentials used for bearer authentication for the hosted suppressions file. |   | +hostedSuppressions | validForHours | The number of hours to wait before checking for new updates of the hosted suppressions file . | 2 #### Example ```groovy @@ -100,8 +113,6 @@ Config Group | Property | Description -------------|-----------------------|-------------------------------------------------------------------------------------------------------------------|------------------ analyzers | experimentalEnabled | Sets whether the [experimental analyzers](../analyzers/index.html) will be used. If not set to true the analyzers marked as experimental (see below) will not be used | false analyzers | archiveEnabled | Sets whether the Archive Analyzer will be used. | true -analyzers | knownExploitedEnabled | Sets whether the Known Exploited Vulnerability update and analyzer are enabled. | true -analyzers | knownExploitedURL | Sets URL to the CISA Known Exploited Vulnerabilities JSON data feed. | https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json analyzers | zipExtensions | A comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. |   analyzers | jarEnabled | Sets whether Jar Analyzer will be used. | true analyzers | dartEnabled | Sets whether the [experimental](../analyzers/index.html) Dart Analyzer will be used. | true @@ -145,9 +156,17 @@ artifactory | parallelAnalysis | Whether the Artifactory analyzer should b artifactory | username | The user name (only used with API token) to connect to Artifactory instance. |   artifactory | apiToken | The API token to connect to Artifactory instance, only used if the username or the API key are not defined by artifactoryAnalyzerServerId,artifactoryAnalyzerUsername or artifactoryAnalyzerApiToken |   artifactory | bearerToken | The bearer token to connect to Artifactory instance |   +kev | enabled | Sets whether the Known Exploited Vulnerability update and analyzer are enabled. | true | +kev | url | The URL to (a mirror of) the CISA Known Exploited Vulnerabilities JSON data feed. | https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json | +kev | user | Credentials used for basic authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | +kev | password | Credentials used for basic authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | +kev | bearerToken | Credentials used for bearer authentication for the CISA Known Exploited Vulnerabilities JSON data feed. |   | +kev | validForHours | The number of hours to wait before checking for new updates of the hosted suppressions file . | 2 | nodeAudit | enabled | Sets whether the Node Audit Analyzer should be used. This analyzer requires an internet connection. | true nodeAudit | useCache | Sets whether the Node Audit Analyzer should cache results locally. | true nodeAudit | skipDevDependencies | Sets whether the Node Audit Analyzer should skip devDependencies. | false +nodeAudit | pnpmEnabled | Sets whether the Pnpm Audit Analyzer should be used. This analyzer requires yarn and an internet connection. | true +nodeAudit | pnpmPath | Sets the path to the `pnpm` executable. |   nodeAudit | yarnEnabled | Sets whether the Yarn Audit Analyzer should be used. This analyzer requires yarn and an internet connection. | true nodeAudit | yarnPath | Sets the path to the `yarn` executable. |   nodeAudit | pnpmEnabled | Sets whether the Pnpm Audit Analyzer should be used. This analyzer requires pnpm and an internet connection. | true @@ -156,18 +175,15 @@ nodeAudit | url | The node audit API url to use. retirejs | enabled | Sets whether the RetireJS Analyzer should be used. | true retirejs | forceupdate | Sets whether the RetireJS Analyzer should update regardless of the `autoupdate` setting. | false retirejs | retireJsUrl | The URL to the Retire JS repository. | https://raw.githubusercontent.com/Retirejs/retire.js/master/repository/jsrepository.json +retirejs | user | Credentials used for basic authentication for the Retire JS repository URL. |   | +retirejs | password | Credentials used for basic authentication for the Retire JS repository URL. |   | +retirejs | bearerToken | Credentials used for bearer authentication for the Retire JS repository URL. |   | retirejs | filterNonVulnerable | Configures the RetireJS Analyzer to remove non-vulnerable JS dependencies from the report. | false retirejs | filters | Configures the list of regular expessions used to filter JS files based on content. |   ossIndex | enabled | Sets whether Sonatype's [OSS Index Analyzer](../analyzers/oss-index-analyzer.html) will be used. This analyzer requires an internet connection. | true ossIndex | username | The optional user name to connect to Sonatype's OSS Index. |   ossIndex | password | The optional passwod or API token to connect to Sonatype's OSS Index, |   ossIndex | warnOnlyOnRemoteErrors| Sets whether remote errors from the OSS Index (e.g. BAD GATEWAY, RATE LIMIT EXCEEDED) will result in warnings only instead of failing execution. | false -slack | enabled | Whether or not slack notifications are enabled. | false -slack | webhookUrl | The custom incoming webhook URL to receive notifications. |   -hostedSuppressions | enabled | Whether the hosted suppressions file will be used. | true -hostedSuppressions | forceupdate | Sets whether hosted suppressions file will update regardless of the `autoupdate` setting. | false -hostedSuppressions | url | The URL to a mirrored copy of the hosted suppressions file for internet-constrained environments. | https://jeremylong.github.io/DependencyCheck/suppressions/publishedSuppressions.xml -hostedSuppressions | validForHours | The number of hours to wait before checking for new updates of the hosted suppressions file . | 2 #### Example ```groovy