Documentation Nexus IQ Server 1.22

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

13.1. Integrating Nexus Repository Manager 2.x and IQ Server

[Tip]

The features discussed in this section require IQ Server and Nexus Repository Manager Pro with the Repository license plus either the Firewall or Lifecycle license.

13.1.1. Connecting to IQ Server

The first step to integrating IQ Server features with Nexus Repository Manager 2.x is connecting to IQ Server from Nexus Repository Manager.

To configure the connection to IQ Server, follow these instructions:

  1. Click on the IQ Server Connection menu item in Administration, located on the left of the Nexus Repository Manager application window.
  2. Enter the URL for your IQ Server installation.
  3. Enter the username and password.

    [Tip]

    It is recommended that you create a unique machine account with desired permissions for linking IQ Server with Nexus Repository Manager. At a minimum, the account needs Evaluate Individual Components permission at the repositories level for Audit and Quarantine features and/or Evaluate Applications permission at the application level for Staging functionality. For more information about permissions, see Role Management in the Security Administration chapter.

    Optionally, you can configure these properties:

    1. Enter a Request Timeout.
    2. Enter information in the Properties input field using a key=value definition per line. For example:

      procArch=false
      ipAddresses=true
      operatingSystem=false

      These properties are passed to IQ Server and can, for example, determine what properties are logged as part of a validation. Consult the IQ Server documentation for suitable parameters. In most use cases you will not need to configure any properties.

  4. Click Test Connection to verify the information you have entered is correct and a connection to IQ Server can be established.
  5. Click the Save button.

If successfully connected, a list of available applications in IQ Server is displayed as shown in the figure below.

figs/web/nexus-clm-config-tab.png

Figure 13.1. IQ Server Connection Tab in Nexus Repository Manager 2.x


Alternatively you can enable, disable, and/or configure IQ Server integration by adding the IQ: Server Connection capability like any other capability as documented in the Accessing and Configuring Capabilities section of the Nexus Repository Manager book.

[Note]

The features described here require licenses for Nexus Repository Manager as well as IQ Server. These are made available through purchase of our solutions. You can obtain them from the Sonatype Support team.

13.1.2. Viewing Component Information

In Nexus Repository Manager, the Artifact Search feature helps you find components in your repositories. In the search results, you can drill down for more detailed information. For example, after you perform a search, click Show All Versions, if available, in the search results to see information such as version, age, popularity, and more. This is displayed in the figure below.

figs/web/nexus-clm-search-results.png

Figure 13.2. Typical Search Results in Nexus Repository Manager 2.x


[Tip]

To get results that are not in the local Nexus Repository Manager cache, you will want to make sure the Download Remote Index option is enabled for the proxy repository. For guidance on this, check out section 6.2.4 (specifically Fig 6.9): Configuring Repositories in the Nexus Repository Manager book.

Once you’ve configured the IQ Server connection, additional component information such as security issues is displayed in the Nexus Repository Manager search results, for example:

figs/web/nexus-clm-show-all-versions.png

Figure 13.3. Nexus Repository Manager Search Showing All Versions


[Note]

Nexus Repository Manager search is only available for open source Java components.

You can access more detailed component information by selecting a component and clicking the Component Info tab located below the search results.

figs/web/nexus-clm-access-comp-info.png

Figure 13.4. Accessing the Component Info Tab


[Note]

Only users that are logged in will be able to see the Component Info tab.

On the Component Info tab, when you select one of the applications configured in your IQ Server, the Component Information Panel (CIP) is displayed. It contains the most granular details about a component.

figs/web/nexus-clm-comp-info-cip.png

Figure 13.5. Component Information Panel


Component Info

The Component Info tab displays the following information about a specific component:

  • Declared License - Any license(s) that has been declared by the author.
  • Observed License - Any license(s) found during the scan of the component’s source code.
  • Effective License - Either all licenses included in the Declared or Observed Group, or the overridden license.
  • Coordinates - The identifying information for a component. For known components, all available coordinate information will be displayed.
  • 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 threat level security issue and the total number of security issues.
  • Cataloged - The age of the component based on when it was first uploaded to an accessible storage site such as the Central Repository, for example.
  • Match State - How the component was matched (exact, similar, or unknown).
  • Identification Source - Whether a component is identified by Sonatype, or claimed by your own process.
  • Website - If available, an information icon providing a link to the project is displayed.
figs/web/nexus-clm-cip-text.png

Figure 13.6. CIP Text


The Component Info tab also includes a graph, which is laid out like a grid with each vertical column representing a particular version. The selected version is identified by a vertical line. You can move the line horizontally to learn about different versions of a component. The information includes:

  • Popularity - The relative popularity for each version is shown as a bar graph. The taller the bar the more popular the version.
  • License Risk - A display of risk based on license threat group settings from IQ Server.
  • Security Alerts - For each version, the highest security threat will be displayed by color, with the highest shown as red, and no marker indicating no threat.
figs/web/nexus-clm-cip-graph.png

Figure 13.7. CIP Graph


13.1.3. Component Details

The Component Info tab in Nexus Repository Manager has a Component Details button that opens a new tab with information about any policy violations, license issues, or security vulnerabilities that are known about a specific component.

scale-30

Figure 13.8. View Details


[Note]

In order to see the details for additional components, select another component from the search results, or select a different version in the CIP, and then click the View Details button.

13.1.4. Using Staging to Control Releases

With Staging, you can combine the release process controls in Nexus Repository Manager with the component intelligence from IQ Server to test a release automatically before its deployed.

To use IQ Server with Nexus Repository Manager 2.x, you must first create the following items:

In IQ Server
  • An Organization
  • An Application
  • A Policy
In Nexus Repository Manager
  • A Staging Profile
[Note]

Before using IQ Server for staging you should be familiar with the general setup and usage patterns of the Nexus Repository Manager Staging Suite documented in the chapter on staging, located in the Nexus Repository Manager book. There, you will be guided through the process to get Nexus Repository Manager prepared to handle your staging needs.

Staging Profile Configuration

To utilize IQ Server evaluation and policy features as part of your build promotion you will need to select an IQ Server Application as part of the staging profile configuration. This is done via Nexus Repository Manager. An example is provided below.

figs/web/clm-staging-profile.png

Figure 13.9. Staging Profile with an IQ Server Application Configured


Policy Actions for Staging

While not a requirement for using IQ Server with Nexus Repository Manager staging, IQ Server does have the ability to Fail or Warn on staging closure. This is managed by setting the Stage Release and Release actions for each policy. These policy actions can be configured to warn, fail, or no action (default). The figure below provides an example policy that would warn for a staging deployment and fail a release.

figs/web/server-policy-staging.png

Figure 13.10. Staging and Release Configuration for a Policy in IQ Server


The configuration of the Stage Release action is used for closing the staging repository. Based on the action chosen, the staging repository responds to policy violations as follows:

  • If the policy action is set to Fail, closing the staging repository fails.
  • If the policy action is set to Warn, the staging repository closes successfully, but a warning is produced.
  • If the policy action is set to No Action, the staging repository closes successfully regardless of any policy violations.

For more information on setting these actions see the Actions section in the Basic Policy Management chapter.

Policy Actions for Release Repositories

Nexus Repository Manager also has actions specific to the Release feature, and these can be configured to fail, warn or do nothing and are used for releasing or promoting the staging repository.

Once the staging profile is configured with the IQ Server application identifier, any deployment triggers an evaluation with IQ Server. The results are visible as Activity for the staging repository as shown in the figure below. Any rule failures are provided with further information in the detail panel. The View Full Report button links back to the detailed Application Composition Report.

figs/web/clm-staging-repository-failure.png

Figure 13.11. Staging Repository Activity with IQ Server Evaluation Failure and Details


13.1.5. Using Audit and Quarantine

[Tip]

The features discussed in the Using Audit & Quarantine section require Nexus Repository Manager Pro and IQ Server with the following licenses: Repository and Firewall.

The Audit and Quarantine features provide a way to protect your development environment from risky or undesirable components. These features use IQ Server policy management to identify, and if desired, prevent a proxy repository from serving unwanted components.

Before activating Audit and Quarantine, there are several items you need to complete:

  • Both Nexus Repository Manager and IQ Server must be running and must have a working connection between the two systems. For more information, see the Section 13.1.1, “Connecting to IQ Server” section in this chapter.
  • In Nexus Repository Manager, you need the following privileges to use Audit and Quarantine:

    • Add, edit, and delete privileges for capabilities, which allows you to configure, enable, and disable the Audit and Quarantine features.
    • Read privilege for repositories, which lets you view a results column in the Repositories tab.

      For information on assigning privileges, see the Managing Privileges section in the Nexus Repository Manager book.

  • For IQ Server, you must be assigned to a role in the root organization with permissions to view and edit IQ Elements. The built-in roles of Policy Administrator and Owner have these permissions. For more information on assigning roles and permissions, see the Security Administration chapter. To learn more about the root organization, see the Organization and Application Management chapter.
  • Also with regard to IQ Server, you should create a policy in the root organization that defines the rules or criteria to use when evaluating components of a proxy repository. The policy must be at the root organization level in the system hierarchy; policies at other levels are ignored by Audit and Quarantine. To learn more about creating a policy, see the Basic Policy Management chapter.

Once these items are completed, you are ready to configure Audit and Quarantine and view audit results. Each of these actions is described below in more detail.

Configuring Audit and Quarantine

You configure the Audit and Quarantine features by adding them to Nexus Repository Manager as a plug-in capability.

To configure Audit and Quarantine:

  1. In Nexus Repository Manager, click Capabilities on the Administration menu.
  2. Click the New button on the Capabilities tab. The Create new capability dialog is displayed.
  3. In the Type list, choose IQ: Audit and Quarantine.
  4. Configure Settings as follows:

    1. Enabled - Make sure the check box is selected to activate the Audit feature. The check box is selected by default.
    2. Repository - Select a specific proxy repository to scan, for example, Central.
    3. Quarantine - Select the check box to quarantine any components that violate policy whenever you add new components to the selected proxy repository. This setting affects only components that are added to the repository after Quarantine is enabled. When a component is quarantined, the Nexus Repository Manager prevents it from being served from the proxy repository. The check box is deselected by default.
  5. Click Add to create the new capability for Audit and Quarantine.

At this point, an audit of the selected repository is automatically started. Nexus Repository Manager contacts IQ Server and evaluates the components within the selected repository against any associated policy. The results are displayed in Repository Results, which is described in the next section.

[Note]

To successfully quarantine components when the Quarantine feature is enabled, the policy used to evaluate components must be configured to fail when policy violations occur at the proxy stage in the development lifecycle. If the policy is set to warn (rather than fail), the quarantining of components will not occur. For more information about setting policy and the proxy stage, see the Basic Policy Management chapter.

After the IQ: Audit and Quarantine capability is added, it appears on the Capabilities tab in Nexus Repository Manager as shown in the figure below.

figs/web/nexus-clm-capabilities.png

Figure 13.12. Capabilities Tab in Nexus Repository Manager


Disabling Audit and/or Quarantine

To disable Audit and/or Quarantine:

  1. In the Nexus Repository Manager interface, click Capabilities on the Administration menu.
  2. Click the IQ: Audit and Quarantine capability for a specific repository.
  3. Click the Settings tab of the IQ: Audit and Quarantine capability and set the following attributes:

    1. Click the Enabled check box to deselect it and disable the Audit feature.

      [Note]

      When you disable the IQ: Audit and Quarantine capability, Quarantine is also disabled.

    2. Click the Quarantine check box to deselect it and disable only the Quarantine feature.

      [Caution]

      When Quarantine is disabled, all quarantined components are made available for download from your proxy repository. This remains true, if you re-enable Quarantine. That is, any previously quarantined components are not quarantined again; only new components are evaluated for quarantine when you re-enable the Quarantine feature.

  4. Click Save to save your changes or click Discard to undo your changes.

Releasing a Component from Quarantine

When a component is quarantined due to a violation, it is not available for download from the proxy repository. You must first resolve the violation(s) that caused the quarantine before releasing the component and making it downloadable. For information on resolving violations from labels, security vulnerabilities, or license issues, see the Application Composition Report chapter. For information on waiving policy violations, see the Waiving Repository Policy Violations section of this chapter. Once the violations are resolved, you can proceed with releasing a component from quarantine.

To release a component from quarantine:

  1. In Nexus Repository Manager, select a repository that has been evaluated.
  2. Click the IQ Policy Violations count for a repository. This opens the Repository Results hosted on IQ Server.
  3. Navigate to the Policy tab, and click the Quarantined filter.
  4. Click a quarantined component. This expands the row to display the Component Information Panel (CIP).
  5. Click the Policy tab, and then click the Release Quarantine button.
  6. In the confirmation box, click the Release button.
figs/web/unquarantine-repo.png

Figure 13.13. Release Quarantine


[Note]

Once a component is released from quarantine, it cannot be put back into quarantine even if it has subsequent policy violations. If you want to re-quarantine a component, you must delete the component from its repository. The component will be quarantined again if, during an audit, it violates a policy that is set to Fail at the Proxy stage.

Re-enabling Audit and/or Quarantine

To re-enable Audit and/or Quarantine:

  1. In Nexus Repository Manager, click Capabilities on the Administration menu.
  2. Click the IQ: Audit and Quarantine capability for a specific repository.
  3. Click the Settings tab of the IQ: Audit and Quarantine capability and set the following attributes:

    1. Click the Enabled check box to enable the Audit feature.
    2. Click the Quarantine check box to enable to the Quarantine feature.

      [Note]

      Any previously quarantined components are not quarantined again even though they were quarantined in the past. Only new components are evaluated for quarantine when the Quarantine feature is re-enabled.

  4. Click Save to save your changes or click Discard to undo your changes.

Viewing Repository Results

Once the Audit and Quarantine features are enabled, whenever you add a component to a proxy repository (or delete one), Nexus Repository Manager contacts IQ Server to evaluate the components within the proxy repository against any associated policy. The IQ Policy Violations, are summarized in Nexus Repository Manager, and detailed in IQ Server.

In Nexus Repository Manager:

The results of an audit are summarized in the IQ Policy Violations column of the Repositories tab as shown in the figure below.

figs/web/firewall-column.png

Figure 13.14. IQ Policy Violations Column


The IQ Policy Violations column includes the following items:

  • A count of components by their highest policy violation level.
  • A count of quarantined components.
  • A link to Repository Results on IQ Server

The IQ Policy Violations column will also alert you if there are any errors in the audit and quarantine process. If there is an error, for example if Nexus Repository Manager cannot communicate with IQ Server, a red exclamation mark will appear to the right of the Repository Results link along with text pertinent to the error that occurred. Additional information will be available in the Nexus Repository Manager logs.

If you have permissions to add capabilities in Nexus Repository Manager, then you can also access Repository Results from the Capabilities tab:

  1. In the Type list of capabilities, select IQ: Audit and Quarantine.
  2. Click the Status tab of the IQ: Audit and Quarantine capability.
  3. Click View Results.

Both methods open Repository Results on IQ Server as shown in the figure below.

figs/web/repo-results.png

Figure 13.15. Repository Results


In IQ Server:

Repository Results is a display of policy violations and the components that violated those policies, as well as components that don’t have violations. At the top of the view is a summary section with the following information:

  • A count of components that were identified and scanned in the selected proxy repository.
  • A percentage of scanned components that are identified.
  • A count of policy violation alerts displayed by threat level.
  • A count of components affected by policy violations.
  • A count of quarantined components.

Below the summary section is a list of policy violations and the components that violated those policies. By default, this information is ordered by the highest policy threat level. You can refine the list using one of the following filter categories:

Filter
  • All - Every component in the proxy repository.
  • Exact - Components in the proxy repository that have an exact match to a component known to IQ Server.
  • Unknown - Components in the proxy repository that have no exact match in IQ Server and cannot be identified.
Violations
  • Summary - The most severe policy violation of each component.
  • All - Every policy violation and the components that violated those policies. A component may appear more than once, if it violated multiple policies.
  • Quarantined - Components that are prevented from being served by the proxy repository because they violate policy.
  • Waived - Only policy violations that have been waived.
[Note]

You can update the audit results for the entire proxy repository by clicking the Re-evaluate Policy button in the upper right corner of the Audit View. This is useful especially after an associated policy is added or modified on IQ Server. However, it may take some time, if the repository is large.

During re-evaluation any previously quarantined components remain quarantined, no matter whether they still violate policy.

With quarantine enabled, if you delete a quarantined component, its quarantine status is also deleted. If you add the component back in, it is evaluated again just like any new addition to the repository. Currently the only way to remove a component from quarantine is to change the policy accordingly, then delete and add back the component.

Also, whenever you add or delete a component in the proxy repository, the audit results are automatically updated for the individual component only (not the entire repository).

Using the Component Information Panel (CIP)

When you click an individual component in the Repository Results, the Component Information Panel (CIP) opens with the Component Info tab displayed.

Component Info

This tab contains the same granular details about an individual component as the Component Info tab in Nexus Repository Manager. For an explanation of those details, see Component Info earlier in this chapter.

figs/web/audit-view-component-info.png

Figure 13.16. The Component Info Tab


Policy

The Policy tab displays all policies that were violated by a component. Here you can see the name of the policy that has been violated (and any action that was taken), the name of the constraint that has been violated, and the value that was found.

While the Policy/Action and Constraint names are straight forward, the Condition Value may be a little confusing at first. A condition is simply the if part of an if/then statement. If a certain condition value is found which is equivalent to a condition being met, then the policy will be violated. E.g. if we have a policy that has a condition such that if a security vulnerability is found, our Condition Value column would indicate, Found x Security Vulnerabilities. In the same regard, Constraints are simply multiple conditions joined together.

The Policy Tab. image::figs/web/audit-view-policy.png

Licenses

The Licenses tab displays all Effective licenses, any licenses identified as declared by the author of the component, as well as any license found during the scan of the component source code. It also allows you to override the Effective license. To do this:

  1. Select the Scope of the override
  2. Select the Status
  3. Select one, or more, of the License(s)
  4. Optionally, but advised, provide a Comment
  5. Click Update
figs/web/audit-view-licenses.png

Figure 13.17. The Licenses Tab


Vulnerabilities

The Vulnerabilities tab displays all security vulnerabilities related to a component. The list of vulnerabilities is sorted by Threat Level from higher to lower risk. The Problem Code column displays unique identifiers obtained from security information web sites such as CVE and OSVDB. The Info button provides additional information about each security vulnerability. Lastly, the Status column tracks the state of your research regarding the vulnerability.

figs/web/audit-view-vulnerabilities.png

Figure 13.18. The Vulnerabilities Tab


If desired, you can change the security vulnerability status of a component in a proxy repository. This can help you keep track of your research when you investigate any security vulnerabilities identified by IQ Server.

To change the security vulnerability status of a component:

  1. In the Repository Results, click a desired component to open the Component Information Panel (CIP).
  2. Click the Vulnerabilities tab.
  3. In the list of vulnerabilities on the left, click one to select it.
  4. In the Status list on the right, select one of the following settings:

    • Open - The security vulnerability has not been reviewed; no research is under way.
    • Acknowledged - The security vulnerability is under review.
    • Not Applicable - The security vulnerability has been researched and deemed as having no effect on the repository.
    • Confirmed - The security vulnerability has been researched and deemed as valid and applicable.
  5. Click Update to save the changed setting.

Labels

The Labels tab displays any component labels that have been defined previously at the root organization level on IQ Server. Component labels are metadata that is assigned to a component within the context of a particular application or organization.

figs/web/audit-view-labels.png

Figure 13.19. The Labels Tab


Assigning a Label

When assigning a label, you will only see labels defined on the root organization.

To assign a label:

  1. Click a component you wish to assign a label to. The Component Information Panel (CIP) is displayed.
  2. Click the Label option from the CIP menu. Two boxes are displayed:

    • The Available box on the left displays all labels.
    • The Applied box on the right displays labels that have been assigned to the component.
  3. Click the button on the right side of a label to move it to the opposite side. You can hover over a label to view its description.
  4. Click on the + button on the right side of a label in the Available list to assign the label to the component.
  5. Click on the - button on the right side of a label in the Applied list to remove the label from the component.

When applying a label, you have the following options:

  • Assign label for a repository
  • Assign label for All Repositories
  • Assign label for all within the Root Organization

Waiving Repository Policy Violations

Policy violations for components found in your repositories can be waived with a number of options for the scope and target of the waiver. As with all features, make sure to verify you have the appropriate level of access provided by the role you have been assigned.

[Note]

Waiving policy violations for components in your repository is different than waiving for an application. See Section 11.9.2, “Adding a Waiver” for additional information on waiving components at that level.

Waive Policy Violation
  1. From within Nexus Repository Manager select a repository that has been evaluated.
  2. Click the IQ Policy Violations count for a repository. This will open the Repository Results hosted on IQ Server.
  3. Click a component that has a policy violation. This will expand the row to display the Component Information Panel (CIP).
  4. Click the Policy tab within the CIP to display the current policy violations for the selected component.
  5. Click the Waive button next to the policy violation you wish to waive.
  6. A dialog is displayed with the following settings:

    1. Determine the scope of the waiver:

      1. Repository selected repository [default]
      2. All repositories
      3. Organization Root Organization (This is displayed only if you have the appropriate level of access.)
    2. Determine the targeted component of the waiver:

      1. Selected component component name [default]
      2. All components
    3. Comments - Add a brief note if desired.
  7. Click the Waive button to complete the waiving process.
figs/web/audit-view-policy.png

Figure 13.20. Waiving Policy Violations


View/Remove Existing Waivers
  1. From within Nexus Repository Manager select a repository that has been evaluated by IQ Server.
  2. Click the IQ Policy Violations count for a repository. This will open the Repository Results hosted on IQ Server.
  3. Just above the list of components, you will see three options in the Violations filter. Click Waived, and then click one of the displayed components.
  4. Click the Policy tab within the CIP to display the current policy violations for the selected component.
  5. Click the View Existing Waivers button located above the list of policy violations. The Component Waivers dialog is displayed.
  6. If you wish to remove a waiver, click the Remove icon (shaped like a minus sign). A confirmation dialog is displayed. Click the Remove button to remove the waiver.
figs/web/repoman-view-waiver.png

Figure 13.21. Waiving Policy Violations


[Note]

Waivers will not be applied until a re-evaluation of the Repository Results has occurred. This will occur automatically if the targeted component is left to the default settings (i.e. not set to All). In cases where the selected component is set to All, a manual re-evaluation will need to occur for any results previously applying the violation.

13.1.6. Managing Repositories

The creation, modification, and deletion of repositories is managed via Nexus Repository Manager. However, IQ Server also displays information about any connected repositories.

To view this information:

  1. Click the Organization & Policies button located in the IQ Server toolbar.
  2. Click on Repositories, located in the sidebar on the left side of the screen. The Configuration tab is displayed, as shown in the figure below.
figs/web/clm-server-repositories.png

Figure 13.22. IQ Repositories


Details on repositories include:

  • The public id of the repository
  • The instance id of the Nexus Repository Manager hosting the repository
  • The current audit-enabled state of the repository

Clicking the Delete button (shaped like a trash can) allows you to delete the repository after you confirm the deletion in a dialog.

[Note]

The deletion of a repository in IQ Server will NOT be replicated to Nexus Repository Manager.

13.1.7. Managing User Roles

The Repositories page, accessible from the sidebar of the Organization & Policies area, lets you adjust access settings for repository evaluation results. The process is the same as managing roles and permissions for organizations and applications on IQ Server. Through role assignments, you have the ability to grant users different permissions for repository evaluation results without granting them access to organizations and applications. For example, to grant a user the ability to view repository results, you assign the user to a role with View IQ Elements permission. To edit repository results, you assign the user to a role with Edit IQ Elements permission. The role assignments affect all repositories, not individual ones. For more information about assigning user roles, see Role Management in the Security Administration chapter.

[Note]

Any role assignments made at the Root Organization level are inherited automatically by Repositories. However, if you set a role in Repositories, the Root Organization is unaffected.

13.1.8. Removing a Repository in IQ Server

To remove a repository:

  1. Click the Organization & Policies icon figs/web/clm-server-manage-app-org-icon.png on the IQ Server toolbar.
  2. Click Repositories in the sidebar to display the Repositories page.
  3. Locate the repository you want to remove in the Configuration section and click its Remove Repository icon (looks like a trash can).
  4. In the Remove Repository confirmation box, click Continue to delete the entity, or click Cancel to keep it.

This action affects only IQ Server, not Nexus Repository Manager. While the repository entity and its data are permanently removed from IQ Server, the repository in Nexus Repository Manager remains unchanged.

figs/web/repo-config.png

Figure 13.23. The Configuration Section