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.
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.
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 in the table below.
|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.|
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.
In addition to the filters above, there is an Aggregation toggle that allows a fine-grained control for whether to display all violations for each component. More information can be found in Reviewing a Report.
Managing Proprietary Components
Proprietary components are unique to your organization. In many cases, these are developed by your organization and distributed among the applications you create.
Reviewing unknown components is a good place to start determining which of your components are in need to be marked as proprietary.
In the Application Composition Report, you can view proprietary components by selecting Proprietary in the Proprietary filter as shown below. You can have proprietary components that are an exact match, similar match, or unknown match.
IQ Server uses proprietary component matchers to identify proprietary components when applications are evaluated. Proprietary component matchers are configured in the Organization & Policies area, but you can also add them from within the Application Composition Report. This is especially useful when the report contains unknown components that you know are proprietary.
You need to be assigned to a role with "Edit Proprietary Components" permission in order to add proprietary component matchers. The built-in Policy Administrator and Owner roles have this permission.
To add proprietary component matchers:
- Click to select an unknown component.
- Click the Add Proprietary Component Matchers button. Note that this button only appears for unknown components.
- In the dialog, click the occurrences of the component that are proprietary.
- Optionally, add a regular expression to identify proprietary components.
- Click Add.
- Re-evaluate the binary application or repository to see the component identified as proprietary.
Existing reports are unaffected by additions to the Proprietary Component Matchers list; only after the next evaluation will you see the newly added components identified as proprietary.
For more information about the Proprietary Component Matchers, see Proprietary Component Configuration.
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 as similar or unknown , and instead result in an exact match.
- Access an Application Composition Report.
- Select Unknown or Similar in Component Match State filter.
- Click the row of component you wish to claim in the list - the Component Information Panel is displayed.
- Click on the Claim Component section of the CIP .
- Enter values for the coordinates of the component.
- As an option, enter the coordinates classifier, 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.
- Click the Claim button, to officially stake your claim for the component.
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 tab. Then, use the Revoke or Update buttons respectively.
Use the cancel button to undo any changes you made but haven’t saved.
Any changes to claimed components are visible only when the application is re-analyzed (via the re-evaluation button or a new evaluation being triggered from CI, CLI, policy monitoring, etc).