Sonatype CLM for Eclipse
The rebranding and renaming of Sonatype CLM to Nexus IQ Server started with the 1.17 release. You will see references to "Sonatype CLM" in the Eclipse plugin. We realize this may cause some confusion, and appreciate your patience as we move forward.
Often only called Eclipse, the Eclipse IDE is a very powerful, open source IDE written mostly in Java and managed by the Eclipse Foundation. It can be used for development in a number of languages, and is the most widely used IDE for Java development. It features a powerful plug-in system that allows you to customize the IDE, with features that support a large number software development-related tasks including localization options, version control systems, and myriad of other tasks.
Installing Sonatype CLM for Eclipse
Be sure to check the Integration Requirements for Eclipse before attempting to install.
Sonatype CLM for Eclipse can be installed by adding a new software repository.
- Navigate to the Help menu and select Install New Software.
- Press the Add button in the Install dialog and create a new repository with the following information:
Location: Set to URL for the Sonatype CLM for Eclipse repository:
Name: Enter a name of your choice.
Click OK. A list of available releases is downloaded and an entry for the latest version of Sonatype CLM for Eclipse is displayed.
Uncheck the item Show only the latest versions of available software, if you need to install an older release.
Select the version of Sonatype CLM for Eclipse you would like to install and press Next>, proceed through accepting the end user license agreement and restart Eclipse to complete the installation.
Configuring Sonatype CLM for Eclipse
After successful installation of Sonatype CLM for Eclipse, you will be able to choose to show the Sonatype CLM view. To access this view:
- Choose the Window menu and select Other in the Show View submenu.
- Locate the Sonatype CLM section with Component Info:
Select it and press OK and the view will appear in your IDE.
By typing "Compo" in the filter input, Component Info is automatically highlighted.
Once the view is displayed, a warning appears. This is because the you need to point Eclipse at your IQ Server:
Press the Configure buttonin the top right-hand side of the component view.
- Once in Sonatype CLM for Eclipse Configuration area, there are a number of parameters you will need to complete before you can review data from IQ Server:
- CLM Server URL: The CLM Server URL input field has to be configured with the URL of your IQ server.
User Authentication: Select this option to enter the username and password your system administrator has assigned you. In many cases this will simply be your single sign on credentials (e.g. LDAP), though it may also be a unique username.
Selecting the option to persist credentials in Eclipse secure storage will reuse your credentials after a restart. If this is not selected you will need to reenter your credentials after a restart.
- PKI Authentication: Select this option to delegate authentication to the JVM.
Application Name: The Application Name is the application which has been configured in the IQ Server for you. This should match the common name you associate with the application. If you don’t see a name you recognize, contact your IQ Server Administrator.
The drop down will display a list of all available applications after pressing the Refresh button.
- Additional Maven Scopes: The compile and runtime scopes will always be considered. Additional scopes (provided, test, and system) you would like CLM to include can also be selected.
Assigned vs. Unassigned Content: After selecting an application name that represents a collection of policies configured in your IQ Server, you can determine the Eclipse projects that should be analyzed. The list on the left titled Unassigned content contains all projects in your current Eclipse workspace that have not been assigned to an IQ Server Application. Select a project from that list and add it to the Assigned content list on the right by clicking the Add button. This will add the project to the component analysis via the IQ Server. In order to perform an analysis, the project needs to be open. To select multiple projects use the Shift and Control keys, and then click the Add button. The Add All, Remove and Remove All buttons help you to control the projects to analyze for different analysis sessions.
Projects can, at most, be assigned to a single application.
With a finished selection of the projects you want to analyze, press the Finish button and wait for the component list to be displayed in the view.
Only open projects will be taken into account as part of the component analysis.
Using the Component Info View
Once configured and the component analysis is completed, a component view will look similar to the example shown below. The list of components will reflect an analysis of the build path.
For Maven projects we include the compile and runtime scopes in the CLM evaluation. If you wish to include additional dependencies found in provided, test, and system scope, these can be configured.
The top left-hand corner of the Sonatype CLM for Eclipse Component Info view displays either the number of projects currently being examined in the view, or the name of the specific project. Next to that, the number of components found, and the number of components shown in the list is displayed.
The top right-hand corner provides a number of buttons to access the following features of Sonatype CLM for Eclipse:
|Open Component Details|
Opens another window with more details about the selected component including policy violations, license analysis and security issues.
|Open POM||Opens the Maven pom.xml file of the selected component from the list in the Maven POM Editor.|
|Locate Declarations||Starts a search that displays all usages of a selected component in the projects currently examined.|
|Filter||Brings up the filter selection, that lets you narrow down the number of components visible in the view.|
|Configure||Activates the configuration dialog for the component analysis.|
|Refresh||Refreshes the component list and analysis results.|
|Show information about the plugin||Displays the Sonatype CLM for Eclipse support pages in an external browser.|
|Minimize||Minimize the view.|
|Maximize||Maximize the view.|
The left-hand side of the view contains the list of components found in the project and identified by their artifact identifier and version number. A color indicator beside the components signals potential policy violations. The right-hand side of the view displays the details of the selected component from the list on the left.
You may notice some components are black or gray. This indicates components you have included (black) in your application, versus components that are included via a transitive dependency (gray).
By clicking on the list header on the left, the list can be ordered by the threat level of the policy a component has violated. In cases where there is no violation, the threat is simply light blue.
When you select a specific component in the list, the details, various properties, and a visualization of the different versions is displayed to the right of the list.
Depending on your screen size, the visual display may be shown below the component list. Try adjusting your screen size, or adjusting the panel.
The details of a specific component as displayed in the image below include properties about the component and provide access to further features:
|Group||The Maven groupId the component was published with. In many cases this is equivalent with the reverse domain name of the organization responsible for the deployment or running the project.|
|Artifact||The Maven artifactId of the component acts as a short and ideally descriptive name.|
|Version||The Maven version of the component. A version string ending in -SNAPSHOT signifies a transient, in development version, any other version is a release version.|
|Overridden License||The value of a license override configured in your IQ Server.|
|Declared License||The software license declared by the developer of the project, which in some cases, is identified during research by Sonatype, or directly from the Maven POM file.|
|Observed License||The licenses found by the IQ Server in a source code analysis.|
|Highest Policy Threat||The highest threat level policy that has been violated, as well as the total number of violations.|
|Highest Security Threat||The highest security threat level as well as the number of issues found with the respective level.|
|Patch Available||This is a future feature that will provide details in instances where a patch is available. Patches will be provided and verified by Sonatype.|
|Cataloged||The age of the component in the Central Repository.|
|Identification Source||The catalog in which a component identification match was found. This includes either a match made by Sonatype (e.g. the catalog of the Central Repository), or a match made manually (i.e. through the IQ Server claiming process).|
|Website||If available, an information icon providing a link to the project is displayed.|
|View Details||Press this button to display the details view for the selected component as detailed in Section 19.6, “Inspecting Component Details”.|
|Migrate||Press this button to start a project refactoring that allows you to change all usages of the current component to a different version as documented in Section 19.7, “Migrating to Different Component Versions”.|
|Custom Metadata||This is a future feature that will allow you to display all custom metadata tags assigned to the component.|
The visualization chart shown below shows a number of properties for different, available versions of the selected component. Older versions are displayed on the left and newer versions on the right. Click on any section in the visualization, and all information for that particular version will be highlighted, with the specific version number at the bottom. In addition, the details for that version of the component will display in the left-hand list of properties. Arrows to the left and right of the visualization allow you to view the full range of available versions.
The properties displayed include:
|Popularity||The relative popularity of a version as compared to all other component versions.|
|License Conflict||Displays an indicator, if the observed licenses in the component are creating a legal conflict, e.g. GPL V2 and Apache V2 are not compatible for distribution of one component.|
|License Risk||The risk posed based on what has been set within the license threat groups. While defaults are available, these are configurable via the IQ Server.|
|Security Alerts||Indicators for the severity of security alerts affecting the component version.|
You will likely notice a number of colors within the visualization chart. The value for each of these colors is as follows:
- Grey for any versions older than the current version.
- Green for newer, but within the same major version of the component.
- Blue for newer component versions, but with a greater major version than the current component.
For License and Security
- Blue - no security or license risk
- Yellow - minor security or license risk
- Orange - medium security or license risk
- Red - severe security or license risk
Filtering the Component List
The list of components found in the analysis and displayed in the component info view can be configured by pressing the Filter button. The filter dialog, displayed bdlow, allows you to narrow down the components shown.
The Scope setting determines which projects' components are displayed in the list:
|All open projects||include all the components, from all open projects.|
|Current selection project(s)||include the components from the project currently selected in the package explorer.|
|Current selection working set(s)||include the components from all the projects in the working set currently selected in the package explorer.|
|Project||include the components from the project selected in the drop down.|
|Working Set||include the components from all the projects in the working set selected in the drop down.|
Searching for Component Usages
Once you have selected a specific component in the list on the left of the component info view, IQ Server can determine in which projects the component is used. After pressing the Locate Declarations button, and once the search has completed, you will see the results in a tree view of projects and project pom.xml files, all displayed in the Search window.
Inspecting this list can help you assess the impact of a potential upgrade to a new component version. Looking at the found projects, you can potentially remove wrong declarations, determine side effects from transitive dependencies, or find out why this component shows up as dependency at all.
Inspecting Component Details
Press the Open Component Details buttonto access the details about policy violations, license analysis and security issues for a specific component selected in the list. An example details view is shown below:
The Policy Violations section in the top contains a list of all the policies that have been violated by the component.
The License Analysis section contains the threat levels posed by the licenses declared for each component, as well as those that have been observed in the source code.
The Security Issues section below contains the list of issues found. They are sorted from higher to lower risk, with each issue detailed by a threat level ranging from 0 to 10, or potentially with the value unscored and a descriptive text in the Summary column. In addition, links to the security vulnerability database entry are added as links in the Problem Code column.
Migrating to Different Component Versions
This feature relies on the project being a Maven project.
If you determine that a component upgrade is required to avoid a security or license issue or a policy violation, after reviewing your component usage, Sonatype CLM for Eclipse can be used to assist you in the necessary refactoring.
The first step to start the migration is to select a newer version for the component in the visualization chart. An example is displayed in the image below:
Once you have selected a different version than the one currently used, the Migrate button will become active. Pressing the button opens a dialog that assists you in the migration to the newer component. The complexity of this task varies considerably from project setup to project setup. The migration wizard is able to detect circumstances such as the component being a transitive dependency or versions managed in a property.
The simplest flow is when a dependency version can be applied and the result is a single dialog like the one displayed below.
If the version is managed in a property, the initial screen in the following example allows you to select if you want to continue with a property upgrade, or perform a replacing version upgrade.
Once you have selected to perform a property upgrade, you will be able to apply it in the next screen, as shown below:
The Refactoring screen features navigation tools allowing you to view all potential changes in the dialog, and step through them one-by-one before deciding to continue.
After you have completed the refactoring of your project files, you should perform a full build, as well as a thorough test, to determine that you can proceed with the new version in your development.
Typically, smaller version changes will have a higher chance of working without any major refactorings, or adaptations, of your code base and projects, while larger version changes potentially give you more new features or bug fixes.
Your release cycle, customer demands, productions issues, and other influencing factors will determine your version upgrade choices. You might decide a multi-step approach, where you do a small version upgrade immediately to resolve current issues and then work on the larger upgrade subsequently to get the benefits of using a newer version. Or, you might be okay with doing an upgrade to the latest available version straight away. Potentially, a combination of approaches in different branches of your source code management system is used to figure out the best way of going forward with the upgrade.
Sonatype CLM for Eclipse and other tools of the IQ Server suite can assist you through the process of upgrading, as well as monitoring, the applications after upgrade completion.