Back to Dependencycheck

Configuration

ant/src/site/markdown/configuration.md

12.2.258.8 KB
Original Source

Configuration

Once dependency-check-ant has been installed the defined tasks can be used.

  • dependency-check - the primary task used to check the project dependencies. Configuration options are below.
  • dependency-check-purge - deletes the local copy of the NVD; this should rarely be used (if ever). See the purge configuration for more information.
  • dependency-check-update - downloads and updates the local copy of the NVD. See the update configuration for more information.

To configure the dependency-check task you can add it to a target and include a file based resource collection such as a FileSet, DirSet, or FileList that includes the project's dependencies.

xml

<target name="dependency-check" description="Dependency-Check Analysis">
    <dependency-check projectname="Hello World"
                      reportoutputdirectory="${basedir}"
                      reportformat="ALL">
        <suppressionfile path="${basedir}/path/to/suppression.xml"/>
        <retireJsFilter regex="copyright.*jeremy long"/>
        <fileset dir="lib">
            <include name="**/*.jar"/>
        </fileset>
    </dependency-check>
</target>

Configuration: dependency-check Task

The following properties can be set on the dependency-check task.

PropertyDescriptionDefault Value
autoUpdateSets whether auto-updating of the NVD CVE/CPE data is enabled. It is not recommended that this be turned to false.true
failBuildOnCVSSSpecifies if the build should be failed if a CVSS score equal to or above a specified level is identified. The default is 11 which means since the CVSS scores are 0-10, by default the build will never fail. More information on CVSS scores can be found at the NVD11
junitFailOnCVSSIf using the JUNIT report format the junitFailOnCVSS sets the CVSS score threshold that is considered a failure.0
prettyPrintWhether the XML and JSON formatted reports should be pretty printed.false
projectNameThe name of the project being scanned.Dependency-Check
reportFormatThe report format to be generated (HTML, XML, CSV, JSON, JUNIT, SARIF, JENKINS, GITLAB, ALL).HTML
reportOutputDirectoryThe location to write the report(s). Note, this is not used if generating the report as part of a mvn site build'target'
hintsFileThe file path to the XML hints file - used to resolve false negatives 
dataDirectoryData directory that is used to store the local caches and NVD CVE database<folder-of-dependency-check-ant.jar>/data/11.0
failOnErrorWhether the build should fail if there is an error executing the dependency-check analysistrue
proxyServerThe Proxy Server; see the proxy configuration page for more information. 
proxyPortThe Proxy Port. 
proxyUsernameDefines the proxy user name. 
proxyPasswordDefines the proxy password. 
nonProxyHostsDefines the hosts that will not be proxied. 
connectionTimeoutThe URL Connection Timeout (in milliseconds).10000
readtimeoutThe URL Read Timeout (in milliseconds).60000
enableExperimentalEnable the experimental analyzers. If not enabled the experimental analyzers (see below) will not be loaded or used.false
enableRetiredEnable the retired analyzers. If not enabled the retired analyzers (see below) will not be loaded or used.false
suppressionFileThe file path to the XML suppression file - used to suppress false positives. The parameter value can be a local file path, a URL to a suppression file, or even a reference to a file on the class path (see https://github.com/dependency-check/DependencyCheck/issues/1878#issuecomment-487533799) 
failBuildOnUnusedSuppressionRuleSpecifies that if any unused suppression rule is found, the build will fail.false
junitFailOnCVSSIf using the JUNIT report format the junitFailOnCVSS sets the CVSS score threshold that is considered a failure.0

The following nested elements can be set on the dependency-check task.

ElementPropertyDescriptionDefault Value
suppressionFilepathThe file path to the XML suppression file - used to suppress false positives. Element can be specified multiple times. The parameter value can be a local file path, a URL to a suppression file, or even a reference to a file on the class path (see https://github.com/dependency-check/DependencyCheck/issues/1878#issuecomment-487533799) 
reportFormatformatThe report format to be generated (HTML, XML, CSV, JSON, JUNIT, SARIF, JENKINS, GITLAB, ALL). Element can be specified multiple times. 

Analyzer Configuration

The following properties are used to configure the various file type analyzers. These properties can be used to turn off specific analyzers if it is not needed. Note, that specific analyzers will automatically disable themselves if no file types that they support are detected - so specifically disabling them may not be needed.

PropertyDescriptionDefault Value
archiveAnalyzerEnabledSets whether the Archive Analyzer will be used.true
zipExtensionsA comma-separated list of additional file extensions to be treated like a ZIP file, the contents will be extracted and analyzed. 
jarAnalyzerSets whether the Jar Analyzer will be used.true
centralAnalyzerEnabledSets whether the Central Analyzer will be used. Disabling this analyzer for Ant builds is not recommended as it could lead to false negatives (e.g. libraries that have vulnerabilities may not be reported correctly). If this analyzer is being disabled there is a good chance you also want to disable the Nexus Analyzer (see below).true
centralAnalyzerUseCacheSets whether the Central Analyzer will cache results. Cached results expire after 30 days.true
dartAnalyzerEnabledSets whether the experimental Dart Analyzer will be used.true
knownExploitedEnabledSets whether the Known Exploited Vulnerability update and analyzer are enabled.true
knownExploitedUrlSets URL to the CISA Known Exploited Vulnerabilities JSON data feed.https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json
ossIndexAnalyzerEnabledSets whether the OSS Index Analyzer will be enabled. This analyzer requires an internet connection, and authentication is mandatory. Deprecated alias: ossindexAnalyzerEnabledtrue
ossIndexAnalyzerUseCacheSets whether the OSS Index Analyzer will cache results. Deprecated alias: ossindexAnalyzerUseCachetrue
ossIndexAnalyzerCacheValidForHoursThe number of hours to wait before checking for new updates on individual packages/components from Sonatype OSS Index.24
ossIndexAnalyzerUrlAlternative base URL for the OSS Index API. If not set the public Sonatype OSS Index API on Sonatype Guide will be used. Deprecated alias: ossindexAnalyzerUrlhttps://api.guide.sonatype.com
ossIndexAnalyzerUsername(deprecated) Sets the OSS Index API username for use with legacy OSS Index API tokens. Username is not required after migration to using Sonatype Guide personal access token as password. Deprecated alias: ossindexAnalyzerUsername 
ossIndexAnalyzerPasswordSets the Sonatype Guide personal access token or (deprecated) legacy OSS Index API token to authenticate with. Deprecated alias: ossindexAnalyzerPassword 
ossIndexAnalyzerWarnOnlyOnRemoteErrorsWhether we should only warn about Sonatype OSS Index remote errors instead of failing completely. 
nexusAnalyzerEnabledSets whether Nexus Analyzer will be used. This analyzer is an alternative to the Central or Artifactory Analyzers, allowing retrieval from Sonatype Nexus installations.false
nexusUrlDefines the Nexus web service endpoint (example http://domain.enterprise/nexus/service/local/). If not set the Nexus Analyzer will be disabled. 
nexusUserThe username to authenticate to the Nexus Server's web service end point. If not set the Nexus Analyzer will use an unauthenticated connection. 
nexusPasswordThe password to authenticate to the Nexus Server's web service end point. If not set the Nexus Analyzer will use an unauthenticated connection. 
nexusUsesProxyWhether the defined proxy should be used when connecting to Nexus.true
artifactoryAnalyzerEnabledSets whether Artifactory analyzer will be usedfalse
artifactoryAnalyzerUrlThe Artifactory server URL. 
artifactoryAnalyzerUseProxyWhether Artifactory should be accessed through a proxy or not.false
artifactoryAnalyzerParallelAnalysisWhether the Artifactory analyzer should be run in parallel or nottrue
artifactoryAnalyzerUsernameThe user name (only used with API token) to connect to Artifactory instance 
artifactoryAnalyzerApiTokenThe API token to connect to Artifactory instance, only used if the username or the API key are not defined by artifactoryAnalyzerServerId,artifactoryAnalyzerUsername or artifactoryAnalyzerApiToken 
artifactoryAnalyzerBearerTokenThe bearer token to connect to Artifactory instance 
pyDistributionAnalyzerEnabledSets whether the experimental Python Distribution Analyzer will be used. enableExperimental must be set to true.true
pyPackageAnalyzerEnabledSets whether the experimental Python Package Analyzer will be used. enableExperimental must be set to true.true
rubygemsAnalyzerEnabledSets whether the experimental Ruby Gemspec Analyzer will be used. enableExperimental must be set to true.true
opensslAnalyzerEnabledSets whether the openssl Analyzer should be used.true
cmakeAnalyzerEnabledSets whether the experimental CMake Analyzer should be used. enableExperimental must be set to true.true
autoconfAnalyzerEnabledSets whether the experimental autoconf Analyzer should be used. enableExperimental must be set to true.true
pipAnalyzerEnabledSets whether the experimental pip Analyzer should be used. enableExperimental must be set to true.true
pipfileAnalyzerEnabledSets whether the experimental Pipfile Analyzer should be used. enableExperimental must be set to true.true
poetryAnalyzerEnabledSets whether the experimental Poetry Analyzer should be used. enableExperimental must be set to true.true
composerAnalyzerEnabledSets whether the experimental PHP Composer Lock File Analyzer should be used. enableExperimental must be set to true.true
composerAnalyzerSkipDevSets whether the experimental PHP Composer Lock File Analyzer should skip "packages-dev"false
cpanfileAnalyzerEnabledSets whether the experimental Perl CPAN File Analyzer should be used. enableExperimental must be set to true.true
nodeAnalyzerEnabledSets whether the Node Package Analyzer should be used.true
nodePackageSkipDevDependenciesSets whether the Node Package Analyzer will skip devDependencies.false
nodeAuditAnalyzerEnabledSets whether the Node Audit Analyzer should be used. This analyzer requires an internet connection.true
nodeAuditAnalyzerUseCacheSets whether the Node Audit Analyzer will cache results. Cached results expire after 24 hours.true
nodeAuditSkipDevDependenciesSets whether the Node Audit Analyzer will skip devDependencies.false
yarnAuditAnalyzerEnabledSets whether the Yarn Audit Analyzer should be used. This analyzer requires yarn and an internet connection. Use nodeAuditSkipDevDependencies to skip dev dependencies.true
pnpmAuditAnalyzerEnabledSets whether the Pnpm Audit Analyzer should be used. This analyzer requires pnpm and an internet connection. Use nodeAuditSkipDevDependencies to skip dev dependencies.true
pathToYarnThe path to yarn. 
pathToPnpmThe path to pnpm. 
retireJsAnalyzerEnabledSets whether the RetireJS Analyzer update and analyzer are enabled.true
retireJsFilterNonVulnerableConfigures the RetireJS Analyzer to remove non-vulnerable JS dependencies from the report. Deprecated alias: retirejsFilterNonVulnerablefalse
retireJsFilterA nested configuration that can be specified multple times; The regex defined is used to filter JS files based on content. Deprecated alias: retirejsFilter 
nuspecAnalyzerEnabledSets whether the .NET Nuget Nuspec Analyzer will be used.true
nugetconfAnalyzerEnabledSets whether the experimental .NET Nuget packages.config Analyzer will be used. enableExperimental must be set to true.true
libmanAnalyzerEnabledSets whether the Libman Analyzer will be used.true
cocoapodsAnalyzerEnabledSets whether the experimental Cocoapods Analyzer should be used. enableExperimental must be set to true.true
carthageAnalyzerEnabledSets whether the experimental Carthage Analyzer should be used. enableExperimental must be set to true.true
mixAuditAnalyzerEnabledSets whether the experimental Mix Audit Analyzer should be used. enableExperimental must be set to true.true
mixAuditPathSets the path to the mix_audit executable; only used if mix audit analyzer is enabled and experimental analyzers are enabled. 
bundleAuditAnalyzerEnabledSets whether the experimental Bundle Audit Analyzer should be used. enableExperimental must be set to true.true
bundleAuditPathSets the path to the bundle audit executable; only used if bundle audit analyzer is enabled and experimental analyzers are enabled. 
swiftPackageManagerAnalyzerEnabledSets whether the experimental Swift Package Analyzer should be used. enableExperimental must be set to true.true
swiftPackageResolvedAnalyzerEnabledSets whether the experimental Swift Package Resolved should be used. enableExperimental must be set to true.true
assemblyAnalyzerEnabledSets whether the .NET Assembly Analyzer should be used.true
msbuildAnalyzerEnabledSets whether the MSBuild Analyzer should be used.true
pathToCoreThe path to dotnet core .NET assembly analysis on non-windows systems. 
golangDepEnabledSets whether the experimental Golang Dependency Analyzer should be used. enableExperimental must be set to true.true
golangModEnabledSets whether the experimental Goland Module Analyzer should be used; requires go to be installed. enableExperimental must be set to true.true
pathToGoThe path to go. 
versionCheckEnabledWhether dependency-check should check if a new version of dependency-check-maven exists.true

Advanced Configuration

The following properties can be configured in the plugin. However, they are less frequently changed.

PropertyDescriptionDefault Value
nvdApiKeyThe API Key to access the NVD API; obtained from https://nvd.nist.gov/developers/request-an-api-key 
nvdApiEndpointThe NVD API endpoint URL; setting this is uncommon.https://services.nvd.nist.gov/rest/json/cves/2.0
nvdMaxRetryCountThe maximum number of retry requests for a single call to the NVD API.10
nvdApiDelayThe number of milliseconds to wait between calls to the NVD API.3500 with an NVD API Key or 8000 without an API Key
nvdApiResultsPerPageThe number records for a single page from NVD API (must be <=2000).2000
nvdDatafeedUrlThe URL for the NVD API Data feed that can be generated using https://github.com/jeremylong/open-vulnerability-cli/blob/main/README.md#mirroring-the-nvd-cve-data - example value https://internal.server/cache/nvdcve-{0}.json.gz 
nvdUserCredentials used for basic authentication for the NVD API Data feed. 
nvdPasswordCredentials used for basic authentication for the NVD API Data feed. 
nvdValidForHoursThe number of hours to wait before checking for new updates from the NVD.4
databaseDriverNameThe 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. 
databaseDriverPathThe path to the database driver JAR file; only needs to be set if the driver is not in the class path. 
connectionStringThe connection string used to connect to the database. See using a database server. 
databaseUserThe username used when connecting to the database. 
databasePasswordThe password used when connecting to the database. 
hostedSuppressionsEnabledWhether the hosted suppression file will be used.true
hostedSuppressionsUrlThe URL to a mirrored copy of the hosted suppressions file for internet-constrained environmentshttps://dependency-check.github.io/DependencyCheck/suppressions/publishedSuppressions.xml
hostedSuppressionsUserThe user for a Basic-auth-protected mirrored copy of the hosted suppressions file for internet-constrained environments 
hostedSuppressionsPasswordThe password/token for a Basic-auth-protected mirrored copy of the hosted suppressions file for internet-constrained environments 
hostedSuppressionsBearerTokenThe bearer token for a Bearer-auth-protected mirrored copy of the hosted suppressions file for internet-constrained environments 
hostedSuppressionsValidForHoursSets the number of hours to wait before checking for new updates of the hosted suppressions file2
hostedSuppressionsForceUpdateSets whether the hosted suppressions file should update regardless of the autoupdate and validForHours settingsfalse
retireJsForceUpdateSets whether the RetireJS repository should update regardless of the autoupdate setting.false
retireJsUrlThe URL to a mirrored copy of the RetireJS repository for internet-constrained environmentshttps://raw.githubusercontent.com/Retirejs/retire.js/main/repository/jsrepository.json
retireJsUrlUserThe user for a Basic-auth-protected mirrored copy of the RetireJS repository for internet-constrained environments 
retireJsUrlPasswordThe password/token for a Basic-auth-protected mirrored copy of the RetireJS repository for internet-constrained environments 
retireJsUrlBearerTokenThe bearer token for a Bearer-auth-protected mirrored copy of the RetireJS repository for internet-constrained environments 
suppressionFileUserThe user for Basic-auth-protected suppression files hosted on a webserver 
suppressionFilePasswordThe password/token for Basic-auth-protected suppression files hosted on a webserver 
suppressionFileBearerTokenThe bearer token for Bearer-auth-protected suppression files hosted on a webserver 
knownExploitedEnabledSets whether the Known Exploited Vulnerability update and analyzer are enabled.true
knownExploitedUrlSets URL to the CISA Known Exploited Vulnerabilities JSON data feed.https://www.cisa.gov/sites/default/files/feeds/known_exploited_vulnerabilities.json
knownExploitedUserThe user for a Basic-auth-protected mirrored copy of the CISA Known Exploited Vulnerabilities JSON data feed for internet-constrained environments 
knownExploitedPasswordThe password/token for a Basic-auth-protected mirrored copy of the CISA Known Exploited Vulnerabilities JSON data feed for internet-constrained environments 
knownExploitedBearerTokenThe bearer token for a Bearer-auth-protected mirrored copy of the CISA Known Exploited Vulnerabilities JSON data feed for internet-constrained environments 
knownExploitedValidForHoursSets the number of hours to wait before checking for new updates of the CISA Known Exploited Vulnerabilities JSON data feed24