Firewall Quick Start Guide

IQ Server | Reading time: 12 minutes

Is this article helpful?

Use this guide to get IQ Server up and running for the purpose of trying out the associated Nexus Firewall functionality before installing it in your development environment. If you have a Nexus Repository Manager or Artifactory server available, you can expect to spend 15 to 30 minutes for installation and configuration, a bit longer if you don’t.

To dive into Nexus Firewall further, check out our help docs on IQ Server and NXRM 3, IQ Server and NXRM 2, or IQ Server and Firewall for Artifactory.

In this guide

This guide is divided in three sections: First we’ll go over Nexus IQ Server setup. From there, select a
Firewall integration for specific configuration and evaluation information. Finally, see how to use available component information to resolve violations.

NOTE: To integrate Nexus Repository Manager or Artifactory with IQ Server you need a Nexus Firewall or Nexus Firewall for Artifactory license. If you don’t have one, request a 14-day trial.

If using a trial license, we recommend installing a fresh copy of IQ Server instead of using an existing instance. This simplifies tear-down when your trial license expires.

Nexus IQ Server Setup

This section goes over Nexus IQ Server setup, including installation, reference policies, and policy action configuration.

Installing & Starting the IQ Server

Installing the IQ server is done in a few easy steps - pick a location, download the archived server, and unpack the contents. Since we’re not focused on mimicking a production experience, most laptop and desktop configurations should run IQ Server with no problem. If you are looking to plan for the future, be sure to review the Installation Requirements.

  1. Create an installation directory in your desired location.
  2. Download the latest version of IQ Server to the installation directory.
  3. Extract the tar.gz or .zip file.

Once you’ve extracted the contents, follow the steps below to run IQ Server:

  1. Using a command line interface, switch to the nexus-iq-server bundle directory in your installation directory e.g. nexus-iq-server-x.xx.x-xx-bundle.
  2. Run one of the following commands to start IQ Server:
    • Linux or Mac: ./demo.sh
    • Windows: demo.bat
  3. Open IQ Server in a browser using the default URL: http://localhost:8070
  4. Log in using the default Administrator account:
    • Username: admin
    • Password: admin123
  5. Install the required product license supplied to you by the Sonatype Support team.
    • Click Install License.
    • Navigate to the license file (.lic) and click Open.
    • Click I Accept to accept the End User License Agreement.

NOTE: IQ Server needs access to an external data service to perform evaluations, which may be blocked in your internal environment. For a workaround, see Running IQ Server Behind an HTTP Proxy Server.

Evaluating an application through the user interface will transfer the bits to your IQ server. If you are working on a slower connection, or over a VPN, this means longer analysis times.

Reference Policies

NOTE As of version 1.44, reference policies are automatically created for new IQ Server installations.

Policy is at the core of IQ Server’s automation capabilities. While you can create a completely custom set of policies, the Sonatype Reference Policy Set is the quickest way to get started. This set includes multiple policies for triggering violations on security vulnerabilities, licensing issues, architecture issues, and more.

The Reference Policy Set is downloaded and imported into the Root Organization automatically when IQ server is started for the first time.

You can also download the Reference Policy Set (.json file) and import it manually.

Configuring Policy Actions

Policy actions directly affect how IQ Server automates processes in the available integrations when policy violations are encountered. In the case of Nexus Firewall, you can set an action to warn, which will audit, or simply display any violations. Alternatively, you can set the action to Fail, which will quarantine, or block developers from accessing new components entering a repository that also violate the specified policy. To set Policy actions for the Proxy stage:

  1. In IQ Server, click the Organization & Policies icon on the IQ Server toolbar.
  2. Click Root Organization in the sidebar, and then click the policies section.
  3. Click on the policy you want to add an action to, and in the Proxy column choose Warn (Audit) or Fail (Quarantine).
  4. Click Update button.

When using the Fail action (Quarantine), the repository will need to be configured accordingly. A few additional things to keep in mind when using quarantine:

  • New components entering the repository can be quarantined.
  • Existing components in the repository will not be quarantined. This ensures that turning on quarantine will not break your existing builds.
  • If IQ Server goes down or your license expires, you will not be able to proxy new components unless the IQ: Audit and Quarantine capability is disabled or deleted.
  • If you delete the IQ: Audit and Quarantine capability, any quarantined components will be unquarantined.
  • Developers will only see a 404 in their build logs when trying to retrieve a quarantined component, so it’s important to let them know when quarantine is in use.

NOTE: We recommend that you create a new proxy repository when trying out quarantine for the first time.

For additional information on what actions can be set and how they can affect automation, check out Understanding the Parts of a Policy.

Firewall Integration Setup

The IQ Server Firewall integration is available for the following products:

Nexus Repository Manager 2

Firewall for Nexus Repository Manager lets you integrate IQ Server’s policy management and component intelligence features with proxy repositories in Nexus Repository Manager. In order to do this, first you will need to configure the capabilities that allow for communication between IQ Server and Nexus Repository Manager.

Supported versions

  • Nexus Repository Manager OSS: 2.14.8
  • Nexus Repository Manager Pro: 2.12

Configuring

There are two steps required for IQ Server to interact with an instance of Nexus Repository Manager and evaluate repositories. First, you need to configure the IQ Server connection:

  1. In Nexus Repository Manager 2, click IQ Server Connection under Administration.
  2. Enter the URL for your IQ Server installation.
  3. Select an Authentication Method:
    • User Authentication: Enter the username and password.
    • PKI Authentication: Delegate to the JVM for authentication.
  4. Click Save.

NXRM2 Configuration

If successfully connected, a list of available applications in IQ Server displays in the Server Connection tab.

TIP: For this quick start guide, using the default admin credentials is acceptable. However, for a real implementation, you would want to create a unique user for this integration, making sure to review Role Management.

Next, add the Audit and/or Quarantine capability for each repository you want to evaluate. To configure Audit and/or Quarantine:

  1. In Nexus Repository Manager, click Capabilities on the Administration menu.
  2. Click New on the Capabilities tab. The Create new capability dialog displays.
  3. In the Type list, choose IQ: Audit and Quarantine.
  4. Select a specific proxy repository to analyze, for example Central.
  5. Click Add.

An audit of the selected repository automatically starts. Nexus Repository Manager contacts IQ Server and evaluates the components within the selected repository against any associated policy.

Repository Audit

INFO: These features use IQ Server policy management to identify, and if desired, prevent a proxy repository from serving unwanted components. If you have chosen to Audit, policies must also be configured with a fail action. For Quarantine configuration, see Configuring Audit and Quarantine. Additional information is available in IQ Server and Repository Management.

Reviewing Results

Once configured, the evaluation of the repository is automatic and will occur given any repository changes (e.g. adding a new component). Depending on the size (number of components) of the repository, the evaluation could take a minute or so.

A more in-depth review of Nexus Firewall IQ Server can be found in IQ Server and Repository Results.

To review results in Nexus Repository Manager 2, click Repositories under the Views/Repositories menu. Repository Results are summarized in the IQ Policy Violations column of the Repositories tab.

View Results NXRM2

To view detailed results, click the open icon in the IQ Policy Violations column of the Repositories tab.

View Detailed Results NXRM2

IQ Server will open in a new tab showing detailed Repository Results.

Nexus Repository Manager 3

Firewall for Nexus Repository Manager lets you integrate IQ Server’s policy management and component intelligence features with proxy repositories in Nexus Repository Manager. In order to do this, first you will need to configure the capabilities that allow for communication between IQ Server and Nexus Repository Manager.

Supported versions

  • Nexus Repository Manager OSS: 3.9.x or higher
  • Nexus Repository Manager Pro: 3.2 or higher
  • Nexus Repository Manager Pro with High Availability: 3.8.x or higher with Nexus IQ Server 1.35.x or higher

Configuring

There are two steps required for IQ Server to interact with an instance of Nexus Repository Manager, and evaluate repositories. First, you need to configure the IQ Server connection:

  1. In Nexus Repository Manager, click Administration on the main toolbar.
  2. In the Administration main menu, click Server under IQ Server.
  3. Select Whether to use IQ Server to enable IQ Server.
  4. Enter the IQ Server URL.
  5. Select an Authentication Method:
    • User Authentication: Enter the username and password.
    • PKI Authentication: Delegate to the JVM for authentication.
  6. Click Verify Connection to save.

INFO: For this quick start guide, using the default admin credentials is acceptable. However, for a real implementation, you would want to create a unique user for this integration, making sure to review Role Management.

Next, add the Audit and/or Quarantine capability for each repository you want to evaluate. To configure Audit and/or Quarantine:

  1. In Nexus Repository Manager 3, go to the Administration main menu and click Capabilities under System.
  2. Click Create capability.
  3. In the Select Capability Type view, click IQ: Audit and Quarantine.
  4. Select a specific proxy repository to analyze, for example Central.
  5. Click Create capability to save the new capability for Audit and Quarantine.

New Audit and Quarantine Capability

An audit of the selected repository automatically starts. Nexus Repository Manager contacts IQ Server and evaluates the components within the selected repository against any associated policy.

INFO: These features use IQ Server policy management to identify, and if desired, prevent a proxy repository from serving unwanted components. If you have chosen to Audit, policies must also be configured with a fail action. For Quarantine configuration, see Configuring Audit and Quarantine. Additional information is available in IQ Server and Repository Management.

Reviewing Results

Once configured, the evaluation of the repository is automatic and will occur given any repository changes (e.g. adding a new component). Depending on the size (number of components) of the repository, the evaluation could take a minute or so.

A more in-depth review of Nexus Firewall IQ Server can be found in IQ Server and Repository Results.

In Nexus Repository Manager 3, the results of an audit are summarized in the IQ Policy Violations column of the Repositories view as shown in the figure below. Access the Repositories view from the Repository sub menu of the Administration menu.

View Results NXRM3

To view detailed results, click the open icon in the IQ Policy Violations column of the Repositories view. IQ Server will open in a new tab showing detailed Repository Results.

View Detailed Results NXRM3

Artifactory

The Nexus Firewall for Artifactory plugin uses audit and quarantine features to help protect your development environment from risky or undesirable components. These features use IQ Server policy management to identify, and if desired, prevent proxy repositories from serving unwanted components.

Supported versions

  • Plugin tested with JFrog Artifactory Pro version 6.6.5 with IQ Server release 61 or higher

Installation

  1. Download the latest version of the plugin.
  2. Extract the contents of the plugin to ${ARTIFACTORY_HOME}/etc/plugins. The zip file includes an example configuration file for the plugin, and all necessary files for the operation of the plugin. The final folder structure should resemble:

    ${ARTIFACTORY_HOME}
       /etc
          /plugins
             /lib
                lib/nexus-iq-artifactory-plugin.jar
             nexusFirewallForArtifactoryPlugin.groovy
             firewall.properties
    
  3. Rename firewall.properties.example to firewall.properties to use as a base for your configuration.

  4. Configure which repositories you would like to enable in the firewall.properties file.

Configuration

All plugin configuration is done through the firewall.properties file. When changes are made to this file, they can be applied by restarting Artifactory.

# These properties are to configure the connection to the IQ server.
# The values below are example values and should be updated with your own.
firewall.iq.url=http://iq.example.com:8070
firewall.iq.username=exampleusername
firewall.iq.password=examplepassword
 
# The URL that users will use to connect to the IQ Server.
# This URL will be preprended to the Application Composition report URI.
# For example,
#   http://iq.public.com:8070/ui/links/repository/0396e6d401d143399d53493e57c106e8/result
firewall.iq.public.url=http://iq.public.com:8070
 
# Define http proxy settings if applicable
# firewall.iq.proxy.hostname=company-proxy.example.com
# firewall.iq.proxy.port=8080
# firewall.iq.proxy.username=proxyusername
# firewall.iq.proxy.password=proxypassword
# firewall.iq.proxy.ntlm.domain=companydomain
# firewall.iq.proxy.ntlm.workstation=localworkstation
 
# Define repositories with a 'firewall.repo.' prefix. Possible options are 'quarantine' and 'audit'.
# firewall.repo.<example-repository-name>=quarantine
# firewall.repo.<other-example-repository-name>=audit

The username defined must exist in IQ and have the Component Evaluator role. See Role Management for further information.

The plugin only supports the remote repository type, usually configured as a remote proxy of Maven Central at https://repo1.maven.org/maven2. The virtual repository type is indirectly supported - if your virtual repository includes a remote repository that has Firewall enabled, then components can be quarantined or audited.

WARNING:: Removing the firewall.properties file will disable the plugin. Any repositories that were previously enabled with quarantine or audit will no longer perform quarantine or audit actions on artifacts in those repositories.

Reviewing Results

Every repository that has Firewall enabled will receive its own Application Composition report URL. To obtain this URL, make the following call to the Artifactory server:

curl -u yourusername:yourpassword "https://artifactory.example.com/api/plugins/execute/firewallEvaluationSummary?params=repo=your-virtual-repo-name"

NOTE: In the above example, you will need to substitute your appropriate username, password, Artifactory URL, and virtual repository name.

The result is a JSON response with details on the repository:

{
  "moderateComponentCount":0,
  "quarantinedComponentCount":0,
  "reportUrl":"https://myiqserver:8070/ui/links/repository/0396e6d401d143399d53493e57c106e8/result",
  "severeComponentCount":0,
  "criticalComponentCount":0,
  "affectedComponentCount":0
}

Copy and paste the reportUrl into your browser. This takes you to the static policy report URL which can be bookmarked for future use.

In addition, each repository enabled for Firewall has a property called firewall.iqRepositoryUrl. This is also a copy + paste URL with access to the same Application Composition Report.

Investigating & Remediating Violations

Repository Results allow you to drill down to learn specific details about a violation, including the ability to isolate quarantined components. Click an individual component to open the Component Information Panel (CIP). The CIP displays many details, which are divided into different sections or tabs. To get you started using the CIP, take a look at these sections:

  • Component Info - In the graph, you can move the vertical bar to learn the differences between versions of a component.
  • Policy - Click the Waive button to force IQ Server to ignore a policy violation.
  • Licenses - Track your research about a particular license and even override one.
  • Vulnerabilities - Click Info for a thorough explanation of a component’s vulnerability and a recommended action.
  • Claim Component - Tell IQ Server to recognize a component even though it was previously identified as unknown.

This is just a small sample of the component information available in the CIP. For a complete discussion of the CIP, see Component Information Panel.