Documentation Nexus IQ Server 1.18

Our documentation site has moved. For the most current version, please see http://help.sonatype.com

10.7. Component Identification

One of the most important things you can do with regards to understanding the components in your application, is to identify them. What remains unidentified is of obvious concern.

figs/web/app-comp-report-unknown.png

Figure 10.29. Unknown Component


Components can be identified in a number of ways, including:

  • Extensive matching via various, proprietary algorithms
  • Claiming components
  • Establishing proprietary components

In this section, we’ll describe all of these in detail, within the context of identifying components using the Application Composition Report, as well as offer our suggestion for best practices.

10.7.1. Matching Components

When an evaluation is performed, hashes of the components in your application are created. This in many ways is like a fingerprint, which is unique to a component. That fingerprint (hash), is compared back to components known to the IQ Server, which will provide all the available component info. This includes: usage statistics, security vulnerability, and license information.

All of this information can be used as parameters in your policy, which translates to more understanding of the component usage in your organization. That data however, can only be linked based on a matching of hashes, which can be exact or similar, and in some cases, unknown. We discuss these three match types below.

figs/web/app-comp-report-filter-matches.png

Figure 10.30. Filter and Matching Options


Exact
An exact match means that a one-to-one link was found between a component hash in your application, and a component known to the IQ Server. This is the best case scenario with regard to component identification, and most components should fit in this category.
Similar
A similar match is found using various, proprietary matching algorithms. In a way it’s a "best guess" to match a component that you have in your application with a similar one known to the IQ Server. In some cases, multiple matches may be found, and this is where the Similar section of the CIP is important. While the most likely match is used to display any information about a similar matched component, you can see all other matches in this section of the Application Composition Report. An example is displayed in Figure 10.13, “CIP, Similar Section”.
Unknown
There are instances where not even a similar component match can be determined. This should be considered a serious situation, at least one that needs to be investigated. This could be a case of a component being recompiled and modified so that a match is no longer possible.

However, there is a chance that component is something malicious introduced into the application. Either way, an unknown component should prompt an investigation. Of course, if during your investigation, you are able to identify the component, you can claim that component, via the Claim Components section, which we will walk you through in more detail a little bit later. An example is displayed in Figure 10.29, “Unknown Component”.

[Note]

Unknown components will not be displayed in the License tab until they have been claimed.

In addition to the main filters above, you can also control whether all violations for each component will be displayed. By default the summary of violations is shown. This means that only the worst violation for a component will be shown, and the component will only appear once in the list. Choosing All or Waived, will show all violations (including those waived), or only the waived violations, respectively.

[Note]

Changing the Violations filter can result in the components being displayed in the component list more than once.

10.7.2. Managing Proprietary Components

Simply put, proprietary components are those components that are unique to your organization. In many cases these are actually developed by your organization and distributed among the applications you develop.

As with matched components, proprietary is one of the options included in the Filter on the Policy tab of the Application Composition Report. Unfortunately, there is often a little bit of confusion around identifying a proprietary component, so lets start first with what a proprietary component is.

figs/web/app-comp-report-proprietary.png

Figure 10.31. Proprietary Component


First and foremost, it’s important to point out that a component identified as proprietary is not "matched" as proprietary.

Identifying a component as proprietary is separate from our matching process. In this, a component identified as proprietary will also be assigned to one of three match states: similar, exact, or unknown. In most cases a proprietary component is unknown. As a suggestion for figuring out which of your components are proprietary, a good place to start is by reviewing unknown components.

[Note]

Policy can be set in such a way as to exclude components marked as proprietary from triggering violations. Care should be taken in using that condition.

To set up proprietary identification, follow these steps:

  1. Log into the IQ Server with a user that has been assigned to the CLM Administrator role.
  2. Click the System Preferences icon figs/web/clm-server-system-preferences-icon.png, and then the Proprietary Components option.
  3. There are two methods for identifying proprietary components.

    1. Method 1: Add packages that are considered proprietary. For example, if we entered com.sonatype, all components that contain a package com/sonatype would be marked as a proprietary component, and therefore not evaluated. Care should be taken to be as specific as possible here, as the provided package is compared greedily against your scanned binaries. For instance, if you specify com.sonatype it will match all of the following content locations:

      • com/sonatype
      • com/sonatype/anything
      • com/sonatype/anything/more
      • shaded/and/relocated/com/sonatype
      • shaded/and/relocated/com/sonatype/anything

        On the other hand, the following locations would not be matched for our example:

      • org/sonatype
      • com/sonatypestuff
      • com/sonatypestuff/anything
    2. Method 2: Enter a regular expression, which will be compared against the paths of all files scanned. This is provided as a means for recognizing components as proprietary based on the existence of a specific file within them.

      If you choose this option, make sure to click the Regular JAVA Expression (RegEx) check box. For more information on regular expressions, check out Oracle’s Java documentation.

      An example of a regular expression might be test\.zip. In this example anything in the top level directory named test.zip would be marked as a proprietary component. If you wanted to apply this to match a file named test.zip nested anywhere within the scanned binaries, use .*/test\.zip.

      [Note]

      Occurrences inside the identified archive will make the binary proprietary as well. For example, if a proprietary zip is found inside a jar, the jar is also considered proprietary.

  4. After entering your proprietary component identification, click the Add button. This will queue your new proprietary component identifier for saving. Additionally, click any remove icon (resembles a minus symbol) in the list to remove an entry. No changes will be persisted to the server until you click the Save button.
figs/web/clm-server-proprietary-packages-configuration.png

Figure 10.32. Proprietary Packages Configuration via the IQ Server


Once your proprietary components are configured, during an evaluation, the component and the directory structure will be considered. If it matches your proprietary component configuration, it will be identified as proprietary and displayed accordingly in the reports.

Remember, proprietary is not a type of match. Most proprietary components will still be identified as unknown. That’s not a hard fast rule, but it is the most common case.

[Tip]

The proprietary component changes will not be evaluated against existing reports, but will be picked up on the next evaluation.

10.7.3. Claiming a Component

When a component is similar or unknown, yet you are certain the component is recognized by your organization, you can prevent that component from being identified as similar or unknown in future reports. In other words, you can claim the component as your own.

Once claimed, that component will be known to the IQ Server. It will no longer be treated it as similar or unknown, and instead result in an exact match.

figs/web/app-comp-report-claim-component.png

Figure 10.33. Claim a Component


  1. Access an Application Composition Report.
  2. Click the Policy tab, and then click the Unknown or Similar component filter.
  3. Click the row of component you wish to claim in the list - the Component Information Panel is displayed.
  4. Click on the Claim Component section of the CIP .
  5. Enter values for the coordinates of the component.
  6. As an option, enter the coordinates classifier and extension, the Created Date, and/or a Comment. The created date is initialized with the date of the youngest entry in the component to be claimed.
  7. Click the Claim button, to officially stake your claim for the component.

On review of the existing report, as well as those in the future, there is now an indicator that information about the component has been edited. When hovered over, a tooltip is displayed identifying that the component has been claimed.

We refer to this as the edited component tick mark (a small red triangle) on all future scans for this application, as well as any application with a valid Application ID on the IQ Server.

figs/web/app-comp-report-claimed-component.png

Figure 10.34. Claimed Component Indicator


In addition, the Component Info section for the claimed component will now have two new fields, one indicating the Identification Source is Manual, and the other, Identification Comment will include any comments that were entered. While any policy violations will be displayed, the component graph will not.

Finally, if you have made a mistake and wish to revoke the claim on the component or make an edit, click on the Claim Component tab. Then, use the Revoke or Update buttons respectively.

figs/web/app-comp-report-update-claimed-component.png

Figure 10.35. Update or Revoke Claimed Component Indicator


[Tip]

Use the cancel button to undo any changes you made but haven’t saved.