Firewall Quickstart

This guide instructs you on setting up a demo of Nexus Firewall in your local environment. This lets you explore its features before integrating it into your development environment. 

The Quickstart guide covers basic IQ Server installation, repository configuration, and basic operation. If you have a Nexus Repository Pro or Artifactory server available, you can expect to spend 15 to 30 minutes for installation and configuration, and a bit longer if you don’t. 

To dive into Nexus Firewall further, check out our Firewall help docs.

A Nexus Firewall License is required to integrate Nexus Repository Pro or Artifactory with IQ Server. If you don’t have one, please request a demo. 

This Quickstart assumes you are using a Firewall License issued after June 1, 2021. Older licenses may not have access to Next-Gen Firewall Features. Check out our Next-Gen Firewall documentation for more information. Contact us if you need to upgrade your Firewall License. 

IQ Server Setup 

This section tells you how to set up IQ Server - including installation, reference policies, and policy action configuration.

Requirements

Nexus Firewall requires IQ Server and an artifact repository manager. The following versions are required to use all Firewall Features:

  • IQ Server 134 or later

Supported repository managers:

  • Nexus Repository Pro 3.38.1 (Recommended) 
  • JFrog Artifactory 7.2.6
    • Version 2.2 of the Firewall for JFrog Artifactory Plugin

Supported Versions

  • Next-gen Firewall for Nexus Repository Pro requires IQ Server version 114 or above.
  • Firewall for Artifactory requires IQ Server version 119 or above.

Download and Install 

Installing the IQ server is done in a few quick steps:

  1. Select an installation location.
  2. Download the server archive. 
  3. Unpack the tar.gz or .zip file.

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.

Start the IQ Server 

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

  1. Using a command-line interface, navigate 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 the IQ Server user interface in a browser. The default URL is http://localhost:8070
  4. Log in using the default Administrator account:
    • Default username: admin
    • Default 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.


 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.

IQ Server Policies 

Sonatype's IQ Server automates software supply chain security by allowing you to define a set of policies to define your risk tolerance and open source management strategy. Sonatype's Reference Policy set is automatically installed the first time you start IQ Server. These policies jump-start your policy creation process by giving you a comprehensive set of pre-defined policies that cover security, licensing, architectural, and general quality issues. The reference policy set can also be downloaded here. 


Configuring Policy Actions

A Policy Action tells the IQ Server what to do when it encounters a policy violation. This feature is how Nexus Firewall automates your open source component management. Firewall actions are controlled through the Proxy Stage action. Actions set at other stages are handled by Nexus Lifecycle. There are three possible actions Firewall can take in response to a policy violation:

  • No Action - This is the default action. Violations will be visible in the Repository Results screen. 
  • Warn - This action will not impact components entering the repository. It is functionally comparable to No Action at the proxy stage. 
  • Fail - The Fail Action tells Nexus Firewall to quarantine any new component in violation of this policy. This is the way to turn on Firewall for a specific condition. 

Nexus Firewall only quarantines components if a policy at the Root Organization or Repositories level has the Proxy Stage set to Fail. Other organizations and applications will not trigger the quarantine even with the proxy stage action set to fail. 

Set the Fail Action 

To set a policy action to fail: 

  1. Log in to IQ Server.
  2. Select Orgs and Policies from the sidebar.
  3. Select the desired policy level Root Organization or Repositories
  4. Select the policy you wish to trigger the quarantine. 
  5. Set the Proxy Stage Action to Fail
  6. Click Update. 

To create a new policy that triggers the quarantine, see the Configuring Policies documentation.

Fail Action Considerations

Here are some additional considerations for using the Fail Action at the Proxy Stage:

  • Quarantine will not trigger if your proxy repository is not configured with Nexus Firewall
  • Only new components can be quarantined. This ensures that the quarantine will not break existing builds. 
  • In the event your license lapses, or you disable your IQ Server, you will not be able to proxy new components unless you disable Nexus Firewall on your proxy repository.
  • Disabling Nexus Firewall on your proxy repository will unblock any quarantined component.
  • Build logs may only show a 404 error for quarantined components. Let all developers and stakeholders know if quarantine is in use. 


We recommend creating a new proxy repository when testing 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.

Viewing Repository Results

Nexus Firewall will automatically audit any configured repository. Any change to the repository will trigger a new evaluation. This process could take a minute or so. The Repository Results screen is a list of all stored components, quarantined components, and corresponding policy violations in your repository, listed by severity. There is a column that indicates if a component is quarantined. 

To view the Repository Results: 

  1. Log in to IQ Server
  2. Select Orgs and Policies from the sidebar
  3. Select Repositories
  4. Select a Repository from the Configuration Section. 

See the Repository Results documentation for more info. 

The Firewall Tab

The Firewall Tab is your home for managing Nexus Firewall. This section gives you tools to manage quarantine behavior, release components from quarantine, request waivers, and view a record of components automatically released. Basic remediation will be covered at the end of this guide. For more detailed information and advanced features, see the following technical documentation: 

To access the Firewall Tab, select Firewall from the sidebar in IQ Server. 

Firewall Integration Setup 

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

Nexus Repository Pro 3 Setup

Nexus Firewall lets you integrate IQ Server’s policy management and component intelligence features with proxy repositories. To enable Firewall you have to connect Nexus Repository Pro to your IQ Server installation and then add the IQ: Audit and Quarantine capability for your proxy repository. 

Supported versions

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

IQ Server Connection Setup

To connect Nexus Repository 3 Pro to IQ Server: 

  1. Log in to your Nexus Repository 3 Pro Instance.
  2. Click the Administration Cog on the main toolbar.
  3. Select IQ Server from the sidebar
  4. Complete the IQ Server Setup form.
    1. Check the Enable the Use of IQ Server box. 
    2. Add your IQ Server URL
    3. Select an authentication method.
      • User Authentication: enter the IQ Server username and password. The default IQ user is admin, the default password is admin123
      • PKI Authentication: Delegate to the JVM for Authentication.
    4. Click Save.
  5. Click Verify Connection to check the configuration. 

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.

Enable Audit & Quarantine

The IQ: Audit and Quarantine Capability must be created for each proxy repository you wish to use with Nexus Firewall. 

To create this capability: 

  1. Log in to Nexus Repository Pro 3.
  2. Select the Administration Cog from the main toolbar. 
  3. Select Capabilities under System on the sidebar.
  4. Click the Create Capability Button.
  5. Select IQ: Audit and Quarantine.
  6. Select the repository you want to use with Nexus Firewall.
  7. Click the Enable Quarantine for Repository checkbox. 
  8. Click Create Capability button. 

Audit and Quarantine capability creation menu

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

Enabling the Quarantine capability. With this capability created and enabled, Nexus Firewall can block new components from entering your proxy repository. Next-Gen Firewall's automatic protection from pending and malicious components will not work without checking that box. Managing which policies quarantine components is managed in IQ Server. 

Results in Nexus Repository

An IQ Server Policy Evaluation is available through Nexus Repository Pro. A summary of these results can be seen on the Repositories view in the Administration menu. 

Click the link in the IQ Policy Violations column to view the Repository Results Screen.

JFrog Artifactory Setup

Nexus Firewall connects to JFrog Artifactory using the Firewall for JFrog Artifactory Plugin. This plugin enables JFrog Artifactory to use Firewall's features to protect your software supply chain from risky and undesirable components. 

Supported Versions

  • We tested Firewall with JFrog Artifactory Pro version 7.2.6
  • Multi-node clusters require the Firewall for JFrog Artifactory Plugin 2.2 or later

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:

    JFrog Artifactory 7.xJFrog Artifactory 6.x
    ${ARTIFACTORY_HOME}
   /var
      /etc
         /artifactory
            /plugins
               nexusFirewallForArtifactoryPlugin.groovy
               firewall.properties
               /lib
                  nexus-iq-artifactory-plugin.jar
    ${ARTIFACTORY_HOME}
   /etc
      /plugins
         nexusFirewallForArtifactoryPlugin.groovy
         firewall.properties
         /lib
            nexus-iq-artifactory-plugin.jar
  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.

# 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

# This identifies this JFrog Artifactory instance in the IQ 'Repositories' view
firewall.repository.manager.id=artifactory-instance-1

# The URL that users will use to connect to the IQ Server.
# This URL will be prepended to the Repository Results view URI.
# For example, a complete Repository Results view URL:
#   http://iq.public.com:8070/ui/links/repository/0396e6d401d143399d53493e57c106e8/result
firewall.iq.public.url=http://iq.public.com:8070

# Define repositories with a 'firewall.repo.' prefix.
# Possible options are 'quarantine', 'audit', 'policyCompliantComponentSelection' and 'disabled'.
# 'policyCompliantComponentSelection' implies 'quarantine'.
#
# If quarantine is enabled and later disabled, all quarantined components will be made available
# in the repository; those components cannot be re-quarantined.
# firewall.repo.<example-repository-name>=quarantine
# firewall.repo.<other-example-repository-name>=audit
# firewall.repo.<another-example-repository-name>=disabled

# Define http proxy settings if applicable
# firewall.iq.proxy.hostname=
# firewall.iq.proxy.port=
# firewall.iq.proxy.username=
# firewall.iq.proxy.password=
# firewall.iq.proxy.ntlm.domain=
# firewall.iq.proxy.ntlm.workstation=

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

This plugin only supports the 'remote' repository type. The 'virtual' repository type is only indirectly supported. If your virtual repository includes a remote repository that has Firewall enabled, then components can be quarantined or audited.

Removing the firewall.properties with the plugin installed will cause all download requests to be denied until the firewall.properties file is restored and JFrog Artifactory is restarted.

If quarantine is enabled and later disabled, all currently quarantined components will be made available in the repository; those components cannot be re-quarantined.

Usage

When JFrog Artifactory is restarted with the configured plugin:

  1. JFrog Artifactory reads the configuration file and enables configured repositories in IQ. You can view these repositories under 'Organization and Policies' in IQ Server.
  2. In Audit mode, new components added to remote repositories are evaluated against IQ policy, but no components are blocked. This information is available in the repository results. 
  3. In Quarantine mode, only components downloaded after enabling Firewall's quarantine feature will be blocked. Existing components can still be downloaded from the proxy repository. Firewall blocks your proxy repository from serving new components that violate policies configured to fail for the Proxy stage in IQ.

Reviewing Results

Every repository with Firewall enabled receives its own Repository Results URL. Make the following call to the JFrog Artifactory server to get the URL. 

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

Substitute your username, password, JFrog Artifactory URL, and virtual repository name in the example above.

This returns a JSON with details on the repository:

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

The  reportUrl can be opened in a browser. This forwards you to the static policy report URL which can be bookmarked for future access.

The property firewall.iqRepositoryUrl links to the same Repository Results URL and is unique to each repository. 

IQ Repository URL property for a repository with Firewall enabled:

Violation Remediation 

Policy violations from Nexus Firewall are available in the Firewall tab and the Repository Results screen. When the quarantine capability is enabled, Firewall will block unwanted components from entering your repository. There are three approaches to policy violation remediation:

  • Select a different version - The easiest way to select remediate a violation is to select a different version of the same component without the failing violation. The Version Graph in the Component Details Page shows information about policy violations for other versions.
    screenshot of the version graph
  • Select a different component - If there is no version of the component that meets your policy standards, the best way to remove the risk might be to select a similar component without the risk. 
  • Waive the violation - If an essential component has no versions that meet your risk tolerance you can waive the violation. Waiving a policy violation is accepting the risk that comes with that component - it does not remove the risk. You can waive a component or request a waiver from the Component Details Page, under the Policy tab.

Firewall Waiver screen

Additional Resources 

Visit Organization Policies in Lifecycle for an interactive course about policies in IQ Server.

Check out the rest of our Firewall Documentation for all Firewall features.