JFrog Artifactory Setup

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:

Installation

  1. Stop the JFrog Artifactory server
  2. Download the latest version of the plugin
  3. 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.
  4. 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.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
  5. Configure and enable your repositories in the firewall.properties file.

  6. 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.

  1. Install Nexus IQ Server 119 or higher
  2. Install Nexus Firewall for JFrog Artifactory Plugin version 2.2 or higher
  3. 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:

  1. JFrog Artifactory reads the configuration file and enables configured repositories in IQ. View these repositories in 'Repositories' under 'Organization and Policies' in IQ Server. 
  2. 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.
  3. 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

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

    JFrog Artifactory 7.xJFrog Artifactory 6.x
    ${ARTIFACTORY_HOME}
       /var
          /etc
             /artifactory
                /plugins
                   nexusFirewallForArtifactoryPlugin.groovy
                   nexusFirewallForArtifactoryPlugin.groov?~
                   firewall.properties
                   firewall.propertie?~
                   /lib
                      nexus-iq-artifactory-plugin.jar
    ${ARTIFACTORY_HOME}
       /etc
          /plugins
             nexusFirewallForArtifactoryPlugin.groovy
             nexusFirewallForArtifactoryPlugin.groov?~
             firewall.properties
             firewall.propertie?~
             /lib
                 nexus-iq-artifactory-plugin.jar
  3.  Clean up files that are no longer used (optional).
    1. Remove backup files created by JFrog Artifactory: nexusFirewallForArtifactoryPlugin.groov?~ and firewall.propertie?~ (where ? is a character used to indicate the version of the config file)
    2. Remove the lib/nexus-iq-artifactory-plugin.jar
  4. Start the JFrog Artifactory server
  5. Attributes on repository objects created by Nexus Firewall for JFrog Artifactory are safe to delete. All attributes the Firewall for JFrog Artifactory plugin creates use the prefix firewall. The screenshot below shows a typical example of firewall repository attributes in JFrog Artifactory:

Release notes

DateVersion

Notes

2023-04-062.4.4
2022-10-192.4.3
  • Fixed an issue with the retrieval of version number for JFrog Artifactory
  • Fixed an issue with high availability cache strategy. The firewall.cache.quarantine.strategy configuration settings is deprecated and will now be ignored.
2022-08-192.4.2
  • Fixed issue with API incompatibility with JFrog Artifactory 7.38+
2021-10-082.2
  • Added High-Availablity sections

2021-02-08

2.0.20210202-144950.fea7183

  • Fixed issue with 'Repository Manager' name in the 'Repositories' view in IQ. See the "1.x to 2.0 Migration" for more information.

2020-10-06

1.5.20200826-145900.1e80e0e

  • Ability to re-quarantine a component

2019-05-08

1.3.20190506-103422.bcec6d6

  • Fixed CSRF issue with IQ URL

2019-04-01

1.2.20190401-141713.4839bdb

  • Audit the entire repository when enabled

  • Improved how to access the IQ policy report URL

  • Improved IQ connection handling

  • More graceful handling if the firewall.properties configuration file goes missing

  • Fixed issue when using a web application path

2019-03-18

1.1.20190318-124352.6da59c5

  • Added support for proxies

  • Improved IQ summary report URL

  • Allow readers to access the Evaluation Summary

2019-03-01

1.0.20190228-114947.80c1638

  • Initial release