-
Notifications
You must be signed in to change notification settings - Fork 72
v5 Migration
If you're looking to upgrade the Dependency-Check Jenkins plugin to v5, read this first. Version 5 is a complete rewrite with breaking changes. Many of the best practices previously employed, no longer apply.
Version 5 is not compatible with previous versions
- Utilizes Jenkins Global Tool Configuration and automatically installs Dependency-Check CLI if necessary
- Multiple versions of Dependency-Check can be executed at the same time
- Jobs can be configured to always use the latest version of Dependency-Check, or can specify exactly which version to use
- Jenkins plugin will no longer need updating upon every Dependency-Check release. It now has an independent release schedule
- Jobs now have full control over every configurable option
- Publisher parses Dependency-Check XML reports generated from Dependency-Check v5.0 and higher
- Dynamic and interactive trends and results
- Builder is no longer integrated with the Jenkins runtime
- Builder utilizes Jenkins Global Tool Configuration
- Builder has one textarea for configuration, not individual configurable options
- Builder no longer has global configuration
- Publisher is no longer based on analysis-core
- Publisher can now put build into warning or failed state based on risk thresholds
- Publisher can only parse reports from Dependency-Check v5 or higher
- Previously configured jobs containing a Dependency-Check builder step will need to have the step added again
- Previously configured jobs containing a Dependency-Check publisher step with non-default values will need to be reconfigured
- Installations utilizing Jenkins proxy, NIST/NVD mirroring, external database, or custom analyzer settings will need to copy those configurations to a properties file for use with the Dependency-Check CLI
- Version 5 no longer works on older versions of Jenkins
In 2012 when the first version of the Dependency-Check Jenkins plugin was being written, Dependency-Check itself contained only 18 external dependencies and was only capable of scanning Java libraries. It was lightweight and fully capable of running within the Jenkins process. At the time, only a single incompatibility existed due to differences in Apache Velocity. The issue was minor and was worked around. It relied on analysis-core, a state-of-the-art health-aware publishing framework that also powered the Findbugs and PMD Jenkins plugins.
By 2018, Dependency-Check incorporated 20 analyzers, had 36 external dependencies, normalized output from other analyzers (nsp/npm, and retirejs), and analysis-core was no longer supported. At a minimum, the publisher needed rewritten, and the configuration to support all of the various options, which grew organically over time, needed simplifying. Jar-hell was also starting to become apparent. Some of the Jenkins dependencies, which were also used by Dependency-Check, were 8 years old. The inclusion of modern versions of dependencies in Dependency-Check on a Jenkins base which relied on older versions of the same dependencies, caused issues. A lot of effort was involved in ensuring that library APIs introduced in recent versions were not used to prevent ClassNotFoundException and NoSuchMethodError conditions at runtime. It was Jar-hell, but it was manageable.
In 2019 with the release of Dependency-Check v5.0.0, the original design was no longer viable. There was no escaping the need to rewrite and start from scratch. Jar-hell could no longer be mitigated. Modern versions of Jenkins had more restrictions on library usage, and downstream dependencies used by Dependency-Check v5 and its analyzers were now violating API compatibility with Jenkins. With the current design, specific analyzers would need to be permanently disabled to prevent runtime exceptions. In short, the plugin would need to be intentionally crippled to keep functioning.
In v5 of the Jenkins plugin, the global tool configuration mechanism is used to manage one or more versions of Dependency-Check. This same facility is used to manage JDKs, Maven, Ant and other external tool installations. The display of available versions to install, the downloading and extraction of the various Dependency-Check versions, is completely handled by Jenkins, not the plugin. The plugin uses a Jenkins mechanism to create a new external process which runs dependency-check.sh or dependency-check.bat (depending on platform). Since it's a new JVM process, library conflicts that existed in previous versions of the plugin are no longer an issue. It also allowed the Jenkins plugin to be greatly simplified. Instead of recreating the functionality of the CLI, the Jenkins plugin now uses the CLI. This approach is similar to how current commercial SCA tools work.
Also in v5, the publisher, which was previously powered by analysis-core, was replaced by code ported from the Dependency-Track Jenkins plugin. The new publisher has REST endpoints, is interactive, and no longer consists of multiple static pages.
Historically, the Dependency-Check team has always recommended using native build plugins (i.e. Gradle, Maven, or SBT plugin), followed by the command-line interface (CLI), followed by the Jenkins plugin builder. Analyzing with the Jenkins plugin was always viewed as a convenience as the CLI offered much more functionality and was more capable.
With Version 5 of the Jenkins plugin, the historic builder no longer exists. It's been replaced by a builder which simply wraps the CLI.
- For installations which utilized the CLI with Jenkins, the management of the CLI has become incredibly simplified and can now be automatically deployed across any builder node in a Jenkins cluster.
- For installations that relied on the legacy Jenkins builder, the migration to v5 will be the most impactful.
- For installations which relied on native build plugins (Gradle, Maven, or SBT) to perform the analysis and used the Jenkins publisher step to visualize results, the impact will likely be minor.