Important: The Firewall for JFrog Artifactory 2.0 plugin fixes an issue with the 'Repository Name' attribute when viewed from IQ. Please see the "1.x to 2.0 Migration" section below for further details.

Multinode clusters require version 2.2 of the Firewall for JFrog Artifactory plugin

Overview

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

To get Nexus Firewall visit the Firewall home page.

Check out the Firewall Quick Start Guide for detailed installation information.

Prerequisites

Additional requirements for Multi-node Clusters:

Firewall for JFrog Artifactory Plugin version 2.2 or later
JFrog Artifactory version 7.49.3, 7.49.5, 7.49.8 and 7.55.2 are not supported because of a cluster synchronization bug

Requirements:

Nexus IQ Server version 119 or higher and a "Nexus Firewall for JFrog Artifactory" license
- Next-Gen Firewall features require a new license issued after June 1, 2021
A version of JFrog Artifactory which has not reached the "Artifactory End of Life" date

Installation

Stop the JFrog Artifactory server
Download the latest version of the plugin
Extract zip file into JFrog Artifactory's /plugins directory (see table below). The zip file includes an example configuration file for the plugin and all necessary files for use.

Rename firewall.properties.example to firewall.properties to use it as the base for your configuration.

The final folder structure should resemble:

JFrog Artifactory 7.x

JFrog 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

Configure and enable your repositories in the firewall.properties file.
Start the JFrog Artifactory server

High Availability

Install the plugin zip and the firewall.properties in the primary node of your JFrog Artifactory High Availability System. JFrog Artifactory HA will automatically synchronize the plugin and its configuration to the remaining nodes. Also update the plugin configuration for JFrog Artifactory HA as documented here.

Upgrade

To upgrade to the latest version of the plugin, repeat the installation steps above and overwrite the nexusFirewallForArtifactoryPlugin.groovy file and the lib/nexus-iq-artifactory-plugin.jar file. The sample configuration file firewall.properties.example can be extracted as well, but is not required. Your actual configuration file will be named firewall.properties. The firewall.properties.example file will not overwrite your firewall.properties configuration file.

1.x to 2.0 Migration

Nexus Firewall for JFrog Artifactory 2.0 fixes an issue in the 1.x series where the 'Repository Manager' column in the 'Repositories' view in IQ displayed a hash value instead of the Repository Manager name.

1.x plugin

2.0 plugin

Do the following to complete the migration and display the repository manager identifier:

Backup your IQ database before updating. See Backing up the IQ Server.

Install Nexus IQ Server 119 or higher
Install Nexus Firewall for JFrog Artifactory Plugin version 2.2 or higher
Update the firewall.properties file and configure the firewall.repository.manager.id property

The migration will automatically begin on JFrog Artifactory startup after completing the above steps. Omitting a step will result in the Repository Manager identifier displayed as a hash value.

Configuration

All plugin configuration is managed by the firewall.properties file.

# 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', 'proprietary' and 'disabled'.
# 'policyCompliantComponentSelection' implies 'quarantine'.
# 'proprietary' can only be set on repositories of type 'local'.
#
# 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
# firewall.repo.<example-local-repository-name>=proprietary

# 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 match an IQ user with the "Component Evaluator" role. See Role Management for further information.

This plugin only supports the 'remote' repository type. The 'virtual' repository type is indirectly supported. Firewall can audit and quarantine components in a virtual repository if it includes a remote repository with Firewall enabled. 'local' repositories can be configured as 'proprietary' to prevent Namespace Confusion Attacks.

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.

Using an HTTP Proxy for Outbound Traffic

If your JFrog Artifactory instance needs to reach IQ Server via an HTTP proxy server, use the following configuration options.

# The host running the proxy server.
firewall.iq.proxy.hostname=company-proxy.example.com

# The port which the proxy server listens on.
firewall.iq.proxy.port=8080

# The username used to access the proxy server (if necessary).
firewall.iq.proxy.username=proxyusername

# The password used to access the proxy server (if necessary).
# firewall.iq.proxy.password=proxypassword

NTLM

If your proxy server uses NT LAN Manager (NTLM) authentication, additionally configure the domain and workstation

# The Windows domain used for authentication
firewall.iq.proxy.ntlm.domain=companydomain
 
# The name of the local computer running JFrog Artifactory
firewall.iq.proxy.ntlm.workstation=localworkstation

High Availability Cache Strategy

Firewall for JFrog Artifactory HA requires a different internal cache strategy and can be configured with the following:

For versions 2.2 and 2.4.2 only. This configuration setting was removed in 2.4.3.

# Disable local memory cache (default: MEMORY_THEN_STORAGE )
firewall.cache.quarantine.strategy=STORAGE_ONLY

It is safe to switch between different cache strategies. Restart JFrog Artifactory for the changes to take effect.

Usage

When JFrog Artifactory is restarted with the configured plugin:

JFrog Artifactory reads the configuration file and enables configured repositories in IQ. View these repositories in 'Repositories' under 'Organization and Policies' in IQ Server.
Only components downloaded after enabling Firewall's quarantine feature will be blocked. Existing components can still be downloaded from the proxy repository. Firewall prevents new components that violate policy from being served from the remote repository.
In Audit mode, new components added to remote repositories are evaluated against IQ policy. This information is available in the repository results.

Reviewing Results

Every repository with Firewall enabled receives its own Application Composition Report 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 Application Composition report URL and is unique to each repository.

IQ Repository URL property for a repository with Firewall enabled:

About Timestamps

The plugin only processes components new to the repository beginning when Firewall was enabled. Components previously served by JFrog Artifactory will always be allowed regardless of their policy status. This prevents any existing builds from breaking.

Logging

The Nexus Firewall for JFrog Artifactory plugin ships with some basic informative logging by default. Additional logs are available for debugging if necessary. Per component blocking is not logged by default to prevent excessive log entries.

JFrog Artifactory uses the Logback library for logging. To understand JFrog Artifactory logging and modify logged information, see the JFrog documentation here: Artifactory Log Files - Configuring Log Verbosity

Add this section to the logback.xml file to increase logging for the Firewall plugin:

<logger name="com.sonatype.iq.artifactory">
    <level value="debug"/>
</logger>

Uninstallation

Stop the JFrog Artifactory server

Remove the nexusFirewallForArtifactoryPlugin.groovy file from the plugins directory to disable the Nexus Firewall for JFrog Artifactory plugin.